Skip to content

The README's first code block contain some LangGraph's API, not GraphARC's - #55

Merged
Shashankss1205 merged 1 commit into
mainfrom
fix/readme-quickstart-is-not-the-real-api
Aug 3, 2026
Merged

The README's first code block contain some LangGraph's API, not GraphARC's#55
Shashankss1205 merged 1 commit into
mainfrom
fix/readme-quickstart-is-not-the-real-api

Conversation

@Shashankss1205

Copy link
Copy Markdown
Collaborator

Every call in the Quick Start was wrong, and it was the first code a visitor copies. Verified against this tree rather than read:

  • from grapharc.runtime import StateGraph -> ImportError. This package has never exported StateGraph; the module exports GraphARC. The very first line failed, so nobody who pasted the block got as far as the rest.
  • add_node("process", lambda ...) with no writes= -> TypeError, the argument is required. Per-node write permissions are the project's headline claim, and the snippet showed them being skipped.
  • add_edge("START", "process") -> ValueError: unknown node 'START'. START is a sentinel, not the string.
  • Plain pydantic.BaseModel for state. Accepted at runtime, but it sidesteps GraphARCState and the typed-contract story the page is selling.

The block came in with 241b272 ("README refactoring: improve discoverability and structure"), which also added a contents list whose #usage and #documentation entries point at sections that do not exist — a dead anchor on GitHub silently does nothing when clicked, so reading the page never surfaced it either.

Replaced with a snippet that runs, and that shows the three things that are actually the point: typed state, declared writes, a Budget on the run. The contents list now names the real sections.

Nothing caught any of this because nothing ran it. This module's own docstring describes exactly that drift for the admission-gate section and fixes it by executing the block; the Quick Start had the same standing on the page and none of the discipline. So it gets the same treatment:

  • test_the_quick_start_block_actually_runs_against_this_tree executes the block and compares stdout with the result the page states.
  • test_the_quick_start_reaches_no_live_backend keeps the first snippet a visitor copies from being able to spend money.
  • test_every_table_of_contents_link_resolves_to_a_real_heading derives anchors the way GitHub does and fails on a dead one.

Both new tests were confirmed to fail against the old README and pass against the new one, so they are not vacuous. Full suite green on 3.12; ruff clean.

Every call in the Quick Start was wrong, and it was the first code a visitor
copies. Verified against this tree rather than read:

- `from grapharc.runtime import StateGraph` -> ImportError. This package has
  never exported `StateGraph`; the module exports `GraphARC`. The very first
  line failed, so nobody who pasted the block got as far as the rest.
- `add_node("process", lambda ...)` with no `writes=` -> TypeError, the
  argument is required. Per-node write permissions are the project's headline
  claim, and the snippet showed them being skipped.
- `add_edge("START", "process")` -> ValueError: unknown node 'START'. START is
  a sentinel, not the string.
- Plain `pydantic.BaseModel` for state. Accepted at runtime, but it sidesteps
  `GraphARCState` and the typed-contract story the page is selling.

The block came in with 241b272 ("README refactoring: improve discoverability
and structure"), which also added a contents list whose `#usage` and
`#documentation` entries point at sections that do not exist — a dead anchor
on GitHub silently does nothing when clicked, so reading the page never
surfaced it either.

Replaced with a snippet that runs, and that shows the three things that are
actually the point: typed state, declared writes, a Budget on the run. The
contents list now names the real sections.

Nothing caught any of this because nothing ran it. This module's own docstring
describes exactly that drift for the admission-gate section and fixes it by
executing the block; the Quick Start had the same standing on the page and
none of the discipline. So it gets the same treatment:

- `test_the_quick_start_block_actually_runs_against_this_tree` executes the
  block and compares stdout with the result the page states.
- `test_the_quick_start_reaches_no_live_backend` keeps the first snippet a
  visitor copies from being able to spend money.
- `test_every_table_of_contents_link_resolves_to_a_real_heading` derives
  anchors the way GitHub does and fails on a dead one.

Both new tests were confirmed to fail against the old README and pass against
the new one, so they are not vacuous. Full suite green on 3.12; ruff clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Shashankss1205
Shashankss1205 merged commit a68d957 into main Aug 3, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants