Metadata-Version: 2.4
Name: retrace-ai
Version: 0.1.0
Summary: Deterministic record/replay + causal-diff flight recorder for AI agents
Project-URL: Homepage, https://arnpal961.github.io/retrace/
Project-URL: Repository, https://github.com/arnpal961/retrace
Project-URL: Documentation, https://github.com/arnpal961/retrace/tree/main/docs
Project-URL: Live viewer, https://arnpal961.github.io/retrace/viewer/
Project-URL: Changelog, https://github.com/arnpal961/retrace/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/arnpal961/retrace/issues
Author: Arnab Pal
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,debugging,determinism,llm,observability,pytest,record-replay,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: flake8>=7; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Retrace

[![CI](https://github.com/arnpal961/retrace/actions/workflows/ci.yml/badge.svg)](https://github.com/arnpal961/retrace/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/retrace-ai.svg)](https://pypi.org/project/retrace-ai/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.13%2B-blue.svg)](pyproject.toml)

**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](https://arnpal961.github.io/retrace/)** ·
**[Live viewer](https://arnpal961.github.io/retrace/viewer/)** — time-travel through a trace in your
browser, no install.

Built by [Arnab Pal](https://arnabpal.me).

> 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/`](plan/).

<p align="center">
  <img src="docs/demo/reproduce-the-flake.gif" alt="Retrace pinning the root cause of a non-deterministic agent failure to one event" width="820">
  <br><em>Two runs of the same agent diverge — <code>retrace diff</code> pins the root cause to one event and shows the propagation chain.</em>
</p>

## 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](docs/diffing.md))

## Install

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

## Try it

```bash
# 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 and open viewer/index.html in a browser to time-travel through it
python -m retrace.cli export /tmp/weather.flight
```

## Documentation

Full docs live in [`docs/`](docs/): [getting started](docs/getting-started.md),
[concepts](docs/concepts.md), [guide](docs/guide.md), [diffing](docs/diffing.md),
[testing](docs/testing.md), [observability](docs/observability.md), [integrations](docs/integrations.md),
[API reference](docs/api-reference.md), [CLI](docs/cli.md), [trace format](docs/trace-format.md),
[limitations](docs/limitations.md), and [FAQ](docs/faq.md).

The `.flight` trace format is a language-neutral open standard — see [`SPEC.md`](SPEC.md) and
[`schema/flight-event.schema.json`](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`](REFERENCES.md).

## Design

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

## Contributing

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

## License

Apache-2.0 — see [`LICENSE`](LICENSE).
