langgraph-stream-parser 0.1.6__tar.gz → 0.1.7__tar.gz

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.1.7] - 2026-04-18
+
+### Added
+- `FastAPIAdapter` for streaming LangGraph events over WebSocket and Server-Sent Events; stateless by design — conversation state is keyed by `session_id` used as LangGraph `thread_id`
+- Per-session asyncio lock with refcounted cleanup to serialize concurrent turns on the same thread
+- `BaseAdapter._text_prompt_interrupt()` helper, shared by `PrintAdapter` and `JupyterDisplay`
+- `BaseAdapter._truncate()` helper for preview-length capping
+- `fastapi` optional dependency group (`pip install langgraph-stream-parser[fastapi]`)
+
+### Changed
+- Hoisted `_last_rendered_count` incremental-render cursor from Print/CLI into `BaseAdapter`
+- Slimmed `examples/fastapi_websocket.py` from ~455 to ~234 lines by using the new adapter
+
+### Fixed
+- `UsageEvent` now has an explicit case in `BaseAdapter._process_event` instead of silently falling through
+
 ## [0.1.6] - 2026-03-28
 
 ### Added

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.1.6
+Version: 0.1.7
 Summary: Universal parser for LangGraph streaming outputs
 Project-URL: Homepage, https://github.com/dkedar7/langgraph-stream-parser
 Project-URL: Documentation, https://github.com/dkedar7/langgraph-stream-parser#readme
@@ -21,12 +21,16 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
 Requires-Dist: langchain-core>=0.2.0; extra == 'dev'
 Requires-Dist: langgraph>=0.2.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: rich>=13.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
 Provides-Extra: jupyter
 Requires-Dist: ipython>=8.0; extra == 'jupyter'
 Requires-Dist: rich>=13.0; extra == 'jupyter'
@@ -342,6 +346,66 @@ adapter.run(graph=agent, input_data=input_data, config=config)
 
 Universal output that works in any Python environment without dependencies.
 
+### FastAPIAdapter - WebSocket / SSE Streaming
+
+Stream events to a web client over WebSocket or Server-Sent Events. The adapter is stateless — conversation state lives in LangGraph's checkpointer, keyed by `session_id` (used as `thread_id`).
+
+```python
+from fastapi import FastAPI, WebSocket
+from langgraph_stream_parser.adapters import FastAPIAdapter
+
+app = FastAPI()
+adapter = FastAPIAdapter(graph=agent)  # agent must be compiled with a checkpointer
+
+@app.websocket("/chat/{session_id}")
+async def chat(ws: WebSocket, session_id: str):
+    await adapter.handle_websocket(ws, session_id)
+```
+
+Reconnecting with the same `session_id` resumes the conversation — LangGraph's checkpointer rehydrates history automatically.
+
+**WebSocket message protocol (client ↔ server)**
+
+Client → Server:
+
+```jsonc
+{"type": "message", "content": "Hello"}
+{"type": "decision", "decisions": [{"type": "approve"}]}
+{"type": "decision", "decisions": [{"type": "edit", "args": {...}}]}
+{"type": "cancel"}
+```
+
+Server → Client: every event's `to_dict()` output (e.g. `{"type": "content", ...}`, `{"type": "tool_start", ...}`, `{"type": "interrupt", ...}`, `{"type": "complete"}`), plus protocol-level messages:
+
+```jsonc
+{"type": "ack", "ref": "message|decision|cancel"}
+{"type": "error", "error": "..."}
+```
+
+**Server-Sent Events**
+
+```python
+from fastapi.responses import StreamingResponse
+from langgraph_stream_parser import prepare_agent_input
+
+@app.post("/chat/{session_id}")
+async def chat(session_id: str, body: dict):
+    input_data = prepare_agent_input(message=body["message"])
+    return StreamingResponse(
+        adapter.sse_stream(session_id, input_data),
+        media_type="text/event-stream",
+    )
+
+@app.post("/chat/{session_id}/resume")
+async def resume(session_id: str, body: dict):
+    return StreamingResponse(
+        adapter.resume(session_id, body["decisions"]),
+        media_type="text/event-stream",
+    )
+```
+
+Requires: `pip install langgraph-stream-parser[fastapi]`
+
 ### JupyterDisplay - Rich Notebook Display
 
 ```python

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/README.md

@@ -308,6 +308,66 @@ adapter.run(graph=agent, input_data=input_data, config=config)
 
 Universal output that works in any Python environment without dependencies.
 
+### FastAPIAdapter - WebSocket / SSE Streaming
+
+Stream events to a web client over WebSocket or Server-Sent Events. The adapter is stateless — conversation state lives in LangGraph's checkpointer, keyed by `session_id` (used as `thread_id`).
+
+```python
+from fastapi import FastAPI, WebSocket
+from langgraph_stream_parser.adapters import FastAPIAdapter
+
+app = FastAPI()
+adapter = FastAPIAdapter(graph=agent)  # agent must be compiled with a checkpointer
+
+@app.websocket("/chat/{session_id}")
+async def chat(ws: WebSocket, session_id: str):
+    await adapter.handle_websocket(ws, session_id)
+```
+
+Reconnecting with the same `session_id` resumes the conversation — LangGraph's checkpointer rehydrates history automatically.
+
+**WebSocket message protocol (client ↔ server)**
+
+Client → Server:
+
+```jsonc
+{"type": "message", "content": "Hello"}
+{"type": "decision", "decisions": [{"type": "approve"}]}
+{"type": "decision", "decisions": [{"type": "edit", "args": {...}}]}
+{"type": "cancel"}
+```
+
+Server → Client: every event's `to_dict()` output (e.g. `{"type": "content", ...}`, `{"type": "tool_start", ...}`, `{"type": "interrupt", ...}`, `{"type": "complete"}`), plus protocol-level messages:
+
+```jsonc
+{"type": "ack", "ref": "message|decision|cancel"}
+{"type": "error", "error": "..."}
+```
+
+**Server-Sent Events**
+
+```python
+from fastapi.responses import StreamingResponse
+from langgraph_stream_parser import prepare_agent_input
+
+@app.post("/chat/{session_id}")
+async def chat(session_id: str, body: dict):
+    input_data = prepare_agent_input(message=body["message"])
+    return StreamingResponse(
+        adapter.sse_stream(session_id, input_data),
+        media_type="text/event-stream",
+    )
+
+@app.post("/chat/{session_id}/resume")
+async def resume(session_id: str, body: dict):
+    return StreamingResponse(
+        adapter.resume(session_id, body["decisions"]),
+        media_type="text/event-stream",
+    )
+```
+
+Requires: `pip install langgraph-stream-parser[fastapi]`
+
 ### JupyterDisplay - Rich Notebook Display
 
 ```python

langgraph_stream_parser-0.1.7/examples/fastapi_websocket.py

@@ -0,0 +1,234 @@
+"""
+FastAPI WebSocket Example using FastAPIAdapter.
+
+Demonstrates the built-in ``FastAPIAdapter`` streaming LangGraph events
+over a WebSocket with interrupt handling. The adapter is stateless —
+conversation state lives in LangGraph's checkpointer keyed by
+``session_id`` (used as ``thread_id``).
+
+Requirements:
+    pip install 'langgraph-stream-parser[fastapi]' uvicorn langgraph
+
+Run:
+    uvicorn examples.fastapi_websocket:app --reload
+
+Then open http://localhost:8000 in your browser.
+"""
+import uuid
+
+from fastapi import FastAPI, WebSocket
+from fastapi.responses import HTMLResponse
+from dotenv import load_dotenv
+
+from langgraph_stream_parser.adapters import FastAPIAdapter
+
+load_dotenv()
+
+from .agent import agent
+
+
+app = FastAPI()
+adapter = FastAPIAdapter(graph=agent)
+
+
+@app.websocket("/ws/chat/{session_id}")
+async def websocket_chat(websocket: WebSocket, session_id: str):
+    """WebSocket endpoint. Reconnecting with the same session_id resumes
+    the conversation (state lives in the checkpointer)."""
+    await adapter.handle_websocket(websocket, session_id)
+
+
+@app.get("/")
+async def get_client():
+    """Serve the HTML test client, seeded with a fresh session_id."""
+    return HTMLResponse(HTML_CLIENT.replace("{{SESSION_ID}}", str(uuid.uuid4())))
+
+
+# ── HTML client ─────────────────────────────────────────────────────
+# The protocol: client sends
+#   {"type": "message", "content": "..."}
+#   {"type": "decision", "decisions": [{"type": "approve"}, ...]}
+# Server sends: event_to_dict(event) for each StreamEvent, plus
+#   {"type": "ack", "ref": "..."} and {"type": "error", "error": "..."}
+
+HTML_CLIENT = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>LangGraph Stream Parser - WebSocket Demo</title>
+    <style>
+        * { box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+            background: #f5f5f5;
+        }
+        h1 { color: #333; }
+        #chat {
+            background: white;
+            border: 1px solid #ddd;
+            border-radius: 8px;
+            height: 500px;
+            overflow-y: auto;
+            padding: 16px;
+            margin-bottom: 16px;
+        }
+        .message { margin: 8px 0; padding: 12px; border-radius: 8px; }
+        .user { background: #007bff; color: white; margin-left: 20%; }
+        .assistant { background: #e9ecef; margin-right: 20%; }
+        .tool-start { background: #fff3cd; border-left: 4px solid #ffc107; font-size: 0.9em; }
+        .tool-end { background: #d4edda; border-left: 4px solid #28a745; font-size: 0.9em; }
+        .tool-error { background: #f8d7da; border-left: 4px solid #dc3545; }
+        .complete { background: #d1ecf1; border-left: 4px solid #17a2b8; text-align: center; font-style: italic; }
+        .error { background: #f8d7da; border-left: 4px solid #dc3545; }
+        .interrupt { background: #fff3cd; border: 2px solid #ffc107; padding: 16px; }
+        .interrupt h4 { margin: 0 0 12px 0; color: #856404; }
+        .interrupt pre { background: #f8f9fa; padding: 8px; border-radius: 4px; overflow-x: auto; font-size: 0.85em; }
+        .interrupt-buttons { margin-top: 12px; display: flex; gap: 8px; }
+        .interrupt-buttons button { padding: 8px 16px; font-size: 14px; }
+        .btn-approve { background: #28a745; }
+        .btn-reject { background: #dc3545; }
+        #input-area { display: flex; gap: 8px; }
+        #message-input { flex: 1; padding: 12px; border: 1px solid #ddd; border-radius: 8px; font-size: 16px; }
+        button { padding: 12px 24px; background: #007bff; color: white; border: none; border-radius: 8px; cursor: pointer; font-size: 16px; }
+        button:disabled { background: #6c757d; cursor: not-allowed; }
+        code { background: #f4f4f4; padding: 2px 6px; border-radius: 4px; font-family: Monaco, Consolas, monospace; }
+        .session { color: #666; font-size: 0.85em; }
+    </style>
+</head>
+<body>
+    <h1>LangGraph Stream Parser Demo</h1>
+    <p class="session">Session: <code>{{SESSION_ID}}</code></p>
+
+    <div id="chat"></div>
+
+    <div id="input-area">
+        <input type="text" id="message-input" placeholder="Type a message..." />
+        <button id="send-btn" onclick="sendMessage()">Send</button>
+    </div>
+
+    <script>
+        const sessionId = "{{SESSION_ID}}";
+        const chat = document.getElementById('chat');
+        const input = document.getElementById('message-input');
+        const sendBtn = document.getElementById('send-btn');
+
+        let ws = null;
+        let currentAssistantMessage = null;
+
+        function connect() {
+            ws = new WebSocket(`ws://${window.location.host}/ws/chat/${sessionId}`);
+            ws.onopen = () => addMessage('system', 'Connected.');
+            ws.onmessage = (event) => handleEvent(JSON.parse(event.data));
+            ws.onclose = () => {
+                addMessage('error', 'Disconnected. Refresh to reconnect.');
+                sendBtn.disabled = true;
+            };
+        }
+
+        function handleEvent(data) {
+            switch (data.type) {
+                case 'ack':
+                    if (data.ref === 'message') sendBtn.disabled = true;
+                    break;
+                case 'content':
+                    if (!currentAssistantMessage) {
+                        currentAssistantMessage = addMessage('assistant', '');
+                    }
+                    currentAssistantMessage.textContent += data.content;
+                    break;
+                case 'tool_start':
+                    addMessage('tool-start',
+                        `🔧 Calling <code>${data.name}</code> with: ${JSON.stringify(data.args)}`);
+                    break;
+                case 'tool_end':
+                    const cls = data.status === 'success' ? 'tool-end' : 'tool-error';
+                    const icon = data.status === 'success' ? '✓' : '✗';
+                    addMessage(cls, `${icon} <code>${data.name}</code>: ${data.result}`);
+                    break;
+                case 'complete':
+                    addMessage('complete', '— Response complete —');
+                    sendBtn.disabled = false;
+                    currentAssistantMessage = null;
+                    break;
+                case 'error':
+                    addMessage('error', `Error: ${data.error}`);
+                    sendBtn.disabled = false;
+                    break;
+                case 'interrupt':
+                    showInterrupt(data);
+                    break;
+            }
+            chat.scrollTop = chat.scrollHeight;
+        }
+
+        function showInterrupt(data) {
+            const div = document.createElement('div');
+            div.className = 'message interrupt';
+
+            let actionsHtml = '';
+            for (const action of data.action_requests) {
+                const tool = action.tool || action.action?.tool || 'unknown';
+                const args = action.args || action.action?.args || {};
+                actionsHtml += `<p><strong>Tool:</strong> <code>${tool}</code></p>`;
+                actionsHtml += `<pre>${JSON.stringify(args, null, 2)}</pre>`;
+            }
+
+            const allowed = data.allowed_decisions || ['approve', 'reject'];
+            let buttonsHtml = '<div class="interrupt-buttons">';
+            if (allowed.includes('approve')) {
+                buttonsHtml += `<button class="btn-approve" onclick="sendDecision('approve')">Approve</button>`;
+            }
+            if (allowed.includes('reject')) {
+                buttonsHtml += `<button class="btn-reject" onclick="sendDecision('reject')">Reject</button>`;
+            }
+            buttonsHtml += '</div>';
+
+            div.innerHTML = `<h4>Action Required</h4>${actionsHtml}${buttonsHtml}`;
+            chat.appendChild(div);
+            chat.scrollTop = chat.scrollHeight;
+        }
+
+        function sendDecision(decisionType) {
+            if (!ws) return;
+            document.querySelectorAll('.interrupt-buttons').forEach(el => el.remove());
+            ws.send(JSON.stringify({
+                type: 'decision',
+                decisions: [{ type: decisionType }],
+            }));
+        }
+
+        function addMessage(type, content) {
+            const div = document.createElement('div');
+            div.className = `message ${type}`;
+            div.innerHTML = content;
+            chat.appendChild(div);
+            chat.scrollTop = chat.scrollHeight;
+            return div;
+        }
+
+        function sendMessage() {
+            const message = input.value.trim();
+            if (!message || !ws) return;
+            addMessage('user', message);
+            ws.send(JSON.stringify({ type: 'message', content: message }));
+            input.value = '';
+            sendBtn.disabled = true;
+        }
+
+        input.addEventListener('keypress', (e) => {
+            if (e.key === 'Enter') sendMessage();
+        });
+
+        connect();
+    </script>
+</body>
+</html>
+"""
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.1.6"
+version = "0.1.7"
 description = "Universal parser for LangGraph streaming outputs"
 readme = "README.md"
 license = {text = "MIT"}
@@ -35,6 +35,9 @@ jupyter = [
     "rich>=13.0",
     "ipython>=8.0",
 ]
+fastapi = [
+    "fastapi>=0.100",
+]
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
@@ -42,6 +45,8 @@ dev = [
     "langgraph>=0.2.0",
     "langchain-core>=0.2.0",
     "rich>=13.0",
+    "fastapi>=0.100",
+    "httpx>=0.25",
 ]
 
 [project.urls]

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/src/langgraph_stream_parser/__init__.py

@@ -56,7 +56,7 @@ from .compat import (
     aresume_graph_from_interrupt,
 )
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 
 __all__ = [
     # Main parser

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/src/langgraph_stream_parser/adapters/__init__.py

@@ -3,5 +3,13 @@
 from .base import BaseAdapter, ToolStatus, ToolState
 from .print import PrintAdapter
 from .cli import CLIAdapter
+from .fastapi import FastAPIAdapter
 
-__all__ = ["BaseAdapter", "ToolStatus", "ToolState", "PrintAdapter", "CLIAdapter"]
+__all__ = [
+    "BaseAdapter",
+    "ToolStatus",
+    "ToolState",
+    "PrintAdapter",
+    "CLIAdapter",
+    "FastAPIAdapter",
+]

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/src/langgraph_stream_parser/adapters/base.py

@@ -18,6 +18,7 @@ from ..events import (
     ToolExtractedEvent,
     InterruptEvent,
     StateUpdateEvent,
+    UsageEvent,
     CustomEvent,
     ValuesEvent,
     DebugEvent,
@@ -142,6 +143,12 @@ class BaseAdapter(ABC):
         self._error: ErrorEvent | None = None
         self._complete: bool = False
 
+        # Incremental-render cursor — the render() implementations that
+        # emit chunks as they arrive (PrintAdapter, CLIAdapter) use this
+        # to slice _display_items and only render what's new. Jupyter
+        # re-renders the full list each time, so it ignores this.
+        self._last_rendered_count: int = 0
+
     def reset(self) -> None:
         """Reset state for a new stream."""
         self._display_items.clear()
@@ -151,6 +158,7 @@ class BaseAdapter(ABC):
         self._interrupt = None
         self._error = None
         self._complete = False
+        self._last_rendered_count = 0
 
     def run(
         self,
@@ -325,6 +333,13 @@ class BaseAdapter(ABC):
             case StateUpdateEvent():
                 pass  # Ignored in display
 
+            case UsageEvent():
+                pass  # Ignored in display — subclasses may override
+
+            case _:
+                # Any future event types fall through here.
+                pass
+
     # Helper methods for subclasses
 
     def get_allowed_decisions(self, event: InterruptEvent) -> set[str]:
@@ -364,6 +379,58 @@ class BaseAdapter(ABC):
 
         return decisions
 
+    def _text_prompt_interrupt(
+        self,
+        event: InterruptEvent,
+    ) -> list[dict[str, Any]] | None:
+        """Shared ``input()``-based interrupt prompt.
+
+        Used by PrintAdapter and JupyterDisplay — both prompt the user
+        via ``input()`` for a decision string and, if "edit" is chosen,
+        a JSON args object. CLIAdapter has its own arrow-key variant
+        and does not call this.
+
+        Returns:
+            Decision list for ``create_resume_input(decisions=...)``,
+            or None if the user cancelled.
+        """
+        import json as _json
+
+        allowed = self.get_allowed_decisions(event)
+        options = sorted(allowed)
+        options_str = "/".join(options)
+
+        try:
+            response = input(f"Decision ({options_str}): ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return None
+
+        if not response or response not in allowed:
+            response = "reject" if "reject" in allowed else options[0]
+
+        args_modifier = None
+        if response == "edit":
+            try:
+                new_args_str = input("New args (JSON): ").strip()
+                if new_args_str:
+                    new_args = _json.loads(new_args_str)
+                    args_modifier = lambda _: new_args  # noqa: E731
+            except (EOFError, KeyboardInterrupt, _json.JSONDecodeError):
+                response = "reject"
+
+        return self.build_decisions(event, response, args_modifier)
+
+    def _truncate(self, s: str, limit: int | None = None) -> str:
+        """Truncate a string to ``max_content_preview`` (or ``limit``).
+
+        Used by adapters to cap preview sizes without each one
+        re-implementing the same slice-and-ellipsis logic.
+        """
+        cap = limit if limit is not None else self._max_content_preview
+        if len(s) > cap:
+            return s[:cap] + "..."
+        return s
+
     @staticmethod
     def format_duration(duration_ms: float | None) -> str:
         """Format duration for display."""

{langgraph_stream_parser-0.1.6 → langgraph_stream_parser-0.1.7}/src/langgraph_stream_parser/adapters/cli.py

@@ -128,7 +128,6 @@ class CLIAdapter(BaseAdapter):
         )
         self._use_spinner = use_spinner
         self._use_colors = use_colors
-        self._last_rendered_count = 0
         self._spinner: Spinner | None = None
         self._active_tools: set[str] = set()
 
@@ -139,7 +138,6 @@ class CLIAdapter(BaseAdapter):
     def reset(self) -> None:
         """Reset state for a new stream."""
         super().reset()
-        self._last_rendered_count = 0
         self._stop_spinner()
         self._active_tools.clear()
 
@@ -420,9 +418,7 @@ class CLIAdapter(BaseAdapter):
         """Print extracted content with styled formatting."""
         c = self._c
 
-        data_str = str(event.data)
-        if len(data_str) > self._max_content_preview:
-            data_str = data_str[:self._max_content_preview] + "..."
+        data_str = self._truncate(str(event.data))
 
         # Special handling for todo types
         if event.extracted_type in self._todo_types and isinstance(event.data, list):