trace-sdk 0.3.8

Local version control for AI agent behavior.

trace-sdk

Local observability for multi-agent AI systems. Capture every model call, tool call, and decision your agent makes — then diff any two runs to see exactly where behavior changed.

Install

pip install trace-sdk

Quick start

import trace_sdk as trace

@trace.track(agent="planner", config={"model": "gemini-2.5-flash", "prompt_id": "v1"})
def run(request):
    llm   = trace.wrap(your_llm_client)        # intercept model calls
    tools = trace.wrap_tools(your_tools)        # intercept tool calls
    trace.decision("route_selected", dest=city) # log branching logic
    return your_existing_code(llm, tools, request)

Runs are written to .trace/runs/ as JSON. Nothing leaves the machine.

CLI

trace log                 # list captured runs
trace show <run_id>       # pretty-print a run
trace diff <id_a> <id_b>  # behavioral diff between two runs
trace snapshot <run_id>   # per-agent input/output snapshot
trace serve               # launch TraceHub at http://localhost:7000
trace clear               # wipe captured runs

API

@trace.track(agent, config)

Decorator that creates a Run record around the decorated function. Supports sync and async functions.

@trace.track(agent="my_agent", config={"model": "gpt-4o", "prompt_id": "v2"})
async def run(input): ...

trace.wrap(client)

Wraps any LLM client so every call is captured as a model_call step.

llm = trace.wrap(openai_client)

trace.wrap_tools(tools_dict)

Wraps a {name: callable} dict so every invocation is captured as a tool_call step.

tools = trace.wrap_tools({"search": search_fn, "lookup": lookup_fn})

trace.span(name)

Context manager that groups steps under a named sub-agent span.

with trace.span("retrieval_agent"):
    ...

trace.decision(label, **meta)

Records a branching decision with arbitrary metadata.

trace.decision("budget_check", passed=True, limit=500)

trace.load_config(agent)

Reads the config last written by trace diff / trace revert from .trace/config.json.

config = trace.load_config("planner")

TraceHub

trace serve launches a local web dashboard with:

• Run list with live updates (SSE)
• Multi-agent column view with per-step detail
• Run diff — step-aligned comparison with inferred cause

Data & privacy

• Inputs and outputs are stored as type + length + SHA-256 hash + capped 1 000-character preview — not verbatim.
• All data is local. No telemetry, no cloud dependency.

Requirements

Python 3.9+