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 inplan/.
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.tooldecorator, into an append-only, hash-linked.flighttrace. Auto-wrapshttpxclients, so wrapping a run inwith 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.
Metadata
Release files for retrace-ai 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| retrace_ai-0.1.1.tar.gz | 210.1 kB | Without provenance | Details for retrace_ai-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| retrace_ai-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for retrace_ai-0.1.1-py3-none-any.whl |
Total release size: 257.4 kB
Release files / retrace_ai-0.1.1.tar.gz
| Download URL | retrace_ai-0.1.1.tar.gz |
|---|---|
| Size | 210.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
765bffe04b608f3536e28a5c71901e323d5d326e32c57fe7f32434b4fd0ddf37
|
|
BLAKE2b-256 checksum How to use checksums |
acb31f0e028fe95c25efaa869731a2612030d5b9521c8cab7dd0a39091b865a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / retrace_ai-0.1.1-py3-none-any.whl
| Download URL | retrace_ai-0.1.1-py3-none-any.whl |
|---|---|
| Size | 47.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7093269588fc84b460fcd8fad3d64c7d84fece2c9b98bfd4bc3fb23525ee4b52
|
|
BLAKE2b-256 checksum How to use checksums |
1653612cfc67afdcc48b0ad9856236f95f5452cbf4e877c48962101ed692b347
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for retrace-ai 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.