langgraph-stream-parser 0.1.0__tar.gz

langgraph_stream_parser-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(source ~/.venvs/langgraph-stream-parser/bin/activate)",
+      "Bash(pytest:*)",
+      "Bash(test:*)",
+      "Bash(uv run python -m pytest:*)",
+      "Bash(~/.venvs/langgraph-stream-parser/bin/python -m pytest:*)",
+      "Bash(uv run pytest:*)"
+    ]
+  }
+}

langgraph_stream_parser-0.1.0/.gitignore

@@ -0,0 +1,208 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.jupyter_ystore.db

langgraph_stream_parser-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.1.0] - 2026-02-01
+
+### Initial Release
+
+- Add `StreamParser` for parsing LangGraph stream outputs into typed events
+- Add typed event classes: `ContentEvent`, `ToolCallStartEvent`, `ToolCallEndEvent`, `ToolExtractedEvent`, `InterruptEvent`, `StateUpdateEvent`, `CompleteEvent`, `ErrorEvent`
+- Add tool lifecycle tracking (start → end)
+- Add extensible extractor system with built-in `ThinkToolExtractor` and `TodoExtractor`
+- Add interrupt handling with `create_resume_input()` and `prepare_agent_input()`
+- Add async support via `aparse()`
+- Add legacy dict-based API for backward compatibility (`stream_graph_updates`, `resume_graph_from_interrupt`)
+
+### Display Adapters
+
+- Add `BaseAdapter` abstract class for building custom display adapters
+- Add `PrintAdapter` for plain text output in any Python environment
+- Add `CLIAdapter` for styled terminal output with ANSI colors and spinner animation
+- Add `JupyterDisplay` for rich notebook display with live updates
+- Add configurable `reflection_types` and `todo_types` for custom tool rendering
+- Add `**stream_kwargs` pass-through to `graph.stream()`

langgraph_stream_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kedar Dabhadkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langgraph_stream_parser-0.1.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: langgraph-stream-parser
+Version: 0.1.0
+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
+Project-URL: Repository, https://github.com/dkedar7/langgraph-stream-parser
+Project-URL: Issues, https://github.com/dkedar7/langgraph-stream-parser/issues
+Author: Kedar Dabhadkar
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,langchain,langgraph,parser,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-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: jupyter
+Requires-Dist: ipython>=8.0; extra == 'jupyter'
+Requires-Dist: rich>=13.0; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
+# langgraph-stream-parser
+
+Universal parser for LangGraph streaming outputs. Normalizes complex, variable output shapes from `graph.stream()` and `graph.astream()` into consistent, typed event objects.
+
+## Installation
+
+```bash
+pip install langgraph-stream-parser
+```
+
+## Quick Start
+
+```python
+from langgraph_stream_parser import StreamParser
+from langgraph_stream_parser.events import ContentEvent, ToolCallStartEvent, InterruptEvent
+
+parser = StreamParser()
+
+for event in parser.parse(graph.stream(input_data, stream_mode="updates")):
+    match event:
+        case ContentEvent(content=text):
+            print(text, end="")
+        case ToolCallStartEvent(name=name):
+            print(f"\nCalling {name}...")
+        case InterruptEvent(action_requests=actions):
+            # Handle human-in-the-loop
+            decision = get_user_decision(actions)
+            # Resume with create_resume_input()
+```
+
+## Features
+
+- **Typed Events**: All stream outputs normalized to dataclass events with full type hints
+- **Tool Lifecycle Tracking**: Automatic tracking of tool calls from start to completion
+- **Interrupt Handling**: Parse and resume from human-in-the-loop interrupts
+- **Extensible Extractors**: Register custom extractors for domain-specific tools
+- **Async Support**: Both sync and async parsing via `parse()` and `aparse()`
+- **Zero Dependencies**: LangGraph/LangChain imported dynamically only when needed
+- **Backward Compatible**: Legacy dict-based API available for gradual migration
+
+## Event Types
+
+| Event | Description |
+|-------|-------------|
+| `ContentEvent` | Text content from AI messages |
+| `ToolCallStartEvent` | Tool call initiated by AI |
+| `ToolCallEndEvent` | Tool call completed with result |
+| `ToolExtractedEvent` | Special content extracted from tool (e.g., reflections, todos) |
+| `InterruptEvent` | Human-in-the-loop interrupt requiring decision |
+| `StateUpdateEvent` | Non-message state updates (opt-in) |
+| `CompleteEvent` | Stream finished successfully |
+| `ErrorEvent` | Error during streaming |
+
+## Usage Examples
+
+### Basic Parsing
+
+```python
+from langgraph_stream_parser import StreamParser
+
+parser = StreamParser()
+
+for event in parser.parse(graph.stream({"messages": [...]}, stream_mode="updates")):
+    print(event)
+```
+
+### Pattern Matching (Python 3.10+)
+
+```python
+from langgraph_stream_parser import StreamParser
+from langgraph_stream_parser.events import *
+
+parser = StreamParser()
+
+for event in parser.parse(stream):
+    match event:
+        case ContentEvent(content=text, node=node):
+            print(f"[{node}] {text}", end="")
+
+        case ToolCallStartEvent(name=name, args=args):
+            print(f"\n⏳ Calling {name}...")
+
+        case ToolCallEndEvent(name=name, status="success"):
+            print(f"✅ {name} completed")
+
+        case ToolCallEndEvent(name=name, status="error", error_message=err):
+            print(f"❌ {name} failed: {err}")
+
+        case InterruptEvent() as interrupt:
+            if interrupt.needs_approval:
+                handle_approval(interrupt.action_requests)
+
+        case CompleteEvent():
+            print("\n✓ Done")
+
+        case ErrorEvent(error=err):
+            print(f"⚠️ Error: {err}")
+```
+
+### Handling Interrupts
+
+```python
+from langgraph_stream_parser import StreamParser, create_resume_input
+from langgraph_stream_parser.events import InterruptEvent
+
+parser = StreamParser()
+config = {"configurable": {"thread_id": "my-thread"}}
+
+for event in parser.parse(graph.stream(input_data, config=config)):
+    if isinstance(event, InterruptEvent):
+        # Show user the pending actions
+        for action in event.action_requests:
+            print(f"Tool: {action['tool']}")
+            print(f"Args: {action['args']}")
+
+        # Get user decision
+        decision = input("Approve? (y/n): ")
+
+        # Resume
+        resume_input = create_resume_input(
+            decisions=[{"type": "approve" if decision == "y" else "reject"}]
+        )
+
+        for resume_event in parser.parse(graph.stream(resume_input, config=config)):
+            handle_event(resume_event)
+        break
+```
+
+### Custom Tool Extractors
+
+```python
+from langgraph_stream_parser import StreamParser, ToolExtractor
+from langgraph_stream_parser.events import ToolExtractedEvent
+
+class CanvasExtractor:
+    tool_name = "add_to_canvas"
+    extracted_type = "canvas_item"
+
+    def extract(self, content):
+        if isinstance(content, dict):
+            return content
+        return {"type": "text", "data": str(content)}
+
+parser = StreamParser()
+parser.register_extractor(CanvasExtractor())
+
+for event in parser.parse(stream):
+    if isinstance(event, ToolExtractedEvent) and event.extracted_type == "canvas_item":
+        add_to_canvas_ui(event.data)
+```
+
+### Async Support
+
+```python
+from langgraph_stream_parser import StreamParser
+
+parser = StreamParser()
+
+async def stream_agent():
+    async for event in parser.aparse(graph.astream(input_data)):
+        handle_event(event)
+```
+
+### Configuration Options
+
+```python
+parser = StreamParser(
+    # Track tool call lifecycle (start -> end)
+    track_tool_lifecycle=True,
+
+    # Skip these tools entirely (no events emitted)
+    skip_tools=["internal_tool"],
+
+    # Include StateUpdateEvent for non-message state keys
+    include_state_updates=False,
+)
+```
+
+## Legacy Dict-Based API
+
+For backward compatibility or simpler use cases:
+
+```python
+from langgraph_stream_parser import stream_graph_updates, resume_graph_from_interrupt
+
+for update in stream_graph_updates(agent, input_data, config=config):
+    if update.get("status") == "interrupt":
+        interrupt = update["interrupt"]
+        # Handle interrupt...
+    elif "chunk" in update:
+        print(update["chunk"], end="")
+    elif "tool_calls" in update:
+        print(f"Calling tools: {update['tool_calls']}")
+    elif update.get("status") == "complete":
+        break
+
+# Resume from interrupt
+for update in resume_graph_from_interrupt(agent, decisions=[{"type": "approve"}], config=config):
+    handle_update(update)
+```
+
+## Display Adapters
+
+Pre-built adapters for rendering stream events in different environments:
+
+### CLIAdapter - Styled Terminal Output
+
+```python
+from langgraph_stream_parser.adapters import CLIAdapter
+
+adapter = CLIAdapter()
+adapter.run(
+    graph=agent,
+    input_data={"messages": [("user", "Hello")]},
+    config={"configurable": {"thread_id": "my-thread"}}
+)
+```
+
+Features:
+- ANSI color formatting
+- Spinner animation during tool execution
+- Interactive arrow-key interrupt handling
+
+### PrintAdapter - Plain Text Output
+
+```python
+from langgraph_stream_parser.adapters import PrintAdapter
+
+adapter = PrintAdapter()
+adapter.run(graph=agent, input_data=input_data, config=config)
+```
+
+Universal output that works in any Python environment without dependencies.
+
+### JupyterDisplay - Rich Notebook Display
+
+```python
+from langgraph_stream_parser.adapters.jupyter import JupyterDisplay
+
+display = JupyterDisplay()
+display.run(graph=agent, input_data=input_data, config=config)
+```
+
+Requires: `pip install langgraph-stream-parser[jupyter]`
+
+### Adapter Options
+
+All adapters support:
+
+```python
+adapter = CLIAdapter(
+    show_tool_args=True,           # Show tool arguments
+    max_content_preview=200,       # Max chars for extracted content
+    reflection_types={"thinking"}, # Custom reflection type names
+    todo_types={"tasks"},          # Custom todo type names
+)
+```
+
+### Custom Adapters
+
+Extend `BaseAdapter` for custom rendering:
+
+```python
+from langgraph_stream_parser.adapters import BaseAdapter
+
+class MyAdapter(BaseAdapter):
+    def render(self):
+        # Implement your rendering logic
+        pass
+
+    def prompt_interrupt(self, event):
+        # Handle interrupt prompts
+        return [{"type": "approve"}]
+```
+
+## Built-in Extractors
+
+The package includes extractors for common LangGraph tools:
+
+- **ThinkToolExtractor**: Extracts reflections from `think_tool`
+- **TodoExtractor**: Extracts todo lists from `write_todos`
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=langgraph_stream_parser
+```
+
+## License
+
+MIT