handoffmap 0.2.0__py3-none-any.whl

handoffmap/__init__.py

@@ -0,0 +1,50 @@
+"""handoffmap: fold OTLP agent traces into a Mermaid flow and a per-agent table."""
+
+from __future__ import annotations
+
+from .errors import HandoffmapError, NoAgentSpansError, NotOtlpError
+from .model import (
+    AgentRun,
+    AgentStats,
+    Edge,
+    Flow,
+    FlowWarning,
+    Member,
+    ParallelGroup,
+    Span,
+    ToolCall,
+    Trace,
+)
+from .normalize import analyze
+from .otlp import load, parse
+from .render.jsonout import to_dict
+from .render.explain import render_explain
+from .render.markdown import render_markdown
+from .render.mermaid import render_mermaid
+from .render.table import render_table
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AgentRun",
+    "AgentStats",
+    "Edge",
+    "Flow",
+    "FlowWarning",
+    "HandoffmapError",
+    "Member",
+    "NoAgentSpansError",
+    "NotOtlpError",
+    "ParallelGroup",
+    "Span",
+    "ToolCall",
+    "Trace",
+    "analyze",
+    "load",
+    "parse",
+    "render_explain",
+    "render_markdown",
+    "render_mermaid",
+    "render_table",
+    "to_dict",
+]

handoffmap/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

handoffmap/adapters/__init__.py

@@ -0,0 +1,70 @@
+"""Convention adapters: decide what role a span plays (agent, tool, LLM call).
+
+Each adapter looks at attributes only, never at the span name, because the
+OTel GenAI conventions are still in development and frameworks name spans
+differently (Pydantic AI instrumentation v2 says ``agent run``, v5 says
+``invoke_agent orchestrator``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..model import Span
+
+GENAI = "otel-genai"
+OPENINFERENCE = "openinference"
+
+
+@dataclass
+class Classified:
+    """What an adapter learned about one span."""
+
+    role: str  # "agent" | "tool" | "llm" | "ignored"
+    convention: str
+    name: str = ""
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cost: float | None = None
+    handoff_marker: bool = False  # a tool span that only records "transfer to X"
+    handoff_from: str | None = None  # OpenInference graph.node.parent_id
+    reported_usage: tuple[int, int] | None = None  # usage attributes on an agent span
+
+
+def classify(span: Span, unknown_operations: set[str] | None = None) -> Classified | None:
+    """Classify a span, or return None if it is neither an agent, a tool nor an LLM call."""
+    from . import genai, openinference
+
+    if "gen_ai.operation.name" in span.attributes:
+        result = genai.classify(span, unknown_operations)
+        if result is not None or "openinference.span.kind" not in span.attributes:
+            return result
+    if "openinference.span.kind" in span.attributes:
+        return openinference.classify(span)
+    return None
+
+
+def as_int(value: object) -> int | None:
+    """Return value as int when it is a number (or numeric string), else None."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str) and value.strip().lstrip("-").isdigit():
+        return int(value)
+    return None
+
+
+def as_float(value: object) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return None
+    return None

handoffmap/adapters/genai.py

@@ -0,0 +1,56 @@
+"""OTel GenAI semantic conventions (``gen_ai.operation.name`` based)."""
+
+from __future__ import annotations
+
+from ..model import Span
+from . import GENAI, Classified, as_int
+
+LLM_OPERATIONS = {"chat", "text_completion", "generate_content"}
+# Operations the conventions define that carry no agent/tool/LLM role here.
+OTHER_KNOWN_OPERATIONS = {"create_agent", "invoke_workflow", "embeddings", "retrieval"}
+
+
+def _strip_prefix(name: str, prefix: str) -> str:
+    return name[len(prefix) :].strip() if name.startswith(prefix) else name
+
+
+def classify(span: Span, unknown_operations: set[str] | None = None) -> Classified | None:
+    attrs = span.attributes
+    operation = attrs.get("gen_ai.operation.name")
+
+    if operation == "invoke_agent":
+        name = (
+            attrs.get("gen_ai.agent.name")
+            or attrs.get("agent_name")  # Pydantic AI also sets this non-standard key
+            or _strip_prefix(span.name, "invoke_agent")
+            or attrs.get("gen_ai.agent.id")
+            or "agent"
+        )
+        reported = _reported_usage(attrs)
+        return Classified(role="agent", convention=GENAI, name=str(name), reported_usage=reported)
+
+    if operation == "execute_tool":
+        name = attrs.get("gen_ai.tool.name") or _strip_prefix(span.name, "execute_tool") or "tool"
+        return Classified(role="tool", convention=GENAI, name=str(name))
+
+    if operation in LLM_OPERATIONS:
+        return Classified(
+            role="llm",
+            convention=GENAI,
+            input_tokens=as_int(attrs.get("gen_ai.usage.input_tokens")),
+            output_tokens=as_int(attrs.get("gen_ai.usage.output_tokens")),
+        )
+
+    if operation not in OTHER_KNOWN_OPERATIONS and unknown_operations is not None:
+        unknown_operations.add(str(operation))
+    return None
+
+
+def _reported_usage(attrs: dict) -> tuple[int, int] | None:
+    """Usage attributes on an agent span. Used only as a cross-check, never summed."""
+    for prefix in ("gen_ai.aggregated_usage", "gen_ai.usage"):
+        i = as_int(attrs.get(f"{prefix}.input_tokens"))
+        o = as_int(attrs.get(f"{prefix}.output_tokens"))
+        if i is not None or o is not None:
+            return (i or 0, o or 0)
+    return None

handoffmap/adapters/openinference.py

@@ -0,0 +1,40 @@
+"""OpenInference conventions (``openinference.span.kind`` based)."""
+
+from __future__ import annotations
+
+from ..model import Span
+from . import OPENINFERENCE, Classified, as_float, as_int
+
+
+def classify(span: Span) -> Classified | None:
+    attrs = span.attributes
+    kind = str(attrs.get("openinference.span.kind", "")).upper()
+
+    if kind == "AGENT":
+        name = attrs.get("agent.name") or attrs.get("graph.node.id")
+        if not name:
+            # e.g. the OpenAI Agents SDK "Agent workflow" wrapper: an AGENT span with no agent behind it
+            return Classified(role="ignored", convention=OPENINFERENCE, name=span.name)
+        parent = attrs.get("graph.node.parent_id")
+        return Classified(
+            role="agent",
+            convention=OPENINFERENCE,
+            name=str(name),
+            handoff_from=str(parent) if parent else None,
+        )
+
+    if kind == "TOOL":
+        name = attrs.get("tool.name") or span.name or "tool"
+        # The Agents SDK records a handoff as a TOOL span named "handoff to <agent>".
+        marker = span.name.lower().startswith("handoff to ")
+        return Classified(role="tool", convention=OPENINFERENCE, name=str(name), handoff_marker=marker)
+
+    if kind == "LLM":
+        return Classified(
+            role="llm",
+            convention=OPENINFERENCE,
+            input_tokens=as_int(attrs.get("llm.token_count.prompt")),
+            output_tokens=as_int(attrs.get("llm.token_count.completion")),
+            cost=as_float(attrs.get("llm.cost.total")),
+        )
+    return None

handoffmap/checks.py

@@ -0,0 +1,33 @@
+"""Flow warnings: things that usually mean a loop or a runaway fan-out."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .i18n import t
+from .model import Edge, FlowWarning, ParallelGroup
+
+
+def find_warnings(
+    edges: list[Edge],
+    parallel: list[ParallelGroup],
+    repeat_threshold: int = 3,
+    max_parallel: int = 8,
+) -> list[FlowWarning]:
+    """Return ``repeated-delegation`` and ``wide-parallel`` warnings.
+
+    ``message`` is English; ``args`` lets the renderers rebuild it in another language.
+    """
+    warnings: list[FlowWarning] = []
+
+    pairs = Counter((e.caller, e.callee) for e in edges if e.kind != "root")
+    for (caller, callee), count in pairs.items():
+        if count >= repeat_threshold:
+            args = {"caller": caller, "callee": callee, "count": count, "threshold": repeat_threshold}
+            warnings.append(FlowWarning("repeated-delegation", t("en", "warn.repeated-delegation", **args), args))
+
+    for group in parallel:
+        if len(group.members) > max_parallel:
+            args = {"agent": group.agent, "count": len(group.members), "limit": max_parallel}
+            warnings.append(FlowWarning("wide-parallel", t("en", "warn.wide-parallel", **args), args))
+    return warnings

handoffmap/cli.py

@@ -0,0 +1,169 @@
+"""Command line interface.
+
+Exit codes: 0 ok, 1 no agent spans in the trace, 2 bad input (not OTLP, missing file, bad option).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib import resources
+from pathlib import Path
+
+from . import __version__
+from .errors import HandoffmapError, NoAgentSpansError, NotOtlpError
+from .i18n import LANGS, argparse_translator, resolve_lang, t
+from .model import Flow, Trace
+from .normalize import analyze
+from .otlp import load, parse
+from .render.explain import render_explain
+from .render.jsonout import to_dict
+from .render.markdown import render_markdown
+from .render.mermaid import render_mermaid
+from .render.table import render_table
+
+SAMPLES = {
+    "pydantic-ai": "pydantic_ai_v5.otlp.json",
+    "pydantic-ai-v2": "pydantic_ai_v2.otlp.json",
+    "pydantic-ai-v6": "pydantic_ai_v6.otlp.json",
+    "openinference": "openinference_agents.otlp.json",
+}
+FORMATS = ("md", "mermaid", "table", "json")
+
+
+def _positive_for(lang: str):
+    """Return an argparse ``type=`` function whose error messages are in ``lang``."""
+
+    def _positive(text: str) -> int:
+        try:
+            value = int(text)
+        except ValueError:
+            raise argparse.ArgumentTypeError(t(lang, "cli.err.not_whole", text=text)) from None
+        if value < 1:
+            raise argparse.ArgumentTypeError(t(lang, "cli.err.min_one"))
+        return value
+
+    return _positive
+
+
+def _peek_lang(argv: list[str]) -> str:
+    """Read only ``--lang`` from argv first, so help and parse errors can already be localized."""
+    peek = argparse.ArgumentParser(add_help=False, allow_abbrev=False)
+    peek.add_argument("--lang")
+    known, _rest = peek.parse_known_args(argv)
+    return resolve_lang(known.lang)
+
+
+@contextmanager
+def _argparse_in(lang: str) -> Iterator[None]:
+    """Render argparse's built-in messages (usage, choices errors, ...) in ``lang`` while parsing."""
+    original = argparse._  # type: ignore[attr-defined]
+    argparse._ = argparse_translator(lang)  # type: ignore[attr-defined]
+    try:
+        yield
+    finally:
+        argparse._ = original  # type: ignore[attr-defined]
+
+
+def build_parser(lang: str = "en") -> argparse.ArgumentParser:
+    """Build the argument parser with help text in ``lang`` (``en`` or ``ko``)."""
+    positive = _positive_for(lang)
+    p = argparse.ArgumentParser(prog="handoffmap", description=t(lang, "cli.description"), add_help=False)
+    p.add_argument("-h", "--help", action="help", help=t(lang, "argparse.help"))
+    p.add_argument("file", nargs="?", help=t(lang, "cli.help.file"))
+    p.add_argument("--sample", choices=sorted(SAMPLES), help=t(lang, "cli.help.sample"))
+    p.add_argument("--format", "-f", choices=FORMATS, default="md", help=t(lang, "cli.help.format"))
+    p.add_argument("--explain", action="store_true", help=t(lang, "cli.help.explain"))
+    p.add_argument("--trace", metavar="TRACE_ID", help=t(lang, "cli.help.trace"))
+    p.add_argument("--max-parallel", type=positive, default=8, metavar="N", help=t(lang, "cli.help.max_parallel"))
+    p.add_argument("--repeat-threshold", type=positive, default=3, metavar="N", help=t(lang, "cli.help.repeat_threshold"))
+    p.add_argument("--no-tools", action="store_true", help=t(lang, "cli.help.no_tools"))
+    p.add_argument("-o", "--output", metavar="OUT", help=t(lang, "cli.help.output"))
+    p.add_argument("--lang", choices=LANGS, metavar="{en,ko}", help=t(lang, "cli.help.lang"))
+    p.add_argument("--version", action="version", version=f"handoffmap {__version__}", help=t(lang, "cli.help.version"))
+    return p
+
+
+def _load_traces(args: argparse.Namespace) -> list[Trace]:
+    if args.sample:
+        text = resources.files("handoffmap").joinpath("samples", SAMPLES[args.sample]).read_text(encoding="utf-8")
+        traces = parse(text)
+    else:
+        traces = load(args.file)
+    if args.trace:
+        traces = [t for t in traces if t.trace_id.startswith(args.trace.lower())]
+        if not traces:
+            raise NotOtlpError("cli.err.no_trace", prefix=args.trace)
+    return traces
+
+
+def _analyze_all(traces: list[Trace], args: argparse.Namespace) -> list[Flow]:
+    flows: list[Flow] = []
+    last_error: NoAgentSpansError | None = None
+    for trace in traces:
+        try:
+            flows.append(analyze(trace, repeat_threshold=args.repeat_threshold, max_parallel=args.max_parallel))
+        except NoAgentSpansError as exc:
+            last_error = exc  # other traces in the file may still have agents
+    if not flows:
+        assert last_error is not None
+        raise last_error
+    return flows
+
+
+def _render(flows: list[Flow], args: argparse.Namespace, lang: str) -> tuple[str, str]:
+    """Return (report, explain) text. ``json`` and ``mermaid`` ignore ``lang`` (machine output)."""
+    show_tools = not args.no_tools
+    explain = (
+        "".join(render_explain(f, lang) + ("\n" if len(flows) > 1 else "") for f in flows) if args.explain else ""
+    )
+    if args.format == "json":
+        payload = [to_dict(f) for f in flows]
+        report = json.dumps(payload[0] if len(payload) == 1 else {"traces": payload}, indent=2, ensure_ascii=False) + "\n"
+    elif args.format == "mermaid":
+        report = "\n".join(render_mermaid(f, show_tools=show_tools) for f in flows)
+    elif args.format == "table":
+        report = "\n".join(render_table(f, lang=lang) for f in flows)
+    else:
+        report = "\n".join(render_markdown(f, show_tools=show_tools, heading=True, lang=lang) for f in flows)
+    if args.sample and args.format == "md":
+        report += "\n" + t(lang, "cli.sample_note") + "\n"
+    return report, explain
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")  # the table uses an en dash; C locales would choke
+    raw_args = sys.argv[1:] if argv is None else list(argv)
+    lang = _peek_lang(raw_args)  # --lang > HANDOFFMAP_LANG > LC_ALL/LC_MESSAGES/LANG > en
+    with _argparse_in(lang):  # the parser must be built inside: argparse looks up some titles at construction
+        parser = build_parser(lang)
+        args = parser.parse_args(raw_args)
+        if bool(args.file) == bool(args.sample):
+            parser.error(t(lang, "cli.err.one_of"))
+
+    try:
+        flows = _analyze_all(_load_traces(args), args)
+        report, explain = _render(flows, args, lang)
+    except HandoffmapError as exc:
+        print(f"handoffmap: {exc.localized(lang)}", file=sys.stderr)
+        return exc.exit_code
+
+    # explain goes before the report for md/table; to stderr for mermaid/json so stdout stays machine-readable
+    if explain and args.format in ("mermaid", "json"):
+        print(explain, file=sys.stderr, end="")
+        explain = ""
+    text = (explain + "\n" if explain else "") + report
+    if args.output:
+        try:
+            Path(args.output).write_text(text, encoding="utf-8")
+        except OSError as exc:
+            print(f"handoffmap: {t(lang, 'cli.err.cannot_write', path=args.output, error=exc)}", file=sys.stderr)
+            return 2
+    else:
+        sys.stdout.write(text)
+    return 0

handoffmap/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions raised by handoffmap. The CLI maps them to exit codes."""
+
+from __future__ import annotations
+
+from .i18n import MESSAGES, t
+
+
+class HandoffmapError(Exception):
+    """Base class for all handoffmap errors.
+
+    Built from a message key of :mod:`handoffmap.i18n` plus its parameters. ``str(exc)`` is
+    always English; the CLI calls :meth:`localized` to show the user's language.
+    """
+
+    exit_code = 2
+
+    def __init__(self, key: str, **params: object) -> None:
+        self.key = key
+        self.params = params
+        # a key that is not in the table is treated as a plain English message
+        super().__init__(t("en", key, **params) if key in MESSAGES["en"] else key)
+
+    def localized(self, lang: str) -> str:
+        """Return the message in ``lang`` (``en`` or ``ko``)."""
+        return t(lang, self.key, **self.params) if self.key in MESSAGES["en"] else str(self)
+
+
+class NotOtlpError(HandoffmapError):
+    """The input is not an OTLP trace export (exit code 2)."""
+
+    exit_code = 2
+
+
+class NoAgentSpansError(HandoffmapError):
+    """The trace has no agent spans, so there is no flow to draw (exit code 1)."""
+
+    exit_code = 1