agent-event-stream 0.1.0__tar.gz

agent_event_stream-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node / React
+node_modules/
+packages/react/dist/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp

agent_event_stream-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agent-event-stream
+Version: 0.1.0
+Summary: Typed SSE event protocol for AI agents — token, tool_use, thinking, progress, done
+License: MIT
+Keywords: ai-agents,anthropic,fastapi,llm,openai,sse,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'

agent_event_stream-0.1.0/agent_stream/__init__.py

@@ -0,0 +1,5 @@
+from .emitter import AgentStreamEmitter
+from .batcher import TokenBatcher
+
+__all__ = ["AgentStreamEmitter", "TokenBatcher"]
+__version__ = "0.1.0"

agent_event_stream-0.1.0/agent_stream/batcher.py

@@ -0,0 +1,50 @@
+"""TokenBatcher — accumulates text tokens and flushes every `interval_ms` milliseconds.
+
+Prevents excessive SSE emissions (and client re-renders) by batching
+tokens that arrive faster than the flush interval.
+
+Usage::
+
+    batcher = TokenBatcher(interval_ms=50)
+
+    for chunk in llm_stream:
+        if batched := batcher.add(chunk.text):
+            yield emitter.token(batched)
+
+    # Always flush at end of stream
+    if remaining := batcher.flush():
+        yield emitter.token(remaining)
+"""
+from __future__ import annotations
+
+import time
+
+
+class TokenBatcher:
+    """Accumulates text tokens and flushes every `interval_ms` milliseconds."""
+
+    def __init__(self, interval_ms: int = 50) -> None:
+        self._buffer: list[str] = []
+        self._interval = interval_ms / 1000.0
+        self._last_flush = time.monotonic()
+
+    def add(self, text: str) -> str | None:
+        """Add a token. Returns flushed text if interval elapsed, else None."""
+        self._buffer.append(text)
+        if time.monotonic() - self._last_flush >= self._interval:
+            return self.flush()
+        return None
+
+    def flush(self) -> str | None:
+        """Flush buffer and return accumulated text, or None if empty."""
+        if not self._buffer:
+            return None
+        text = "".join(self._buffer)
+        self._buffer.clear()
+        self._last_flush = time.monotonic()
+        return text
+
+    @property
+    def has_content(self) -> bool:
+        """True if there are buffered tokens not yet flushed."""
+        return bool(self._buffer)

agent_event_stream-0.1.0/agent_stream/emitter.py

@@ -0,0 +1,136 @@
+"""AgentStreamEmitter — formats SSE event strings for AI agent streaming.
+
+No external dependencies. Each method returns a ready-to-yield SSE string:
+
+    event: <type>
+    data: <json>
+
+    (blank line terminates the event)
+
+Usage::
+
+    from agent_stream import AgentStreamEmitter
+
+    emitter = AgentStreamEmitter()
+
+    async def generate():
+        yield emitter.token("Hello")
+        yield emitter.tool_use("search", "tu_1", "query=foo")
+        yield emitter.tool_result("search", "tu_1", "3 results", 120)
+        yield emitter.done(message_id="msg_1", num_turns=1, tool_count=1)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _fmt(event_type: str, data: dict[str, Any]) -> str:
+    return f"event: {event_type}\ndata: {json.dumps(data, default=str)}\n\n"
+
+
+class AgentStreamEmitter:
+    """Formats typed SSE events for AI agent streaming."""
+
+    def token(self, text: str) -> str:
+        """Incremental text chunk from the agent."""
+        return _fmt("token", {"text": text})
+
+    def thinking(self, text: str) -> str:
+        """Extended reasoning / chain-of-thought block."""
+        return _fmt("thinking", {"text": text})
+
+    def tool_use(
+        self,
+        tool_name: str,
+        tool_use_id: str,
+        input_summary: str = "",
+    ) -> str:
+        """Tool invocation started."""
+        return _fmt("tool_use", {
+            "tool_name": tool_name,
+            "tool_use_id": tool_use_id,
+            "input_summary": input_summary,
+            "status": "running",
+        })
+
+    def tool_result(
+        self,
+        tool_name: str,
+        tool_use_id: str,
+        output_summary: str = "",
+        duration_ms: int = 0,
+        is_error: bool = False,
+    ) -> str:
+        """Tool execution completed."""
+        return _fmt("tool_result", {
+            "tool_name": tool_name,
+            "tool_use_id": tool_use_id,
+            "output_summary": output_summary,
+            "duration_ms": duration_ms,
+            "status": "error" if is_error else "done",
+        })
+
+    def turn(self, turn_number: int, total_tools: int = 0) -> str:
+        """Agentic turn boundary."""
+        return _fmt("turn", {"turn_number": turn_number, "total_tools": total_tools})
+
+    def progress(
+        self,
+        step: str,
+        percentage: int,
+        message: str,
+        sub_progress: dict[str, Any] | None = None,
+    ) -> str:
+        """Pipeline step progress update."""
+        data: dict[str, Any] = {"step": step, "percentage": percentage, "message": message}
+        if sub_progress is not None:
+            data["sub_progress"] = sub_progress
+        return _fmt("progress", data)
+
+    def creation(
+        self,
+        creation_type: str,
+        count: int,
+        tool_use_id: str = "",
+        items: list[dict[str, Any]] | None = None,
+    ) -> str:
+        """Agent created a persistent artifact."""
+        return _fmt("creation", {
+            "creation_type": creation_type,
+            "count": count,
+            "tool_use_id": tool_use_id,
+            "items": items or [],
+        })
+
+    def error(
+        self,
+        error_type: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> str:
+        """Structured error during execution."""
+        return _fmt("error", {
+            "error_type": error_type,
+            "message": message,
+            "details": details or {},
+        })
+
+    def done(
+        self,
+        message_id: str = "",
+        num_turns: int = 0,
+        tool_count: int = 0,
+        duration_ms: int = 0,
+        model: str = "",
+        total_cost_usd: float = 0.0,
+    ) -> str:
+        """Stream complete — always the last event emitted."""
+        return _fmt("done", {
+            "message_id": message_id,
+            "num_turns": num_turns,
+            "tool_count": tool_count,
+            "duration_ms": duration_ms,
+            "model": model,
+            "total_cost_usd": total_cost_usd,
+        })

agent_event_stream-0.1.0/agent_stream/fastapi.py

@@ -0,0 +1,52 @@
+"""FastAPI integration for agent-stream.
+
+Optional module — only import if FastAPI is installed.
+
+Usage::
+
+    from agent_stream import AgentStreamEmitter, TokenBatcher
+    from agent_stream.fastapi import agent_stream_response
+
+    @app.post("/api/chat")
+    async def chat(req: ChatRequest):
+        async def generate():
+            emitter = AgentStreamEmitter()
+            batcher = TokenBatcher()
+            async for chunk in your_llm_call(req.message):
+                if batched := batcher.add(chunk.text):
+                    yield emitter.token(batched)
+            if remaining := batcher.flush():
+                yield emitter.token(remaining)
+            yield emitter.done()
+
+        return agent_stream_response(generate())
+"""
+from __future__ import annotations
+
+from typing import AsyncGenerator
+
+try:
+    from fastapi.responses import StreamingResponse
+except ImportError as e:
+    raise ImportError(
+        "fastapi is required to use agent_stream.fastapi. "
+        "Install it with: pip install agent-stream[fastapi]"
+    ) from e
+
+
+def agent_stream_response(
+    generator: AsyncGenerator[str, None],
+) -> StreamingResponse:
+    """Wrap an SSE generator in a FastAPI StreamingResponse.
+
+    Sets the correct content type and disables proxy buffering so events
+    reach the client immediately.
+    """
+    return StreamingResponse(
+        generator,
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )

agent_event_stream-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-event-stream"
+version = "0.1.0"
+description = "Typed SSE event protocol for AI agents — token, tool_use, thinking, progress, done"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["llm", "ai-agents", "sse", "streaming", "fastapi", "anthropic", "openai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+dev = ["pytest>=8", "fastapi>=0.100", "httpx>=0.27"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_stream"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agent_event_stream-0.1.0/tests/test_batcher.py

@@ -0,0 +1,53 @@
+import time
+import pytest
+from agent_stream.batcher import TokenBatcher
+
+
+def test_add_below_interval_returns_none():
+    batcher = TokenBatcher(interval_ms=200)
+    result = batcher.add("hello")
+    assert result is None
+
+
+def test_add_above_interval_returns_batched():
+    batcher = TokenBatcher(interval_ms=0)  # 0ms = always flush
+    result = batcher.add("hello")
+    assert result == "hello"
+
+
+def test_flush_returns_accumulated_text():
+    batcher = TokenBatcher(interval_ms=200)
+    batcher.add("foo")
+    batcher.add("bar")
+    result = batcher.flush()
+    assert result == "foobar"
+
+
+def test_flush_empty_returns_none():
+    batcher = TokenBatcher()
+    assert batcher.flush() is None
+
+
+def test_flush_clears_buffer():
+    batcher = TokenBatcher(interval_ms=200)
+    batcher.add("x")
+    batcher.flush()
+    assert batcher.flush() is None
+
+
+def test_has_content_false_when_empty():
+    batcher = TokenBatcher()
+    assert batcher.has_content is False
+
+
+def test_has_content_true_after_add():
+    batcher = TokenBatcher(interval_ms=200)
+    batcher.add("x")
+    assert batcher.has_content is True
+
+
+def test_multiple_adds_batched():
+    batcher = TokenBatcher(interval_ms=200)
+    for ch in ["a", "b", "c"]:
+        batcher.add(ch)
+    assert batcher.flush() == "abc"

agent_event_stream-0.1.0/tests/test_emitter.py

@@ -0,0 +1,113 @@
+import json
+import pytest
+from agent_stream.emitter import AgentStreamEmitter
+
+
+@pytest.fixture
+def emitter():
+    return AgentStreamEmitter()
+
+
+def _parse(sse: str) -> tuple[str, dict]:
+    """Parse 'event: X\ndata: {...}\n\n' into (event_type, data)."""
+    lines = sse.strip().splitlines()
+    event_type = lines[0].removeprefix("event: ")
+    data = json.loads(lines[1].removeprefix("data: "))
+    return event_type, data
+
+
+def test_token(emitter):
+    ev, data = _parse(emitter.token("hello"))
+    assert ev == "token"
+    assert data["text"] == "hello"
+
+
+def test_thinking(emitter):
+    ev, data = _parse(emitter.thinking("step 1: consider X"))
+    assert ev == "thinking"
+    assert data["text"] == "step 1: consider X"
+
+
+def test_tool_use(emitter):
+    ev, data = _parse(emitter.tool_use("search", "tu_123", "query=foo"))
+    assert ev == "tool_use"
+    assert data["tool_name"] == "search"
+    assert data["tool_use_id"] == "tu_123"
+    assert data["input_summary"] == "query=foo"
+    assert data["status"] == "running"
+
+
+def test_tool_result_success(emitter):
+    ev, data = _parse(emitter.tool_result("search", "tu_123", "3 results", 42))
+    assert ev == "tool_result"
+    assert data["status"] == "done"
+    assert data["duration_ms"] == 42
+
+
+def test_tool_result_error(emitter):
+    ev, data = _parse(emitter.tool_result("search", "tu_123", is_error=True))
+    assert ev == "tool_result"
+    assert data["status"] == "error"
+
+
+def test_turn(emitter):
+    ev, data = _parse(emitter.turn(2, total_tools=5))
+    assert ev == "turn"
+    assert data["turn_number"] == 2
+    assert data["total_tools"] == 5
+
+
+def test_progress(emitter):
+    ev, data = _parse(emitter.progress("synthesis", 40, "Extracting insights"))
+    assert ev == "progress"
+    assert data["percentage"] == 40
+
+
+def test_progress_with_sub(emitter):
+    ev, data = _parse(emitter.progress(
+        "synthesis", 50, "Processing",
+        sub_progress={"current": 3, "total": 10, "item_title": "Interview 3"}
+    ))
+    assert data["sub_progress"]["current"] == 3
+
+
+def test_creation(emitter):
+    ev, data = _parse(emitter.creation("insights", 5, tool_use_id="tu_abc"))
+    assert ev == "creation"
+    assert data["count"] == 5
+    assert data["creation_type"] == "insights"
+    assert data["tool_use_id"] == "tu_abc"
+    assert data["items"] == []  # default empty list always emitted
+
+
+def test_creation_defaults(emitter):
+    ev, data = _parse(emitter.creation("document", 1))
+    assert data["tool_use_id"] == ""
+    assert data["items"] == []
+
+
+def test_error(emitter):
+    ev, data = _parse(emitter.error("timeout", "Request timed out"))
+    assert ev == "error"
+    assert data["error_type"] == "timeout"
+    assert data["message"] == "Request timed out"
+    assert data["details"] == {}  # default empty dict always emitted
+
+
+def test_error_with_details(emitter):
+    ev, data = _parse(emitter.error("auth", "Unauthorized", details={"code": 401}))
+    assert data["details"] == {"code": 401}
+
+
+def test_done(emitter):
+    ev, data = _parse(emitter.done(
+        message_id="msg_1", num_turns=3, tool_count=7,
+        duration_ms=4200, model="claude-sonnet-4-6"
+    ))
+    assert ev == "done"
+    assert data["num_turns"] == 3
+    assert data["model"] == "claude-sonnet-4-6"
+
+
+def test_sse_format_ends_with_double_newline(emitter):
+    assert emitter.token("x").endswith("\n\n")

agent_event_stream-0.1.0/tests/test_fastapi.py

@@ -0,0 +1,30 @@
+import pytest
+
+pytest.importorskip("fastapi")  # Skip if FastAPI not installed
+
+from fastapi.responses import StreamingResponse
+from agent_stream.fastapi import agent_stream_response
+
+
+async def mock_generator():
+    yield "event: token\ndata: {\"text\": \"hi\"}\n\n"
+
+
+def test_returns_streaming_response():
+    response = agent_stream_response(mock_generator())
+    assert isinstance(response, StreamingResponse)
+
+
+def test_content_type_is_event_stream():
+    response = agent_stream_response(mock_generator())
+    assert response.media_type == "text/event-stream"
+
+
+def test_no_cache_header():
+    response = agent_stream_response(mock_generator())
+    assert response.headers.get("Cache-Control") == "no-cache"
+
+
+def test_no_buffering_header():
+    response = agent_stream_response(mock_generator())
+    assert response.headers.get("X-Accel-Buffering") == "no"