Reel

VCR for LLM APIs. Record real OpenAI / Anthropic / Gemini calls once, replay them deterministically forever — including streaming, tool calls, and timing. No SDK changes. No real network in CI. No surprise spend.

Docs: https://tathagat22.github.io/reel/

The 30-second pitch

# Start once
uv run reel auto -c tape.jsonl

# Point any LLM SDK at the proxy
export OPENAI_BASE_URL=http://127.0.0.1:7878/v1

# Run your code — first run records, every run after replays in ~3ms with $0 spend
python my_app.py

That's the entire workflow. The cassette is plain JSONL: diff it in PRs, grep it, share it. Secrets and PII are scrubbed at capture time, so it's safe to commit.

your code  ─►  127.0.0.1:7878  ─►  reel proxy  ─►  api.openai.com
                                       │
                                       ├── writes JSONL on first call
                                       └── replays on next calls

Why people pick it up

Quickstart

# From PyPI once v0.1.0 is published:
pip install reel-vcr                # distribution name is reel-vcr;
                                     # binary + import path stay `reel`
# Or from source today:
git clone https://github.com/tathagat22/reel && cd reel && uv sync

uv run reel auto -c demo.jsonl &
export OPENAI_BASE_URL=http://127.0.0.1:7878/v1
python -c "from openai import OpenAI; print(OpenAI().chat.completions.create(model='gpt-5', messages=[{'role':'user','content':'Hi'}]).choices[0].message.content)"

Note: the bare reel name on PyPI was already taken by an unrelated async-subprocess library, so the distribution name is reel-vcr. The CLI binary, GitHub repo, and Python import path (import reel) all stay as reel.

Drop into an existing pytest suite

# tests/test_chatbot.py
def test_summarize(reel_cassette):       # ← that's the entire integration
    from openai import OpenAI
    OpenAI().chat.completions.create(...)

The pytest plugin auto-registers; no conftest.py edits needed. First run records to tests/cassettes/test_chatbot/test_summarize.jsonl; subsequent runs replay it.

pytest                           # first time: records (costs real money)
pytest                           # every time after: replays (free, ~3ms)
pytest --reel-mode replay        # CI mode — fails loud on uncaptured calls

Full guide: docs/guides/pytest.md.

Commands

What's in the box

• OpenAI / Anthropic / Gemini — single proxy, routed by path or explicit /<provider>/… URL prefix
• SSE streaming with timing fidelity — chunks captured per-ms; replay reproduces TTFT and inter-chunk gaps; --timing realtime | fast | slow=N
• Four match modes — exact, normalized (default), ignore-fields (great for per-call request_id), fuzzy (embedding similarity, optional reel[fuzzy])
• Capture-time redaction — OpenAI / Anthropic / Google / GitHub / AWS / Slack key shapes + Bearer tokens, always. PII (email + phone) on by default; opt out with REEL_REDACT_PII=0
• pytest plugin — auto-discovered via pytest11 entry point; reel_cassette fixture / @cassette decorator / @pytest.mark.cassette
• Analytics CLI — inspect / cost / diff / stats with composable filters and pricing tables for the major models
• Structured logs — --log-format json for jq-pipeable per-request observability
• JSONL cassettes — git-friendly, append-only, ~5 KB per buffered call
• Pre-commit hook to refuse any cassette that contains a detectable secret
• 344 tests including multi-provider E2E + a pytester-driven plugin suite

Architecture

src/reel/
├── proxy/        # HTTP + SSE core (forwarder, modes, stream, logs)
├── adapters/     # openai · anthropic · gemini (one ProviderAdapter interface)
├── cassette/     # schema · writer · reader · matcher · body codec · store
├── redact/       # secret + PII scrubbing
├── analytics/    # filters · cost · diff · stats (pure over CassetteEntry)
├── inspector/    # `reel ui` — Starlette + HTMX + Pico.css
├── cli/          # typer commands wired into `reel` entry point
└── sdk/          # @cassette decorator + pytest plugin

Deeper dive: docs/architecture.md. Roadmap: docs/SPRINT_SHEET.md.

Status

Sprints 1-6 of 6 are shipped. Currently pre-alpha — usable today from source, PyPI publish + v0.1.0 tag is the last open item.

Development

uv sync
make check         # ruff + pyright (strict) + pytest — must pass before every commit
uv run reel auto -c ./scratch/test.jsonl

CI runs lint + format + typecheck + tests on Python 3.11 / 3.12 / 3.13 — see .github/workflows/ci.yml. Docs deploy to GitHub Pages — .github/workflows/docs.yml.

Contributing

PRs welcome — see CONTRIBUTING.md. The pre-commit hook will refuse any cassette with a detectable secret, so capture won't silently leak.

License

Apache 2.0