replai 0.1.0__tar.gz

replai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

replai-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# replai local data
+.replai/
+*.db
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

replai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+replai is a personal project maintained solely by its author. The source is open
+(MIT licensed) so you are free to use, fork, and adapt it for your own needs.
+
+## Pull requests
+
+External pull requests are **not accepted**. All code is written by the author.
+If you open a PR it will be closed — please don't take it personally, this is just
+how the project is run.
+
+## Bug reports
+
+Bug reports are welcome. If something doesn't work:
+
+1. Open an [issue](../../issues).
+2. Describe what you did, what you expected, and what actually happened.
+3. Include your Python version, replai version, and a minimal example if you can.
+
+Feature ideas are fine to raise in an issue too, but there's no guarantee they'll
+be picked up.
+
+## Fixes
+
+If you've found a bug, report it in an issue — the author will handle the fix.

replai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert
+
+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.

replai-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: replai
+Version: 0.1.0
+Summary: Local-first, framework-agnostic debugger for LLM agents — see, replay, and diff what your agent did.
+Project-URL: Homepage, https://github.com/Rostanic20/replai
+Project-URL: Issues, https://github.com/Rostanic20/replai/issues
+Author: Robert
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,debugging,llm,local-first,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn>=0.27; extra == 'dev'
+Provides-Extra: viewer
+Requires-Dist: fastapi>=0.110; extra == 'viewer'
+Requires-Dist: uvicorn>=0.27; extra == 'viewer'
+Description-Content-Type: text/markdown
+
+# replai
+
+**A local-first debugger for LLM agents.** See exactly what your agent did — every model call, tool call, and decision — step by step. No account, no cloud, no Docker. Just `pip install` and look.
+
+> ⚠️ **Early alpha (v0.1).** The capture engine and local viewer work today. Replay and run-diffing are next on the roadmap.
+
+<!-- TODO: drop a GIF of the timeline view here — this is the most important part of the README. -->
+
+## Why
+
+When an AI agent does the wrong thing, you're usually staring at a wall of logs trying to reconstruct what happened. Production observability platforms exist, but they're heavy — dashboards, servers, accounts — built for *monitoring at scale*, not for the moment you're on your laptop going *"wait, why did it call that tool?"*
+
+`replai` is the other thing: a **debugger** for the dev inner loop. Drop it in, run your agent, and get a clickable, step-by-step timeline of everything it did — locally.
+
+## Install
+
+```sh
+pip install "replai[viewer]"
+```
+
+## Quickstart
+
+```python
+import replai
+replai.init()          # auto-captures Anthropic & OpenAI calls
+
+# ... run your agent exactly as you normally would ...
+```
+
+Then open the viewer:
+
+```sh
+replai ui
+```
+
+Want to annotate your own steps?
+
+```python
+with replai.run("my-agent"):
+    with replai.span("retrieve", type="tool_call") as s:
+        s.output = my_retriever(query)
+```
+
+Or decorate functions and tools:
+
+```python
+@replai.tool
+def web_search(query): ...
+
+@replai.trace
+def plan(goal): ...
+```
+
+### Try it with no API keys
+
+```sh
+python example.py
+replai ui
+```
+
+## How it works
+
+- **Auto-instrumentation** wraps the Anthropic / OpenAI clients, so calls are captured with zero code changes.
+- **`@replai.trace` / `@replai.tool` / `replai.span()`** annotate your own functions and tool calls. Spans nest automatically.
+- Everything is stored in a local **SQLite** file (`~/.replai/replai.db`). Nothing leaves your machine.
+- A small **FastAPI** viewer renders each run as a step-by-step timeline.
+
+## Roadmap
+
+- [x] Capture engine (LLM + tool + function spans, sync & async)
+- [x] Local timeline viewer
+- [ ] **Replay** — step through a run; re-run from any step
+- [ ] **Diff** — compare two runs, highlight where they diverged
+- [ ] Framework adapters (LangChain, LlamaIndex, …)
+- [ ] MCP tool-call capture
+- [ ] OpenTelemetry GenAI export
+
+## License
+
+MIT

replai-0.1.0/README.md

@@ -0,0 +1,80 @@
+# replai
+
+**A local-first debugger for LLM agents.** See exactly what your agent did — every model call, tool call, and decision — step by step. No account, no cloud, no Docker. Just `pip install` and look.
+
+> ⚠️ **Early alpha (v0.1).** The capture engine and local viewer work today. Replay and run-diffing are next on the roadmap.
+
+<!-- TODO: drop a GIF of the timeline view here — this is the most important part of the README. -->
+
+## Why
+
+When an AI agent does the wrong thing, you're usually staring at a wall of logs trying to reconstruct what happened. Production observability platforms exist, but they're heavy — dashboards, servers, accounts — built for *monitoring at scale*, not for the moment you're on your laptop going *"wait, why did it call that tool?"*
+
+`replai` is the other thing: a **debugger** for the dev inner loop. Drop it in, run your agent, and get a clickable, step-by-step timeline of everything it did — locally.
+
+## Install
+
+```sh
+pip install "replai[viewer]"
+```
+
+## Quickstart
+
+```python
+import replai
+replai.init()          # auto-captures Anthropic & OpenAI calls
+
+# ... run your agent exactly as you normally would ...
+```
+
+Then open the viewer:
+
+```sh
+replai ui
+```
+
+Want to annotate your own steps?
+
+```python
+with replai.run("my-agent"):
+    with replai.span("retrieve", type="tool_call") as s:
+        s.output = my_retriever(query)
+```
+
+Or decorate functions and tools:
+
+```python
+@replai.tool
+def web_search(query): ...
+
+@replai.trace
+def plan(goal): ...
+```
+
+### Try it with no API keys
+
+```sh
+python example.py
+replai ui
+```
+
+## How it works
+
+- **Auto-instrumentation** wraps the Anthropic / OpenAI clients, so calls are captured with zero code changes.
+- **`@replai.trace` / `@replai.tool` / `replai.span()`** annotate your own functions and tool calls. Spans nest automatically.
+- Everything is stored in a local **SQLite** file (`~/.replai/replai.db`). Nothing leaves your machine.
+- A small **FastAPI** viewer renders each run as a step-by-step timeline.
+
+## Roadmap
+
+- [x] Capture engine (LLM + tool + function spans, sync & async)
+- [x] Local timeline viewer
+- [ ] **Replay** — step through a run; re-run from any step
+- [ ] **Diff** — compare two runs, highlight where they diverged
+- [ ] Framework adapters (LangChain, LlamaIndex, …)
+- [ ] MCP tool-call capture
+- [ ] OpenTelemetry GenAI export
+
+## License
+
+MIT

replai-0.1.0/example.py

@@ -0,0 +1,45 @@
+"""A runnable demo — no API keys needed.
+
+    python example.py
+    replai ui
+"""
+import time
+
+import replai
+
+replai.init(instrument=False)
+
+
+@replai.tool
+def web_search(query: str):
+    time.sleep(0.15)
+    return [f"result about {query}", "another result"]
+
+
+@replai.trace(name="plan")
+def plan(goal: str):
+    replai.record_llm_call(
+        model="claude-opus-4",
+        input=[{"role": "user", "content": goal}],
+        output="I'll search the web, then summarize.",
+        tokens_in=14, tokens_out=9,
+    )
+    return "search then summarize"
+
+
+def agent(goal: str):
+    with replai.run("demo-agent", goal=goal):
+        plan(goal)
+        hits = web_search("python sqlite tutorial")
+        replai.record_llm_call(
+            model="claude-opus-4",
+            input=str(hits),
+            output="Here is the summary you asked for.",
+            tokens_in=22, tokens_out=18,
+        )
+        return "done"
+
+
+if __name__ == "__main__":
+    agent("learn how to use sqlite in python")
+    print("Recorded a run. Now launch the viewer:\n\n    replai ui\n")

replai-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "replai"
+version = "0.1.0"
+description = "Local-first, framework-agnostic debugger for LLM agents — see, replay, and diff what your agent did."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Robert" }]
+keywords = ["llm", "agents", "observability", "debugging", "ai", "tracing", "local-first"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Debuggers",
+]
+dependencies = []
+
+[project.optional-dependencies]
+viewer = ["fastapi>=0.110", "uvicorn>=0.27"]
+dev = ["pytest>=8", "ruff>=0.4", "fastapi>=0.110", "uvicorn>=0.27"]
+
+[project.scripts]
+replai = "replai.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Rostanic20/replai"
+Issues = "https://github.com/Rostanic20/replai/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/replai"]
+
+[tool.ruff]
+line-length = 100

replai-0.1.0/src/replai/__init__.py

@@ -0,0 +1,109 @@
+"""replai — a local-first, framework-agnostic debugger for LLM agents.
+
+See exactly what your agent did, step by step — then replay and diff runs.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import functools
+import time
+from typing import Any, Optional
+
+from . import context as _ctx
+from .models import Run, Span
+from .store import Store
+
+__version__ = "0.1.0"
+__all__ = ["init", "run", "span", "trace", "tool", "record_llm_call", "Store", "Run", "Span"]
+
+
+def init(db: Optional[str] = None, instrument: bool = True) -> Store:
+    """Set up replai. Call once at startup.
+
+    db: path to the local SQLite file (defaults to ~/.replai/replai.db).
+    instrument: auto-capture Anthropic & OpenAI client calls.
+    """
+    store = Store(db)
+    _ctx.set_store(store)
+    if instrument:
+        from .instrument import instrument as _do_instrument
+        _do_instrument()
+    return store
+
+
+@contextlib.contextmanager
+def run(name: str = "run", **metadata):
+    """Open a run — the top-level container for everything an agent does."""
+    store = _ctx.get_store()
+    r = Run(name=name, metadata=metadata)
+    store.save_run(r)
+    token = _ctx.enter_run(r)
+    try:
+        yield r
+    finally:
+        r.end = time.time()
+        store.save_run(r)
+        _ctx.exit_run(token)
+
+
+@contextlib.contextmanager
+def span(name: str, type: str = "function", input: Any = None, **metadata):
+    """Record a step. Nests automatically inside the current run/span."""
+    store = _ctx.get_store()
+    r = _ctx.ensure_run()
+    sp = Span(
+        run_id=r.id, name=name, type=type,
+        parent_id=_ctx.current_span_id(), input=input, metadata=metadata,
+    )
+    store.save_span(sp)
+    _ctx.push_span(sp.id)
+    try:
+        yield sp
+    except Exception as exc:
+        sp.error = repr(exc)
+        raise
+    finally:
+        sp.end = time.time()
+        store.save_span(sp)
+        _ctx.pop_span()
+
+
+def trace(fn=None, *, name: Optional[str] = None, type: str = "function"):
+    """Decorator that records a function call as a span (sync or async)."""
+    def deco(f):
+        span_name = name or getattr(f, "__name__", "fn")
+
+        if asyncio.iscoroutinefunction(f):
+            @functools.wraps(f)
+            async def awrapper(*args, **kwargs):
+                with span(span_name, type=type, input={"args": args, "kwargs": kwargs}) as s:
+                    out = await f(*args, **kwargs)
+                    s.output = out
+                    return out
+            return awrapper
+
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            with span(span_name, type=type, input={"args": args, "kwargs": kwargs}) as s:
+                out = f(*args, **kwargs)
+                s.output = out
+                return out
+        return wrapper
+
+    return deco(fn) if callable(fn) else deco
+
+
+def tool(fn=None, *, name: Optional[str] = None):
+    """Decorator for tool calls — same as @trace but tagged as a tool."""
+    return trace(fn, name=name, type="tool_call")
+
+
+def record_llm_call(model: str, input: Any, output: Any, *,
+                    tokens_in: Optional[int] = None, tokens_out: Optional[int] = None,
+                    name: str = "llm_call") -> Span:
+    """Manually record a single LLM call (when not using auto-instrumentation)."""
+    return _ctx.record_span(
+        name, "llm_call", input=input, output=output, model=model,
+        tokens_in=tokens_in, tokens_out=tokens_out,
+    )

replai-0.1.0/src/replai/cli.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import argparse
+import time
+
+
+def main(argv=None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="replai", description="Local-first debugger for LLM agents."
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    ui = sub.add_parser("ui", help="Launch the local viewer")
+    ui.add_argument("--host", default="127.0.0.1")
+    ui.add_argument("--port", type=int, default=8473)
+    ui.add_argument("--db", default=None)
+
+    sub.add_parser("runs", help="List recorded runs")
+    sub.add_parser("version", help="Show the installed version")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "ui":
+        _launch_ui(args.host, args.port, args.db)
+    elif args.command == "runs":
+        _list_runs()
+    elif args.command == "version":
+        from . import __version__
+        print(__version__)
+    else:
+        parser.print_help()
+
+
+def _launch_ui(host: str, port: int, db) -> None:
+    try:
+        import uvicorn
+    except ImportError:
+        raise SystemExit("The viewer needs extra deps. Install with:  pip install 'replai[viewer]'")
+    from . import context as _ctx
+    from .store import Store
+    _ctx.set_store(Store(db))
+    from .viewer.app import app
+    print(f"replai viewer → http://{host}:{port}  (Ctrl-C to stop)")
+    uvicorn.run(app, host=host, port=port, log_level="warning")
+
+
+def _list_runs() -> None:
+    from .store import Store
+    runs = Store().runs()
+    if not runs:
+        print("No runs recorded yet. Instrument your agent, run it, then try again.")
+        return
+    for r in runs:
+        print(f"{r['id']}  {r['name']:<24}  {_ago(r['start'])}")
+
+
+def _ago(ts) -> str:
+    if not ts:
+        return ""
+    secs = int(time.time() - ts)
+    for unit, n in (("d", 86400), ("h", 3600), ("m", 60)):
+        if secs >= n:
+            return f"{secs // n}{unit} ago"
+    return f"{secs}s ago"

replai-0.1.0/src/replai/context.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import contextvars
+import time
+from typing import Optional
+
+from .models import Run, Span
+from .store import Store
+
+_store: Optional[Store] = None
+_current_run: contextvars.ContextVar = contextvars.ContextVar("replai_run", default=None)
+_span_stack: contextvars.ContextVar = contextvars.ContextVar("replai_span_stack", default=())
+
+
+def set_store(store: Store) -> None:
+    global _store
+    _store = store
+
+
+def get_store() -> Store:
+    global _store
+    if _store is None:
+        _store = Store()
+    return _store
+
+
+def current_run() -> Optional[Run]:
+    return _current_run.get()
+
+
+def enter_run(run: Run):
+    return _current_run.set(run)
+
+
+def exit_run(token) -> None:
+    _current_run.reset(token)
+
+
+def ensure_run() -> Run:
+    run = current_run()
+    if run is None:
+        run = Run(name="auto")
+        get_store().save_run(run)
+        enter_run(run)
+    return run
+
+
+def current_span_id() -> Optional[str]:
+    stack = _span_stack.get()
+    return stack[-1] if stack else None
+
+
+def push_span(span_id: str) -> None:
+    _span_stack.set(_span_stack.get() + (span_id,))
+
+
+def pop_span() -> None:
+    stack = _span_stack.get()
+    if stack:
+        _span_stack.set(stack[:-1])
+
+
+def record_span(name: str, type: str, **fields) -> Span:
+    """Record an already-completed span (used for one-shot LLM/tool calls)."""
+    run = ensure_run()
+    span = Span(run_id=run.id, name=name, type=type, parent_id=current_span_id(), **fields)
+    span.end = time.time()
+    get_store().save_span(span)
+    return span

replai-0.1.0/src/replai/instrument.py

@@ -0,0 +1,96 @@
+"""Best-effort auto-instrumentation of LLM client libraries.
+
+Patches the Anthropic and OpenAI SDK call sites so every model call is captured
+without changing your code. Safe no-op if a library isn't installed, and the
+capture wrappers never raise into your actual call.
+"""
+from __future__ import annotations
+
+import functools
+
+from . import context as _ctx
+
+_patched = False
+
+
+def instrument() -> None:
+    global _patched
+    if _patched:
+        return
+    _patch_anthropic()
+    _patch_openai()
+    _patched = True
+
+
+def _patch_anthropic() -> None:
+    try:
+        from anthropic.resources.messages import Messages
+    except Exception:
+        return
+    if getattr(Messages.create, "_replai", False):
+        return
+    original = Messages.create
+
+    @functools.wraps(original)
+    def create(self, *args, **kwargs):
+        resp = original(self, *args, **kwargs)
+        try:
+            usage = getattr(resp, "usage", None)
+            _ctx.record_span(
+                "anthropic.messages.create", "llm_call",
+                input=kwargs.get("messages"),
+                output=_anthropic_text(resp),
+                model=kwargs.get("model"),
+                tokens_in=getattr(usage, "input_tokens", None),
+                tokens_out=getattr(usage, "output_tokens", None),
+            )
+        except Exception:
+            pass
+        return resp
+
+    create._replai = True
+    Messages.create = create
+
+
+def _patch_openai() -> None:
+    try:
+        from openai.resources.chat.completions import Completions
+    except Exception:
+        return
+    if getattr(Completions.create, "_replai", False):
+        return
+    original = Completions.create
+
+    @functools.wraps(original)
+    def create(self, *args, **kwargs):
+        resp = original(self, *args, **kwargs)
+        try:
+            usage = getattr(resp, "usage", None)
+            _ctx.record_span(
+                "openai.chat.completions.create", "llm_call",
+                input=kwargs.get("messages"),
+                output=_openai_text(resp),
+                model=kwargs.get("model"),
+                tokens_in=getattr(usage, "prompt_tokens", None),
+                tokens_out=getattr(usage, "completion_tokens", None),
+            )
+        except Exception:
+            pass
+        return resp
+
+    create._replai = True
+    Completions.create = create
+
+
+def _anthropic_text(resp) -> str:
+    try:
+        return "".join(getattr(block, "text", "") for block in resp.content)
+    except Exception:
+        return str(resp)
+
+
+def _openai_text(resp):
+    try:
+        return resp.choices[0].message.content
+    except Exception:
+        return str(resp)

replai-0.1.0/src/replai/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+def _id() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+def _now() -> float:
+    return time.time()
+
+
+@dataclass
+class Span:
+    run_id: str
+    name: str
+    type: str = "function"  # llm_call | tool_call | function
+    id: str = field(default_factory=_id)
+    parent_id: Optional[str] = None
+    start: float = field(default_factory=_now)
+    end: Optional[float] = None
+    input: Any = None
+    output: Any = None
+    error: Optional[str] = None
+    model: Optional[str] = None
+    tokens_in: Optional[int] = None
+    tokens_out: Optional[int] = None
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def duration_ms(self) -> Optional[float]:
+        if self.end is None:
+            return None
+        return round((self.end - self.start) * 1000, 1)
+
+
+@dataclass
+class Run:
+    name: str
+    id: str = field(default_factory=_id)
+    start: float = field(default_factory=_now)
+    end: Optional[float] = None
+    metadata: dict = field(default_factory=dict)

replai-0.1.0/src/replai/store.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+from .models import Run, Span
+
+DEFAULT_DB = Path(os.environ.get("REPLAI_DB", str(Path.home() / ".replai" / "replai.db")))
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY,
+    name TEXT,
+    start REAL,
+    end REAL,
+    metadata TEXT
+);
+CREATE TABLE IF NOT EXISTS spans (
+    id TEXT PRIMARY KEY,
+    run_id TEXT,
+    parent_id TEXT,
+    name TEXT,
+    type TEXT,
+    start REAL,
+    end REAL,
+    input TEXT,
+    output TEXT,
+    error TEXT,
+    model TEXT,
+    tokens_in INTEGER,
+    tokens_out INTEGER,
+    metadata TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_spans_run ON spans(run_id);
+"""
+
+
+def _enc(value) -> Optional[str]:
+    if value is None:
+        return None
+    return json.dumps(value, default=str)
+
+
+def _dec(value):
+    return json.loads(value) if value else None
+
+
+class Store:
+    def __init__(self, path: Optional[str | Path] = None):
+        self.path = Path(path) if path else DEFAULT_DB
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self.path), check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.executescript(SCHEMA)
+        self._conn.commit()
+
+    def save_run(self, run: Run) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO runs (id, name, start, end, metadata) VALUES (?, ?, ?, ?, ?)",
+            (run.id, run.name, run.start, run.end, _enc(run.metadata)),
+        )
+        self._conn.commit()
+
+    def save_span(self, span: Span) -> None:
+        self._conn.execute(
+            """INSERT OR REPLACE INTO spans
+               (id, run_id, parent_id, name, type, start, end,
+                input, output, error, model, tokens_in, tokens_out, metadata)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                span.id, span.run_id, span.parent_id, span.name, span.type, span.start, span.end,
+                _enc(span.input), _enc(span.output), span.error, span.model,
+                span.tokens_in, span.tokens_out, _enc(span.metadata),
+            ),
+        )
+        self._conn.commit()
+
+    def runs(self) -> list[dict]:
+        rows = self._conn.execute("SELECT * FROM runs ORDER BY start DESC").fetchall()
+        return [dict(r) for r in rows]
+
+    def run(self, run_id: str) -> Optional[dict]:
+        row = self._conn.execute("SELECT * FROM runs WHERE id = ?", (run_id,)).fetchone()
+        return dict(row) if row else None
+
+    def spans(self, run_id: str) -> list[dict]:
+        rows = self._conn.execute(
+            "SELECT * FROM spans WHERE run_id = ? ORDER BY start", (run_id,)
+        ).fetchall()
+        result = []
+        for row in rows:
+            span = dict(row)
+            span["input"] = _dec(span["input"])
+            span["output"] = _dec(span["output"])
+            span["metadata"] = _dec(span["metadata"])
+            span["duration_ms"] = (
+                round((span["end"] - span["start"]) * 1000, 1) if span["end"] else None
+            )
+            result.append(span)
+        return result
+
+    def close(self) -> None:
+        self._conn.close()

replai-0.1.0/src/replai/viewer/app.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from ..context import get_store
+
+STATIC = Path(__file__).parent / "static"
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="replai", docs_url=None, redoc_url=None)
+
+    @app.get("/api/runs")
+    def list_runs():
+        return get_store().runs()
+
+    @app.get("/api/runs/{run_id}")
+    def run_detail(run_id: str):
+        store = get_store()
+        return {"run": store.run(run_id), "spans": store.spans(run_id)}
+
+    app.mount("/", StaticFiles(directory=str(STATIC), html=True), name="static")
+    return app
+
+
+app = create_app()

replai-0.1.0/src/replai/viewer/static/index.html

@@ -0,0 +1,127 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>replai</title>
+<style>
+  :root {
+    --bg: #0e0f13; --panel: #16181f; --line: #262932; --text: #e6e8ee;
+    --muted: #8b909e; --accent: #6ea8fe; --llm: #b07cff; --tool: #59c19a; --fn: #d6975a;
+    --err: #ff6b6b;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+         background: var(--bg); color: var(--text); height: 100vh; display: flex; }
+  #sidebar { width: 280px; border-right: 1px solid var(--line); overflow-y: auto; flex: none; }
+  #main { flex: 1; display: flex; min-width: 0; }
+  #timeline { flex: 1; overflow-y: auto; padding: 14px; min-width: 0; }
+  #detail { width: 42%; border-left: 1px solid var(--line); overflow-y: auto; padding: 14px;
+            background: var(--panel); }
+  h1 { font-size: 15px; margin: 0; padding: 14px; border-bottom: 1px solid var(--line);
+       letter-spacing: .5px; }
+  h1 span { color: var(--accent); }
+  .run { padding: 10px 14px; border-bottom: 1px solid var(--line); cursor: pointer; }
+  .run:hover { background: var(--panel); }
+  .run.active { background: var(--panel); border-left: 2px solid var(--accent); }
+  .run .name { font-weight: 600; }
+  .run .meta { color: var(--muted); font-size: 12px; }
+  .span { padding: 7px 10px; margin: 3px 0; border-radius: 6px; cursor: pointer;
+          background: var(--panel); border: 1px solid transparent; display: flex; gap: 8px;
+          align-items: center; }
+  .span:hover { border-color: var(--line); }
+  .span.active { border-color: var(--accent); }
+  .badge { font-size: 10px; text-transform: uppercase; padding: 1px 6px; border-radius: 4px;
+           font-weight: 700; letter-spacing: .5px; flex: none; }
+  .badge.llm_call { background: rgba(176,124,255,.18); color: var(--llm); }
+  .badge.tool_call { background: rgba(89,193,154,.18); color: var(--tool); }
+  .badge.function { background: rgba(214,151,90,.18); color: var(--fn); }
+  .span .label { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .span .dur { color: var(--muted); font-size: 12px; flex: none; }
+  .span.err .label { color: var(--err); }
+  .empty { color: var(--muted); padding: 40px 14px; text-align: center; }
+  pre { background: var(--bg); border: 1px solid var(--line); border-radius: 6px; padding: 10px;
+        overflow-x: auto; white-space: pre-wrap; word-break: break-word; }
+  .k { color: var(--muted); font-size: 12px; margin: 14px 0 4px; text-transform: uppercase;
+       letter-spacing: .5px; }
+  .pill { display: inline-block; background: var(--bg); border: 1px solid var(--line);
+          border-radius: 4px; padding: 1px 7px; margin-right: 6px; font-size: 12px; }
+</style>
+</head>
+<body>
+  <div id="sidebar"><h1>repl<span>ai</span></h1><div id="runs"></div></div>
+  <div id="main">
+    <div id="timeline"><div class="empty">Select a run.</div></div>
+    <div id="detail"><div class="empty">Select a step.</div></div>
+  </div>
+<script>
+const $ = s => document.querySelector(s);
+let activeRun = null, activeSpan = null;
+
+async function loadRuns() {
+  const runs = await (await fetch('/api/runs')).json();
+  const el = $('#runs');
+  if (!runs.length) { el.innerHTML = '<div class="empty">No runs yet.<br>Run your agent, then refresh.</div>'; return; }
+  el.innerHTML = '';
+  for (const r of runs) {
+    const d = document.createElement('div');
+    d.className = 'run' + (r.id === activeRun ? ' active' : '');
+    const when = r.start ? new Date(r.start * 1000).toLocaleString() : '';
+    d.innerHTML = `<div class="name">${esc(r.name)}</div><div class="meta">${esc(r.id)} · ${when}</div>`;
+    d.onclick = () => loadRun(r.id);
+    el.appendChild(d);
+  }
+}
+
+async function loadRun(id) {
+  activeRun = id; activeSpan = null;
+  await loadRuns();
+  const { spans } = await (await fetch('/api/runs/' + id)).json();
+  const tl = $('#timeline');
+  $('#detail').innerHTML = '<div class="empty">Select a step.</div>';
+  if (!spans.length) { tl.innerHTML = '<div class="empty">No steps recorded.</div>'; return; }
+  const byParent = {};
+  for (const s of spans) (byParent[s.parent_id] = byParent[s.parent_id] || []).push(s);
+  tl.innerHTML = '';
+  render(byParent, null, 0, tl, spans);
+}
+
+function render(byParent, parent, depth, container, all) {
+  for (const s of (byParent[parent] || [])) {
+    const row = document.createElement('div');
+    row.className = 'span ' + (s.error ? 'err' : '') + (s.id === activeSpan ? ' active' : '');
+    row.style.marginLeft = (depth * 18) + 'px';
+    const dur = s.duration_ms != null ? s.duration_ms + 'ms' : '';
+    row.innerHTML = `<span class="badge ${s.type}">${s.type.replace('_call','')}</span>`
+      + `<span class="label">${esc(s.name)}</span><span class="dur">${dur}</span>`;
+    row.onclick = () => showDetail(s, row);
+    container.appendChild(row);
+    render(byParent, s.id, depth + 1, container, all);
+  }
+}
+
+function showDetail(s, row) {
+  activeSpan = s.id;
+  document.querySelectorAll('.span.active').forEach(e => e.classList.remove('active'));
+  if (row) row.classList.add('active');
+  const d = $('#detail');
+  const tokens = (s.tokens_in != null || s.tokens_out != null)
+    ? `<span class="pill">in ${s.tokens_in ?? '?'}</span><span class="pill">out ${s.tokens_out ?? '?'}</span>` : '';
+  d.innerHTML =
+    `<div><span class="badge ${s.type}">${s.type.replace('_call','')}</span> <b>${esc(s.name)}</b></div>`
+    + (s.model ? `<div class="k">model</div><span class="pill">${esc(s.model)}</span>` : '')
+    + (tokens ? `<div class="k">tokens</div>${tokens}` : '')
+    + (s.duration_ms != null ? `<div class="k">duration</div><span class="pill">${s.duration_ms} ms</span>` : '')
+    + (s.error ? `<div class="k">error</div><pre style="color:var(--err)">${esc(s.error)}</pre>` : '')
+    + `<div class="k">input</div><pre>${esc(fmt(s.input))}</pre>`
+    + `<div class="k">output</div><pre>${esc(fmt(s.output))}</pre>`;
+}
+
+const fmt = v => v == null ? '—' : (typeof v === 'string' ? v : JSON.stringify(v, null, 2));
+const esc = s => String(s).replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+
+loadRuns();
+setInterval(() => { if (!activeRun) loadRuns(); }, 3000);
+</script>
+</body>
+</html>

replai-0.1.0/tests/test_store.py

@@ -0,0 +1,66 @@
+import replai
+from replai.store import Store
+
+
+def test_run_and_span(tmp_path):
+    db = str(tmp_path / "t.db")
+    replai.init(db=db, instrument=False)
+
+    with replai.run("t") as r:
+        with replai.span("step", type="tool_call", input={"x": 1}) as s:
+            s.output = {"y": 2}
+
+    store = Store(db)
+    runs = store.runs()
+    assert len(runs) == 1
+    assert runs[0]["name"] == "t"
+
+    spans = store.spans(r.id)
+    assert len(spans) == 1
+    assert spans[0]["type"] == "tool_call"
+    assert spans[0]["input"] == {"x": 1}
+    assert spans[0]["output"] == {"y": 2}
+    assert spans[0]["end"] is not None
+
+
+def test_nested_spans_and_parents(tmp_path):
+    db = str(tmp_path / "n.db")
+    replai.init(db=db, instrument=False)
+
+    with replai.run("nested") as r:
+        with replai.span("outer") as outer:
+            with replai.span("inner"):
+                pass
+
+    spans = {s["name"]: s for s in Store(db).spans(r.id)}
+    assert spans["inner"]["parent_id"] == outer.id
+    assert spans["outer"]["parent_id"] is None
+
+
+def test_error_is_recorded(tmp_path):
+    db = str(tmp_path / "e.db")
+    replai.init(db=db, instrument=False)
+
+    with replai.run("boom") as r:
+        try:
+            with replai.span("explodes"):
+                raise ValueError("nope")
+        except ValueError:
+            pass
+
+    spans = Store(db).spans(r.id)
+    assert "ValueError" in spans[0]["error"]
+
+
+def test_record_llm_call(tmp_path):
+    db = str(tmp_path / "l.db")
+    replai.init(db=db, instrument=False)
+
+    with replai.run("chat") as r:
+        replai.record_llm_call(model="m", input="hi", output="hello",
+                               tokens_in=2, tokens_out=3)
+
+    span = Store(db).spans(r.id)[0]
+    assert span["type"] == "llm_call"
+    assert span["model"] == "m"
+    assert span["tokens_out"] == 3