tracefork 0.1.0__py3-none-any.whl

tracefork/report.py

@@ -0,0 +1,131 @@
+"""Report generator: produces a self-contained HTML file from a Tape.
+
+In static mode, the entire tape data is serialized as JSON and injected
+into the HTML template as `window.__TRACEFORK_DATA__ = {...}`.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_INJECT_MARKER = "</head>"
+
+
+def _template_path() -> Path:
+    """Locate ``web/report.html`` in both an installed wheel and a source checkout.
+
+    A built wheel force-includes the file at ``tracefork/web/report.html`` (next to
+    this module); an editable/source checkout keeps it at the repo root. Resolved at
+    call time so importing this module never depends on the file's location.
+    """
+    here = Path(__file__).parent
+    for cand in (
+        here / "web" / "report.html",  # installed wheel (force-included)
+        here.parent.parent / "web" / "report.html",  # repo root (src/tracefork -> repo)
+    ):
+        if cand.exists():
+            return cand
+    raise FileNotFoundError("web/report.html not found (looked in the package and the repo root)")
+
+
+def _tape_to_data(tape, blame: dict | None = None) -> dict:
+    """Convert a Tape to the JSON shape expected by the web UI."""
+    exchanges = []
+    for req_bytes, resp_bytes in tape.exchanges:
+        try:
+            req_json = json.loads(req_bytes.decode())
+        except Exception:
+            req_json = {"_raw": req_bytes.hex()}
+
+        try:
+            resp_json = json.loads(resp_bytes.decode())
+        except Exception:
+            # SSE stream — extract first data line
+            lines = resp_bytes.decode(errors="replace").splitlines()
+            data_lines = [
+                line[6:] for line in lines if line.startswith("data: ") and line != "data: [DONE]"
+            ]
+            try:
+                resp_json = json.loads(data_lines[0]) if data_lines else {"_raw": "sse"}
+            except Exception:
+                resp_json = {"_raw": "sse"}
+
+        # Determine role from response
+        role = "unknown"
+        if isinstance(resp_json, dict):
+            if resp_json.get("type") == "message":
+                role = "assistant"
+            elif resp_json.get("role") == "user":
+                role = "user"
+        if "messages" in req_json:
+            msgs = req_json["messages"]
+            if msgs:
+                role = msgs[-1].get("role", role)
+
+        # Preview: first 80 chars of last user message or response text
+        preview = ""
+        try:
+            if isinstance(resp_json, dict) and resp_json.get("content"):
+                for block in resp_json["content"]:
+                    if block.get("type") == "text":
+                        preview = block["text"][:80]
+                        break
+                    if block.get("type") == "tool_use":
+                        tool_input_preview = json.dumps(block.get("input", {}))[:60]
+                        preview = f"→ {block.get('name', 'tool')}({tool_input_preview})"
+                        break
+        except Exception:
+            pass
+
+        exchanges.append(
+            {
+                "role": role,
+                "preview": preview,
+                "request": req_json,
+                "response_preview": resp_json,
+            }
+        )
+
+    return {
+        "agent_name": tape.agent_name,
+        "exchanges": exchanges,
+        "blame": blame or {},
+        "created_at": "",
+        "fingerprint": tape.digest()[:16],
+    }
+
+
+def _safe_json(data: dict) -> str:
+    """Serialize `data` and escape HTML-significant chars so recorded agent I/O
+    (which can contain ``</script>``) cannot break out of the inline <script>.
+
+    Replacing ``< > &`` with their ``\\uXXXX`` forms yields valid JSON string
+    escapes, so the loader's parse still works. The JS line separators
+    U+2028/U+2029 are already emitted as ``\\u`` escapes by ``ensure_ascii=True``.
+    """
+    return (
+        json.dumps(data, indent=2)
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+    )
+
+
+def generate_report(
+    tape,
+    output_path: Path,
+    *,
+    blame: dict | None = None,
+) -> None:
+    """Write a self-contained HTML report to `output_path`.
+
+    The tape data is injected before </head> so the UI loads it synchronously.
+    """
+    html = _template_path().read_text()
+    data = _tape_to_data(tape, blame)
+    inject = f"\n<script>\nwindow.__TRACEFORK_DATA__ = {_safe_json(data)};\n</script>\n"
+    html = html.replace(_INJECT_MARKER, inject + _INJECT_MARKER, 1)
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(html)

tracefork/server.py

@@ -0,0 +1,73 @@
+"""FastAPI server for tracefork live mode.
+
+Serves the report HTML at / and JSON endpoints at /api/run/{run_id}
+and /api/branch/{branch_id}. Single-threaded (uvicorn --workers 1).
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from .report import _tape_to_data, _template_path
+from .store import TapeStore
+
+# No CORS middleware: the UI is served same-origin by this app and uvicorn
+# binds to 127.0.0.1 (see the `serve` CLI command), so cross-origin access is
+# neither needed nor desirable.
+app = FastAPI(title="tracefork", docs_url=None, redoc_url=None)
+
+_store: TapeStore | None = None
+
+
+def get_store() -> TapeStore:
+    if _store is None:
+        raise RuntimeError("Store not initialized — call init_store() first")
+    return _store
+
+
+def init_store(db_path: str = "store.db") -> None:
+    global _store
+    _store = TapeStore(db_path)
+
+
+@app.get("/", response_class=HTMLResponse)
+async def serve_ui() -> HTMLResponse:
+    html = _template_path().read_text()
+    # Empty server URL → the UI fetches same-origin (works on any --port).
+    inject = "\n<script>\nwindow.__TRACEFORK_SERVER_URL__ = '';\n</script>\n"
+    html = html.replace("</head>", inject + "</head>", 1)
+    return HTMLResponse(html)
+
+
+@app.get("/api/runs")
+async def list_runs() -> JSONResponse:
+    store = get_store()
+    return JSONResponse(store.list_runs())
+
+
+@app.get("/api/run/{run_id}")
+async def get_run(run_id: str) -> JSONResponse:
+    store = get_store()
+    try:
+        tape = store.load_tape(run_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"run {run_id!r} not found") from None
+    data = _tape_to_data(tape)
+    data["run_id"] = run_id
+    return JSONResponse(data)
+
+
+@app.get("/api/branch/{branch_id}")
+async def get_branch(branch_id: str) -> JSONResponse:
+    store = get_store()
+    try:
+        branch = store.load_branch(branch_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"branch {branch_id!r} not found") from None
+    data = _tape_to_data(branch["delta_tape"])
+    data["branch_id"] = branch_id
+    data["parent_run_id"] = branch["parent_run_id"]
+    data["divergence_step"] = branch["divergence_step"]
+    data["mutation_desc"] = branch["mutation_desc"]
+    return JSONResponse(data)

tracefork/store.py

@@ -0,0 +1,123 @@
+"""TapeStore — SQLite-backed persistence for tapes and branch metadata.
+
+Schema:
+  tapes   (run_id TEXT PK, agent_name TEXT, tape_bytes BLOB, created_at TEXT)
+  branches(branch_id TEXT PK, parent_run_id TEXT, divergence_step INT,
+           delta_tape_bytes BLOB, mutation_desc TEXT, created_at TEXT)
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import uuid
+
+from .tape import Tape
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS tapes (
+    run_id       TEXT PRIMARY KEY,
+    agent_name   TEXT NOT NULL,
+    tape_bytes   BLOB NOT NULL,
+    created_at   TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS branches (
+    branch_id         TEXT PRIMARY KEY,
+    parent_run_id     TEXT NOT NULL,
+    divergence_step   INTEGER NOT NULL,
+    delta_tape_bytes  BLOB NOT NULL,
+    mutation_desc     TEXT NOT NULL DEFAULT '',
+    created_at        TEXT NOT NULL,
+    FOREIGN KEY(parent_run_id) REFERENCES tapes(run_id)
+);
+"""
+
+
+class TapeStore:
+    """SQLite-backed store for tapes and branches."""
+
+    def __init__(self, db_path: str = "store.db") -> None:
+        self._path = db_path
+        self._con = sqlite3.connect(db_path, check_same_thread=False)
+        self._con.executescript(_DDL)
+        self._con.commit()
+
+    # ── tapes ──────────────────────────────────────────────────────────────
+
+    def save_tape(self, tape: Tape, *, run_id: str | None = None, created_at: str = "") -> str:
+        rid = run_id or uuid.uuid4().hex[:12]
+        blob = tape.to_bytes()
+        self._con.execute(
+            "INSERT OR REPLACE INTO tapes(run_id, agent_name, tape_bytes, created_at) "
+            "VALUES(?,?,?,?)",
+            (rid, tape.agent_name, blob, created_at),
+        )
+        self._con.commit()
+        return rid
+
+    def load_tape(self, run_id: str) -> Tape:
+        row = self._con.execute("SELECT tape_bytes FROM tapes WHERE run_id=?", (run_id,)).fetchone()
+        if row is None:
+            raise KeyError(f"run_id {run_id!r} not found")
+        return Tape.from_bytes(bytes(row[0]))
+
+    def list_runs(self) -> list[dict]:
+        rows = self._con.execute(
+            "SELECT run_id, agent_name, created_at FROM tapes ORDER BY created_at DESC"
+        ).fetchall()
+        return [{"run_id": r[0], "agent_name": r[1], "created_at": r[2]} for r in rows]
+
+    # ── branches ────────────────────────────────────────────────────────────
+
+    def save_branch(
+        self,
+        *,
+        parent_run_id: str,
+        divergence_step: int,
+        delta_tape: Tape,
+        mutation_desc: str = "",
+        created_at: str = "",
+    ) -> str:
+        bid = uuid.uuid4().hex[:12]
+        blob = delta_tape.to_bytes()
+        self._con.execute(
+            """INSERT INTO branches
+               (branch_id, parent_run_id, divergence_step, delta_tape_bytes,
+                mutation_desc, created_at)
+               VALUES(?,?,?,?,?,?)""",
+            (bid, parent_run_id, divergence_step, blob, mutation_desc, created_at),
+        )
+        self._con.commit()
+        return bid
+
+    def load_branch(self, branch_id: str) -> dict:
+        row = self._con.execute(
+            """SELECT branch_id, parent_run_id, divergence_step,
+                      delta_tape_bytes, mutation_desc, created_at
+               FROM branches WHERE branch_id=?""",
+            (branch_id,),
+        ).fetchone()
+        if row is None:
+            raise KeyError(f"branch_id {branch_id!r} not found")
+        return {
+            "branch_id": row[0],
+            "parent_run_id": row[1],
+            "divergence_step": row[2],
+            "delta_tape": Tape.from_bytes(bytes(row[3])),
+            "mutation_desc": row[4],
+            "created_at": row[5],
+        }
+
+    def list_branches(self, parent_run_id: str) -> list[dict]:
+        rows = self._con.execute(
+            """SELECT branch_id, divergence_step, mutation_desc, created_at
+               FROM branches WHERE parent_run_id=? ORDER BY created_at DESC""",
+            (parent_run_id,),
+        ).fetchall()
+        return [
+            {"branch_id": r[0], "divergence_step": r[1], "mutation_desc": r[2], "created_at": r[3]}
+            for r in rows
+        ]
+
+    def close(self) -> None:
+        self._con.close()

tracefork/synthetic.py

@@ -0,0 +1,104 @@
+"""Synthetic Anthropic transports — offline, deterministic stand-ins for the API.
+
+These serve real Anthropic wire-format bytes (built by `tracefork.wire`) so the
+genuine SDK parses them, but never touch the network. They are production
+components: the self-validation suite (`tracefork validate`) and the test suite
+both drive the recorder/fork/blame machinery through them at $0.
+
+  - `ScriptedFakeLLM`     — returns a fixed list of responses in order.
+  - `AsyncScriptedFakeLLM`— async variant.
+  - `FaultAwareFakeLLM`   — returns a *failure* script when a fault marker
+    appears in the request body, else a *normal* script; this is how an
+    injected fault propagates into a flipped outcome during validation.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class ScriptedFakeLLM(httpx.BaseTransport):
+    """Returns scripted Anthropic wire-format responses in sequence.
+
+    Pass a list of response bytes (from make_text_response / make_tool_use_response).
+    Raises ScriptExhausted if more requests arrive than the script has responses.
+    """
+
+    class ScriptExhausted(RuntimeError):
+        pass
+
+    def __init__(self, responses: list[bytes]) -> None:
+        self._responses = list(responses)
+        self._i = 0
+        self.requests_received: list[bytes] = []
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        self.requests_received.append(request.content)
+        if self._i >= len(self._responses):
+            raise self.ScriptExhausted(
+                f"ScriptedFakeLLM exhausted after {len(self._responses)} responses"
+            )
+        resp = self._responses[self._i]
+        self._i += 1
+        return httpx.Response(
+            200,
+            headers={"content-type": "application/json"},
+            content=resp,
+        )
+
+
+class AsyncScriptedFakeLLM(httpx.AsyncBaseTransport):
+    """Async variant of ScriptedFakeLLM."""
+
+    class ScriptExhausted(RuntimeError):
+        pass
+
+    def __init__(self, responses: list[bytes]) -> None:
+        self._responses = list(responses)
+        self._i = 0
+        self.requests_received: list[bytes] = []
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        self.requests_received.append(request.content)
+        if self._i >= len(self._responses):
+            raise self.ScriptExhausted(
+                f"AsyncScriptedFakeLLM exhausted after {len(self._responses)} responses"
+            )
+        resp = self._responses[self._i]
+        self._i += 1
+        return httpx.Response(
+            200,
+            headers={"content-type": "application/json"},
+            content=resp,
+        )
+
+
+class FaultAwareFakeLLM(httpx.BaseTransport):
+    """Returns different response scripts based on a fault marker in the request.
+
+    If `fault_marker` (bytes) appears anywhere in the request body, serve
+    `fault_responses`; otherwise serve `normal_responses`. Each script cycles
+    independently. This lets an injected fault — which the agent echoes into a
+    later request — deterministically flip the run's outcome.
+    """
+
+    def __init__(
+        self,
+        normal_responses: list[bytes],
+        fault_responses: list[bytes],
+        fault_marker: bytes,
+    ) -> None:
+        self._normal = list(normal_responses)
+        self._fault = list(fault_responses)
+        self._marker = fault_marker
+        self._normal_i = 0
+        self._fault_i = 0
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        if self._marker in request.content:
+            resp = self._fault[self._fault_i % len(self._fault)]
+            self._fault_i += 1
+        else:
+            resp = self._normal[self._normal_i % len(self._normal)]
+            self._normal_i += 1
+        return httpx.Response(200, headers={"content-type": "application/json"}, content=resp)

tracefork/tape.py

@@ -0,0 +1,135 @@
+"""Content-addressed, zstd-compressed, persistable tape.
+
+A tape is the recorded artifact of one agent run: ordered HTTP exchanges
+(request body + response body) and nondeterminism draws. Blobs are stored
+content-addressed (keyed by sha256) and zstd-compressed so identical bytes
+are stored once. `digest()` is a hash chain over all draws + exchanges.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+from dataclasses import dataclass, field
+
+import zstandard as zstd
+
+from .constants import BOUNDARY_V1
+
+_ZCTX = zstd.ZstdCompressor(level=3)
+_DCTX = zstd.ZstdDecompressor()
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass
+class Tape:
+    exchanges: list[tuple[bytes, bytes]] = field(default_factory=list)
+    draws: list[tuple[str, str]] = field(default_factory=list)
+    boundary: str = BOUNDARY_V1
+    agent_name: str = ""
+
+    def append_exchange(self, request_body: bytes, response_body: bytes) -> None:
+        self.exchanges.append((request_body, response_body))
+
+    def exchange(self, i: int) -> tuple[bytes, bytes]:
+        return self.exchanges[i]
+
+    def digest(self) -> str:
+        """sha256 hash chain over draws then exchanges — the tape fingerprint."""
+        h = hashlib.sha256()
+        for kind, value in self.draws:
+            h.update(b"D:" + kind.encode() + b":" + value.encode() + b"\n")
+        for req, resp in self.exchanges:
+            h.update(b"X:" + sha256_hex(req).encode() + b":" + sha256_hex(resp).encode() + b"\n")
+        return h.hexdigest()
+
+    def to_bytes(self) -> bytes:
+        """Serialize tape to JSON bytes (base64-encoded for binary exchange fields)."""
+        import base64
+        import json
+
+        return json.dumps(
+            {
+                "exchanges": [
+                    [base64.b64encode(req).decode(), base64.b64encode(resp).decode()]
+                    for req, resp in self.exchanges
+                ],
+                "draws": self.draws,
+                "boundary": self.boundary,
+                "agent_name": self.agent_name,
+            }
+        ).encode()
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Tape:
+        """Deserialize tape from JSON bytes produced by to_bytes()."""
+        import base64
+        import json
+
+        d = json.loads(data)
+        tape = cls(
+            boundary=d["boundary"],
+            agent_name=d["agent_name"],
+        )
+        tape.draws = [tuple(pair) for pair in d["draws"]]
+        tape.exchanges = [
+            (base64.b64decode(req), base64.b64decode(resp)) for req, resp in d["exchanges"]
+        ]
+        return tape
+
+    def save(self, path: str) -> None:
+        con = sqlite3.connect(path)
+        try:
+            con.executescript("""
+                DROP TABLE IF EXISTS blobs;
+                DROP TABLE IF EXISTS events;
+                DROP TABLE IF EXISTS meta;
+                CREATE TABLE blobs (hash TEXT PRIMARY KEY, data BLOB NOT NULL);
+                CREATE TABLE events (
+                    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+                    kind TEXT NOT NULL, a TEXT NOT NULL, b TEXT NOT NULL
+                );
+                CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+            """)
+            for kind, value in self.draws:
+                con.execute("INSERT INTO events (kind, a, b) VALUES ('draw', ?, ?)", (kind, value))
+            for req, resp in self.exchanges:
+                rh, sh = sha256_hex(req), sha256_hex(resp)
+                con.execute(
+                    "INSERT OR IGNORE INTO blobs VALUES (?, ?)",
+                    (rh, _ZCTX.compress(req)),
+                )
+                con.execute(
+                    "INSERT OR IGNORE INTO blobs VALUES (?, ?)",
+                    (sh, _ZCTX.compress(resp)),
+                )
+                con.execute("INSERT INTO events (kind, a, b) VALUES ('exchange', ?, ?)", (rh, sh))
+            con.execute("INSERT INTO meta VALUES ('boundary', ?)", (self.boundary,))
+            con.execute("INSERT INTO meta VALUES ('agent_name', ?)", (self.agent_name,))
+            con.execute("INSERT INTO meta VALUES ('schema_version', '1')")
+            con.commit()
+        finally:
+            con.close()
+
+    @classmethod
+    def load(cls, path: str) -> Tape:
+        con = sqlite3.connect(path)
+        try:
+            raw_blobs = dict(con.execute("SELECT hash, data FROM blobs").fetchall())
+            blobs = {k: _DCTX.decompress(bytes(v)) for k, v in raw_blobs.items()}
+            meta = dict(con.execute("SELECT key, value FROM meta").fetchall())
+            tape = cls(
+                boundary=meta.get("boundary", BOUNDARY_V1),
+                agent_name=meta.get("agent_name", ""),
+            )
+            for kind, a, b in con.execute("SELECT kind, a, b FROM events ORDER BY seq").fetchall():
+                if kind == "draw":
+                    tape.draws.append((a, b))
+                elif kind == "exchange":
+                    tape.exchanges.append((blobs[a], blobs[b]))
+            return tape
+        finally:
+            con.close()