Skip to main content

Retrace

CI PyPI License: Apache-2.0 Python

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/.

Retrace pinning the root cause of a non-deterministic agent failure to one event
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.

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)

Source distribution for retrace-ai 0.1.1
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)

Table of built distributions (wheels) for retrace-ai 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page