agentcanvas 0.1.0__py3-none-any.whl

agentcanvas/__init__.py

@@ -0,0 +1,22 @@
+"""agentcanvas — visualize a Pydantic AI agent workflow from Logfire logs.
+
+Reads the OpenTelemetry (GenAI) spans emitted by Pydantic AI's instrumentation,
+parses them into a typed :class:`WorkflowReport` (turns, rounds, tools, nested
+agents), prices each model call with ``genai-prices``, and renders a
+self-contained, interactive HTML report.
+"""
+
+from .logfire_client import LogfireClient
+from .models import AgentRun, ModelCall, ToolCall, WorkflowReport
+from .parser import parse_run
+from .render import render_html
+
+__all__ = [
+    "LogfireClient",
+    "WorkflowReport",
+    "AgentRun",
+    "ModelCall",
+    "ToolCall",
+    "parse_run",
+    "render_html",
+]

agentcanvas/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentcanvas/cli.py

@@ -0,0 +1,79 @@
+"""Command-line interface: pull an agent run from Logfire and build the HTML report."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .logfire_client import LogfireClient
+from .parser import parse_run
+from .render import render_html
+
+
+def main(argv: list[str] | None = None) -> int:
+    load_dotenv()
+    parser = argparse.ArgumentParser(
+        prog="agentcanvas",
+        description="Visualize a Pydantic AI agent workflow from Logfire logs.",
+    )
+    parser.add_argument("--trace-id", help="Trace id to visualize (default: latest).")
+    parser.add_argument("--list", action="store_true", help="List recent runs and exit.")
+    parser.add_argument("-o", "--output", default="agent_flow.html", help="Output HTML file.")
+    parser.add_argument(
+        "--no-open", action="store_true", help="Do not open the report in a browser."
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        client = LogfireClient()
+    except RuntimeError as exc:
+        print(f"✖ {exc}", file=sys.stderr)
+        return 1
+
+    if args.list:
+        rows = client.list_recent_traces()
+        if not rows:
+            print("No agent runs found in the project.")
+            return 0
+        print("Recent agent runs:\n")
+        for row in rows:
+            dur = row.get("duration")
+            suffix = f"  ({float(dur):.2f}s)" if dur else ""
+            print(f"  {row['trace_id']}  {row.get('start_timestamp', '')}{suffix}")
+        return 0
+
+    trace_id = args.trace_id or client.latest_trace_id()
+    if not trace_id:
+        print("✖ No trace found in Logfire.", file=sys.stderr)
+        return 1
+
+    print(f"→ Fetching trace {trace_id} …")
+    spans = client.fetch_trace(trace_id)
+    if not spans:
+        print("✖ Trace contains no spans.", file=sys.stderr)
+        return 1
+
+    report = parse_run(spans, trace_id)
+    totals = report.totals
+    cost = f", cost ${totals.total_cost_usd:.6f}" if report.meta.cost_known else ", cost unknown"
+    print(
+        f"→ Parsed: {totals.num_turns} turn(s), {totals.num_model_calls} model call(s), "
+        f"{totals.num_tools} tool call(s), {totals.num_nested_agents} nested agent(s), "
+        f"{totals.total_tokens} tokens{cost}"
+    )
+
+    out = Path(args.output).resolve()
+    out.write_text(render_html(report), encoding="utf-8")
+    print(f"✓ Report written: {out}")
+
+    if not args.no_open:
+        webbrowser.open(out.as_uri())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentcanvas/logfire_client.py

@@ -0,0 +1,104 @@
+"""A thin client for the Logfire Query API (read spans via SQL + read token)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+# Default region; override with LOGFIRE_BASE_URL (e.g. https://logfire-eu.pydantic.dev).
+DEFAULT_BASE_URL = "https://logfire-us.pydantic.dev"
+
+# Columns the parser needs. `attributes` carries the whole GenAI payload.
+_SPAN_COLUMNS = (
+    "span_id, parent_span_id, span_name, "
+    "start_timestamp, end_timestamp, duration, "
+    "otel_status_code, otel_status_message, attributes"
+)
+
+
+def _sql_str(value: str) -> str:
+    """Quote a value as a SQL string literal, escaping embedded quotes (ANSI style)."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+class LogfireClient:
+    """Runs SQL queries against Logfire and returns rows as a list of dicts."""
+
+    def __init__(self, read_token: str | None = None, base_url: str | None = None):
+        self.read_token = read_token or os.environ.get("LOGFIRE_READ_TOKEN")
+        if not self.read_token:
+            raise RuntimeError(
+                "Missing Logfire read token. Set LOGFIRE_READ_TOKEN in .env or pass read_token=..."
+            )
+        resolved = base_url or os.environ.get("LOGFIRE_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolved.rstrip("/")
+
+    def query(self, sql: str) -> list[dict[str, Any]]:
+        """Run SQL and return rows (Logfire returns columns — we transpose here)."""
+        resp = httpx.get(
+            f"{self.base_url}/v1/query",
+            params={"sql": sql},
+            headers={
+                "Authorization": f"Bearer {self.read_token}",
+                "Accept": "application/json",
+            },
+            timeout=30.0,
+        )
+        resp.raise_for_status()
+        payload = resp.json()
+        return _columns_to_rows(payload)
+
+    def latest_trace_id(self) -> str | None:
+        """Latest trace that is an actual agent run (has an `invoke_agent` span)."""
+        rows = self.query(
+            "SELECT trace_id FROM records WHERE span_name LIKE 'invoke_agent%' "
+            "ORDER BY start_timestamp DESC LIMIT 1"
+        )
+        return rows[0]["trace_id"] if rows else None
+
+    def list_recent_traces(self, limit: int = 20) -> list[dict[str, Any]]:
+        """List recent agent runs (by the invoke_agent span)."""
+        return self.query(
+            "SELECT trace_id, span_name, start_timestamp, duration "
+            "FROM records WHERE span_name LIKE 'invoke_agent%' "
+            f"ORDER BY start_timestamp DESC LIMIT {int(limit)}"
+        )
+
+    def fetch_trace(self, trace_id: str) -> list[dict[str, Any]]:
+        """All spans of a given trace, sorted chronologically."""
+        if not trace_id:
+            raise ValueError("trace_id must not be empty")
+        rows = self.query(
+            f"SELECT {_SPAN_COLUMNS} FROM records "
+            f"WHERE trace_id = {_sql_str(trace_id)} ORDER BY start_timestamp ASC"
+        )
+        for row in rows:
+            row["attributes"] = _ensure_dict(row.get("attributes"))
+        return rows
+
+
+def _columns_to_rows(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    cols = payload.get("columns", [])
+    if not cols:
+        return []
+    names = [c["name"] for c in cols]
+    values = [c["values"] for c in cols]
+    n = len(values[0]) if values else 0
+    return [{names[c]: values[c][i] for c in range(len(names))} for i in range(n)]
+
+
+def _ensure_dict(value: Any) -> dict[str, Any]:
+    """The `attributes` column may come back as a JSON string or a native object."""
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return {}
+    return {}

agentcanvas/models.py

@@ -0,0 +1,102 @@
+"""Typed models for a parsed agent workflow.
+
+These mirror exactly the data the HTML renderer consumes. ``WorkflowReport`` is
+serialised to JSON and embedded in the report; nothing outside these fields is
+emitted, so the payload stays lean and the renderer stays in sync.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolDefinition(BaseModel):
+    """A tool the model was offered for a request (name + description)."""
+
+    name: str | None = None
+    description: str | None = None
+
+
+class ToolCall(BaseModel):
+    """A single tool execution. ``nested`` is set when the tool is itself an agent."""
+
+    name: str
+    arguments: Any = None
+    result: str | None = None
+    duration_s: float = 0.0
+    nested: AgentRun | None = None
+
+
+class ModelCall(BaseModel):
+    """One request to the model (a ``chat`` span) plus the tools it triggered."""
+
+    model: str = ""
+    provider: str | None = None
+    server: str | None = None
+    response_id: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    reasoning_tokens: int = 0
+    cost_usd: float | None = None
+    cost_input_usd: float | None = None
+    cost_output_usd: float | None = None
+    finish_reasons: list[str] = Field(default_factory=list)
+    duration_s: float = 0.0
+    thinking: list[str] = Field(default_factory=list)
+    text_out: list[str] = Field(default_factory=list)
+    decided_tool_calls: list[str] = Field(default_factory=list)
+    available_tools: list[ToolDefinition] = Field(default_factory=list)
+    thinking_config: Any = None
+    tools: list[ToolCall] = Field(default_factory=list)
+
+
+class AgentRun(BaseModel):
+    """One agent invocation: a conversation turn, or a nested sub-agent."""
+
+    agent_name: str = "agent"
+    model: str = ""
+    final_output: str | None = None
+    user_prompt: str | None = None
+    rounds: list[ModelCall] = Field(default_factory=list)
+
+
+class ConversationMessage(BaseModel):
+    """One entry in the human-readable transcript."""
+
+    role: str
+    text: str = ""
+    thinking: list[str] = Field(default_factory=list)
+    tool_calls: list[str] = Field(default_factory=list)
+
+
+class Meta(BaseModel):
+    trace_id: str
+    model: str = ""
+    duration_s: float = 0.0
+    num_turns: int = 0
+    cost_known: bool = False
+
+
+class Totals(BaseModel):
+    total_tokens: int = 0
+    total_cost_usd: float | None = None
+    reasoning_tokens: int = 0
+    num_model_calls: int = 0
+    num_tools: int = 0
+    num_nested_agents: int = 0
+    num_turns: int = 0
+
+
+class WorkflowReport(BaseModel):
+    """The complete, renderable workflow."""
+
+    meta: Meta
+    totals: Totals
+    conversation: list[ConversationMessage] = Field(default_factory=list)
+    turns: list[AgentRun] = Field(default_factory=list)
+
+
+# Resolve the ToolCall <-> AgentRun forward reference.
+ToolCall.model_rebuild()

agentcanvas/parser.py

@@ -0,0 +1,311 @@
+"""Parse raw Logfire spans into a typed :class:`WorkflowReport`.
+
+Logfire spans form a tree via ``parent_span_id``. We turn that tree into a
+recursive structure that naturally supports multiple conversation turns,
+arbitrarily deep nested agents-as-tools, per-call reasoning, token usage and
+exact cost. Relies on Pydantic AI v2's OpenTelemetry GenAI span names:
+``invoke_agent <name>``, ``chat <model>``, ``execute_tool <name>``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .models import (
+    AgentRun,
+    ConversationMessage,
+    Meta,
+    ModelCall,
+    ToolCall,
+    ToolDefinition,
+    Totals,
+    WorkflowReport,
+)
+from .pricing import price_request
+
+Span = dict[str, Any]
+ChildIndex = dict[str | None, list[Span]]
+
+
+def _maybe_json(value: Any) -> Any:
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def _stringify(value: Any) -> str | None:
+    if value is None or isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False)
+
+
+@dataclass
+class _Part:
+    kind: str
+    role: str | None = None
+    content: str | None = None
+    name: str | None = None
+
+
+def _parts(raw: Any) -> list[_Part]:
+    """Flatten a GenAI message list into ordered parts (text/thinking/tool_call)."""
+    messages = _maybe_json(raw)
+    out: list[_Part] = []
+    if not isinstance(messages, list):
+        return out
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        for part in message.get("parts", []):
+            if not isinstance(part, dict):
+                continue
+            ptype = part.get("type", "")
+            if ptype == "tool_call":
+                out.append(_Part("tool_call", role, name=part.get("name")))
+            elif ptype in ("text", "thinking") and part.get("content"):
+                out.append(_Part(ptype, role, content=part.get("content")))
+    return out
+
+
+def _user_prompt(chat_attrs: dict[str, Any]) -> str | None:
+    """The last user-authored text in a request's input — the turn's prompt."""
+    for part in reversed(_parts(chat_attrs.get("gen_ai.input.messages"))):
+        if part.kind == "text" and part.role == "user" and part.content:
+            return part.content
+    return None
+
+
+def _conversation(all_messages: Any) -> list[ConversationMessage]:
+    """Flatten the full message history into a human-readable transcript."""
+    messages = _maybe_json(all_messages)
+    out: list[ConversationMessage] = []
+    if not isinstance(messages, list):
+        return out
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        texts: list[str] = []
+        thinking: list[str] = []
+        tool_calls: list[str] = []
+        tool_results: list[str] = []
+        for part in message.get("parts", []):
+            if not isinstance(part, dict):
+                continue
+            ptype = part.get("type")
+            content = part.get("content")
+            if ptype == "text" and content:
+                texts.append(content)
+            elif ptype == "thinking" and content:
+                thinking.append(content)
+            elif ptype == "tool_call" and part.get("name"):
+                tool_calls.append(part["name"])
+            elif ptype == "tool_call_response" and part.get("name"):
+                tool_results.append(part["name"])
+        if role == "user" and texts:
+            out.append(ConversationMessage(role="user", text="\n".join(texts)))
+        elif role == "user" and tool_results:
+            out.append(
+                ConversationMessage(
+                    role="tool", text="Returned results from: " + ", ".join(tool_results)
+                )
+            )
+        elif role == "assistant":
+            out.append(
+                ConversationMessage(
+                    role="assistant",
+                    text="\n".join(texts),
+                    thinking=thinking,
+                    tool_calls=tool_calls,
+                )
+            )
+    return out
+
+
+def _child_index(spans: list[Span]) -> ChildIndex:
+    children: ChildIndex = {}
+    for span in spans:
+        children.setdefault(span.get("parent_span_id"), []).append(span)
+    for siblings in children.values():
+        siblings.sort(key=lambda s: s.get("start_timestamp") or "")
+    return children
+
+
+def _kind(span: Span) -> str:
+    name = span["span_name"]
+    if name.startswith("invoke_agent"):
+        return "agent"
+    if name.startswith("chat "):
+        return "model"
+    if name.startswith("execute_tool "):
+        return "tool"
+    return "other"
+
+
+def _parse_model_call(span: Span) -> ModelCall:
+    attrs = span["attributes"]
+    model = attrs.get("gen_ai.request.model") or attrs.get("gen_ai.response.model") or ""
+    input_tokens = int(attrs.get("gen_ai.usage.input_tokens", 0) or 0)
+    output_tokens = int(attrs.get("gen_ai.usage.output_tokens", 0) or 0)
+    cost = price_request(model, input_tokens, output_tokens)
+
+    parts = _parts(attrs.get("gen_ai.output.messages"))
+    finish = attrs.get("gen_ai.response.finish_reasons") or []
+    if isinstance(finish, str):
+        finish = [finish]
+
+    request_params = _maybe_json(attrs.get("model_request_parameters"))
+    available = []
+    thinking_config = None
+    if isinstance(request_params, dict):
+        thinking_config = request_params.get("thinking")
+        for tool in request_params.get("function_tools") or []:
+            if isinstance(tool, dict):
+                available.append(
+                    ToolDefinition(name=tool.get("name"), description=tool.get("description"))
+                )
+
+    return ModelCall(
+        model=model,
+        provider=attrs.get("gen_ai.provider.name") or attrs.get("gen_ai.system"),
+        server=attrs.get("server.address"),
+        response_id=attrs.get("gen_ai.response.id"),
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        reasoning_tokens=int(attrs.get("gen_ai.usage.details.reasoning_tokens", 0) or 0),
+        cost_usd=cost.total_usd,
+        cost_input_usd=cost.input_usd,
+        cost_output_usd=cost.output_usd,
+        finish_reasons=list(finish),
+        duration_s=float(span.get("duration") or 0.0),
+        thinking=[p.content for p in parts if p.kind == "thinking" and p.content],
+        text_out=[p.content for p in parts if p.kind == "text" and p.content],
+        decided_tool_calls=[p.name for p in parts if p.kind == "tool_call" and p.name],
+        available_tools=available,
+        thinking_config=thinking_config,
+    )
+
+
+def _parse_tool(span: Span, index: ChildIndex) -> ToolCall:
+    attrs = span["attributes"]
+    nested: AgentRun | None = None
+    for child in index.get(span["span_id"], []):
+        if _kind(child) == "agent":
+            nested = _parse_agent(child, index)
+            break
+    return ToolCall(
+        name=attrs.get("gen_ai.tool.name", span["span_name"].replace("execute_tool ", "")),
+        arguments=_maybe_json(attrs.get("gen_ai.tool.call.arguments")),
+        result=_stringify(attrs.get("gen_ai.tool.call.result")),
+        duration_s=float(span.get("duration") or 0.0),
+        nested=nested,
+    )
+
+
+def _parse_agent(span: Span, index: ChildIndex) -> AgentRun:
+    attrs = span["attributes"]
+    rounds: list[ModelCall] = []
+    current: ModelCall | None = None
+    user_prompt: str | None = None
+
+    for child in index.get(span["span_id"], []):
+        kind = _kind(child)
+        if kind == "model":
+            current = _parse_model_call(child)
+            rounds.append(current)
+            if user_prompt is None:
+                user_prompt = _user_prompt(child["attributes"])
+        elif kind == "tool":
+            if current is None:
+                current = ModelCall()
+                rounds.append(current)
+            current.tools.append(_parse_tool(child, index))
+
+    return AgentRun(
+        agent_name=attrs.get("gen_ai.agent.name", span["span_name"].replace("invoke_agent ", "")),
+        model=attrs.get("model_name", ""),
+        final_output=_stringify(_maybe_json(attrs.get("final_result"))),
+        user_prompt=user_prompt,
+        rounds=rounds,
+    )
+
+
+@dataclass
+class _Acc:
+    input: int = 0
+    output: int = 0
+    reasoning: int = 0
+    cost: float = 0.0
+    cost_known: bool = False
+    model_calls: int = 0
+    tools: int = 0
+    nested_agents: int = 0
+
+
+def _accumulate(agent: AgentRun, acc: _Acc) -> None:
+    for call in agent.rounds:
+        acc.input += call.input_tokens
+        acc.output += call.output_tokens
+        acc.reasoning += call.reasoning_tokens
+        if call.model:
+            acc.model_calls += 1
+        if call.cost_usd is not None:
+            acc.cost += call.cost_usd
+            acc.cost_known = True
+        for tool in call.tools:
+            acc.tools += 1
+            if tool.nested is not None:
+                acc.nested_agents += 1
+                _accumulate(tool.nested, acc)
+
+
+def parse_run(spans: list[Span], trace_id: str) -> WorkflowReport:
+    """Build a :class:`WorkflowReport` from the spans of a single trace."""
+    index = _child_index(spans)
+    tool_ids = {s["span_id"] for s in spans if _kind(s) == "tool"}
+    top_agents = sorted(
+        (s for s in spans if _kind(s) == "agent" and s.get("parent_span_id") not in tool_ids),
+        key=lambda s: s.get("start_timestamp") or "",
+    )
+
+    turns = [_parse_agent(span, index) for span in top_agents]
+
+    acc = _Acc()
+    for turn in turns:
+        _accumulate(turn, acc)
+
+    roots = index.get(None, [])
+    duration = max((float(s.get("duration") or 0.0) for s in roots), default=0.0)
+    conversation = (
+        _conversation(top_agents[-1]["attributes"].get("pydantic_ai.all_messages"))
+        if top_agents
+        else []
+    )
+    model = next((t.model for t in turns if t.model), "")
+
+    return WorkflowReport(
+        meta=Meta(
+            trace_id=trace_id,
+            model=model,
+            duration_s=duration,
+            num_turns=len(turns),
+            cost_known=acc.cost_known,
+        ),
+        totals=Totals(
+            total_tokens=acc.input + acc.output,
+            total_cost_usd=acc.cost if acc.cost_known else None,
+            reasoning_tokens=acc.reasoning,
+            num_model_calls=acc.model_calls,
+            num_tools=acc.tools,
+            num_nested_agents=acc.nested_agents,
+            num_turns=len(turns),
+        ),
+        conversation=conversation,
+        turns=turns,
+    )

agentcanvas/pricing.py

@@ -0,0 +1,51 @@
+"""Compute exact per-request model costs from token counts via ``genai-prices``.
+
+Logfire records token counts but not a dollar amount; this fills that gap using
+Pydantic's local price database. If the model is unknown (or the library is
+unavailable), the cost is reported as not known rather than guessed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CostBreakdown:
+    total_usd: float | None
+    input_usd: float | None
+    output_usd: float | None
+    known: bool
+
+
+_UNKNOWN = CostBreakdown(None, None, None, False)
+
+
+def _model_ref(model: str) -> str:
+    """``openai/gpt-5.5`` -> ``gpt-5.5`` (genai-prices resolves the bare name)."""
+    return model.split("/")[-1] if model else model
+
+
+def price_request(model: str, input_tokens: int, output_tokens: int) -> CostBreakdown:
+    """Return the cost breakdown of a single model request."""
+    if not model:
+        return _UNKNOWN
+    try:
+        from genai_prices import calc_price
+        from genai_prices.types import Usage
+
+        calc = calc_price(
+            Usage(input_tokens=input_tokens, output_tokens=output_tokens),
+            model_ref=_model_ref(model),
+        )
+    except Exception:
+        return _UNKNOWN
+
+    total = float(calc.total_price)
+    input_price = float(getattr(calc, "input_price", 0) or 0)
+    output_price = float(getattr(calc, "output_price", 0) or 0)
+    if input_price == 0 and output_price == 0 and total:
+        total_tokens = max(input_tokens + output_tokens, 1)
+        input_price = total * input_tokens / total_tokens
+        output_price = total * output_tokens / total_tokens
+    return CostBreakdown(total, input_price, output_price, True)