Metadata-Version: 2.4
Name: langgraph-replay
Version: 0.1.0
Summary: Time-travel debugging for LangGraph agents — record, replay, fork, and catch regressions from a single SQLite file.
Project-URL: Homepage, https://github.com/devendra116/agent-replay-engine
Project-URL: Documentation, https://github.com/devendra116/agent-replay-engine/blob/main/packages/sdk/README.md
Project-URL: Repository, https://github.com/devendra116/agent-replay-engine
Project-URL: Issues, https://github.com/devendra116/agent-replay-engine/issues
Project-URL: Changelog, https://github.com/devendra116/agent-replay-engine/releases
Author-email: Devendra <chauhandevendra116@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,checkpoints,debugging,deterministic,fork,langchain,langgraph,regression-testing,replay,sqlite,time-travel
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.110
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph-checkpoint>=2.0
Requires-Dist: langgraph>=0.2
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/devendra116/agent-replay-engine/raw/main/docs/logo.svg" alt="LangGraph Replay" width="80" height="80" />
</p>

<h1 align="center">langgraph-replay</h1>

<p align="center">
  <strong>Time-travel debugging for LangGraph agents.</strong><br/>
  Record every step. Replay without API calls. Fork from any checkpoint. Catch regressions before they ship.
</p>

<p align="center">
  <a href="https://pypi.org/project/langgraph-replay/"><img src="https://img.shields.io/pypi/v/langgraph-replay.svg" alt="PyPI" /></a>
  <a href="https://pypi.org/project/langgraph-replay/"><img src="https://img.shields.io/pypi/pyversions/langgraph-replay.svg" alt="Python" /></a>
  <a href="https://github.com/devendra116/agent-replay-engine/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
</p>

---

## Install

```bash
pip install langgraph-replay
```

Requires **Python 3.10+** and a [LangGraph](https://github.com/langchain-ai/langgraph) agent.

## Why langgraph-replay?

LLM agents are non-deterministic. A prompt tweak or model upgrade can silently break routing, and you only discover it in production. langgraph-replay gives you:

- **Full execution history** in a single SQLite file — no external services.
- **Deterministic replay** — substitute recorded LLM + tool responses. Zero API calls, instant re-execution.
- **Regression detection** — real LLM + recorded tools. If the agent routes differently after a code change, you see exactly where it diverged.
- **Fork from any step** — branch, modify inputs, and re-run downstream logic.
- **Built-in dashboard** — timeline, state diffs, and one-click replay/fork in your browser.

## Quick start

```python
from langgraph_replay import ReplayCheckpointer, ReplayCallbackHandler

checkpointer = ReplayCheckpointer(db_path="replay.db")
handler = ReplayCallbackHandler("replay.db")

graph = workflow.compile(checkpointer=checkpointer)
graph.invoke(
    {"messages": [("user", "What's the weather in Tokyo?")]},
    {"configurable": {"thread_id": "run-1"}, "callbacks": [handler]},
)
```

Launch the dashboard:

```bash
langgraph-replay dev --db replay.db
langgraph-replay dev --db replay.db --graph my_agent:build_graph   # enables Re-run and Fork
```

## Features

| Feature | Description |
|---|---|
| **Checkpoint timeline** | Every LangGraph step persisted to SQLite with full state |
| **State diffs** | Message-level and tool-call diffs between any two steps |
| **Fork** | Branch from any checkpoint and re-execute downstream |
| **Re-run / Restart** | Re-execute from step 0 or any mid-run checkpoint |
| **Deterministic replay** | Recorded LLM + tools — no API calls, instant verification |
| **Regression replay** | Live LLM + recorded tools — detect routing drift |

## Dashboard

| Action | What it does |
|---|---|
| **Re-run** | Restart the workflow from step 0 with current code |
| **Fork** | Branch from the selected step with modified inputs |
| **Deterministic** | Replay with fake LLM + tools — verify routing logic |
| **Regression** | Replay with real LLM + fake tools — detect divergence |

## CLI

```bash
# Launch dashboard
langgraph-replay dev --db replay.db --graph my_agent:build_graph

# Restart from a specific step
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --from-step 3

# Deterministic replay (no API calls)
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --mode deterministic

# Regression replay (real LLM, recorded tools)
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --mode regression
```

## Python API

```python
from langgraph_replay import (
    ReplayCheckpointer,
    ReplayCallbackHandler,
    StateDiffEngine,
    ForkManager,
    RestartEngine,
    ReplayRunner,
    DivergenceReport,
    serve,
)

# Restart from a checkpoint
RestartEngine("replay.db", graph).restart("run-1", from_step=3)

# Deterministic replay
ReplayRunner("replay.db", graph).replay("run-1", mode="deterministic")

# Regression replay with divergence report
report = ReplayRunner("replay.db", graph).replay("run-1", mode="regression")
```

## Examples

See the [examples directory](https://github.com/devendra116/agent-replay-engine/tree/main/examples) for a runnable chat agent with tools (`chat_agent.py`).

## Links

- **Repository:** https://github.com/devendra116/agent-replay-engine
- **Issues:** https://github.com/devendra116/agent-replay-engine/issues
- **License:** [MIT](https://github.com/devendra116/agent-replay-engine/blob/main/LICENSE)
