langgraph-stream-parser 0.4.0__tar.gz → 0.4.1__tar.gz

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.4.1}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.4.1] - 2026-06-14
+
+AG-UI bridge robustness — an edge-case audit (`tests/test_agui_matrix.py`, run against purpose-built tool-calling / interrupting / erroring / checkpointer-less agents) surfaced three real issues, now fixed:
+
+### Fixed
+- **Graphs compiled without a checkpointer no longer hard-crash.** The AG-UI adapter calls `graph.aget_state()`, which raises `No checkpointer set` — common for plain user graphs. `build_agent()` now auto-attaches an in-memory checkpointer when the graph lacks one (AG-UI needs threaded state for interrupts/resume regardless).
+- **Agent exceptions mid-run now emit a terminal `RUN_ERROR`** instead of silently killing the stream / unhandled 500. The endpoint is now a resilient wrapper around the agent run.
+
+### Verified (was previously only claimed)
+- Tool calls map to `TOOL_CALL_START`/`ARGS`/`END` + `TOOL_CALL_RESULT`.
+- Interrupts surface as a `CUSTOM` `on_interrupt` event; resume via `forwardedProps.command.resume` continues the run (HITL round-trip).
+- Multi-turn thread state persists; concurrent requests are isolated (per-request agent clone). Note: AG-UI clients must use **unique message ids** per turn — the adapter dedupes by id.
+
 ## [0.4.0] - 2026-06-14
 
 Adopt **AG-UI** for the wire (see `docs/adr/0001-adopt-ag-ui-for-the-wire.md`).

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.4.0
+Version: 0.4.1
 Summary: Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, and an AG-UI bridge
 Project-URL: Homepage, https://github.com/dkedar7/langgraph-stream-parser
 Project-URL: Documentation, https://github.com/dkedar7/langgraph-stream-parser#readme

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.4.0"
+version = "0.4.1"
 description = "Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, and an AG-UI bridge"
 readme = "README.md"
 license = {text = "MIT"}

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.4.1}/src/langgraph_stream_parser/agui/__init__.py

@@ -24,8 +24,9 @@ Quick start::
     from langgraph_stream_parser.agui import build_app
     app = build_app(my_compiled_graph)   # an ASGI app; run with uvicorn
 """
-from __future__ import annotations
-
+# NB: intentionally NOT `from __future__ import annotations`. The resilient
+# endpoint below needs real (non-string) annotations so FastAPI can resolve
+# RunAgentInput as the request body; PEP 604 unions work natively on >=3.11.
 from typing import Any
 
 __all__ = ["build_agent", "add_agui_endpoint", "build_app", "serve", "DEFAULT_AGENT_NAME"]
@@ -71,6 +72,17 @@ def build_agent(
         from ag_ui_langgraph import LangGraphAgent
     except ImportError as e:  # pragma: no cover - exercised only without the extra
         raise RuntimeError(_IMPORT_HINT) from e
+    # AG-UI requires threaded state — the adapter calls graph.aget_state() and
+    # supports interrupts/resume, both of which need a checkpointer. Many user
+    # graphs are compiled without one (and would otherwise hard-crash with
+    # "No checkpointer set"), so attach an in-memory default when absent.
+    if getattr(graph, "checkpointer", None) is None:
+        try:
+            from langgraph.checkpoint.memory import InMemorySaver
+
+            graph.checkpointer = InMemorySaver()
+        except Exception:  # pragma: no cover - best-effort; LangGraphAgent will surface real issues
+            pass
     return LangGraphAgent(name=name, graph=graph, description=description, config=config)
 
 
@@ -87,15 +99,53 @@ def add_agui_endpoint(
 
     ``graph`` may be a compiled graph or an already-built ``LangGraphAgent``.
     Returns the same ``app`` for chaining.
+
+    The endpoint is *resilient*: if the agent raises mid-run, a terminal
+    ``RUN_ERROR`` event is emitted and the stream closes cleanly, rather than
+    crashing the connection with an unhandled 500 (the bare upstream adapter
+    lets node exceptions propagate). Each request runs on its own cloned agent.
     """
     try:
-        from ag_ui_langgraph import add_langgraph_fastapi_endpoint
+        from ag_ui.core import EventType, RunAgentInput, RunErrorEvent
+        from ag_ui.encoder import EventEncoder
+        from fastapi import Request
+        from fastapi.responses import StreamingResponse
     except ImportError as e:  # pragma: no cover
         raise RuntimeError(_IMPORT_HINT) from e
+
     agent = graph if _is_langgraph_agent(graph) else build_agent(
         graph, name=name, description=description, config=config
     )
-    add_langgraph_fastapi_endpoint(app, agent, path=path)
+
+    @app.post(path)
+    async def _run(input_data: RunAgentInput, request: Request):
+        accept = request.headers.get("accept")
+        try:
+            encoder = EventEncoder(accept=accept)
+        except TypeError:  # pragma: no cover - older SDKs without the accept kwarg
+            encoder = EventEncoder()
+        media_type = getattr(encoder, "get_content_type", lambda: "text/event-stream")()
+        run_agent = agent.clone()
+
+        async def gen():
+            try:
+                async for ev in run_agent.run(input_data):
+                    # run() yields SSE-encoded strings; encode objects defensively.
+                    yield ev if isinstance(ev, (str, bytes)) else encoder.encode(ev)
+            except Exception as exc:  # noqa: BLE001 - surfaced to the client as RUN_ERROR
+                yield encoder.encode(
+                    RunErrorEvent(
+                        type=EventType.RUN_ERROR,
+                        message=f"{type(exc).__name__}: {exc}",
+                    )
+                )
+
+        return StreamingResponse(gen(), media_type=media_type)
+
+    @app.get(path)
+    async def _health():
+        return {"status": "ok", "agent": {"name": getattr(agent, "name", name)}}
+
     return app
 
 

langgraph_stream_parser-0.4.1/tests/test_agui_matrix.py

@@ -0,0 +1,261 @@
+"""AG-UI edge-case matrix — exercises the bridge against purpose-built agents
+that each stress one event class, asserting the *observed* AG-UI output.
+
+This is the audit that converts the langgraph-stream-parser -> AG-UI mapping
+from "claimed" to "proven", and it pins the three robustness fixes the audit
+surfaced:
+  1. graphs compiled WITHOUT a checkpointer are auto-handled (AG-UI's
+     aget_state would otherwise hard-crash with "No checkpointer set");
+  2. an agent exception mid-run becomes a terminal RUN_ERROR event instead of
+     a silently-dying stream / unhandled 500;
+  3. interrupts surface as a CUSTOM `on_interrupt` event and resume via
+     forwardedProps.command.resume.
+
+Every agent here is compiled WITHOUT a checkpointer on purpose, so the suite
+also proves the auto-attach fix end to end.
+"""
+import json
+from concurrent.futures import ThreadPoolExecutor
+from typing import Iterator, List
+
+import pytest
+
+pytest.importorskip("ag_ui_langgraph", reason="needs the 'agui' extra")
+pytest.importorskip("fastapi", reason="needs fastapi")
+pytest.importorskip("langgraph", reason="needs langgraph")
+
+from fastapi.testclient import TestClient  # noqa: E402
+from langchain_core.language_models import BaseChatModel  # noqa: E402
+from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage  # noqa: E402
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult  # noqa: E402
+from langchain_core.tools import tool  # noqa: E402
+from langgraph.graph import END, START, MessagesState, StateGraph  # noqa: E402
+from langgraph.prebuilt import ToolNode  # noqa: E402
+from langgraph.types import interrupt  # noqa: E402
+
+from langgraph_stream_parser.agui import build_app  # noqa: E402
+from langgraph_stream_parser.demo import create_stub_agent  # noqa: E402
+
+
+# ── driver ───────────────────────────────────────────────────────────
+
+def _run_input(text, *, thread="t1", run="r1", resume=None):
+    # NB: each turn needs a UNIQUE message id — the AG-UI/LangGraph adapter
+    # dedupes messages by id, so reusing an id silently drops later turns.
+    body = {
+        "threadId": thread, "runId": run,
+        "messages": [{"id": f"msg-{thread}-{run}", "role": "user", "content": text}],
+        "tools": [], "context": [], "state": {}, "forwardedProps": {},
+    }
+    if resume is not None:
+        body["forwardedProps"] = {"command": {"resume": resume}}
+    return body
+
+
+def _drive(app, body):
+    """POST a run, return (status_code, [event dicts])."""
+    client = TestClient(app, raise_server_exceptions=False)
+    resp = client.post("/", json=body)
+    events = []
+    for line in resp.text.splitlines():
+        line = line.strip()
+        if line.startswith("data:"):
+            try:
+                events.append(json.loads(line[5:].strip()))
+            except json.JSONDecodeError:
+                pass
+    return resp.status_code, events
+
+
+def _types(events):
+    return [e.get("type") for e in events]
+
+
+def _text(events):
+    return "".join(e.get("delta", "") for e in events if e.get("type") == "TEXT_MESSAGE_CONTENT")
+
+
+# ── purpose-built agents (all compiled WITHOUT a checkpointer) ─────────
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+
+class _ToolThenAnswer(BaseChatModel):
+    @property
+    def _llm_type(self) -> str:
+        return "tool-matrix-stub"
+
+    def bind_tools(self, *a, **k):
+        return self
+
+    def _generate(self, messages, stop=None, run_manager=None, **kw):
+        return ChatResult(generations=[ChatGeneration(message=self._reply(messages))])
+
+    def _reply(self, messages: List[BaseMessage]) -> AIMessage:
+        if messages and getattr(messages[-1], "type", None) == "tool":
+            return AIMessage(content="the sum is 5")
+        return AIMessage(content="", tool_calls=[{"id": "call_1", "name": "add", "args": {"a": 2, "b": 3}}])
+
+    def _stream(self, messages, stop=None, run_manager=None, **kw) -> Iterator[ChatGenerationChunk]:
+        if messages and getattr(messages[-1], "type", None) == "tool":
+            for tok in ["the ", "sum ", "is ", "5"]:
+                ch = ChatGenerationChunk(message=AIMessageChunk(content=tok))
+                if run_manager:
+                    run_manager.on_llm_new_token(tok, chunk=ch)
+                yield ch
+        else:
+            yield ChatGenerationChunk(message=AIMessageChunk(
+                content="",
+                tool_call_chunks=[{"name": "add", "args": '{"a": 2, "b": 3}', "id": "call_1", "index": 0}],
+            ))
+
+
+def _tool_agent():
+    model = _ToolThenAnswer()
+
+    def call_model(state):
+        return {"messages": [model.invoke(state["messages"])]}
+
+    def route(state):
+        return "tools" if getattr(state["messages"][-1], "tool_calls", None) else END
+
+    b = StateGraph(MessagesState)
+    b.add_node("model", call_model)
+    b.add_node("tools", ToolNode([add]))
+    b.add_edge(START, "model")
+    b.add_conditional_edges("model", route, {"tools": "tools", END: END})
+    b.add_edge("tools", "model")
+    return b.compile()  # NO checkpointer — exercises the auto-attach fix
+
+
+def _interrupt_agent():
+    def ask(state):
+        decision = interrupt({"question": "approve?", "tool": "deploy"})
+        return {"messages": [AIMessage(content=f"resumed: {decision}")]}
+
+    b = StateGraph(MessagesState)
+    b.add_node("ask", ask)
+    b.add_edge(START, "ask")
+    b.add_edge("ask", END)
+    return b.compile()  # NO checkpointer
+
+
+def _error_agent():
+    def boom(state):
+        raise ValueError("intentional boom")
+
+    b = StateGraph(MessagesState)
+    b.add_node("boom", boom)
+    b.add_edge(START, "boom")
+    b.add_edge("boom", END)
+    return b.compile()  # NO checkpointer
+
+
+def _plain_echo_no_checkpointer():
+    """An echo graph with NO checkpointer (create_stub_agent ships one)."""
+    from langchain_core.messages import AIMessage as _AI
+
+    def respond(state):
+        last = next((m.content for m in reversed(state["messages"])
+                     if getattr(m, "type", None) == "human"), "")
+        return {"messages": [_AI(content=f"echo: {last}")]}
+
+    b = StateGraph(MessagesState)
+    b.add_node("respond", respond)
+    b.add_edge(START, "respond")
+    b.add_edge("respond", END)
+    return b.compile()
+
+
+# ── tests ────────────────────────────────────────────────────────────
+
+def test_tool_calls_map_to_agui():
+    status, events = _drive(build_app(_tool_agent()), _run_input("add 2 and 3"))
+    assert status == 200
+    t = _types(events)
+    assert "TOOL_CALL_START" in t
+    assert "TOOL_CALL_RESULT" in t
+    start = next(e for e in events if e["type"] == "TOOL_CALL_START")
+    result = next(e for e in events if e["type"] == "TOOL_CALL_RESULT")
+    assert start.get("toolCallName") == "add"
+    assert result.get("content") == "5"
+    assert "the sum is 5" in _text(events)
+    assert "RUN_FINISHED" in t and "RUN_ERROR" not in t
+
+
+def test_interrupt_is_signaled_and_resumes():
+    app = build_app(_interrupt_agent())
+
+    status, first = _drive(app, _run_input("go", thread="ti", run="r1"))
+    assert status == 200
+    customs = [e for e in first if e.get("type") == "CUSTOM" and e.get("name") == "on_interrupt"]
+    assert customs, f"interrupt not signaled as CUSTOM/on_interrupt: {_types(first)}"
+    # the interrupt payload travels to the client
+    assert "approve?" in json.dumps(customs[0])
+    assert "RUN_ERROR" not in _types(first)
+
+    # resume the SAME thread with a decision via forwardedProps.command.resume
+    status, second = _drive(app, _run_input("", thread="ti", run="r2", resume="approved"))
+    assert status == 200
+    assert "RUN_FINISHED" in _types(second)
+    assert "RUN_ERROR" not in _types(second)
+    # the resumed value reached the agent (it echoed "resumed: approved" into state)
+    assert "resumed: approved" in json.dumps(second)
+
+
+def test_agent_error_becomes_run_error():
+    """The resilient endpoint emits a terminal RUN_ERROR instead of a
+    silently-dying stream / unhandled 500."""
+    status, events = _drive(build_app(_error_agent()), _run_input("crash"))
+    assert status == 200
+    errs = [e for e in events if e.get("type") == "RUN_ERROR"]
+    assert errs, f"expected a RUN_ERROR event, got: {_types(events)}"
+    assert "intentional boom" in errs[0].get("message", "")
+
+
+def test_graph_without_checkpointer_is_handled():
+    """AG-UI's aget_state needs a checkpointer; the bridge auto-attaches one
+    so a plain compiled graph doesn't hard-crash."""
+    status, events = _drive(build_app(_plain_echo_no_checkpointer()), _run_input("ping"))
+    assert status == 200
+    # The fix's job: no hard-crash, run completes. (This node appends an
+    # AIMessage directly rather than streaming a model, so its content lands in
+    # the state/messages snapshot, not as TEXT_MESSAGE_CONTENT deltas.)
+    assert "RUN_ERROR" not in _types(events)
+    assert "RUN_FINISHED" in _types(events)
+    assert "echo: ping" in json.dumps(events)
+
+
+def test_multi_turn_thread_persists():
+    app = build_app(create_stub_agent(reply_prefix="echo: "))
+    s1, e1 = _drive(app, _run_input("first", thread="conv", run="r1"))
+    s2, e2 = _drive(app, _run_input("second", thread="conv", run="r2"))
+    assert s1 == 200 and s2 == 200
+    assert "first" in _text(e1)
+    assert "second" in _text(e2)
+    # state persisted across turns: the second run carries BOTH turns
+    blob = json.dumps(e2)
+    assert "first" in blob and "second" in blob
+
+
+def test_concurrent_requests_are_isolated():
+    """The adapter clones per request; distinct threads must not cross-talk."""
+    app = build_app(create_stub_agent(reply_prefix="echo: "))
+    inputs = [f"msg-{i}" for i in range(8)]
+
+    def one(i):
+        _, events = _drive(app, _run_input(inputs[i], thread=f"th-{i}", run=f"r-{i}"))
+        return inputs[i], _text(events)
+
+    with ThreadPoolExecutor(max_workers=8) as ex:
+        results = list(ex.map(one, range(8)))
+
+    for sent, got in results:
+        assert sent in got, f"{sent!r} not echoed in {got!r}"
+        # no other request's payload leaked into this response
+        for other in inputs:
+            if other != sent:
+                assert other not in got, f"cross-talk: {other!r} leaked into {got!r}"