langgraph-stream-parser 0.2.1__tar.gz → 0.2.2__tar.gz

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -49,6 +49,27 @@ Description-Content-Type: text/markdown
 
 Universal parser for LangGraph streaming outputs. Normalizes complex, variable output shapes from `graph.stream()` and `graph.astream()` into consistent, typed event objects.
 
+## One agent, every surface
+
+`langgraph-stream-parser` is the shared core of the **deep-agent family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every surface with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `deepagents.toml` config file, and the same `DEEPAGENT_*` environment variables.
+
+| Surface | Package | Try it |
+|---|---|---|
+| Web app | [cowork-dash](https://github.com/dkedar7/cowork-dash) | `cowork-dash run --agent my_agent.py:graph` |
+| JupyterLab | [deepagent-lab](https://github.com/dkedar7/deepagent-lab) | `pip install deepagent-lab`, then the chat sidebar in `jupyter lab` |
+| Terminal | [deepagent-code](https://github.com/dkedar7/deepagent-code) | `deepagent-code -a my_agent.py:graph` |
+| VS Code | [deepagent-vscode](https://github.com/dkedar7/deepagent-vscode) | chat participant + stdio sidecar |
+| Reference agent | [deepagent-hermes](https://github.com/dkedar7/deepagent-hermes) | `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` on any surface |
+| Shared core | langgraph-stream-parser | **you are here** |
+
+No agent yet? Every surface has a keyless demo mode backed by this package's stub agent — no API key required:
+
+```bash
+export DEEPAGENT_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph  # or each CLI's --demo flag
+```
+
+And the resolved configuration (each value, its source, and the env var / `deepagents.toml` key that sets it) is printable everywhere: `python -m langgraph_stream_parser.host`, or each CLI's `--show-config`.
+
 ## Installation
 
 ```bash

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.2.2}/README.md

@@ -6,6 +6,27 @@
 
 Universal parser for LangGraph streaming outputs. Normalizes complex, variable output shapes from `graph.stream()` and `graph.astream()` into consistent, typed event objects.
 
+## One agent, every surface
+
+`langgraph-stream-parser` is the shared core of the **deep-agent family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every surface with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `deepagents.toml` config file, and the same `DEEPAGENT_*` environment variables.
+
+| Surface | Package | Try it |
+|---|---|---|
+| Web app | [cowork-dash](https://github.com/dkedar7/cowork-dash) | `cowork-dash run --agent my_agent.py:graph` |
+| JupyterLab | [deepagent-lab](https://github.com/dkedar7/deepagent-lab) | `pip install deepagent-lab`, then the chat sidebar in `jupyter lab` |
+| Terminal | [deepagent-code](https://github.com/dkedar7/deepagent-code) | `deepagent-code -a my_agent.py:graph` |
+| VS Code | [deepagent-vscode](https://github.com/dkedar7/deepagent-vscode) | chat participant + stdio sidecar |
+| Reference agent | [deepagent-hermes](https://github.com/dkedar7/deepagent-hermes) | `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` on any surface |
+| Shared core | langgraph-stream-parser | **you are here** |
+
+No agent yet? Every surface has a keyless demo mode backed by this package's stub agent — no API key required:
+
+```bash
+export DEEPAGENT_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph  # or each CLI's --demo flag
+```
+
+And the resolved configuration (each value, its source, and the env var / `deepagents.toml` key that sets it) is printable everywhere: `python -m langgraph_stream_parser.host`, or each CLI's `--show-config`.
+
 ## Installation
 
 ```bash

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.2.1"
+version = "0.2.2"
 description = "Universal parser for LangGraph streaming outputs"
 readme = "README.md"
 license = {text = "MIT"}

{langgraph_stream_parser-0.2.1 → langgraph_stream_parser-0.2.2}/src/langgraph_stream_parser/demo/__init__.py

@@ -9,7 +9,13 @@ everything.
 Requires the optional ``deepagents`` dependency:
 
     pip install langgraph-stream-parser[demo]
+
+This package also ships the keyless **stub agent** behind every surface's
+``--demo`` mode (:func:`create_stub_agent` / spec
+``langgraph_stream_parser.demo.stub:graph``) — that one needs no extra and no
+API key.
 """
 from .agent import create_default_agent
+from .stub import create_stub_agent
 
-__all__ = ["create_default_agent"]
+__all__ = ["create_default_agent", "create_stub_agent"]

langgraph_stream_parser-0.2.2/src/langgraph_stream_parser/demo/stub.py

@@ -0,0 +1,139 @@
+"""A keyless, deterministic stub agent — the engine behind every ``--demo`` mode.
+
+Every deep-agent surface (cowork-dash, deepagent-code, deepagent-lab,
+deepagent-vscode) offers a demo mode so a new user can see the surface working
+before configuring a real agent or any API key. This module is the single
+shared implementation: a real compiled LangGraph graph with a checkpointer,
+streaming token-by-token through the exact same parser path as a production
+agent — but the "model" is a local echo, so it needs no network and no keys.
+
+Point any surface at it with the standard spec string::
+
+    DEEPAGENT_AGENT_SPEC=langgraph_stream_parser.demo.stub:graph
+
+or build a customized one in code::
+
+    from langgraph_stream_parser.demo import create_stub_agent
+    agent = create_stub_agent(name="My Demo")
+
+``langgraph`` and ``langchain-core`` are imported lazily — importing this
+module stays dependency-free; only building the agent requires them (every
+host surface already depends on both).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_REPLY_PREFIX = "(demo agent) You said: "
+DEFAULT_NAME = "Demo Agent"
+
+_GRAPH_CACHE: Any = None
+
+
+def create_stub_agent(
+    *,
+    name: str = DEFAULT_NAME,
+    reply_prefix: str = DEFAULT_REPLY_PREFIX,
+    checkpointer: Any = None,
+):
+    """Build the echo stub agent.
+
+    Args:
+        name: Display name surfaced in host UIs.
+        reply_prefix: Prepended to the echoed user message in every reply.
+        checkpointer: LangGraph checkpointer. Defaults to an in-memory saver
+            so multi-turn threads work out of the box.
+
+    Returns:
+        A compiled LangGraph graph that replies to each user message with
+        ``reply_prefix + <last human message>``, streamed token-by-token.
+
+    Raises:
+        RuntimeError: If ``langgraph`` / ``langchain-core`` are not installed.
+    """
+    try:
+        from langchain_core.callbacks import CallbackManagerForLLMRun
+        from langchain_core.language_models import BaseChatModel
+        from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage
+        from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
+        from langgraph.checkpoint.memory import MemorySaver
+        from langgraph.graph import END, START, MessagesState, StateGraph
+    except ImportError as e:  # pragma: no cover — exercised only without the deps
+        raise RuntimeError(
+            "The stub agent needs langgraph + langchain-core "
+            "(every deep-agent surface already installs them): "
+            f"{e}"
+        ) from e
+
+    from typing import Iterator, List, Optional
+
+    def _last_human(messages: List[BaseMessage]) -> str:
+        for message in reversed(messages):
+            if getattr(message, "type", None) == "human":
+                content = message.content
+                return content if isinstance(content, str) else str(content)
+        return ""
+
+    class EchoChatModel(BaseChatModel):
+        """A no-API chat model that echoes the user's last message.
+
+        Implements ``_stream`` so that under LangGraph's ``messages`` stream
+        mode the reply is emitted token-by-token, matching how a real chat
+        model behaves through the parser.
+        """
+
+        @property
+        def _llm_type(self) -> str:
+            return "echo-stub"
+
+        def _generate(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> ChatResult:
+            text = reply_prefix + _last_human(messages)
+            return ChatResult(generations=[ChatGeneration(message=AIMessage(content=text))])
+
+        def _stream(
+            self,
+            messages: List[BaseMessage],
+            stop: Optional[List[str]] = None,
+            run_manager: Optional[CallbackManagerForLLMRun] = None,
+            **kwargs: Any,
+        ) -> Iterator[ChatGenerationChunk]:
+            text = reply_prefix + _last_human(messages)
+            tokens = text.split(" ")
+            for i, token in enumerate(tokens):
+                piece = token if i == len(tokens) - 1 else token + " "
+                chunk = ChatGenerationChunk(message=AIMessageChunk(content=piece))
+                if run_manager is not None:
+                    run_manager.on_llm_new_token(piece, chunk=chunk)
+                yield chunk
+
+    model = EchoChatModel()
+
+    def _respond(state: MessagesState) -> dict:
+        return {"messages": [model.invoke(state["messages"])]}
+
+    builder = StateGraph(MessagesState)
+    builder.add_node("respond", _respond)
+    builder.add_edge(START, "respond")
+    builder.add_edge("respond", END)
+
+    graph = builder.compile(checkpointer=checkpointer or MemorySaver())
+    graph.name = name
+    return graph
+
+
+def __getattr__(attr: str) -> Any:
+    # ``graph`` is built lazily on first access so plain imports of this module
+    # never require langgraph — but ``load_agent_spec("...demo.stub:graph")``
+    # gets a ready compiled agent.
+    if attr == "graph":
+        global _GRAPH_CACHE
+        if _GRAPH_CACHE is None:
+            _GRAPH_CACHE = create_stub_agent()
+        return _GRAPH_CACHE
+    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")

langgraph_stream_parser-0.2.2/tests/test_demo_stub.py

@@ -0,0 +1,65 @@
+"""Tests for the keyless stub agent behind every surface's --demo mode.
+
+Unlike the default agent (which needs deepagents + an API key), the stub only
+needs langgraph + langchain-core — both in the dev extras — so these tests
+exercise it end to end through the parser.
+"""
+from langgraph_stream_parser import StreamParser, load_agent_spec, prepare_agent_input
+from langgraph_stream_parser.demo import create_stub_agent
+from langgraph_stream_parser.events import CompleteEvent, ContentEvent
+
+STREAM_MODE = ["updates", "messages"]
+
+
+def _run_turn(graph, message: str, thread_id: str = "t1"):
+    parser = StreamParser(stream_mode=STREAM_MODE)
+    stream = graph.stream(
+        prepare_agent_input(message=message),
+        config={"configurable": {"thread_id": thread_id}},
+        stream_mode=STREAM_MODE,
+    )
+    return list(parser.parse(stream))
+
+
+def _content(events) -> str:
+    return "".join(e.content for e in events if isinstance(e, ContentEvent))
+
+
+def test_streams_echo_through_the_parser():
+    graph = create_stub_agent()
+    events = _run_turn(graph, "hello demo")
+
+    assert "(demo agent) You said: hello demo" in _content(events)
+    assert isinstance(events[-1], CompleteEvent)
+
+
+def test_streams_token_by_token():
+    graph = create_stub_agent()
+    events = _run_turn(graph, "one two three four")
+    content_events = [e for e in events if isinstance(e, ContentEvent)]
+    # The echo splits on spaces — a multi-word message must arrive in pieces.
+    assert len(content_events) > 1
+
+
+def test_multi_turn_thread_persists():
+    graph = create_stub_agent()
+    _run_turn(graph, "first", thread_id="conv")
+    state = graph.get_state({"configurable": {"thread_id": "conv"}})
+    _run_turn(graph, "second", thread_id="conv")
+    state2 = graph.get_state({"configurable": {"thread_id": "conv"}})
+    assert len(state2.values["messages"]) > len(state.values["messages"])
+
+
+def test_custom_name_and_prefix():
+    graph = create_stub_agent(name="My Demo", reply_prefix="echo: ")
+    assert graph.name == "My Demo"
+    events = _run_turn(graph, "hi")
+    assert "echo: hi" in _content(events)
+
+
+def test_loadable_via_standard_spec_string():
+    graph = load_agent_spec("langgraph_stream_parser.demo.stub:graph")
+    events = _run_turn(graph, "spec works", thread_id="spec")
+    assert "spec works" in _content(events)
+    # The module-level graph is cached — same object on a second load.
+    assert load_agent_spec("langgraph_stream_parser.demo.stub:graph") is graph