agenticreplay 0.1.0 → 0.1.2

package/python/agenticreplay_trace/reader.py

@@ -1,295 +0,0 @@
-"""Reading one recorded run.
-
-Two tolerances are mandated by spec §2 and both are deliberate: a run that crashed mid-write
-leaves a partial final line, and a trace written by a newer AgenticReplay carries event types this build
-has never heard of. Neither may take down the whole trace. Neither is hidden either — everything
-skipped, and everything that violates the spec without being skippable, shows up in
-:meth:`TraceReader.problems`, because a reader that quietly drops events produces evaluation
-datasets with holes nobody can see.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from collections.abc import Iterator, Mapping
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any, Final
-
-from .models import (
-    EVENT_TYPES,
-    BlobRef,
-    Manifest,
-    AgenticReplayTraceError,
-    TraceEvent,
-    TraceFormatError,
-)
-
-__all__ = [
-    "BlobIntegrityError",
-    "BlobNotFoundError",
-    "NotATraceError",
-    "TraceReader",
-]
-
-_HASH_CHUNK: Final = 1 << 20
-_SHA256_PREFIX: Final = "sha256:"
-_HEX64_LENGTH: Final = 64
-
-
-class NotATraceError(AgenticReplayTraceError):
-    """The directory is not a readable AgenticReplay run."""
-
-
-class BlobNotFoundError(AgenticReplayTraceError, FileNotFoundError):
-    """A payload references a blob that is not in the store."""
-
-
-class BlobIntegrityError(AgenticReplayTraceError):
-    """A blob's content does not hash to the name it is stored under."""
-
-
-def _bare_digest(ref: BlobRef | str) -> str:
-    """The 64-char hex digest of `ref`, whatever form it arrived in.
-
-    Digests come out of a file on disk, so this is also the path-traversal guard: nothing that
-    is not 64 hex characters is ever joined onto the blob root.
-    """
-    raw = ref.digest if isinstance(ref, BlobRef) else ref
-    if not isinstance(raw, str):
-        raise TraceFormatError(f"invalid blob digest: {raw!r}")
-    hexdigest = raw[len(_SHA256_PREFIX) :] if raw.startswith(_SHA256_PREFIX) else raw
-    if len(hexdigest) != _HEX64_LENGTH or any(c not in "0123456789abcdef" for c in hexdigest):
-        raise TraceFormatError(f"invalid blob digest: {raw!r}")
-    return hexdigest
-
-
-@dataclass(frozen=True, slots=True)
-class _Line:
-    number: int
-    text: str
-
-
-class TraceReader:
-    """Read-only view of a run directory (spec §1).
-
-    There is no writer here on purpose. The TypeScript implementation owns the write path, and a
-    second writer would mean a second redaction implementation — which is how a secret leaks.
-    """
-
-    def __init__(self, run_dir: Path, manifest: Manifest) -> None:
-        self._run_dir = run_dir
-        self._events_path = run_dir / "events.jsonl"
-        self._manifest = manifest
-        self._problems: list[str] = []
-        self._expected_seq: int | None = 0
-        self._has_read = False
-
-    @classmethod
-    def open(cls, run_dir: str | Path) -> TraceReader:
-        """Open `run_dir`, validating its manifest.
-
-        The manifest is read once and trusted from then on — every later answer depends on it —
-        so unlike events.jsonl it is validated up front rather than tolerated.
-        """
-        directory = Path(run_dir)
-        path = directory / "manifest.json"
-        try:
-            raw = path.read_text(encoding="utf-8")
-        except OSError as exc:
-            raise NotATraceError(f"not an agenticreplay run: cannot read {path}") from exc
-        try:
-            parsed = json.loads(raw)
-        except ValueError as exc:
-            raise NotATraceError(f"invalid manifest: {path} is not JSON") from exc
-        return cls(directory, Manifest.from_json(parsed))
-
-    def __repr__(self) -> str:
-        return f"TraceReader({self._manifest.run_id!r}, {str(self._run_dir)!r})"
-
-    @property
-    def run_dir(self) -> Path:
-        return self._run_dir
-
-    @property
-    def events_path(self) -> Path:
-        return self._events_path
-
-    @property
-    def manifest(self) -> Manifest:
-        return self._manifest
-
-    def problems(self) -> list[str]:
-        """Everything the last read pass could not use, or could not vouch for.
-
-        Reads the trace first if nobody has yet, because returning an empty list for an unread
-        trace would hide precisely what this method exists to surface.
-        """
-        if not self._has_read:
-            for _ in self.stream():
-                pass
-        return list(self._problems)
-
-    def events(self) -> list[TraceEvent]:
-        """Every valid event, in log order. Loads the whole trace; see :meth:`stream` for big ones."""
-        return list(self.stream())
-
-    def stream(self) -> Iterator[TraceEvent]:
-        """Yield events one at a time, holding at most two lines in memory.
-
-        A trace can be hundreds of megabytes because every model turn resends the conversation,
-        so the reader that turns traces into datasets must never need the file resident.
-
-        One line is held back so the last one can be told apart from the rest: only the final
-        line may legitimately be half-written (spec §2). A pass resets :meth:`problems`, so run
-        one pass at a time.
-        """
-        self._problems = []
-        self._expected_seq = 0
-        self._has_read = True
-
-        if not self._events_path.is_file():
-            self._problems.append(f"events.jsonl: missing at {self._events_path}")
-            return
-
-        held: _Line | None = None
-        # errors="replace" rather than "strict": a crash can cut a multi-byte character in half,
-        # and that line should be reported like any other bad line instead of ending the read.
-        with self._events_path.open("r", encoding="utf-8", errors="replace") as handle:
-            for number, text in enumerate(handle, start=1):
-                if not text.strip():
-                    continue
-                if held is not None:
-                    event = self._parse(held, last=False)
-                    if event is not None:
-                        yield event
-                held = _Line(number, text)
-            if held is not None:
-                event = self._parse(held, last=True)
-                if event is not None:
-                    yield event
-
-    def blob(self, ref: BlobRef | str, *, verify: bool = False) -> bytes:
-        """The bytes of a content-addressed payload (spec §2.2).
-
-        `verify` re-hashes the content. It is off by default so that an unverified read returns
-        exactly what the TypeScript reader returns; the spec makes integrity checking a duty for
-        `events.jsonl` (§6) but never states one for blobs, so silently differing here would be
-        a worse failure than a corrupt byte.
-        """
-        hexdigest = _bare_digest(ref)
-        path = self._run_dir / "blobs" / hexdigest[:2] / hexdigest
-        try:
-            data = path.read_bytes()
-        except OSError as exc:
-            raise BlobNotFoundError(
-                f"blob not found: {_SHA256_PREFIX}{hexdigest} (looked in {path})"
-            ) from exc
-        if verify:
-            actual = hashlib.sha256(data).hexdigest()
-            if actual != hexdigest:
-                raise BlobIntegrityError(
-                    f"blob {path} does not match its digest: expected {hexdigest}, got {actual}"
-                )
-        return data
-
-    def payload(self, event: TraceEvent) -> Any:
-        """The event's payload: the inline value, or the blob read back and decoded.
-
-        Undecodable content comes back as `bytes` rather than raising. Callers building datasets
-        sweep every event in a trace, and one binary diff should not abort the sweep — the type
-        of the return value already says what happened.
-        """
-        ref = event.blob
-        if ref is None:
-            return event.payload
-        data = self.blob(ref)
-        if ref.media_type is not None and "json" not in ref.media_type.lower():
-            return data
-        try:
-            return json.loads(data.decode("utf-8"))
-        except (UnicodeDecodeError, ValueError):
-            return data
-
-    def verify_integrity(self) -> tuple[bool, str, str]:
-        """(ok, expected, actual) over events.jsonl. Spec §6: report a mismatch, never repair it.
-
-        `expected` is empty for a run that was never sealed — a crashed run has no integrity root,
-        which is not the same as failing one, so `ok` is False and the caller can tell them apart.
-        """
-        expected = self._manifest.events_sha256 or ""
-        digest = hashlib.sha256()
-        try:
-            with self._events_path.open("rb") as handle:
-                while chunk := handle.read(_HASH_CHUNK):
-                    digest.update(chunk)
-        except OSError:
-            return False, expected, ""
-        actual = digest.hexdigest()
-        return bool(expected) and expected == actual, expected, actual
-
-    def _report(self, line: int, reason: str) -> None:
-        self._problems.append(f"line {line}: {reason}")
-
-    def _parse(self, line: _Line, *, last: bool) -> TraceEvent | None:
-        try:
-            value = json.loads(line.text)
-        except ValueError:
-            self._report(line.number, "truncated final line" if last else "malformed JSON")
-            # The lost line's seq is unknowable, so density resynchronises on the next one
-            # rather than blaming it for a gap this line already accounts for.
-            self._expected_seq = None
-            return None
-
-        if not isinstance(value, Mapping):
-            self._report(line.number, "not a JSON object")
-            self._expected_seq = None
-            return None
-
-        self._check_density(line, value)
-
-        event_type = value.get("type")
-        if not isinstance(event_type, str) or event_type not in EVENT_TYPES:
-            # Spec §2.3: adding a type is a MINOR bump, so an unknown one is a newer writer,
-            # not a broken trace.
-            self._report(
-                line.number,
-                f"unknown event type {event_type!r} — skipped for forward compatibility",
-            )
-            return None
-
-        try:
-            event = TraceEvent.from_json(value)
-        except TraceFormatError as exc:
-            self._report(line.number, str(exc))
-            return None
-
-        self._check_causes(line, event)
-        return event
-
-    def _check_density(self, line: _Line, value: Mapping[str, Any]) -> None:
-        """Spec §2.1: seq is a dense total order starting at 0. A hole means a lost event."""
-        seq = value.get("seq")
-        if isinstance(seq, bool) or not isinstance(seq, int):
-            return  # the envelope check reports the real problem
-        if self._expected_seq is not None and seq != self._expected_seq:
-            self._report(
-                line.number,
-                f"seq {seq} breaks the dense order — expected {self._expected_seq}",
-            )
-        self._expected_seq = seq + 1
-
-    def _check_causes(self, line: _Line, event: TraceEvent) -> None:
-        """Spec §2.1 requires every cause < seq, but the JSON Schema does not encode it.
-
-        Reported rather than enforced: dropping the event would make this reader disagree with
-        the TypeScript one about what a trace contains, which is a worse outcome than a noted
-        edge that points the wrong way.
-        """
-        forward = [c for c in event.causes if c >= event.seq]
-        if forward:
-            self._report(
-                line.number,
-                f"causes {forward} do not precede seq {event.seq} (spec §2.1)",
-            )

package/python/conftest.py

@@ -1,12 +0,0 @@
-"""Puts the SDK on `sys.path` so the suite runs from a clean checkout.
-
-`agenticreplay_trace` has no build step and no dependencies; requiring `pip install -e` before
-`python3 -m pytest python/` would add one for no benefit.
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))

package/python/examples/analyze.py

@@ -1,114 +0,0 @@
-#!/usr/bin/env python3
-"""Answer three questions about a recorded run, using nothing but the SDK and the standard library.
-
-    python3 python/examples/analyze.py [run_dir]
-
-1. What did the tokens go on? (per model, paired back to the request that named it)
-2. Which turn churned the filesystem most?
-3. If I want to retry from the failure, where does a fork actually land?
-
-Question 3 is the one that needs the SDK rather than `jq`: checkpoints are derived from the log
-(spec §3), not recorded in it, and a fork target that is not a checkpoint silently moves.
-"""
-
-from __future__ import annotations
-
-import sys
-from collections import defaultdict
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-from agenticreplay_trace import TraceReader, derive_checkpoints, snap_to_checkpoint, turns_of  # noqa: E402
-
-DEFAULT_RUN = Path(__file__).resolve().parents[2] / "examples" / "traces" / "run_9f2c14a03b71"
-
-
-def main(run_dir: Path) -> int:
-    reader = TraceReader.open(run_dir)
-    manifest = reader.manifest
-    events = reader.events()
-    by_seq = {e.seq: e for e in events}
-
-    ok, expected, actual = reader.verify_integrity()
-    checkpoints = derive_checkpoints(events)
-
-    print(f"{manifest.run_id}  adapter={manifest.adapter_id}  exit={manifest.exit_code}")
-    # Unsealed is not mismatched. A run whose recorder was killed has no digest at all, and
-    # printing "MISMATCH expected  got <hash>" accuses a file that nothing touched.
-    if ok:
-        integrity = "OK"
-    elif not expected:
-        integrity = f"UNSEALED (never finished; events.jsonl is {actual})"
-    else:
-        integrity = f"MISMATCH expected {expected} got {actual}"
-    print(f"integrity: {integrity}")
-    print(
-        f"{len(events)} events, {len(turns_of(events))} turns, "
-        f"{len(checkpoints)} checkpoints, {len(reader.problems())} problems"
-    )
-
-    # 1. Tokens per model. A model.response carries the token counts but not the model name, so
-    # follow `causes` back to the request that chose it — that edge is why the DAG is recorded.
-    tokens: dict[str, dict[str, int]] = defaultdict(lambda: {"in": 0, "out": 0, "calls": 0})
-    for event in events:
-        if event.type != "model.response":
-            continue
-        request = next((by_seq[c] for c in event.causes if c in by_seq), None)
-        model = str((request.attrs if request else event.attrs).get("model", "unknown"))
-        row = tokens[model]
-        row["in"] += int(event.attrs.get("input_tokens", 0))
-        row["out"] += int(event.attrs.get("output_tokens", 0))
-        row["calls"] += 1
-
-    print("\ntokens by model")
-    for model, row in sorted(tokens.items(), key=lambda kv: -kv[1]["in"] - kv[1]["out"]):
-        print(f"  {model:<18} in {row['in']:>7}  out {row['out']:>6}  calls {row['calls']:>3}")
-
-    # 2. Filesystem churn per turn, from fs.change attrs.
-    churn: dict[int, dict[str, int]] = defaultdict(lambda: {"+": 0, "-": 0, "files": 0})
-    paths: dict[int, set[str]] = defaultdict(set)
-    for event in events:
-        if event.type != "fs.change":
-            continue
-        row = churn[event.turn]
-        row["+"] += int(event.attrs.get("insertions", 0))
-        row["-"] += int(event.attrs.get("deletions", 0))
-        paths[event.turn].add(str(event.attrs.get("path", "?")))
-        row["files"] = len(paths[event.turn])
-
-    print("\nfilesystem churn by turn")
-    if not churn:
-        print("  (no fs.change events — the run recorded no diffs)")
-    for turn, row in sorted(churn.items(), key=lambda kv: -(kv[1]["+"] + kv[1]["-"])):
-        touched = ", ".join(sorted(paths[turn]))
-        print(f"  turn {turn:<3} +{row['+']}/-{row['-']}  {row['files']} file(s)  {touched}")
-
-    # 3. Where a fork of the first failure would actually resume.
-    failure = next((e for e in events if e.type == "error"), None)
-    print("\nfork targets")
-    if failure is None:
-        print("  (this run recorded no error to retry)")
-    elif not checkpoints:
-        print("  (no checkpoints: the run recorded no fs.snapshot, so nothing is forkable)")
-    else:
-        # One target that is a checkpoint and one that is not, so both behaviours show. The second
-        # is *found* rather than guessed at with an offset: which seqs are checkpoints depends on
-        # the trace, and an arithmetic guess quietly stops demonstrating anything the day it lands
-        # on one.
-        exact = {c.seq for c in checkpoints}
-        between = next((e.seq for e in events if e.seq > failure.seq and e.seq not in exact), None)
-        for target in (failure.seq, between):
-            if target is None:
-                continue
-            checkpoint, snapped = snap_to_checkpoint(checkpoints, target)
-            moved = f"snapped back from {target}" if snapped else "exact"
-            print(f"  seq {target:<3} -> checkpoint {checkpoint.seq} ({moved}), tree {checkpoint.fs_tree}")
-
-    for problem in reader.problems():
-        print(f"\nproblem: {problem}", file=sys.stderr)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main(Path(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_RUN))

package/python/pyproject.toml

@@ -1,45 +0,0 @@
-[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "agenticreplay-trace"
-version = "0.1.0"
-description = "Read-only reader for the AgenticReplay trace format v0 — record/replay/fork traces for AI agents."
-readme = "README.md"
-requires-python = ">=3.10"
-license = { text = "Apache-2.0" }
-keywords = ["agents", "tracing", "observability", "evaluation", "agenticreplay"]
-classifiers = [
-  "Development Status :: 3 - Alpha",
-  "Intended Audience :: Developers",
-  "License :: OSI Approved :: Apache Software License",
-  "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.13",
-  "Topic :: Software Development :: Debuggers",
-  "Typing :: Typed",
-]
-
-# Deliberately empty, and meant to stay that way: this package is what makes an AgenticReplay trace
-# readable from a notebook that already has its own pinned scientific stack, so it must never
-# force a resolver conflict on the way in.
-dependencies = []
-
-[project.optional-dependencies]
-dev = ["pytest>=7.0"]
-
-[project.urls]
-Homepage = "https://github.com/askdkc/AgenticReplay"
-Specification = "https://github.com/askdkc/AgenticReplay/blob/main/spec/agenticreplay-trace-v0.md"
-
-[tool.setuptools]
-packages = ["agenticreplay_trace"]
-
-[tool.setuptools.package-data]
-agenticreplay_trace = ["py.typed"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]

package/python/tests/conftest.py

@@ -1,102 +0,0 @@
-"""Shared fixtures: the repo's checked-in example trace, and builders for synthetic ones."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-from pathlib import Path
-from typing import Any
-
-import pytest
-
-EXAMPLE_RUN_ID = "run_9f2c14a03b71"
-
-
-def repo_root() -> Path | None:
-    """The AgenticReplay checkout containing this package, when it is present.
-
-    The SDK is publishable on its own, so tests that read repo fixtures must be able to tell
-    that they are running outside the repo rather than fail confusingly.
-    """
-    for parent in Path(__file__).resolve().parents:
-        if (parent / "spec" / "agenticreplay-trace-v0.md").is_file():
-            return parent
-    return None
-
-
-@pytest.fixture
-def example_run() -> Path:
-    root = repo_root()
-    if root is None:
-        pytest.skip("not running inside an AgenticReplay checkout")
-    run = root / "examples" / "traces" / EXAMPLE_RUN_ID
-    if not run.is_dir():
-        pytest.skip(f"missing example trace {run}")
-    return run
-
-
-def write_trace(
-    directory: Path,
-    events: list[dict[str, Any]],
-    *,
-    manifest: dict[str, Any] | None = None,
-    trailing: str = "",
-    seal: bool = True,
-    blobs: dict[str, bytes] | None = None,
-) -> Path:
-    """Write a minimal but schema-valid run directory, plus whatever damage a test asks for.
-
-    `trailing` is appended verbatim after the last newline, which is how a crashed writer's
-    half-line is reproduced (spec §2).
-    """
-    directory.mkdir(parents=True, exist_ok=True)
-    body = "".join(json.dumps(e, separators=(",", ":")) + "\n" for e in events) + trailing
-    events_path = directory / "events.jsonl"
-    # newline="" or Windows rewrites every LF as CRLF on the way out, while the digest below is
-    # taken over the LF form. The file then fails its own integrity check for a reason that has
-    # nothing to do with the reader, which hashes bytes.
-    events_path.write_text(body, encoding="utf-8", newline="")
-
-    for digest, payload in (blobs or {}).items():
-        shard = directory / "blobs" / digest[:2]
-        shard.mkdir(parents=True, exist_ok=True)
-        (shard / digest).write_bytes(payload)
-
-    doc: dict[str, Any] = {
-        "schema_version": "0.4.0",
-        "run_id": "run_abc123",
-        "created_at": "2026-08-29T10:00:00.000Z",
-        "agenticreplay_version": "0.1.0",
-        "adapter": {"id": "test-adapter"},
-        "argv": ["agent"],
-        "cwd": "/work",
-    }
-    if seal:
-        doc["integrity"] = {
-            "events_sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(),
-            "blob_count": len(blobs or {}),
-        }
-    if manifest is not None:
-        doc.update(manifest)
-    (directory / "manifest.json").write_text(json.dumps(doc, indent=2), encoding="utf-8")
-    return directory
-
-
-def event(seq: int, type_: str = "note", **over: Any) -> dict[str, Any]:
-    """One schema-valid envelope. Mirrors the `ev()` helper in packages/core/test."""
-    base: dict[str, Any] = {
-        "seq": seq,
-        "ts": "2026-08-29T10:00:00.000Z",
-        "mono_us": seq * 1000,
-        "turn": 0,
-        "type": type_,
-        "actor": "agenticreplay",
-    }
-    base.update(over)
-    return base
-
-
-def blob_of(data: bytes) -> tuple[str, str]:
-    """(bare hex digest, `sha256:` ref) for content a test wants in the blob store."""
-    hexdigest = hashlib.sha256(data).hexdigest()
-    return hexdigest, f"sha256:{hexdigest}"

package/python/tests/test_capture_contract.py

@@ -1,24 +0,0 @@
-import pytest
-
-from agenticreplay_trace.models import Manifest, TraceEvent, TraceFormatError
-
-
-def test_reader_keeps_capture_status_and_transformations():
-    manifest = Manifest.from_json({
-        "schema_version": "0.4.0", "run_id": "run_123abc",
-        "created_at": "2026-10-10T00:00:00Z", "agenticreplay_version": "0.5.0",
-        "adapter": {"id": "test"}, "argv": [], "cwd": "/tmp/example",
-        "capture": {"status": "incomplete", "issues": ["storage_failure"]},
-    })
-    assert manifest.capture["status"] == "incomplete"
-    audit = {"kind": "redaction", "location": "payload", "rule": "sk_api_key", "count": 1, "reason": "secret policy"}
-    event = TraceEvent.from_json({
-        "seq": 0, "ts": "2026-10-10T00:00:00Z", "mono_us": 0, "turn": 1,
-        "type": "net.request", "actor": "agent", "transformations": [audit],
-    })
-    assert event.transformations == (audit,)
-
-
-def test_legacy_manifest_is_rejected_explicitly():
-    with pytest.raises(TraceFormatError, match="unsupported legacy format"):
-        Manifest.from_json({"schema_version": "0.3.0"})