agent-tracedown 0.3.0__py3-none-any.whl

agent_tracedown/__init__.py

@@ -0,0 +1,32 @@
+"""Tracedown: the flight recorder for AI agents."""
+from . import plugins, redaction
+from .exporters import ConsoleExporter, FanoutExporter, HttpExporter, MemoryExporter, OtlpHttpExporter, to_otlp_json
+from .tracer import (
+    SDK_VERSION as __version__,
+    ManualTrace,
+    ReplayDivergence,
+    ToolError,
+    agent,
+    current_trace_id,
+    declare_tools,
+    decision,
+    fetch_bundle,
+    handoff,
+    init,
+    llm_call,
+    memory_read,
+    memory_write,
+    replay,
+    retrieval,
+    run,
+    tool_call,
+    traced_run,
+    validate_args,
+)
+
+__all__ = [
+    "init", "run", "agent", "llm_call", "tool_call", "retrieval", "memory_read", "memory_write",
+    "decision", "handoff", "declare_tools", "OtlpHttpExporter", "FanoutExporter", "replay", "fetch_bundle", "current_trace_id", "validate_args",
+    "MemoryExporter", "ConsoleExporter", "HttpExporter", "to_otlp_json",
+    "ManualTrace", "ReplayDivergence", "ToolError", "traced_run", "plugins", "__version__",
+]

agent_tracedown/exporters/__init__.py

@@ -0,0 +1,173 @@
+"""Exporters ship finished runs (spans + content blobs) somewhere.
+
+All exporters are stdlib-only so the SDK adds no dependencies to an agent.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+
+class Exporter:
+    def export(self, spans: List[Dict[str, Any]], blobs: Dict[str, str]) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+
+class MemoryExporter(Exporter):
+    """Keeps runs in memory. Used by tests and by replay."""
+
+    def __init__(self) -> None:
+        self.spans: List[Dict[str, Any]] = []
+        self.blobs: Dict[str, str] = {}
+
+    def export(self, spans, blobs):
+        self.spans.extend(spans)
+        self.blobs.update(blobs)
+
+    def trace(self, trace_id: str) -> List[Dict[str, Any]]:
+        return [s for s in self.spans if s["trace_id"] == trace_id]
+
+    def clear(self) -> None:
+        self.spans.clear()
+        self.blobs.clear()
+
+
+class ConsoleExporter(Exporter):
+    """Prints a compact tree of each run to stderr."""
+
+    def __init__(self, stream=None) -> None:
+        self.stream = stream or sys.stderr
+
+    def export(self, spans, blobs):
+        children: Dict[Optional[str], list] = {}
+        for s in spans:
+            children.setdefault(s["parent_span_id"], []).append(s)
+
+        def walk(parent, depth):
+            for s in sorted(children.get(parent, []), key=lambda x: x["start_time"]):
+                ms = ((s["end_time"] or s["start_time"]) - s["start_time"]) / 1e6
+                mark = "x" if s["status"]["code"] == "ERROR" else "-"
+                step = s["attributes"].get("tdn.step", "")
+                print(f"{'  ' * depth}{mark} [{step}] {s['kind']:<9} {s['name']}  {ms:.1f}ms", file=self.stream)
+                walk(s["span_id"], depth + 1)
+
+        walk(None, 0)
+
+
+class HttpExporter(Exporter):
+    """Posts spans and blobs to an TDN server's ingest API."""
+
+    def __init__(self, endpoint: str, api_key: Optional[str] = None, project: str = "default", timeout: float = 5.0):
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+        self.project = project
+        self.timeout = timeout
+        self.last_error: Optional[str] = None
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> None:
+        req = urllib.request.Request(
+            self.endpoint + path,
+            data=json.dumps(payload, default=str).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        if self.api_key:
+            req.add_header("Authorization", f"Bearer {self.api_key}")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            resp.read()
+
+    def export(self, spans, blobs):
+        # Telemetry must never crash the agent: failures are recorded, not raised.
+        try:
+            if blobs:
+                self._post("/v1/ingest/blobs", {"project": self.project, "blobs": blobs})
+            self._post("/v1/ingest/spans", {"project": self.project, "spans": spans})
+            self.last_error = None
+        except (urllib.error.URLError, OSError) as exc:
+            self.last_error = str(exc)
+            print(f"[agent-tracedown] export failed: {exc}", file=sys.stderr)
+
+
+class OtlpHttpExporter(Exporter):
+    """Send runs straight to any OTLP/HTTP endpoint: an OpenTelemetry Collector, Jaeger
+    (``:4318``), Grafana Tempo or Alloy, or the Datadog Agent's OTLP intake.
+
+        tdn.init(exporter=tdn.OtlpHttpExporter("http://localhost:4318/v1/traces"))
+
+    Payload content is not sent (spans carry digests); pair with ``HttpExporter`` via
+    ``FanoutExporter`` to keep replay and RCA in Tracedown.
+    """
+
+    def __init__(self, endpoint: str = "http://localhost:4318/v1/traces", headers: Optional[Dict[str, str]] = None,
+                 service_name: str = "agent", timeout: float = 5.0) -> None:
+        self.endpoint, self.headers, self.service_name, self.timeout = endpoint, headers or {}, service_name, timeout
+        self.last_error: Optional[str] = None
+
+    def export(self, spans, blobs):
+        req = urllib.request.Request(self.endpoint, method="POST",
+                                     data=json.dumps(to_otlp_json(spans, self.service_name)).encode(),
+                                     headers={"Content-Type": "application/json", **self.headers})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                r.read()
+            self.last_error = None
+        except (urllib.error.URLError, OSError) as exc:
+            self.last_error = str(exc)
+            print(f"[agent-tracedown] OTLP export failed: {exc}", file=sys.stderr)
+
+
+class FanoutExporter(Exporter):
+    """Send every run to several exporters (e.g. TDN server + OTLP collector)."""
+
+    def __init__(self, *exporters: Exporter) -> None:
+        self.exporters = exporters
+
+    def export(self, spans, blobs):
+        for e in self.exporters:
+            e.export(spans, blobs)
+
+
+def to_otlp_json(spans: List[Dict[str, Any]], service_name: str = "agent") -> Dict[str, Any]:
+    """Convert TDN spans to an OTLP/JSON ExportTraceServiceRequest body.
+
+    Lets TDN data go to Jaeger, Tempo, Datadog or any OTLP endpoint unchanged.
+    """
+
+    def attr(k, v):
+        if isinstance(v, bool):
+            val = {"boolValue": v}
+        elif isinstance(v, int):
+            val = {"intValue": str(v)}
+        elif isinstance(v, float):
+            val = {"doubleValue": v}
+        else:
+            val = {"stringValue": v if isinstance(v, str) else json.dumps(v, default=str)}
+        return {"key": k, "value": val}
+
+    status_map = {"UNSET": 0, "OK": 1, "ERROR": 2}
+    otlp_spans = []
+    for s in spans:
+        attrs = dict(s["attributes"])
+        attrs["tdn.kind"] = s["kind"]
+        if s.get("input_digest"):
+            attrs["tdn.input.digest"] = s["input_digest"]
+        if s.get("output_digest"):
+            attrs["tdn.output.digest"] = s["output_digest"]
+        otlp_spans.append({
+            "traceId": s["trace_id"],
+            "spanId": s["span_id"],
+            "parentSpanId": s["parent_span_id"] or "",
+            "name": s["name"],
+            "kind": 1 if s["kind"] in ("agent", "decision", "memory") else 3,  # INTERNAL / CLIENT
+            "startTimeUnixNano": str(s["start_time"]),
+            "endTimeUnixNano": str(s["end_time"] or s["start_time"]),
+            "attributes": [attr(k, v) for k, v in attrs.items()],
+            "status": {"code": status_map[s["status"]["code"]], "message": s["status"]["message"]},
+        })
+    return {"resourceSpans": [{
+        "resource": {"attributes": [attr("service.name", service_name)]},
+        "scopeSpans": [{"scope": {"name": "agent-tracedown", "version": "0.3.0"}, "spans": otlp_spans}],
+    }]}

agent_tracedown/integrations/__init__.py

@@ -0,0 +1,66 @@
+"""Agent framework integrations.
+
+Each adapter turns a framework's own callbacks or events into TDN spans, so a run in
+that framework shows up with its agents, LLM calls, tools, retrievals and handoffs.
+
+| Framework         | How to enable                                                        |
+|-------------------|----------------------------------------------------------------------|
+| LangChain/LangGraph | ``graph.invoke(x, config={"callbacks": [langchain.callback()]})``  |
+| OpenAI Agents SDK | ``openai_agents.instrument()`` (adds a tracing processor)            |
+| Claude Agent SDK  | ``async for m in claude_agent.trace_stream(query(...), name=...)``   |
+| Google ADK        | ``App(..., plugins=[google_adk.TracedownPlugin()])``                 |
+| Pydantic AI       | ``await pydantic_ai.run(agent, prompt)`` (or ``run_sync``)           |
+| MCP clients       | ``mcp.instrument(client)`` or ``mcp.instrument_all()``               |
+| CrewAI            | ``crewai.instrument()`` (registers an event listener)                |
+| AutoGen AgentChat | ``async for m in autogen.trace_stream(team.run_stream(task=t), ...)``|
+| Semantic Kernel   | ``semantic_kernel.instrument(kernel)`` inside ``tdn.run(...)``       |
+| LlamaIndex        | ``llamaindex.instrument()`` (span + event handlers)                  |
+
+Adapters import their framework lazily: installing ``agent-tracedown`` never pulls in
+a framework. Replay of adapter-traced runs works for steps that go through an
+instrumented model client (``tdn.plugins.instrument("openai", client)``); framework
+callbacks can observe but not substitute outputs.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def to_jsonable(value: Any, depth: int = 0) -> Any:
+    """Best-effort conversion of framework objects (pydantic models, dataclasses,
+    messages) into JSON-safe values for payload capture."""
+    if depth > 6:
+        return str(value)
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {str(k): to_jsonable(v, depth + 1) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [to_jsonable(v, depth + 1) for v in value]
+    for attr in ("model_dump", "dict", "to_dict"):
+        fn = getattr(value, attr, None)
+        if callable(fn):
+            try:
+                return to_jsonable(fn(), depth + 1)
+            except Exception:  # noqa: BLE001
+                pass
+    if hasattr(value, "__dataclass_fields__"):
+        return {k: to_jsonable(getattr(value, k, None), depth + 1) for k in value.__dataclass_fields__}
+    content = getattr(value, "content", None)
+    if isinstance(content, str):
+        return content
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return str(value)
+
+
+def maybe_json(text: Any) -> Any:
+    if isinstance(text, str) and text[:1] in "{[":
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+    return text

agent_tracedown/integrations/autogen.py

@@ -0,0 +1,116 @@
+"""AutoGen AgentChat (0.4+).
+
+    from agent_tracedown.integrations import autogen as tdn_ag
+    async for msg in tdn_ag.trace_stream(team.run_stream(task=task), name="SupportTeam", task=task):
+        ...                                  # messages pass through unchanged
+
+or, after the fact: ``tdn_ag.trace_result(task_result, name="SupportTeam", task=task)``.
+
+Each change of speaker opens an agent span; model turns become LLM spans (with token
+usage), ``ToolCallRequestEvent`` / ``ToolCallExecutionEvent`` pairs become tool spans
+matched by call id, and ``HandoffMessage`` becomes a handoff. AutoGen Core also emits
+OpenTelemetry spans; point its tracer provider at ``/v1/traces`` to keep those too.
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Iterable, Optional
+
+from ..tracer import ManualTrace
+from . import maybe_json, to_jsonable
+
+
+class _Builder:
+    def __init__(self, name: str, task: Any = None) -> None:
+        self.t = ManualTrace(name, input=to_jsonable(task) if task is not None else None)
+        self.agent_key: Optional[str] = None
+        self.agent: Optional[str] = None
+        self.n = 0
+        self.final: Any = None
+        self.error: Optional[str] = None
+
+    def _speaker(self, source: str) -> Optional[str]:
+        if source == "user":
+            return None
+        if source != self.agent:
+            if self.agent_key:
+                self.t.end(self.agent_key)
+            self.n += 1
+            self.agent_key = f"agent:{self.n}"
+            self.t.start(self.agent_key, f"invoke_agent {source}", "agent", attrs={"gen_ai.agent.name": source})
+            self.agent = source
+        return self.agent_key
+
+    def _llm(self, parent: Optional[str], msg: Any, output: Any) -> None:
+        usage = getattr(msg, "models_usage", None)
+        if usage is None:
+            return  # no model call behind this message (e.g. a tool summary)
+        self.n += 1
+        key = f"llm:{self.n}"
+        self.t.start(key, "chat", "llm", parent=parent)
+        self.t.end(key, output={"text": to_jsonable(output)},
+                   **{"gen_ai.usage.input_tokens": getattr(usage, "prompt_tokens", None),
+                      "gen_ai.usage.output_tokens": getattr(usage, "completion_tokens", None)})
+
+    def feed(self, msg: Any) -> None:
+        kind = type(msg).__name__
+        if kind == "TaskResult":
+            if getattr(msg, "stop_reason", None):
+                self.t.root.set("tdn.autogen.stop_reason", msg.stop_reason)
+            return
+        source = getattr(msg, "source", "agent")
+        parent = self._speaker(source)
+        content = getattr(msg, "content", None)
+        if kind == "ToolCallRequestEvent":
+            self._llm(parent, msg, [{"name": c.name, "arguments": maybe_json(c.arguments)} for c in content])
+            for call in content:
+                self.t.start(f"tool:{call.id}", f"execute_tool {call.name}", "tool", parent=parent,
+                             input=maybe_json(call.arguments), attrs={"gen_ai.tool.name": call.name})
+        elif kind == "ToolCallExecutionEvent":
+            for res in content:
+                self.t.end(f"tool:{res.call_id}", output=None if res.is_error else maybe_json(res.content),
+                           error=str(res.content)[:500] if res.is_error else None)
+        elif kind == "HandoffMessage":
+            self.n += 1
+            key = f"handoff:{self.n}"
+            self.t.start(key, f"handoff {source} -> {msg.target}", "handoff", parent=parent,
+                         input=to_jsonable(content), attrs={"tdn.handoff.from": source, "tdn.handoff.to": msg.target})
+            self.t.end(key)
+        elif kind in ("TextMessage", "StructuredMessage", "ToolCallSummaryMessage", "ThoughtEvent"):
+            if source == "user":
+                if self.t.root.input_digest is None:
+                    from ..tracer import _put_blob
+                    self.t.root.input_digest = _put_blob(self.t.state, to_jsonable(content))
+                return
+            if kind != "ToolCallSummaryMessage":
+                self._llm(parent, msg, content)
+            if kind != "ThoughtEvent":
+                self.final = to_jsonable(content)
+
+    def finish(self) -> str:
+        if self.agent_key:
+            self.t.end(self.agent_key)
+        return self.t.finish(output=self.final, error=self.error)
+
+
+async def trace_stream(stream: AsyncIterator[Any], name: str = "AutoGenTeam", task: Any = None) -> AsyncIterator[Any]:
+    b = _Builder(name, task)
+    try:
+        async for msg in stream:
+            b.feed(msg)
+            yield msg
+    except Exception as exc:
+        b.error = f"{type(exc).__name__}: {exc}"
+        raise
+    finally:
+        b.finish()
+
+
+def trace_result(result: Any, name: str = "AutoGenTeam", task: Any = None) -> str:
+    """Record a finished ``TaskResult`` (or any iterable of messages). Returns the trace id."""
+    b = _Builder(name, task)
+    messages: Iterable[Any] = getattr(result, "messages", result)
+    for m in messages:
+        b.feed(m)
+    if type(result).__name__ == "TaskResult":
+        b.feed(result)
+    return b.finish()

agent_tracedown/integrations/claude_agent.py

@@ -0,0 +1,166 @@
+"""Claude Agent SDK (``claude-agent-sdk``).
+
+    from claude_agent_sdk import query, ClaudeAgentOptions
+    from agent_tracedown.integrations import claude_agent as tdn_claude
+
+    async for msg in tdn_claude.trace_stream(query(prompt=p, options=opts), name="CodingAgent", prompt=p):
+        ...                                  # messages pass through unchanged
+
+Works the same with ``ClaudeSDKClient.receive_response()``. After the fact:
+``tdn_claude.trace_messages(messages, name=..., prompt=...)``.
+
+Each ``AssistantMessage`` becomes an LLM span (model, token usage); each
+``ToolUseBlock`` opens a tool span that the matching ``ToolResultBlock`` closes, with
+``is_error`` results marked as failures. Subagents started through the ``Task`` /
+``Agent`` tool become agent spans, and messages carrying their ``parent_tool_use_id``
+nest under them. The ``ResultMessage`` sets the outcome, the final answer and the cost
+(``tdn.run.cost_usd``); the init ``SystemMessage`` declares the available tools.
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Iterable, Optional
+
+from ..tracer import ManualTrace, _put_blob
+from . import maybe_json, to_jsonable
+
+SUBAGENT_TOOLS = ("Task", "Agent")
+
+
+def _usage(u: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    if not isinstance(u, dict):
+        return {}
+    inp = u.get("input_tokens")
+    if inp is not None:  # cached prompt tokens are input tokens too
+        inp += (u.get("cache_read_input_tokens") or 0) + (u.get("cache_creation_input_tokens") or 0)
+    return {"gen_ai.usage.input_tokens": inp, "gen_ai.usage.output_tokens": u.get("output_tokens")}
+
+
+def _result_payload(content: Any) -> Any:
+    if isinstance(content, list):  # [{"type": "text", "text": ...}, ...]
+        texts = [c.get("text") for c in content if isinstance(c, dict) and c.get("type") == "text"]
+        if texts and len(texts) == len(content):
+            return maybe_json("\n".join(texts))
+        return to_jsonable(content)
+    return maybe_json(content)
+
+
+class _Builder:
+    def __init__(self, name: str, prompt: Any = None) -> None:
+        self.t = ManualTrace(name, input=prompt if isinstance(prompt, (str, dict, list)) else None)
+        self.n = 0
+        self.final: Any = None
+        self.error: Optional[str] = None
+        self.subagents: Dict[str, str] = {}  # tool_use_id -> agent span key
+
+    def _parent(self, msg: Any) -> Optional[str]:
+        pid = getattr(msg, "parent_tool_use_id", None)
+        return self.subagents.get(pid) if pid else None
+
+    def feed(self, msg: Any) -> None:
+        kind = type(msg).__name__
+        if kind == "SystemMessage":
+            data = getattr(msg, "data", None) or {}
+            if getattr(msg, "subtype", None) == "init":
+                if data.get("tools"):
+                    self.t.declare_tools([{"name": n} for n in data["tools"] if isinstance(n, str)])
+                if data.get("model"):
+                    self.t.root.set("gen_ai.request.model", data["model"])
+                if data.get("session_id"):
+                    self.t.root.set("tdn.claude.session_id", data["session_id"])
+        elif kind == "UserMessage":
+            content = msg.content
+            if isinstance(content, str):
+                if self.t.root.input_digest is None and not getattr(msg, "parent_tool_use_id", None):
+                    self.t.root.input_digest = _put_blob(self.t.state, content)
+                return
+            for block in content:
+                if type(block).__name__ != "ToolResultBlock":
+                    continue
+                key = f"tool:{block.tool_use_id}"
+                agent_key = self.subagents.get(block.tool_use_id)
+                err = str(block.content)[:500] if block.is_error else None
+                out = None if block.is_error else _result_payload(block.content)
+                if agent_key:
+                    self.t.end(agent_key, output=out, error=err)
+                else:
+                    self.t.end(key, output=out, error=err)
+        elif kind == "AssistantMessage":
+            parent = self._parent(msg)
+            self.n += 1
+            llm = f"llm:{self.n}"
+            texts, calls = [], []
+            for block in msg.content:
+                b = type(block).__name__
+                if b == "TextBlock":
+                    texts.append(block.text)
+                elif b in ("ToolUseBlock", "ServerToolUseBlock"):
+                    calls.append({"name": block.name, "arguments": to_jsonable(block.input)})
+            self.t.start(llm, f"chat {msg.model}", "llm", parent=parent,
+                         attrs={"gen_ai.request.model": msg.model, "gen_ai.provider.name": "anthropic",
+                                "gen_ai.response.finish_reasons": [msg.stop_reason] if getattr(msg, "stop_reason", None) else None})
+            output: Dict[str, Any] = {"text": "\n".join(texts)}
+            if calls:
+                output["tool_calls"] = calls
+            api_error = getattr(msg, "error", None)
+            self.t.end(llm, output=output, error=f"API error: {api_error}" if api_error else None,
+                       **_usage(getattr(msg, "usage", None)))
+            for block in msg.content:
+                b = type(block).__name__
+                if b == "ToolUseBlock" and block.name in SUBAGENT_TOOLS:
+                    inp = block.input or {}
+                    agent = inp.get("subagent_type") or inp.get("description") or "subagent"
+                    key = f"agent:{block.id}"
+                    self.t.start(key, f"invoke_agent {agent}", "agent", parent=parent, input=to_jsonable(inp),
+                                 attrs={"gen_ai.agent.name": agent, "tdn.agent.role": inp.get("description")})
+                    self.subagents[block.id] = key
+                elif b in ("ToolUseBlock", "ServerToolUseBlock"):
+                    self.t.start(f"tool:{block.id}", f"execute_tool {block.name}", "tool", parent=parent,
+                                 input=to_jsonable(block.input),
+                                 attrs={"gen_ai.tool.name": block.name, "gen_ai.tool.call.id": block.id,
+                                        "tdn.tool.server_side": True if b == "ServerToolUseBlock" else None})
+                elif b == "ServerToolResultBlock":
+                    self.t.end(f"tool:{block.tool_use_id}", output=to_jsonable(block.content))
+            if texts and not parent:
+                self.final = "\n".join(texts)
+        elif kind == "ResultMessage":
+            root = self.t.root
+            if msg.total_cost_usd is not None:
+                root.set("tdn.run.cost_usd", float(msg.total_cost_usd))
+                root.set("tdn.llm.cost_usd", float(msg.total_cost_usd))
+            root.set("tdn.claude.num_turns", msg.num_turns)
+            root.set("tdn.claude.stop_reason", getattr(msg, "terminal_reason", None) or msg.subtype)
+            root.set("tdn.claude.session_id", msg.session_id)
+            u = _usage(getattr(msg, "usage", None))
+            for k, v in u.items():
+                if v is not None:
+                    root.set(k, v)
+            if msg.result is not None:
+                self.final = msg.result
+            if msg.is_error:
+                detail = "; ".join(getattr(msg, "errors", None) or []) or msg.result or msg.subtype
+                self.error = f"{msg.subtype}: {detail}"[:500]
+
+    def finish(self) -> str:
+        return self.t.finish(output=self.final, error=self.error)
+
+
+async def trace_stream(stream: AsyncIterator[Any], name: str = "ClaudeAgent", prompt: Any = None) -> AsyncIterator[Any]:
+    """Wrap ``query(...)`` or ``client.receive_response()``; yields every message unchanged."""
+    b = _Builder(name, prompt)
+    try:
+        async for msg in stream:
+            b.feed(msg)
+            yield msg
+    except Exception as exc:
+        b.error = f"{type(exc).__name__}: {exc}"
+        raise
+    finally:
+        b.finish()
+
+
+def trace_messages(messages: Iterable[Any], name: str = "ClaudeAgent", prompt: Any = None) -> str:
+    """Record messages already collected from a run. Returns the trace id."""
+    b = _Builder(name, prompt)
+    for m in messages:
+        b.feed(m)
+    return b.finish()