showcase/integrations/langgraph-fastapi/PARITY_NOTES.md
Tracks where this integration intentionally diverges from the
langgraph-python north star. Everything not listed here is expected to be
byte-identical (modulo the integration's own name/title). The real judge of
parity is behavior (bin/showcase test langgraph-fastapi:<demo> --d6); the
entries below are known, sanctioned divergences that should NOT be "fixed"
toward byte-identity.
Rule for agents: if a file is listed below, it is different on purpose —
do not "fix" it to match langgraph-python. If you think an entry is wrong,
verify with D6 first (bin/showcase test langgraph-fastapi:<demo> --d6) and
discuss before changing.
app/demos/a2ui-recovery/suggestions.ts — a2ui-recovery fixtures carry NO
x-aimock-context, so each integration MUST use a UNIQUE pill prompt or
fixtures collide across integrations. fastapi's prompt ("Put together a
quarterly metrics overview…") differs from langgraph-python's ("Build my Q2
revenue summary…") by design. See
harness/src/probes/scripts/d5-a2ui-recovery.ts ("per-framework prompt
isolation, load-bearing"). Aligning to LGP's prompt makes aimock fail to
match (STRICT no-match). (a2ui-recovery ALSO has a separate DOM-level D6 red
that is NOT a fastapi defect — see the shared-north-star-defect section
below.)app/demos/a2ui-recovery/chat.tsx — consequence of the unique-prompt design
above: this integration does not inject the declarative-gen-ui sales-context
hook into the recovery demo (the backend prompt + fixtures carry the
dataset). Kept as fastapi's own working version.app/demos/a2ui-recovery/page.tsx — per-slug backend path reference in the
doc comment (src/agents/src/recovery_agent.py). Cosmetic comment
divergence, not behavior.The a2ui-recovery demo is the one place this integration cannot be
byte-identical to langgraph-python. Its aimock fixtures do not send the
x-aimock-context routing header, so aimock can only disambiguate integrations
by the prompt text itself. Each integration therefore keeps a distinct pill
prompt, and its a2ui-recovery.json fixtures are keyed to that prompt. The
frontend (suggestions.ts, and consequently chat.tsx/page.tsx) and the
fixture stay in lockstep per integration. Aligning them to langgraph-python
breaks fixture matching (aimock: STRICT no fixture matched → agent error →
D6 red).
A deeper fix would be to add context routing to the a2ui-recovery flow so all integrations could share one prompt — out of scope here.
Separate from the prompt-isolation divergence above, the a2ui-recovery D6
cell is currently red at the DOM level (surface-missing), and this is
not a fastapi-specific bug — it reproduces identically on the
langgraph-python north star. So fastapi is already behaviorally aligned
with LGP here; there is nothing to fix under integrations/langgraph-fastapi/.
Live-trace findings (2026-07-27):
declarative-metric tiles the probe
requires. The validate→retry loop does not reliably advance
seq0(invalid)→seq1(valid): narration claims "I recovered and painted your
metrics overview" while the DOM shows the hard-fail card "Couldn't generate
the UI." Worker log: waitForTurnComplete: turn 1 did not complete … reason=surface-missing.transferSize
~12–14M on both fastapi and LGP) vs a clean short stream on the green
sibling — consistent with the recovery loop over-iterating / re-emitting
instead of stopping at the healed surface.getA2UITools) is reliably green (3/3), so the demo
itself is achievable. fastapi, LGP, and google-adk share the Python
ag_ui_langgraph.get_a2ui_tools (v0.0.41, a pip dependency in the agent
container — not in this repo), which is the suspected locus.injectA2UITool
(present, correct), catalog registration (defaultCatalogId: "declarative-gen-ui-catalog", identical to LGP), and any fastapi wiring
drift (route.ts, recovery_agent.py, langgraph.json are structurally
identical to LGP).Fixing the shared Python recovery loop is tracked as a separate PR against
the north star / the ag_ui_langgraph package, not in this fastapi
alignment branch. A single one-off green does not reproduce — do not treat a
lone green run as "fixed".
The byoc D6 featureType covers BOTH declarative demos:
declarative-hashbrown (@hashbrownai/react, streamed structured output) and
declarative-json-render (@json-render/react, hierarchical JSON spec + a
Zod-validated catalog). Both render the same sales dashboard (metric card +
pie/bar chart) via two different third-party rendering libraries.
The grid byoc cell is GREEN on fastapi. The shared probe
(harness/src/probes/scripts/d5-byoc.ts) navigates to the preferred route
(declarative-hashbrown) and sends the hashbrown pill, which matches
fastapi's hashbrown fixture → pass.
A scoped bin/showcase test langgraph-fastapi:declarative-json-render --d6
reds, for two layered reasons — neither is a fastapi defect:
d5-byoc.ts always sends the
hashbrown pill even when navigation is forced to the json-render page —
its NOTE says the build context doesn't expose demos[], so it can't pick
the per-page pill. So the scoped json-render run is driven with the wrong
pill by design. Tracked as a follow-up (improve the probe to select the
pill per page).render_dashboard tool-call shape (any pill
→ same payload both pages consume), so its scoped json-render run happens
to pass. fastapi keeps the two libraries as genuinely separate
integrations with their own pills/fixtures (hashbrown pill vs the shorter
"Show me the sales dashboard with metrics and a revenue chart" json-render
pill). fastapi's split is arguably more faithful to what each library
actually does; collapsing it to LGP's unified contract would be a content
downgrade, so it is NOT done here.Net: sanctioned divergence on a manual scoped test path only. The gating grid
cell (byoc) is green and both demos render correctly live. Do not "fix" this
by rewriting fastapi's json-render demo to the unified render_dashboard
contract — the real fix is probe-side (see follow-up).