handoffmap 0.2.0__py3-none-any.whl

handoffmap/otlp.py

@@ -0,0 +1,166 @@
+"""Read OTLP JSON / JSONL trace exports into :class:`~handoffmap.model.Trace` objects.
+
+Two id encodings exist in the wild:
+
+* protobuf-JSON (what ``MessageToDict`` writes): ids are base64 strings, span
+  kinds are names such as ``SPAN_KIND_CLIENT``;
+* the OTLP/JSON spec (Collector ``file`` exporter, JS SDK): ids are hex, kinds
+  are integers.
+
+Both are accepted and normalized to lowercase hex ids and integer kinds.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from .errors import NotOtlpError
+from .model import Span, Trace
+
+_HEX_ID = re.compile(r"^(?:[0-9a-fA-F]{16}|[0-9a-fA-F]{32})$")
+_KINDS = {
+    "SPAN_KIND_UNSPECIFIED": 0,
+    "SPAN_KIND_INTERNAL": 1,
+    "SPAN_KIND_SERVER": 2,
+    "SPAN_KIND_CLIENT": 3,
+    "SPAN_KIND_PRODUCER": 4,
+    "SPAN_KIND_CONSUMER": 5,
+}
+
+
+def normalize_id(raw: Any) -> str | None:
+    """Return a lowercase hex id, or None for a missing/all-zero id."""
+    if raw is None or raw == "":
+        return None
+    if not isinstance(raw, str):
+        raise NotOtlpError("err.id_type", type=type(raw).__name__)
+    if _HEX_ID.match(raw):
+        hex_id = raw.lower()
+    else:
+        try:
+            hex_id = base64.b64decode(raw, validate=True).hex()
+        except (binascii.Error, ValueError) as exc:
+            raise NotOtlpError("err.id_encoding", raw=raw) from exc
+    if set(hex_id) == {"0"}:
+        return None
+    return hex_id
+
+
+def _decode_value(value: Any) -> Any:
+    """Decode an OTLP AnyValue (``{"stringValue": ...}`` and friends) to a Python value."""
+    if not isinstance(value, dict):
+        return value
+    if "stringValue" in value:
+        return value["stringValue"]
+    if "intValue" in value:
+        try:
+            return int(value["intValue"])  # int64 is a JSON string in protobuf-JSON
+        except (TypeError, ValueError):
+            return value["intValue"]
+    if "doubleValue" in value:
+        return value["doubleValue"]
+    if "boolValue" in value:
+        return value["boolValue"]
+    if "arrayValue" in value:
+        return [_decode_value(v) for v in value["arrayValue"].get("values", [])]
+    if "kvlistValue" in value:
+        return _decode_attrs(value["kvlistValue"].get("values", []))
+    if "bytesValue" in value:
+        return value["bytesValue"]
+    return None
+
+
+def _decode_attrs(items: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for item in items or []:
+        if isinstance(item, dict) and "key" in item:
+            out[item["key"]] = _decode_value(item.get("value"))
+    return out
+
+
+def _kind(raw: Any) -> int:
+    if isinstance(raw, int):
+        return raw
+    if isinstance(raw, str):
+        if raw in _KINDS:
+            return _KINDS[raw]
+        if raw.isdigit():
+            return int(raw)
+    return 0
+
+
+def _int(raw: Any) -> int:
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _spans_of_request(request: Any) -> list[Span]:
+    if not isinstance(request, dict) or not isinstance(request.get("resourceSpans"), list):
+        raise NotOtlpError("err.no_resource_spans")
+    spans: list[Span] = []
+    for resource_spans in request["resourceSpans"]:
+        # older exporters use instrumentationLibrarySpans instead of scopeSpans
+        scope_list = resource_spans.get("scopeSpans") or resource_spans.get("instrumentationLibrarySpans") or []
+        for scope_spans in scope_list:
+            scope = scope_spans.get("scope") or scope_spans.get("instrumentationLibrary") or {}
+            for raw in scope_spans.get("spans", []):
+                trace_id = normalize_id(raw.get("traceId"))
+                span_id = normalize_id(raw.get("spanId"))
+                if trace_id is None or span_id is None:
+                    raise NotOtlpError("err.span_no_ids")
+                spans.append(
+                    Span(
+                        trace_id=trace_id,
+                        span_id=span_id,
+                        parent_id=normalize_id(raw.get("parentSpanId")),
+                        name=str(raw.get("name", "")),
+                        kind=_kind(raw.get("kind")),
+                        start_ns=_int(raw.get("startTimeUnixNano")),
+                        end_ns=_int(raw.get("endTimeUnixNano")),
+                        attributes=_decode_attrs(raw.get("attributes")),
+                        scope=str(scope.get("name", "")),
+                    )
+                )
+    return spans
+
+
+def parse(text: str) -> list[Trace]:
+    """Parse OTLP JSON (one request) or JSONL (one request per line) text."""
+    requests: list[Any]
+    try:
+        requests = [json.loads(text)]
+    except json.JSONDecodeError as whole_error:
+        lines = [ln for ln in text.splitlines() if ln.strip()]
+        try:
+            requests = [json.loads(ln) for ln in lines]
+        except json.JSONDecodeError:
+            raise NotOtlpError("err.invalid_json", msg=whole_error.msg, line=whole_error.lineno) from None
+        if not requests:
+            raise NotOtlpError("err.empty") from None
+
+    traces: dict[str, Trace] = {}
+    for request in requests:
+        for span in _spans_of_request(request):
+            traces.setdefault(span.trace_id, Trace(span.trace_id)).spans.append(span)
+    if not traces:
+        raise NotOtlpError("err.no_spans")
+    return list(traces.values())
+
+
+def load(path: str | Path) -> list[Trace]:
+    """Read an OTLP JSON or JSONL file and return one :class:`Trace` per trace id."""
+    p = Path(path)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise NotOtlpError("err.file_not_found", path=p) from None
+    except (OSError, UnicodeDecodeError) as exc:
+        raise NotOtlpError("err.cannot_read", path=p, error=exc) from None
+    return parse(text)

handoffmap/render/__init__.py

@@ -0,0 +1 @@
+"""Renderers: Mermaid sequence diagram, Markdown table, full report, JSON."""

handoffmap/render/explain.py

@@ -0,0 +1,42 @@
+"""``--explain``: show which convention was detected and why each edge got its kind."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from ..i18n import t
+from ..model import Edge, Flow
+
+
+def _edge_line(e: Edge, lang: str) -> str:
+    src = e.caller or t(lang, "ex.none")
+    extra = t(lang, "ex.via", via=e.via) if e.via else ""
+    return f"  {src} -> {e.callee}: {e.kind}{extra}  [{t(lang, 'why.' + e.kind)}]"
+
+
+def render_explain(flow: Flow, lang: str = "en") -> str:
+    """Describe the detection result; ``lang`` is ``en`` (default) or ``ko``."""
+    lines = [
+        t(lang, "ex.trace", trace=flow.trace_id),
+        t(lang, "ex.convention", convention=flow.convention),
+        t(lang, "ex.size", spans=flow.span_count, runs=len(flow.runs), agents=len(flow.agents)),
+        t(lang, "ex.agents", names=", ".join(a.name for a in flow.agents)),
+        t(lang, "ex.edges"),
+    ]
+    lines += [_edge_line(e, lang) for e in flow.edges]
+    if flow.ignored:
+        counts = Counter(flow.ignored)
+        shown = ", ".join(f"'{name}' x{n}" for name, n in counts.items())
+        lines.append(t(lang, "ex.ignored", shown=shown))
+    else:
+        lines.append(t(lang, "ex.ignored_none"))
+    if flow.unknown_operations:
+        lines.append(t(lang, "ex.unknown_ops", names=", ".join(flow.unknown_operations)))
+    tot = flow.totals
+    if tot.input_tokens is None and tot.output_tokens is None:
+        lines.append(t(lang, "ex.tokens_none"))
+    else:
+        lines.append(t(lang, "ex.tokens", input=tot.input_tokens or 0, output=tot.output_tokens or 0))
+    if flow.reported_usage is not None:
+        lines.append(t(lang, "ex.reported", input=flow.reported_usage[0], output=flow.reported_usage[1]))
+    return "\n".join(lines) + "\n"

handoffmap/render/jsonout.py

@@ -0,0 +1,54 @@
+"""Stable JSON output. Only names, ids, timings and counts: never message content."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..model import AgentStats, Flow
+
+
+def _agent(a: AgentStats) -> dict[str, Any]:
+    return {
+        "name": a.name,
+        "runs": a.runs,
+        "llm_calls": a.llm_calls,
+        "tool_calls": a.tool_calls,
+        "input_tokens": a.input_tokens,
+        "output_tokens": a.output_tokens,
+        "cost": a.cost,
+        "duration_ms": round(a.duration_ms, 3),
+    }
+
+
+def to_dict(flow: Flow) -> dict[str, Any]:
+    """Convert a flow to plain dicts/lists (``json.dumps``-able)."""
+    t0 = min((r.start_ns for r in flow.runs.values()), default=0)
+    return {
+        "trace_id": flow.trace_id,
+        "convention": flow.convention,
+        "span_count": flow.span_count,
+        "agents": [_agent(a) for a in flow.agents],
+        "totals": _agent(flow.totals),
+        "edges": [
+            {
+                "kind": e.kind,
+                "from": e.caller,
+                "to": e.callee,
+                "via": e.via,
+                "start_ms": round((e.start_ns - t0) / 1e6, 3),
+                "duration_ms": round(e.duration_ms, 3),
+            }
+            for e in flow.edges
+        ],
+        "parallel": [
+            {
+                "agent": g.agent,
+                "members": [
+                    {"kind": m.kind, "name": m.name, "duration_ms": round((m.end_ns - m.start_ns) / 1e6, 3)}
+                    for m in g.members
+                ],
+            }
+            for g in flow.parallel
+        ],
+        "warnings": [{"code": w.code, "message": w.message} for w in flow.warnings],
+    }

handoffmap/render/markdown.py

@@ -0,0 +1,30 @@
+"""The default report: Mermaid diagram + agent table + warnings."""
+
+from __future__ import annotations
+
+from ..i18n import t
+from ..model import Flow
+from .mermaid import render_mermaid
+from .table import render_table
+
+
+def render_markdown(flow: Flow, *, show_tools: bool = True, heading: bool = True, lang: str = "en") -> str:
+    """Render the full report; ``lang`` (``en`` default, or ``ko``) only changes the prose, not the diagram."""
+    parts: list[str] = []
+    if heading:
+        parts.append(
+            t(lang, "md.heading", trace=flow.trace_id[:8], convention=flow.convention, spans=flow.span_count) + "\n"
+        )
+    parts.append("```mermaid\n" + render_mermaid(flow, show_tools=show_tools) + "```\n")
+    parts.append(t(lang, "md.agents") + "\n")
+    parts.append(render_table(flow, lang=lang))
+    parts.append(t(lang, "md.footnote") + "\n")
+    if flow.warnings:
+        parts.append(t(lang, "md.warnings") + "\n")
+        lines = []
+        for w in flow.warnings:
+            # warnings built by find_warnings carry args; a hand-made one falls back to its English message
+            message = t(lang, f"warn.{w.code}", **w.args) if w.args else w.message
+            lines.append(f"- **{w.code}**: {message}")
+        parts.append("\n".join(lines) + "\n")
+    return "\n".join(parts)

handoffmap/render/mermaid.py

@@ -0,0 +1,115 @@
+"""Mermaid ``sequenceDiagram`` output.
+
+Mermaid is picky about names: participants get plain aliases (``a1``, ``a2``)
+and the real name goes after ``as``; ``#``, ``;``, ``<`` and ``>`` in any text
+are written as Mermaid entity codes (``#59;``).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..model import Edge, Flow, ParallelGroup, ToolCall
+
+_SPECIAL = re.compile(r"[#;<>]")
+
+
+def escape(text: str) -> str:
+    """Make ``text`` safe for a Mermaid message or participant label."""
+    text = re.sub(r"\s+", " ", text).strip()
+    return _SPECIAL.sub(lambda m: f"#{ord(m.group())};", text)
+
+
+def _ms(value_ms: float) -> str:
+    return f"{value_ms:.1f} ms"
+
+
+@dataclass
+class _Act:
+    """One thing an agent run did: start a sub-agent/handoff (edge) or call a tool."""
+
+    ref: str  # callee run id (edge) or tool span id (tool)
+    start_ns: int
+    edge: Edge | None = None
+    tool: ToolCall | None = None
+
+
+def render_mermaid(flow: Flow, *, show_tools: bool = True) -> str:
+    """Render the flow as a Mermaid sequence diagram (no code fence)."""
+    alias: dict[str, str] = {}
+    for run in sorted(flow.runs.values(), key=lambda r: (r.start_ns, r.end_ns)):
+        alias.setdefault(run.name, f"a{len(alias) + 1}")
+
+    lines = ["sequenceDiagram"]
+    for name, a in alias.items():
+        lines.append(f"    participant {a} as {escape(name)}")
+
+    # what each agent run did, in time order
+    acts_by_run: dict[str, list[_Act]] = {}
+    for e in flow.edges:
+        if e.caller_run is not None:
+            acts_by_run.setdefault(e.caller_run, []).append(_Act(e.callee_run, e.start_ns, edge=e))
+    if show_tools:
+        for t in flow.tools:
+            if not t.wraps_agent:  # the sub-agent's own edge already shows this call
+                acts_by_run.setdefault(t.run_id, []).append(_Act(t.span_id, t.start_ns, tool=t))
+    for acts in acts_by_run.values():
+        acts.sort(key=lambda a: a.start_ns)
+
+    groups_by_run: dict[str, list[ParallelGroup]] = {}
+    for g in flow.parallel:
+        groups_by_run.setdefault(g.run_id, []).append(g)
+
+    visited: set[str] = set()  # a run is drawn once, even if the data has a handoff cycle
+
+    def act_line(act: _Act, indent: str) -> str:
+        if act.tool is not None:
+            t = act.tool
+            a = alias[t.agent]
+            return f"{indent}{a}->>{a}: {escape('tool ' + t.name)} ({_ms((t.end_ns - t.start_ns) / 1e6)})"
+        e = act.edge
+        assert e is not None
+        src, dst = alias[e.caller or ""], alias[e.callee]
+        if e.kind == "handoff":
+            return f"{indent}{src}-){dst}: handoff ({_ms(e.duration_ms)})"  # -) = async, control does not come back
+        label = f"as_tool via {e.via}" if e.kind == "as_tool" and e.via else e.kind
+        return f"{indent}{src}->>{dst}: {escape(label)} ({_ms(e.duration_ms)})"
+
+    def emit_act(act: _Act, indent: str) -> None:
+        lines.append(act_line(act, indent))
+        if act.edge is not None:
+            emit_run(act.edge.callee_run, indent)
+
+    def emit_run(run_id: str, indent: str) -> None:
+        if run_id in visited:
+            return
+        visited.add(run_id)
+        acts = acts_by_run.get(run_id, [])
+        by_ref = {a.ref: a for a in acts}
+        group_of: dict[str, list[_Act]] = {}
+        for g in groups_by_run.get(run_id, []):
+            branches = [by_ref[m.ref] for m in g.members if m.ref in by_ref]
+            if len(branches) > 1:  # with --no-tools a group can shrink to one branch: then no par
+                for b in branches:
+                    group_of[b.ref] = branches
+
+        drawn: set[str] = set()
+        for act in acts:
+            branches = group_of.get(act.ref)
+            if branches is None:
+                emit_act(act, indent)
+            elif act.ref not in drawn:
+                lines.append(f"{indent}par concurrent")
+                for i, b in enumerate(branches):
+                    if i:
+                        lines.append(f"{indent}and")
+                    emit_act(b, indent + "    ")
+                    drawn.add(b.ref)
+                lines.append(f"{indent}end")
+
+    for e in flow.edges:
+        if e.kind == "root":
+            lines.append(f"    Note over {alias[e.callee]}: start")
+            emit_run(e.callee_run, "    ")
+    return "\n".join(lines) + "\n"

handoffmap/render/table.py

@@ -0,0 +1,45 @@
+"""Per-agent Markdown table."""
+
+from __future__ import annotations
+
+from ..i18n import t
+from ..model import AgentStats, Flow
+
+DASH = "–"  # shown when a value is not in the trace
+
+
+def _cell(text: str) -> str:
+    # `|` would split the cell; `<`/`>` would be read as HTML by Markdown renderers
+    return text.replace("|", "\\|").replace("<", "&lt;").replace(">", "&gt;").replace("\n", " ")
+
+
+def _tokens(value: int | None) -> str:
+    return DASH if value is None else str(value)
+
+
+def _row(a: AgentStats, with_cost: bool, bold: bool = False, label: str | None = None) -> str:
+    shown = a.name if label is None else label  # the totals row gets a translated label
+    name = f"**{_cell(shown)}**" if bold else _cell(shown)
+    cells = [name, str(a.runs), str(a.llm_calls), str(a.tool_calls), _tokens(a.input_tokens), _tokens(a.output_tokens)]
+    if with_cost:
+        cells.append(DASH if a.cost is None else f"{a.cost:.6f}".rstrip("0").rstrip("."))
+    cells.append(f"{a.duration_ms:.1f} ms")
+    return "| " + " | ".join(cells) + " |"
+
+
+def render_table(flow: Flow, lang: str = "en") -> str:
+    """Render one row per agent name plus a total row (when there is more than one agent)."""
+    with_cost = any(a.cost is not None for a in flow.agents)
+    keys = ["agent", "runs", "llm_calls", "tools", "input_tokens", "output_tokens"]
+    if with_cost:
+        keys.append("cost")
+    keys.append("time")
+    headers = [t(lang, f"table.{k}") for k in keys]
+    lines = [
+        "| " + " | ".join(headers) + " |",
+        "|" + "|".join(["---"] + ["---:"] * (len(headers) - 1)) + "|",
+    ]
+    lines += [_row(a, with_cost) for a in flow.agents]
+    if len(flow.agents) > 1:
+        lines.append(_row(flow.totals, with_cost, bold=True, label=t(lang, "table.total")))
+    return "\n".join(lines) + "\n"

handoffmap/samples/SOURCES.md

@@ -0,0 +1,10 @@
+# Built-in sample traces
+
+All four were recorded on 2026-11-11 with **mock models** (no network, no API key), so token counts and timings are practice values.
+
+| File | Made with |
+|---|---|
+| `pydantic_ai_v2.otlp.json`, `pydantic_ai_v5.otlp.json`, `pydantic_ai_v6.otlp.json` | pydantic-ai-slim 2.67.0, `FunctionModel`, instrumentation `version=2/5/6`; see `examples/make_pydantic_trace.py` |
+| `openinference_agents.otlp.json` | openai-agents 0.24.0 `ScriptedModel`, openinference-instrumentation-openai-agents 2.7.1; see `examples/make_openai_agents_trace.py` |
+
+They use the protobuf-JSON form (base64 ids, `SPAN_KIND_*` names). Prompt/response text in them is mock text; handoffmap never prints it.