agentstep 0.1.1__py3-none-any.whl

agentstep/sdk/exporter.py

@@ -0,0 +1,71 @@
+import sqlite3
+import json
+from typing import Sequence
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace import ReadableSpan
+
+class ReplayOtelExporter(SpanExporter):
+    """
+    Exports OpenTelemetry spans directly to a local SQLite database in the `otel_spans` table.
+    """
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+        self._init_db()
+
+    def _init_db(self):
+        cursor = self.conn.cursor()
+        cursor.execute('''
+            CREATE TABLE IF NOT EXISTS otel_spans (
+                span_id TEXT PRIMARY KEY,
+                trace_id TEXT,
+                parent_span_id TEXT,
+                name TEXT,
+                start_time INTEGER,
+                end_time INTEGER,
+                attributes TEXT,
+                events TEXT,
+                status_code TEXT,
+                thread_id TEXT
+            )
+        ''')
+        # Index on thread_id for fast lookup during branch replay
+        cursor.execute('CREATE INDEX IF NOT EXISTS idx_otel_spans_thread_id ON otel_spans (thread_id)')
+        self.conn.commit()
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        cursor = self.conn.cursor()
+        
+        for span in spans:
+            attrs = dict(span.attributes) if span.attributes else {}
+            thread_id = attrs.get("lg.thread_id")
+            
+            events = []
+            for event in span.events:
+                events.append({
+                    "name": event.name,
+                    "timestamp": event.timestamp,
+                    "attributes": dict(event.attributes) if event.attributes else {}
+                })
+            
+            cursor.execute('''
+                INSERT OR REPLACE INTO otel_spans 
+                (span_id, trace_id, parent_span_id, name, start_time, end_time, attributes, events, status_code, thread_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ''', (
+                str(span.context.span_id),
+                str(span.context.trace_id),
+                str(span.parent.span_id) if span.parent else None,
+                span.name,
+                span.start_time,
+                span.end_time,
+                json.dumps(attrs),
+                json.dumps(events),
+                span.status.status_code.name if span.status else "UNSET",
+                str(thread_id) if thread_id else None
+            ))
+            
+        self.conn.commit()
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        pass

agentstep/sdk/tracer.py

@@ -0,0 +1,118 @@
+import functools
+import sqlite3
+import os
+import json
+from contextlib import contextmanager
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.messages import BaseMessage
+from langchain_core.outputs import LLMResult
+
+from agentstep.sdk.exporter import ReplayOtelExporter
+
+tracer_provider = None
+
+def setup_otel(sqlite_path: str = "trace.sqlite"):
+    global tracer_provider
+    if tracer_provider is not None:
+        return
+        
+    conn = sqlite3.connect(sqlite_path, check_same_thread=False)
+    exporter = ReplayOtelExporter(conn)
+    
+    tracer_provider = TracerProvider()
+    tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
+    trace.set_tracer_provider(tracer_provider)
+
+class ReplayCallbackHandler(BaseCallbackHandler):
+    """
+    A LangChain callback handler that emits OpenTelemetry spans for LLMs and Tools,
+    enriching them with the LangGraph thread_id and optional branch_id.
+    """
+    def __init__(self, thread_id: str, branch_id: str | None = None):
+        self.thread_id = thread_id
+        self.branch_id = branch_id
+        self.tracer = trace.get_tracer("agentstep")
+        self.spans = {}  # run_id -> Span
+
+    def _set_branch_attrs(self, span):
+        span.set_attribute("lg.thread_id", self.thread_id)
+        if self.branch_id:
+            span.set_attribute("lg.branch_id", self.branch_id)
+
+    def on_llm_start(self, serialized: dict, prompts: list[str], *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs):
+        span = self.tracer.start_span("llm_call")
+        self._set_branch_attrs(span)
+        span.set_attribute("gen_ai.system", "langgraph")
+        if prompts:
+            span.set_attribute("gen_ai.prompt", prompts[0])
+        self.spans[str(run_id)] = span
+
+    def on_llm_end(self, response: LLMResult, *, run_id, parent_run_id=None, **kwargs):
+        span = self.spans.get(str(run_id))
+        if span:
+            # Capture output if available
+            if response.generations and response.generations[0]:
+                span.set_attribute("gen_ai.completion", response.generations[0][0].text)
+            
+            # Capture token usage
+            if response.llm_output and "token_usage" in response.llm_output:
+                usage = response.llm_output["token_usage"]
+                if "prompt_tokens" in usage:
+                    span.set_attribute("gen_ai.usage.input_tokens", usage["prompt_tokens"])
+                if "completion_tokens" in usage:
+                    span.set_attribute("gen_ai.usage.output_tokens", usage["completion_tokens"])
+            
+            span.end()
+            del self.spans[str(run_id)]
+
+    def on_tool_start(self, serialized: dict, input_str: str, *, run_id, parent_run_id=None, tags=None, metadata=None, **kwargs):
+        span = self.tracer.start_span("tool_call")
+        self._set_branch_attrs(span)
+        span.set_attribute("gen_ai.tool.name", serialized.get("name", "unknown_tool"))
+        span.set_attribute("gen_ai.tool.input", input_str)
+        self.spans[str(run_id)] = span
+
+    def on_tool_end(self, output: str, *, run_id, parent_run_id=None, **kwargs):
+        span = self.spans.get(str(run_id))
+        if span:
+            span.set_attribute("gen_ai.tool.output", str(output))
+            span.end()
+            del self.spans[str(run_id)]
+
+    def on_tool_error(self, error: BaseException, *, run_id, parent_run_id=None, **kwargs):
+        span = self.spans.get(str(run_id))
+        if span:
+            span.record_exception(error)
+            span.end()
+            del self.spans[str(run_id)]
+
+@contextmanager
+def replay_trace(config: dict, sqlite_path: str = "trace.sqlite", branch_id: str | None = None):
+    """
+    Context manager to wrap LangGraph executions and inject the OTel callback handler.
+    Example:
+        config = {"configurable": {"thread_id": "123"}}
+        with replay_trace(config):
+            graph.invoke(input_data, config=config)
+    """
+    setup_otel(sqlite_path)
+    
+    thread_id = config.get("configurable", {}).get("thread_id", "default_thread")
+    
+    handler = ReplayCallbackHandler(thread_id, branch_id=branch_id)
+    
+    # Inject the handler into the config's callbacks
+    callbacks = config.get("callbacks", [])
+    if isinstance(callbacks, list):
+        callbacks.append(handler)
+    else:
+        callbacks = [callbacks, handler]
+    
+    config["callbacks"] = callbacks
+    
+    yield config

agentstep/server/api.py

@@ -0,0 +1,222 @@
+import sqlite3
+import json
+import uuid
+from typing import Any, Dict, List, Optional
+from fastapi import FastAPI, HTTPException, Request
+from pydantic import BaseModel
+
+from agentstep.server.replayer import replay_branch
+from agentstep.sdk.tracer import replay_trace
+
+from langchain_core.messages import ToolMessage, AIMessage
+
+app = FastAPI(title="Agent Replay Debugger")
+
+
+class BranchRequest(BaseModel):
+    thread_id: str
+    checkpoint_id: str
+    node_name: str
+    span_type: str
+    tool_call_id: Optional[str] = None  # tool *name* sent by the UI
+    new_output: str
+
+
+# ── Threads ────────────────────────────────────────────────────
+
+@app.get("/api/threads")
+def list_threads(request: Request):
+    conn: sqlite3.Connection = request.app.state.db_conn
+    cursor = conn.cursor()
+    cursor.execute("SELECT DISTINCT thread_id FROM otel_spans WHERE thread_id IS NOT NULL")
+    return {"threads": [row[0] for row in cursor.fetchall()]}
+
+
+# ── Traces ─────────────────────────────────────────────────────
+
+@app.get("/api/traces/{thread_id}")
+def get_traces(thread_id: str, request: Request):
+    conn: sqlite3.Connection = request.app.state.db_conn
+    cursor = conn.cursor()
+
+    cursor.execute("""
+        SELECT span_id, parent_span_id, name, start_time, end_time,
+               attributes, events, status_code
+        FROM otel_spans
+        WHERE thread_id = ?
+        ORDER BY start_time ASC
+    """, (thread_id,))
+
+    rows = cursor.fetchall()
+    spans = [
+        {
+            "span_id": r[0],
+            "parent_span_id": r[1],
+            "name": r[2],
+            "start_time": r[3],
+            "end_time": r[4],
+            "attributes": json.loads(r[5]) if r[5] else {},
+            "events": json.loads(r[6]) if r[6] else [],
+            "status_code": r[7],
+        }
+        for r in rows
+    ]
+
+    # Group spans by lg.branch_id (original trace has no branch_id)
+    groups: dict[str | None, list] = {}
+    for s in spans:
+        bid = s["attributes"].get("lg.branch_id")
+        if bid not in groups:
+            groups[bid] = []
+        groups[bid].append(s)
+
+    # Order: original first (branch_id=None), then branches by first span's start_time
+    def sort_key(item):
+        bid, spans = item
+        first_ts = spans[0]["start_time"] if spans else 0
+        return (1 if bid is None else 0, first_ts)
+
+    branches = []
+    for bid, branch_spans in sorted(groups.items(), key=sort_key):
+        is_original = bid is None
+
+        # Compute fork_point: the span immediately before this branch's first span
+        fork_point = None
+        if not is_original and branch_spans:
+            for i, s in enumerate(spans):
+                if s["span_id"] == branch_spans[0]["span_id"]:
+                    if i > 0:
+                        fork_point = spans[i - 1]["span_id"]
+                    break
+
+        branches.append({
+            "branch_id": bid if not is_original else "__original__",
+            "is_original": is_original,
+            "spans": branch_spans,
+            "meta": {
+                "span_count": len(branch_spans),
+                "fork_point": fork_point,
+            },
+        })
+
+    return {"branches": branches}
+
+
+# ── Checkpoints ────────────────────────────────────────────────
+
+@app.get("/api/traces/{thread_id}/checkpoints")
+def get_checkpoints(thread_id: str, request: Request):
+    """Return checkpoints with their *next* node info for matching to spans."""
+    graph = request.app.state.graph
+    if not graph:
+        return {"checkpoints": []}
+
+    config = {"configurable": {"thread_id": thread_id}}
+    history = list(graph.get_state_history(config))
+
+    checkpoints = []
+    for state in history:
+        cp = {
+            "checkpoint_id": state.config["configurable"]["checkpoint_id"],
+            "next": list(state.next) if state.next else [],
+            "has_messages": bool(state.values.get("messages")),
+        }
+        checkpoints.append(cp)
+
+    return {"checkpoints": checkpoints}
+
+
+# ── Branch replay ──────────────────────────────────────────────
+
+@app.post("/api/branch")
+def branch_replay(req: BranchRequest, request: Request):
+    graph = request.app.state.graph
+    if not graph:
+        raise HTTPException(400, "Graph not loaded — pass --app <module:graph>")
+
+    config = {
+        "configurable": {
+            "thread_id": req.thread_id,
+            "checkpoint_id": req.checkpoint_id,
+        }
+    }
+
+    # Sanity-check the checkpoint exists and extract the state
+    try:
+        snapshot = graph.get_state(config)
+    except Exception as e:
+        raise HTTPException(400, f"Checkpoint {req.checkpoint_id} not found: {e}")
+
+    full_config = snapshot.config
+
+    # Ensure checkpoint_ns is present — LangGraph requires it when
+    # resuming from a checkpoint.
+    full_config.setdefault("configurable", {})
+    if "checkpoint_ns" not in full_config["configurable"]:
+        full_config["configurable"]["checkpoint_ns"] = ""
+
+    # ── Resolve real tool_call_id ──────────────────────────────
+    # The UI sends the tool *name* (e.g. "get_weather") as
+    # tool_call_id.  We need to find the actual ID from the
+    # AIMessage tool_calls in the checkpoint state.
+    if req.span_type == "tool_call":
+        tool_name = req.tool_call_id or ""
+        messages = snapshot.values.get("messages", [])
+        real_tool_call_id = None
+
+        for msg in reversed(messages):
+            if hasattr(msg, "tool_calls") and msg.tool_calls:
+                for tc in msg.tool_calls:
+                    if isinstance(tc, dict) and tc.get("name") == tool_name:
+                        real_tool_call_id = tc["id"]
+                        break
+                    elif hasattr(tc, "name") and tc.name == tool_name:
+                        real_tool_call_id = tc.id
+                        break
+                if real_tool_call_id:
+                    break
+
+        if not real_tool_call_id:
+            raise HTTPException(
+                400,
+                f"No tool call named '{tool_name}' found in checkpoint state "
+                f"(messages: {len(messages)}). Available tool calls: "
+                + ", ".join(
+                    tc.get("name", tc.name) if isinstance(tc, dict) else tc.name
+                    for msg in messages if hasattr(msg, "tool_calls")
+                    for tc in (msg.tool_calls or [])
+                ),
+            )
+
+        overridden_msg = ToolMessage(
+            content=req.new_output,
+            tool_call_id=real_tool_call_id,
+        )
+        node = req.node_name or "tools"
+
+    elif req.span_type == "llm_call":
+        overridden_msg = AIMessage(content=req.new_output)
+        node = req.node_name or "agent"
+
+    else:
+        raise HTTPException(400, f"Unsupported span_type: {req.span_type}")
+
+    # ── Replay ─────────────────────────────────────────────────
+    branch_id = f"branch_{uuid.uuid4().hex[:12]}"
+    try:
+        with replay_trace(full_config, sqlite_path=request.app.state.db_path, branch_id=branch_id):
+            result = replay_branch(
+                graph=graph,
+                config=full_config,
+                node_name=node,
+                new_values={"messages": [overridden_msg]},
+            )
+    except Exception as e:
+        raise HTTPException(500, f"Branch replay failed: {e}")
+
+    return {
+        "status": "ok",
+        "thread_id": req.thread_id,
+        "branch_id": branch_id,
+        "checkpoint_id": full_config["configurable"].get("checkpoint_id"),
+    }

agentstep/server/cli.py

@@ -0,0 +1,150 @@
+import argparse
+import importlib
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+import uvicorn
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import HTMLResponse, FileResponse
+
+from agentstep.server.api import app
+from agentstep.sdk.tracer import setup_otel
+from langgraph.checkpoint.sqlite import SqliteSaver
+
+
+def _resolve_ui_build() -> Path | None:
+    """Walk up from the package dir looking for ui/dist, then try CWD."""
+    # The package lives at <repo>/src/agentstep/server/cli.py
+    # We want <repo>/ui/dist — three levels up from this file.
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parents[2] / "ui" / "dist",   # repo-rooted: src/agentstep/server -> src/agentstep -> src -> repo
+        Path.cwd() / "ui" / "dist",
+        Path.cwd() / "dist",
+    ]
+    for p in candidates:
+        if (p / "index.html").is_file():
+            return p
+    return None
+
+
+def parse_app_string(app_str: str):
+    """Import a LangGraph from ``module:graph`` or ``module.graph``."""
+    if ":" in app_str:
+        module_path, attr = app_str.split(":", 1)
+    elif "." in app_str:
+        module_path, attr = app_str.rsplit(".", 1)
+    else:
+        raise ValueError("Use module:graph or module.graph syntax")
+
+    if "" not in sys.path and "." not in sys.path:
+        sys.path.insert(0, "")
+
+    module = importlib.import_module(module_path)
+    graph = getattr(module, attr)
+
+    if callable(graph) and not hasattr(graph, "invoke"):
+        graph = graph()
+
+    return graph
+
+
+def _mount_spa(ui_path: Path) -> None:
+    """Mount the built React app at /, with SPA fallback to index.html.
+
+    Order matters: StaticFiles is mounted AFTER the FastAPI app already
+    registered /api/* routes, but Starlette matches more-specific paths
+    first, so API calls still work. The catch-all on / serves real files
+    (CSS, JS) and falls back to index.html for client-side routes.
+    """
+    # Serve static assets (hashed files in /assets/) directly
+    app.mount(
+        "/assets",
+        StaticFiles(directory=str(ui_path / "assets")),
+        name="assets",
+    )
+    app.mount(
+        "/favicon.svg",
+        StaticFiles(directory=str(ui_path), html=False),
+        name="favicon",
+    )
+
+    @app.get("/", include_in_schema=False)
+    @app.get("/{full_path:path}", include_in_schema=False)
+    async def spa(full_path: str = ""):
+        # If a real file exists in the dist dir (e.g. icons.svg), serve it.
+        target = ui_path / full_path
+        if full_path and target.is_file():
+            return FileResponse(str(target))
+        # Otherwise, SPA fallback to index.html.
+        return FileResponse(str(ui_path / "index.html"))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Agent Replay Debugger")
+    parser.add_argument("db", help="Path to trace SQLite database (e.g. trace.sqlite)")
+    parser.add_argument(
+        "--app", required=True,
+        help="Import path to the compiled LangGraph (e.g. sample:graph)",
+    )
+    parser.add_argument("--port", type=int, default=7337, help="Port to serve on")
+    parser.add_argument(
+        "--dev-ui", action="store_true",
+        help="Backend-only mode for development. Disables the bundled UI. "
+             "Start the Vite dev server separately (cd ui && npm run dev).",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Host to bind to (default 127.0.0.1). Use 0.0.0.0 for LAN access.",
+    )
+
+    args = parser.parse_args()
+
+    print(f"Loading graph from {args.app}…")
+    try:
+        graph = parse_app_string(args.app)
+    except Exception as e:
+        print(f"Failed to load graph: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Connecting to {args.db}…")
+    conn = sqlite3.connect(args.db, check_same_thread=False)
+    setup_otel(args.db)
+
+    checkpointer = SqliteSaver(conn)
+    checkpointer.setup()
+
+    app.state.db_conn = conn
+    app.state.db_path = args.db
+    app.state.graph = graph
+    app.state.checkpointer = checkpointer
+
+    if args.dev_ui:
+        print(
+            "Dev UI mode: bundled UI disabled.\n"
+            "  Start the Vite dev server in another terminal:\n"
+            "    cd ui && npm install && npm run dev\n"
+            "  Then open http://localhost:5173"
+        )
+    
+    if not args.dev_ui:
+        ui_path = _resolve_ui_build()
+        if ui_path is not None:
+            print(f"Serving UI from {ui_path}")
+            _mount_spa(ui_path)
+        else:
+            print(
+                "WARNING: UI build not found.\n"
+                "  Run from ui/: npm run build\n"
+                "  Or start the Vite dev server on :5173 and pass --no-ui.",
+                file=sys.stderr,
+            )
+
+    print(f"Replay Debugger -> http://{args.host}:{args.port}")
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

agentstep/server/replayer.py

@@ -0,0 +1,72 @@
+from typing import Any
+
+
+def replay_branch(
+    graph: Any,
+    config: dict,
+    node_name: str,
+    new_values: dict | Any,
+) -> dict:
+    """Fork execution from a specific checkpoint with modified values.
+
+    Args:
+        graph: The compiled LangGraph with a checkpointer.
+        config: Config containing ``thread_id`` and optionally ``checkpoint_id``.
+        node_name: The node to associate the new values with (e.g. ``"tools"``).
+        new_values: State update dict (e.g. ``{"messages": [ToolMessage(...)]}``).
+
+    Returns:
+        The final state after the branched execution completes.
+    """
+    # 1. Validate the graph has a checkpointer
+    if not getattr(graph, "checkpointer", None):
+        raise ValueError(
+            "Graph must have a checkpointer to replay branches. "
+            "Compile with e.g. checkpointer=SqliteSaver(conn)."
+        )
+
+    # 2. Validate the checkpoint exists
+    try:
+        snapshot = graph.get_state(config)
+    except Exception as e:
+        raise ValueError(
+            f"Could not load checkpoint for config {config}: {e}"
+        ) from e
+
+    # 3. Validate the node exists in the graph
+    if node_name not in graph.nodes:
+        raise ValueError(
+            f"Node '{node_name}' not found in graph. "
+            f"Available: {list(graph.nodes.keys())}"
+        )
+
+    # 4. Create a branched checkpoint with the overridden state
+    new_config = graph.update_state(
+        config=snapshot.config,
+        values=new_values,
+        as_node=node_name,
+    )
+
+    # Ensure checkpoint_ns is present — required by LangGraph for
+    # resuming from a checkpoint via invoke() on some versions.
+    new_config.setdefault("configurable", {})
+    if "checkpoint_ns" not in new_config["configurable"]:
+        new_config["configurable"]["checkpoint_ns"] = (
+            snapshot.config.get("configurable", {}).get("checkpoint_ns", "")
+        )
+
+    # Propagate callbacks from the original config so the tracer
+    # works during the branched execution.
+    if "callbacks" in config:
+        new_config["callbacks"] = config["callbacks"]
+
+    # 5. Resume from the new branch
+    try:
+        return graph.invoke(None, config=new_config)
+    except Exception as e:
+        partial = graph.get_state(new_config)
+        return {
+            "status": "partial",
+            "error": str(e),
+            "checkpoint_id": partial.config["configurable"].get("checkpoint_id"),
+        }

agentstep-0.1.1.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: agentstep
+Version: 0.1.1
+Summary: Time-travel debugger and branch explorer for LangGraph AI agents. Capture execution traces, inspect LLM and tool calls, and branch from any point with overridden outputs.
+Project-URL: Homepage, https://github.com/vanshvisariya/agentstep
+Project-URL: Repository, https://github.com/vanshvisariya/agentstep
+Project-URL: Issues, https://github.com/vanshvisariya/agentstep/issues
+Author-email: vansh visariya <vanshvisariya.workdev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,branch,debugger,langgraph,llm,opentelemetry,otel,replay,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.138.0
+Requires-Dist: langchain-groq>=1.1.3
+Requires-Dist: langchain-openai>=1.3.3
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0
+Requires-Dist: langgraph>=1.2.6
+Requires-Dist: opentelemetry-api>=1.43.0
+Requires-Dist: opentelemetry-sdk>=1.43.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.64b0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: uvicorn>=0.49.0
+Description-Content-Type: text/markdown
+
+# Agent Step
+
+A time-travel debugger and branch explorer for **[LangGraph](https://langchain-ai.github.io/langgraph/)** agents. Capture every LLM call and tool invocation as a span, browse them in a web timeline, then **branch from any point** — override the output and replay to see how the rest of the graph would behave differently.
+
+Think `pdb` + a REPL for agent workflows, with a SQLite file you can hand to a teammate.
+
+---
+
+## Why you'd use it
+
+When an agent goes off the rails, you usually want to answer one of:
+
+- *"What did the LLM actually say at step 4?"* — captured.
+- *"What would have happened if the weather tool returned snow instead of fog?"* — **branch and replay.**
+- *"Why did the agent loop?"* — the timeline shows every call with timing and full prompts/outputs.
+
+Without this, you're adding `print()` statements and re-running with a different seed. With this, you replay against the original trace.
+
+---
+
+## Install
+
+```bash
+pip install agentstep
+```
+
+Or from the repo (development):
+
+```bash
+git clone https://github.com/vanshvisariya/agent-replay
+cd agent-replay
+pip install -e .
+```
+
+Requires **Python 3.13+**.
+
+---
+
+## Quick start
+
+This walks through using Agent Replay on a LangGraph agent in your own project.
+
+### 1. Wrap your graph execution
+
+The SDK exposes one thing: `replay_trace`, a context manager that instruments your graph with OpenTelemetry callbacks and writes spans to a SQLite file.
+
+```python
+from langgraph.graph import StateGraph, START, END
+from agent_replay.sdk.tracer import replay_trace
+
+# build your compiled graph the way you already do
+graph = ...
+
+# a thread_id identifies one conversation/run in the trace
+config = {"configurable": {"thread_id": "user-42"}}
+
+with replay_trace(config, sqlite_path="trace.sqlite") as cfg:
+    for chunk in graph.stream(inputs, cfg, stream_mode="values"):
+        print(chunk)
+```
+
+That's the entire API surface for instrumentation. The context manager:
+
+1. Sets up an OpenTelemetry tracer pointed at your SQLite file.
+2. Injects a callback handler into `config["callbacks"]`.
+3. Records every `llm_call` and `tool_call` span with timing, prompts, completions, and outputs.
+
+The original `config` is mutated in place; you don't need to swap it back.
+
+### 2. Launch the debugger
+
+In a terminal:
+
+```bash
+replay-debugger trace.sqlite --app my_module:graph
+```
+
+- `trace.sqlite` is the file you wrote spans to.
+- `--app my_module:graph` is a Python import path to your compiled graph. Three forms work:
+  - `my_module:graph` — `graph` is a compiled LangGraph instance.
+  - `my_module.graph` — same thing, dotted form.
+  - `my_module:make_graph` — `make_graph` is a callable that returns a compiled graph (it gets called at startup).
+
+Open <http://localhost:7337>.
+
+You should see your thread in the left sidebar and a timeline of spans on the right.
+
+### 3. Branch from any span
+
+1. Click any span — the right panel shows the checkpoint, attributes, and full completion.
+2. Click **branch from here**.
+3. Edit the override output (new tool result or new LLM completion).
+4. Click **run_branch**.
+
+The original trace stays intact. The fork becomes a new branch in the timeline, labeled with a small `b0` chip, color-coded so you can tell at a glance which branch you're looking at.
+
+---
+
+## What gets captured
+
+| Span type | What's recorded |
+|---|---|
+| `llm_call` | prompt, completion, system, input/output token counts, wall time |
+| `tool_call` | tool name, input string, output string, wall time |
+
+Every span carries:
+
+- `lg.thread_id` — the LangGraph `thread_id` so spans from one conversation group together.
+- `lg.branch_id` — set automatically on spans created during a branch replay, so the debugger can group them separately.
+
+Other graph node executions, sub-graphs, and conditional edges are not yet instrumented as spans — but the checkpoint data is still preserved by LangGraph itself, so branch replay works regardless.
+
+---
+
+## Working example
+
+The repo ships a runnable demo (`sample.py`) with a fake LLM so you don't need any API keys:
+
+```bash
+git clone https://github.com/vanshvisariya/replay
+cd agent-replay
+pip install -e .
+python sample.py                              # writes trace.sqlite
+replay-debugger trace.sqlite --app sample:graph
+```
+
+Then open <http://localhost:7337>. Click the LLM call → click **branch from here** → change the response → watch the timeline fork.
+
+---
+
+## Development workflow
+
+When hacking on the debugger itself, run the backend and frontend with hot reload:
+
+```bash
+# Terminal 1 — backend on :7337, API only
+replay-debugger trace.sqlite --app sample:graph --dev-ui
+
+# Terminal 2 — Vite dev server on :5173 (proxies /api/* to :7337)
+cd ui
+npm install
+npm run dev
+```
+
+Open <http://localhost:5173> instead. Edits to React files hot-reload; backend edits need a restart.
+
+---
+
+## Programmatic branch replay
+
+The web UI is the main way to branch, but the same operation is available as a function for scripted use:
+
+```python
+from agent_replay.server.replayer import replay_branch
+
+result = replay_branch(
+    thread_id="user-42",
+    checkpoint_id="1efb...",          # from GET /api/traces/{tid}/checkpoints
+    node_name="tools",                 # or "agent"
+    span_type="tool_call",             # or "llm_call"
+    tool_call_id="get_weather",        # tool name for tool spans
+    new_output="It's snowing in SF.",
+    db_path="trace.sqlite",
+)
+print(result)  # branch_id of the new replay
+```
+
+Useful for regression tests, CI, or batch-exploration of failure modes.
+
+---
+
+## API reference
+
+The FastAPI server (started by the `replay-debugger` CLI) exposes:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/threads` | List all thread IDs in the database. |
+| `GET` | `/api/traces/{thread_id}` | All spans for a thread, grouped by branch. |
+| `GET` | `/api/traces/{thread_id}/checkpoints` | All checkpoints for a thread. |
+| `POST` | `/api/branch` | Fork the graph from a checkpoint with an overridden output. |
+
+`POST /api/branch` body:
+
+```json
+{
+  "thread_id": "user-42",
+  "checkpoint_id": "1efb...",
+  "node_name": "agent",
+  "span_type": "llm_call",
+  "tool_call_id": null,
+  "new_output": "The weather is sunny and 72°F."
+}
+```
+
+Response: `{"branch_id": "branch_a1b2c3...", "status": "ok"}`.
+
+---
+
+## Where things live in your file
+
+After running the demo once:
+
+```
+trace.sqlite
+├── spans table        ← every llm_call / tool_call, with start/end nanoseconds + JSON attributes
+├── checkpoints table  ← LangGraph state snapshots (one per node execution)
+└── thread metadata    ← implicit, keyed off lg.thread_id in span attributes
+```
+
+Everything is one file. Copy it, share it, commit it for reproduction.
+
+---
+
+## Limitations
+
+- **Python 3.13+ only** — pinned in `pyproject.toml`.
+- **LangGraph checkpointers must use SQLite** — `SqliteSaver` is the only supported backend currently; the branch endpoint reads from the same file the tracer wrote to.
+- **No remote export** — spans stay local. (The exporter is OpenTelemetry-native, so wiring Jaeger/Zipkin out the side is doable but not built in.)
+- **Two span types** — only LLM and tool calls. If you want full graph-node tracing, file an issue.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/vanshvisariya/agent-replay
+cd agent-replay
+pip install -e .
+cd ui && npm install
+```
+
+Layout:
+
+```
+src/agent_replay/
+├── sdk/
+│   ├── tracer.py        ← replay_trace() + ReplayCallbackHandler
+│   └── exporter.py      ← OTel span exporter → SQLite
+└── server/
+    ├── api.py           ← FastAPI endpoints
+    ├── replayer.py      ← branch replay logic (used by API + programmatic)
+    └── cli.py           ← `replay-debugger` entry point
+ui/
+└── src/App.tsx          ← single-file React app
+sample.py                ← runnable weather-agent demo
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

agentstep-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentstep/sdk/exporter.py,sha256=FJf7R69nISXjBjhjjF54iA_h7AiiO2_GYxA83-walVQ,2641
+agentstep/sdk/tracer.py,sha256=gmSg4nyqsCYHuURJ75GrR2NUrahLSXZ_Hic4RCqOpsg,4701
+agentstep/server/api.py,sha256=ePvyKC7UN2YO4t02h-VcghFNT5zecvfQ96Z4KMAMO7Y,8272
+agentstep/server/cli.py,sha256=Tmz2IaYIAF38yCxQdQGy4UAXPugJ_dMTwQ9r9q1mGvI,5061
+agentstep/server/replayer.py,sha256=v58H_tkD36RsRfCIOeHxCQkexHieMXZipD2FakUR7BA,2512
+agentstep-0.1.1.dist-info/METADATA,sha256=X-X8iN4ybCZnXhQmJ98bSRPS1qovuq4uG-_2g4d97m8,9403
+agentstep-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentstep-0.1.1.dist-info/entry_points.txt,sha256=591qUoQFp-P9_3_ewiGmj04DwvN83cAl5qB8IVHhKqI,62
+agentstep-0.1.1.dist-info/licenses/LICENSE,sha256=J4oigRWzmkf4ySJTfap_VMVYs5-nv4YFrKZwRQ7rjKY,1090
+agentstep-0.1.1.dist-info/RECORD,,

agentstep-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

agentstep-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+replay-debugger = agentstep.server.cli:main

agentstep-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vansh visariya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.