zespan-autogen 1.2.0__tar.gz

zespan_autogen-1.2.0/.gitignore

@@ -0,0 +1,55 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+
+
+langfuse-main/
+langwatch-main/
+.claude
+.gemini
+
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Wrangler (Cloudflare dev artifacts — not used in VPS deploy)
+.wrangler/
+
+# Build Outputs
+.next/
+.open-next/
+out/
+build
+dist
+
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.DS_Store
+*.pem
+
+.hypothesis
+.kiro
+.vscode
+
+lumiqtrace-landing
+# Production secrets — never commit
+ops/cloudflared/creds.json
+
+# Added by code-review-graph
+.code-review-graph/
+.gitnexus

zespan_autogen-1.2.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: zespan-autogen
+Version: 1.2.0
+Summary: Zespan observability middleware for Microsoft AutoGen
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: agentchat
+Requires-Dist: autogen-agentchat>=0.4; extra == 'agentchat'
+Provides-Extra: dev
+Requires-Dist: autogen-agentchat>=0.4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: legacy
+Requires-Dist: pyautogen>=0.2; extra == 'legacy'
+Description-Content-Type: text/markdown
+
+# zespan-autogen
+
+Observability middleware for [Microsoft AutoGen](https://microsoft.github.io/autogen/) via Zespan.
+
+## Install
+
+```bash
+# For AutoGen v0.4 (autogen-agentchat)
+pip install 'zespan-autogen[agentchat]'
+
+# For AutoGen v0.2 (pyautogen / ag2)
+pip install 'zespan-autogen[legacy]'
+```
+
+## AutoGen v0.4 — `run_with_tracing()`
+
+Replace `await team.run(task=...)` with `await run_with_tracing(team, task, ...)`:
+
+```python
+from zespan_autogen import run_with_tracing
+from autogen_agentchat.teams import RoundRobinGroupChat
+from autogen_agentchat.conditions import MaxMessageTermination
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_agentchat.agents import AssistantAgent
+
+model = OpenAIChatCompletionClient(model="gpt-4o")
+agent = AssistantAgent("assistant", model_client=model)
+team = RoundRobinGroupChat([agent], termination_condition=MaxMessageTermination(5))
+
+trace_id = await run_with_tracing(
+    team=team,
+    task="Analyze the sales data",
+    api_key="zsp_your_key",
+    project_id="your_project_id",
+)
+```
+
+## AutoGen v0.4 — `ZespanModelClient` (per-LLM-call tracing)
+
+```python
+from zespan_autogen import ZespanModelClient
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+base = OpenAIChatCompletionClient(model="gpt-4o")
+model = ZespanModelClient(base, api_key="zsp_your_key", project_id="proj_id")
+agent = AssistantAgent("assistant", model_client=model)
+```
+
+## AutoGen v0.2 — `register_hooks()`
+
+```python
+from autogen import AssistantAgent, UserProxyAgent
+from zespan_autogen import register_hooks
+
+assistant = AssistantAgent("assistant", llm_config={"config_list": [...]})
+user = UserProxyAgent("user", human_input_mode="NEVER")
+
+register_hooks(assistant, user, api_key="zsp_your_key", project_id="proj_id")
+user.initiate_chat(assistant, message="Research quantum computing trends")
+```
+
+## What's captured
+
+- All agent messages (source, content, token counts)
+- Tool call requests and execution results
+- Agent handoffs and delegation
+- Internal reasoning/thought events (thinking models)
+- Memory query events
+- Raw LLM request/response (via `ZespanModelClient`)

zespan_autogen-1.2.0/README.md

@@ -0,0 +1,69 @@
+# zespan-autogen
+
+Observability middleware for [Microsoft AutoGen](https://microsoft.github.io/autogen/) via Zespan.
+
+## Install
+
+```bash
+# For AutoGen v0.4 (autogen-agentchat)
+pip install 'zespan-autogen[agentchat]'
+
+# For AutoGen v0.2 (pyautogen / ag2)
+pip install 'zespan-autogen[legacy]'
+```
+
+## AutoGen v0.4 — `run_with_tracing()`
+
+Replace `await team.run(task=...)` with `await run_with_tracing(team, task, ...)`:
+
+```python
+from zespan_autogen import run_with_tracing
+from autogen_agentchat.teams import RoundRobinGroupChat
+from autogen_agentchat.conditions import MaxMessageTermination
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from autogen_agentchat.agents import AssistantAgent
+
+model = OpenAIChatCompletionClient(model="gpt-4o")
+agent = AssistantAgent("assistant", model_client=model)
+team = RoundRobinGroupChat([agent], termination_condition=MaxMessageTermination(5))
+
+trace_id = await run_with_tracing(
+    team=team,
+    task="Analyze the sales data",
+    api_key="zsp_your_key",
+    project_id="your_project_id",
+)
+```
+
+## AutoGen v0.4 — `ZespanModelClient` (per-LLM-call tracing)
+
+```python
+from zespan_autogen import ZespanModelClient
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+base = OpenAIChatCompletionClient(model="gpt-4o")
+model = ZespanModelClient(base, api_key="zsp_your_key", project_id="proj_id")
+agent = AssistantAgent("assistant", model_client=model)
+```
+
+## AutoGen v0.2 — `register_hooks()`
+
+```python
+from autogen import AssistantAgent, UserProxyAgent
+from zespan_autogen import register_hooks
+
+assistant = AssistantAgent("assistant", llm_config={"config_list": [...]})
+user = UserProxyAgent("user", human_input_mode="NEVER")
+
+register_hooks(assistant, user, api_key="zsp_your_key", project_id="proj_id")
+user.initiate_chat(assistant, message="Research quantum computing trends")
+```
+
+## What's captured
+
+- All agent messages (source, content, token counts)
+- Tool call requests and execution results
+- Agent handoffs and delegation
+- Internal reasoning/thought events (thinking models)
+- Memory query events
+- Raw LLM request/response (via `ZespanModelClient`)

zespan_autogen-1.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zespan-autogen"
+dynamic = ["version"]
+description = "Zespan observability middleware for Microsoft AutoGen"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+agentchat = ["autogen-agentchat>=0.4"]
+legacy = ["pyautogen>=0.2"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "autogen-agentchat>=0.4",
+]
+
+[tool.hatch.version]
+path = "zespan_autogen/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["zespan_autogen"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

zespan_autogen-1.2.0/tests/test_tracer.py

@@ -0,0 +1,76 @@
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+
+def make_stream_events():
+    """Simulate AutoGen v0.4 run_stream() event sequence."""
+    from unittest.mock import MagicMock
+
+    class MockTextMessage:
+        def __init__(self):
+            self.source = "assistant"
+            self.content = "Hello there"
+            self.models_usage = MagicMock(prompt_tokens=10, completion_tokens=5)
+            self.created_at = None
+
+    class MockToolCallReq:
+        def __init__(self):
+            self.source = "assistant"
+            self.content = [MagicMock(name="search", arguments='{"q":"test"}', id="tc1")]
+
+    class MockToolCallExec:
+        def __init__(self):
+            self.source = "assistant"
+            self.content = [MagicMock(call_id="tc1", content="result text")]
+
+    class MockTaskResult:
+        def __init__(self):
+            self.stop_reason = "max_turns"
+            self.messages = [MagicMock(), MagicMock()]
+
+    return [MockToolCallReq(), MockToolCallExec(), MockTextMessage(), MockTaskResult()]
+
+
+async def mock_run_stream(task, **kwargs):
+    for event in make_stream_events():
+        yield event
+
+
+@pytest.mark.asyncio
+async def test_run_with_tracing_captures_events():
+    """run_with_tracing captures all event types and calls send_event."""
+    with patch("zespan_autogen.ingest.send_event") as mock_send:
+        from zespan_autogen.tracer import run_with_tracing
+
+        mock_team = MagicMock()
+        mock_team.run_stream = mock_run_stream
+
+        await run_with_tracing(
+            team=mock_team,
+            task="test task",
+            api_key="zsp_test",
+            project_id="proj_1",
+        )
+
+        calls = [c[0][0] for c in mock_send.call_args_list]
+        assert "tool.call.requested" in calls
+        assert "tool.call.executed" in calls
+        assert "agent.message" in calls
+        assert "conversation.completed" in calls
+
+
+@pytest.mark.asyncio
+async def test_run_with_tracing_returns_trace_id():
+    """run_with_tracing returns a non-empty trace_id."""
+    with patch("zespan_autogen.ingest.send_event"):
+        from zespan_autogen.tracer import run_with_tracing
+
+        mock_team = MagicMock()
+        mock_team.run_stream = mock_run_stream
+
+        trace_id = await run_with_tracing(
+            team=mock_team, task="test", api_key="zsp_test", project_id="proj_1"
+        )
+        assert isinstance(trace_id, str)
+        assert len(trace_id) > 0

zespan_autogen-1.2.0/zespan_autogen/__init__.py

@@ -0,0 +1,17 @@
+"""
+Zespan AutoGen middleware.
+
+For AutoGen v0.4 (autogen-agentchat):
+    from zespan_autogen import run_with_tracing, ZespanModelClient
+
+For AutoGen v0.2 (pyautogen / ag2):
+    from zespan_autogen import register_hooks
+"""
+
+__version__ = "1.2.0"
+
+from .tracer import run_with_tracing
+from .model_client import ZespanModelClient
+from .legacy import register_hooks
+
+__all__ = ["run_with_tracing", "ZespanModelClient", "register_hooks"]

zespan_autogen-1.2.0/zespan_autogen/ingest.py

@@ -0,0 +1,85 @@
+"""HTTP ingest client for Zespan."""
+
+import time
+import threading
+import queue
+from typing import Any
+
+_send_queue: queue.Queue[dict | None] = queue.Queue(maxsize=500)
+_worker_started = False
+_worker_lock = threading.Lock()
+
+_api_key: str = ""
+_project_id: str = ""
+_endpoint: str = "https://api.zespan.com/v1/ingest"
+
+
+def configure(api_key: str, project_id: str, endpoint: str | None = None) -> None:
+    global _api_key, _project_id, _endpoint
+    _api_key = api_key
+    _project_id = project_id
+    if endpoint:
+        _endpoint = endpoint
+    _ensure_worker()
+
+
+def _ensure_worker() -> None:
+    global _worker_started
+    with _worker_lock:
+        if not _worker_started:
+            t = threading.Thread(target=_drain_worker, daemon=True)
+            t.start()
+            _worker_started = True
+
+
+def _drain_worker() -> None:
+    import requests
+
+    batch: list[dict] = []
+    while True:
+        try:
+            item = _send_queue.get(timeout=2.0)
+            if item is None:
+                break
+            batch.append(item)
+            while not _send_queue.empty() and len(batch) < 50:
+                try:
+                    batch.append(_send_queue.get_nowait())
+                except queue.Empty:
+                    break
+            if batch:
+                try:
+                    requests.post(
+                        _endpoint,
+                        headers={"x-api-key": _api_key},
+                        json={"events": batch},
+                        timeout=5,
+                    )
+                except Exception:
+                    pass
+                batch = []
+        except queue.Empty:
+            if batch:
+                try:
+                    import requests as req
+                    req.post(
+                        _endpoint,
+                        headers={"x-api-key": _api_key},
+                        json={"events": batch},
+                        timeout=5,
+                    )
+                except Exception:
+                    pass
+                batch = []
+
+
+def send_event(event_type: str, data: dict[str, Any]) -> None:
+    try:
+        _send_queue.put_nowait({
+            "type": event_type,
+            "project_id": _project_id,
+            "timestamp": time.time(),
+            **data,
+        })
+    except queue.Full:
+        pass

zespan_autogen-1.2.0/zespan_autogen/legacy.py

@@ -0,0 +1,78 @@
+"""
+AutoGen v0.2 (pyautogen / ag2) hook registration.
+
+Adds Zespan message capture hooks to ConversableAgent instances
+without subclassing or modifying agent definitions.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from . import ingest as _ingest
+
+
+def register_hooks(
+    *agents: Any,
+    api_key: str,
+    project_id: str,
+    endpoint: str | None = None,
+) -> str:
+    """
+    Register Zespan observability hooks on one or more AutoGen v0.2 agents.
+
+    Returns a trace_id shared across all registered agents.
+
+    Usage:
+        from autogen import AssistantAgent, UserProxyAgent
+        from zespan_autogen import register_hooks
+
+        assistant = AssistantAgent("assistant", llm_config=...)
+        user = UserProxyAgent("user", human_input_mode="NEVER")
+
+        trace_id = register_hooks(
+            assistant, user,
+            api_key="zsp_your_key",
+            project_id="proj_id",
+        )
+        user.initiate_chat(assistant, message="...")
+    """
+    _ingest.configure(api_key, project_id, endpoint)
+    trace_id = str(uuid.uuid4())
+
+    for agent in agents:
+        _register_agent_hooks(agent, trace_id)
+
+    return trace_id
+
+
+def _register_agent_hooks(agent: Any, trace_id: str) -> None:
+    agent_name = getattr(agent, "name", "unknown")
+
+    def capture_messages(messages: list[dict]) -> list[dict]:
+        for msg in messages:
+            _ingest.send_event("agent.message", {
+                "trace_id": trace_id,
+                "agent_name": agent_name,
+                "role": msg.get("role"),
+                "content": str(msg.get("content", ""))[:2000],
+            })
+        return messages
+
+    def capture_outgoing(sender: Any, message: Any, recipient: Any, silent: bool) -> Any:
+        _ingest.send_event("agent.send", {
+            "trace_id": trace_id,
+            "from": getattr(sender, "name", "unknown"),
+            "to": getattr(recipient, "name", "unknown"),
+            "content": str(message)[:2000] if isinstance(message, str)
+                       else str(message.get("content", ""))[:2000] if isinstance(message, dict)
+                       else str(message)[:2000],
+        })
+        return message
+
+    try:
+        agent.register_hook("process_all_messages_before_reply", capture_messages)
+        agent.register_hook("process_message_before_send", capture_outgoing)
+    except AttributeError:
+        pass  # agent doesn't support hooks (e.g., GroupChatManager subclass)

zespan_autogen-1.2.0/zespan_autogen/model_client.py

@@ -0,0 +1,109 @@
+"""
+ZespanModelClient — wraps OpenAIChatCompletionClient to capture
+raw LLM requests/responses with full token counts and latency.
+
+Use this alongside run_with_tracing() for per-LLM-call observability.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, AsyncGenerator
+
+from . import ingest as _ingest
+
+
+class ZespanModelClient:
+    """
+    Transparent proxy around any AutoGen v0.4 ChatCompletionClient.
+
+    Usage:
+        from autogen_ext.models.openai import OpenAIChatCompletionClient
+        from zespan_autogen import ZespanModelClient
+
+        base = OpenAIChatCompletionClient(model="gpt-4o")
+        model = ZespanModelClient(
+            client=base,
+            api_key="zsp_your_key",
+            project_id="proj_id",
+        )
+        agent = AssistantAgent("assistant", model_client=model)
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        api_key: str,
+        project_id: str,
+        endpoint: str | None = None,
+    ) -> None:
+        self._client = client
+        _ingest.configure(api_key, project_id, endpoint)
+
+    async def create(self, messages: Any, *, tools: Any = [], cancellation_token: Any = None, **kwargs: Any) -> Any:
+        span_id = str(uuid.uuid4())
+        started_at = time.time()
+
+        _ingest.send_event("llm.call.started", {
+            "span_id": span_id,
+            "message_count": len(messages) if hasattr(messages, "__len__") else None,
+        })
+
+        try:
+            result = await self._client.create(
+                messages, tools=tools, cancellation_token=cancellation_token, **kwargs
+            )
+
+            usage = getattr(result, "usage", None)
+            _ingest.send_event("llm.call.completed", {
+                "span_id": span_id,
+                "finish_reason": getattr(result, "finish_reason", None),
+                "prompt_tokens": getattr(usage, "prompt_tokens", None) if usage else None,
+                "completion_tokens": getattr(usage, "completion_tokens", None) if usage else None,
+                "cached": getattr(result, "cached", None),
+                "duration_ms": (time.time() - started_at) * 1000,
+            })
+
+            return result
+
+        except Exception as err:
+            _ingest.send_event("llm.call.failed", {
+                "span_id": span_id,
+                "error": str(err)[:500],
+                "duration_ms": (time.time() - started_at) * 1000,
+            })
+            raise
+
+    async def create_stream(self, messages: Any, *, tools: Any = [], cancellation_token: Any = None, **kwargs: Any) -> AsyncGenerator[Any, None]:
+        span_id = str(uuid.uuid4())
+        started_at = time.time()
+
+        _ingest.send_event("llm.stream.started", {"span_id": span_id})
+
+        try:
+            async for chunk in self._client.create_stream(
+                messages, tools=tools, cancellation_token=cancellation_token, **kwargs
+            ):
+                if isinstance(chunk, str):
+                    _ingest.send_event("llm.stream.chunk", {"span_id": span_id})
+                else:
+                    # Final CreateResult chunk
+                    usage = getattr(chunk, "usage", None)
+                    _ingest.send_event("llm.stream.completed", {
+                        "span_id": span_id,
+                        "prompt_tokens": getattr(usage, "prompt_tokens", None) if usage else None,
+                        "completion_tokens": getattr(usage, "completion_tokens", None) if usage else None,
+                        "duration_ms": (time.time() - started_at) * 1000,
+                    })
+                yield chunk
+        except Exception as err:
+            _ingest.send_event("llm.stream.failed", {
+                "span_id": span_id,
+                "error": str(err)[:500],
+            })
+            raise
+
+    # Delegate all other attributes/methods to the wrapped client
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

zespan_autogen-1.2.0/zespan_autogen/tracer.py

@@ -0,0 +1,126 @@
+"""
+AutoGen v0.4 (autogen-agentchat) observability via run_stream() iteration.
+
+All typed event objects emitted by team.run_stream() are intercepted
+and forwarded to Zespan without modifying agent or team definitions.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from . import ingest as _ingest
+
+
+async def run_with_tracing(
+    team: Any,
+    task: str,
+    api_key: str,
+    project_id: str,
+    endpoint: str | None = None,
+) -> str:
+    """
+    Run an AutoGen team with full observability.
+
+    Wraps team.run_stream(), captures all event types, and returns the trace_id.
+
+    Args:
+        team: Any AutoGen team (RoundRobinGroupChat, SelectorGroupChat, etc.)
+        task: The task string to pass to run_stream()
+        api_key: Zespan API key
+        project_id: Zespan project ID
+        endpoint: Optional custom ingest endpoint
+
+    Returns:
+        trace_id string for this conversation
+    """
+    _ingest.configure(api_key, project_id, endpoint)
+
+    # Import message types lazily — don't require autogen-agentchat at import time
+    try:
+        from autogen_agentchat.messages import (
+            TextMessage,
+            ToolCallRequestEvent,
+            ToolCallExecutionEvent,
+            ModelClientStreamingChunkEvent,
+            ThoughtEvent,
+            MemoryQueryEvent,
+            HandoffMessage,
+        )
+        from autogen_agentchat.base import TaskResult
+        from autogen_core import CancellationToken
+    except ImportError as e:
+        raise ImportError(
+            "autogen-agentchat is required: pip install 'zespan-autogen[agentchat]'"
+        ) from e
+
+    trace_id = str(uuid.uuid4())
+
+    _ingest.send_event("conversation.started", {
+        "trace_id": trace_id,
+        "task": task,
+    })
+
+    async for event in team.run_stream(task=task, cancellation_token=CancellationToken()):
+
+        if isinstance(event, TaskResult):
+            _ingest.send_event("conversation.completed", {
+                "trace_id": trace_id,
+                "stop_reason": getattr(event, "stop_reason", None),
+                "message_count": len(getattr(event, "messages", [])),
+            })
+            break
+
+        elif isinstance(event, TextMessage):
+            usage = getattr(event, "models_usage", None)
+            _ingest.send_event("agent.message", {
+                "trace_id": trace_id,
+                "source": event.source,
+                "content": str(event.content)[:2000],
+                "prompt_tokens": getattr(usage, "prompt_tokens", None) if usage else None,
+                "completion_tokens": getattr(usage, "completion_tokens", None) if usage else None,
+            })
+
+        elif isinstance(event, ToolCallRequestEvent):
+            for fc in getattr(event, "content", []):
+                _ingest.send_event("tool.call.requested", {
+                    "trace_id": trace_id,
+                    "source": event.source,
+                    "tool_name": getattr(fc, "name", None),
+                    "tool_args": getattr(fc, "arguments", None),
+                    "call_id": getattr(fc, "id", None),
+                })
+
+        elif isinstance(event, ToolCallExecutionEvent):
+            for result in getattr(event, "content", []):
+                _ingest.send_event("tool.call.executed", {
+                    "trace_id": trace_id,
+                    "source": event.source,
+                    "call_id": getattr(result, "call_id", None),
+                    "output": str(getattr(result, "content", ""))[:2000],
+                })
+
+        elif isinstance(event, ThoughtEvent):
+            _ingest.send_event("agent.thought", {
+                "trace_id": trace_id,
+                "source": event.source,
+                "thought": str(event.content)[:2000],
+            })
+
+        elif isinstance(event, MemoryQueryEvent):
+            _ingest.send_event("agent.memory_query", {
+                "trace_id": trace_id,
+                "source": event.source,
+                "results_count": len(getattr(event, "content", [])),
+            })
+
+        elif isinstance(event, HandoffMessage):
+            _ingest.send_event("agent.handoff", {
+                "trace_id": trace_id,
+                "source": event.source,
+                "target": getattr(event, "target", None),
+                "content": str(event.content)[:500],
+            })
+
+    return trace_id