Metadata-Version: 2.4
Name: trace-sdk
Version: 0.3.5
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

Trace is local version control for AI agent behavior. It captures structured agent runs, compares behavior across runs, and restores the configuration that produced a trusted run.

```python
import trace_sdk as trace

@trace.track(agent="planner", config={"model": "mock-v1"})
def run_agent(request):
    tools = trace.wrap_tools({"lookup": lookup})
    result = tools["lookup"](request)
    trace.decision("lookup_done", status=result["status"])
    return result
```

## Commands

```bash
trace log
trace show <id>
trace diff <id_a> <id_b>
trace diff <id_a> <id_b> --json
trace revert <id>
trace revert <id> --agent budget_agent
trace serve
trace clear
```

Runs are stored in `.trace/runs/`. Config restored by `trace revert` is stored in `.trace/config.json`.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run python examples/demo_agent.py --variant stable
uv run python examples/demo_agent.py --variant drift
uv run trace log
```

TraceHub lives in `tracehub/`. Build it with `npm install && npm run build`; `trace serve` serves the built assets from `tracehub/dist`.
