Retrace

A deterministic record / replay + causal-diff "flight recorder" for AI agents.

Record any agent run as a tamper-evident, replayable event log; reproduce failures exactly; diff two runs to find where — and why — they diverged.

Project site · Live viewer — time-travel through a trace in your browser, no install.

Built by Arnab Pal.

Status: pre-alpha (0.1.0). Record → replay → verify, streaming (SSE) capture, the causal diff (incl. cross-version), zero-code-change auto-wrap (sync + async), a semantic LLM layer, an OpenTelemetry bridge, a time-travel viewer, and a pytest regression plugin all work. Architecture and design docs live in plan/.

Two runs of the same agent diverge — retrace diff pins the root cause to one event and shows the propagation chain.

Why

AI agents are non-deterministic: the same input can take wildly different execution paths, and failures live in multi-step causal chains, not single calls — so you can't snapshot-and-replay them. There's no framework-agnostic, open standard for capturing an agent run and reproducing it.

Retrace applies distributed-systems record/replay rigor — event sourcing, deterministic replay, hash-linked logs, causal tracing — to the agent-reliability problem.

What it does

• retrace record — capture every source of non-determinism (LLM completions, tool results, retrieval, clock, RNG) at the httpx transport layer + a @retrace.tool decorator, into an append-only, hash-linked .flight trace. Auto-wraps httpx clients, so wrapping a run in with retrace.record(...) is the only code change; large payloads spill to a content-addressed blob store.
• retrace replay — re-run your real agent code with every recorded response served from the log, so the exact path reconstructs with zero API calls and zero side effects.
• retrace diff — align two traces, find the first causal divergence, and classify it: model-output drift / tool error / context corruption / retrieval drift / nondeterministic input — showing the propagation chain from root to the symptom you saw. (docs)

Install

pip install retrace-ai          # the import name is `retrace`

Try it

# record + replay a tiny agent offline, then inspect/verify the trace
python examples/weather_agent.py /tmp/weather.flight
python -m retrace.cli inspect /tmp/weather.flight
python -m retrace.cli verify  /tmp/weather.flight

# record two runs where the model drifts, then diff to find the root cause
python examples/flaky_agent.py /tmp/golden.flight /tmp/prod.flight
python -m retrace.cli diff /tmp/golden.flight /tmp/prod.flight

# export a trace, then load it into the viewer to time-travel through it
python -m retrace.cli export /tmp/weather.flight

The commands above run from a clone (examples/ ships in the repo). After pip install retrace-ai the retrace CLI is on your PATH, and exported traces open in the live viewer — no install, nothing uploaded.

Documentation

Full docs live in docs/: getting started, concepts, guide, diffing, testing, observability, integrations, API reference, CLI, trace format, limitations, and FAQ.

The .flight trace format is a language-neutral open standard — see SPEC.md and schema/flight-event.schema.json. The prior art the design builds on (rr, deterministic replay, Certificate Transparency, JCS, sequence/tree diffing, causal attribution) is collected in REFERENCES.md.

Design

Doc	Covers
plan/00-overview.md	Problem, locked decisions, module map, MVP definition-of-done
plan/01-capture-replay.md	Capture + deterministic replay engine
plan/02-trace-format.md	The open .flight trace-format spec
plan/03-causal-diff.md	Causal divergence diff + classification
plan/10-mvp-roadmap.md	Phased build plan (P0–P5)

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, the test workflow, and the load-bearing invariants. Please also read the CODE_OF_CONDUCT.md. Found a security issue? See SECURITY.md (please don't open a public issue). Release history is in CHANGELOG.md.

License

Apache-2.0 — see LICENSE.