Metadata-Version: 2.4
Name: trace-sdk
Version: 0.3.8
Summary: Local version control for AI agent behavior.
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.111
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.30
Requires-Dist: watchfiles>=0.22
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install trace-sdk
```

## Quick start

```python
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

```bash
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.

```python
@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.

```python
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.

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

### `trace.span(name)`
Context manager that groups steps under a named sub-agent span.

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

### `trace.decision(label, **meta)`
Records a branching decision with arbitrary metadata.

```python
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`.

```python
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+
