rerunner 0.1.1__py3-none-any.whl

rerunner/__init__.py

@@ -0,0 +1,27 @@
+"""Rerunner: Deterministic flight recorder, replay engine, and CI test runner for AI agents."""
+
+from __future__ import annotations
+
+from rerunner.async_transport import AsyncCassetteTransport
+from rerunner.cassette import Cassette, CassetteError
+from rerunner.sanitizer import sanitize_headers, sanitize_payload, sanitize_string
+from rerunner.session import fork, record, replay
+from rerunner.side_effects import side_effect
+from rerunner.transport import CassetteTransport
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "AsyncCassetteTransport",
+    "Cassette",
+    "CassetteError",
+    "CassetteTransport",
+    "fork",
+    "record",
+    "replay",
+    "sanitize_headers",
+    "sanitize_payload",
+    "sanitize_string",
+    "side_effect",
+]
+

rerunner/async_transport.py

@@ -0,0 +1,108 @@
+"""Asynchronous httpx.AsyncBaseTransport implementation for recording and replaying HTTP requests."""
+
+from __future__ import annotations
+
+import httpx
+from typing import Literal
+from pathlib import Path
+from rerunner.cassette import Cassette, CassetteError
+from rerunner.matcher import (
+    compute_request_key,
+    normalize_body,
+    normalize_headers,
+)
+from rerunner.models import CassetteEntry, RecordedRequest, RecordedResponse
+from rerunner.sanitizer import sanitize_headers, sanitize_string
+
+
+class AsyncCassetteTransport(httpx.AsyncBaseTransport):
+    """Custom asynchronous httpx transport that records or replays network traffic via a cassette."""
+
+    def __init__(
+        self,
+        cassette_path: Path | str,
+        mode: Literal["record", "replay", "fork"] = "replay",
+        fork_step: int | None = None,
+        real_transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.cassette_path = Path(cassette_path)
+        self.mode = mode
+        self.fork_step = fork_step
+        self.real_transport = real_transport or httpx.AsyncHTTPTransport()
+        self.current_step = 0
+
+        if self.mode in ("replay", "fork") and self.cassette_path.exists():
+            self.cassette = Cassette.load(self.cassette_path)
+        else:
+            self.cassette = Cassette(self.cassette_path)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        self.current_step += 1
+        body_bytes = await request.aread()
+        request_key = compute_request_key(request.method, str(request.url), body_bytes)
+
+        # Check whether to replay
+        should_replay = (
+            self.mode == "replay"
+            or (self.mode == "fork" and self.fork_step is not None and self.current_step <= self.fork_step)
+        )
+
+        if should_replay:
+            match = self.cassette.find_http_match(request_key)
+            if match is None or match.response is None:
+                raise CassetteError(
+                    f"[Async Step {self.current_step}] No cassette match found in replay mode for "
+                    f"{request.method} {request.url} (key: {request_key[:12]}...)"
+                )
+
+            return httpx.Response(
+                status_code=match.response.status_code,
+                headers=match.response.headers,
+                content=match.response.body.encode("utf-8"),
+                request=request,
+            )
+
+        # LIVE EXECUTION
+        real_response = await self.real_transport.handle_async_request(request)
+        response_bytes = await real_response.aread()
+
+        # Sanitize headers and body before writing to disk
+        cleaned_headers = sanitize_headers(normalize_headers(dict(request.headers)))
+        cleaned_req_body = sanitize_string(normalize_body(body_bytes))
+        cleaned_resp_body = sanitize_string(response_bytes.decode("utf-8", errors="replace"))
+
+        # Record to cassette
+        recorded_req = RecordedRequest(
+            method=request.method,
+            url=str(request.url),
+            headers=cleaned_headers,
+            body=cleaned_req_body,
+            request_key=request_key,
+        )
+
+        recorded_resp = RecordedResponse(
+            status_code=real_response.status_code,
+            headers=sanitize_headers(dict(real_response.headers)),
+            body=cleaned_resp_body,
+            http_version=real_response.extensions.get("http_version", b"HTTP/1.1").decode("ascii", errors="ignore"),
+        )
+
+        entry = CassetteEntry(
+            step=self.current_step,
+            entry_type="http",
+            request=recorded_req,
+            response=recorded_resp,
+        )
+        self.cassette.append(entry)
+        self.cassette.save()
+
+        return httpx.Response(
+            status_code=real_response.status_code,
+            headers=real_response.headers,
+            content=response_bytes,
+            request=request,
+        )
+
+    async def aclose(self) -> None:
+        if hasattr(self.real_transport, "aclose"):
+            await self.real_transport.aclose()

rerunner/cassette.py

@@ -0,0 +1,119 @@
+"""Cassette storage engine for streaming plain and gzip-compressed JSONL reading and writing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+from rerunner.integrity import compute_entry_hash, verify_cassette_integrity
+from rerunner.models import CassetteEntry, CassetteMetadata
+import gzip
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class CassetteError(Exception):
+    """Raised when cassette file operations fail or integrity is violated."""
+
+
+class Cassette:
+    """Represents a recorded agent session cassette stored as append-only JSONL (.jsonl) or gzip-compressed JSONL (.jsonl.gz)."""
+
+    def __init__(self, path: Path | str, metadata: CassetteMetadata | None = None) -> None:
+        self.path = Path(path)
+        self.metadata = metadata or CassetteMetadata()
+        self.entries: list[CassetteEntry] = []
+        self._last_hash = "GENESIS"
+
+    @classmethod
+    def load(cls, path: Path | str, verify_integrity: bool = True) -> Cassette:
+        """Load an existing plain or gzip-compressed cassette from disk and optionally verify its cryptographic chain."""
+        file_path = Path(path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Cassette file not found: {file_path}")
+
+        if file_path.name.endswith(".gz"):
+            with gzip.open(file_path, "rt", encoding="utf-8") as file:
+                lines = file.read().splitlines()
+        else:
+            lines = file_path.read_text(encoding="utf-8").splitlines()
+
+        if not lines:
+            raise CassetteError(f"Cassette file is empty: {file_path}")
+
+        # Parse header
+        try:
+            header_dict = json.loads(lines[0])
+            metadata = CassetteMetadata(**header_dict)
+        except Exception as exc:
+            raise CassetteError(f"Invalid cassette metadata header in {file_path}: {exc}") from exc
+
+        cassette = cls(file_path, metadata=metadata)
+
+        for line_num, line in enumerate(lines[1:], start=2):
+            line_str = line.strip()
+            if not line_str:
+                continue
+            try:
+                entry_dict = json.loads(line_str)
+                entry = CassetteEntry(**entry_dict)
+                cassette.entries.append(entry)
+            except Exception as exc:
+                raise CassetteError(
+                    f"Malformed entry on line {line_num} in {file_path}: {exc}"
+                ) from exc
+
+        if cassette.entries:
+            cassette._last_hash = cassette.entries[-1].entry_hash
+
+        if verify_integrity:
+            is_valid, error = verify_cassette_integrity(cassette.entries)
+            if not is_valid:
+                raise CassetteError(f"Integrity check failed for {file_path}: {error}")
+
+        return cassette
+
+    def append(self, entry: CassetteEntry) -> None:
+        """Append a new entry to the in-memory cassette with tamper-evident chaining."""
+        entry.prev_hash = self._last_hash
+        entry.entry_hash = compute_entry_hash(entry, self._last_hash)
+        self.entries.append(entry)
+        self._last_hash = entry.entry_hash
+
+    def save(self) -> None:
+        """Write the complete cassette to disk atomically, using gzip compression for .gz paths."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = self.path.with_suffix(f"{self.path.suffix}.tmp")
+
+        if self.path.name.endswith(".gz"):
+            with gzip.open(temp_path, "wt", encoding="utf-8") as file:
+                file.write(self.metadata.model_dump_json() + "\n")
+                for entry in self.entries:
+                    file.write(entry.model_dump_json() + "\n")
+        else:
+            with temp_path.open("w", encoding="utf-8") as file:
+                # Write metadata header
+                file.write(self.metadata.model_dump_json() + "\n")
+                for entry in self.entries:
+                    file.write(entry.model_dump_json() + "\n")
+
+        temp_path.replace(self.path)
+
+    def find_http_match(self, request_key: str, step: int | None = None) -> CassetteEntry | None:
+        """Find a recorded HTTP response matching the request key, optionally at a specific step."""
+        for entry in self.entries:
+            if (
+                entry.entry_type == "http"
+                and entry.request
+                and entry.request.request_key == request_key
+                and (step is None or entry.step == step)
+            ):
+                return entry
+        return None
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    def __iter__(self) -> Iterator[CassetteEntry]:
+        return iter(self.entries)

rerunner/cli.py

@@ -0,0 +1,203 @@
+"""Command-line interface for Rerunner built with Typer and Rich."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rerunner.cassette import Cassette
+from rerunner.integrity import verify_cassette_integrity
+
+app = typer.Typer(
+    name="rerunner",
+    help="Deterministic flight recorder, replay engine, and CI test runner for AI agents.",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command()
+def inspect(
+    cassette_path: Path = typer.Argument(..., help="Path to a .jsonl or .jsonl.gz cassette file"),
+) -> None:
+    """Inspect and summarize the contents of a recorded cassette."""
+    try:
+        cassette = Cassette.load(cassette_path, verify_integrity=False)
+    except Exception as exc:
+        console.print(f"[bold red]Failed to load cassette:[/] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    console.print(
+        Panel(
+            f"[bold cyan]File:[/] {cassette_path}\n"
+            f"[bold cyan]Format Version:[/] {cassette.metadata.format_version}\n"
+            f"[bold cyan]Hash Algorithm:[/] {cassette.metadata.hash_algorithm}\n"
+            f"[bold cyan]Total Steps:[/] {len(cassette.entries)}",
+            title="[bold green]Rerunner Cassette Summary[/]",
+            border_style="green",
+        )
+    )
+
+    if not cassette.entries:
+        console.print("[yellow]Cassette contains no recorded steps.[/]")
+        return
+
+    table = Table(title="Recorded Execution Steps", show_header=True, header_style="bold magenta")
+    table.add_column("Step", style="dim", width=6)
+    table.add_column("Type", width=12)
+    table.add_column("Details", justify="left")
+    table.add_column("Hash (SHA-256)", style="dim", width=12)
+
+    for entry in cassette.entries:
+        if entry.entry_type == "http" and entry.request and entry.response:
+            details = f"[bold]{entry.request.method}[/] {entry.request.url} -> [green]{entry.response.status_code}[/]"
+        elif entry.entry_type == "side_effect":
+            details = f"[bold cyan]Tool:[/] {entry.side_effect_name}(...)"
+        else:
+            details = "Unknown payload"
+
+        hash_short = f"{entry.entry_hash[:10]}..." if entry.entry_hash else "None"
+        table.add_row(str(entry.step), entry.entry_type, details, hash_short)
+
+    console.print(table)
+
+
+@app.command()
+def verify(
+    cassette_path: Path = typer.Argument(..., help="Path to the .jsonl cassette file"),
+) -> None:
+    """Verify the cryptographic SHA-256 tamper-evident integrity of a cassette."""
+    try:
+        cassette = Cassette.load(cassette_path, verify_integrity=False)
+        is_valid, error = verify_cassette_integrity(cassette.entries)
+        if not is_valid:
+            console.print(f"[bold red]❌ INTEGRITY FAILURE:[/] {error}")
+            sys.exit(1)
+        console.print(
+            f"[bold green]✔ Cassette integrity verified successfully! ({len(cassette.entries)} chained steps)[/]"
+        )
+    except Exception as exc:
+        console.print(f"[bold red]Error verifying cassette:[/] {exc}")
+        sys.exit(1)
+
+
+@app.command()
+def diff(
+    cassette_a: Path = typer.Argument(..., help="First cassette file"),
+    cassette_b: Path = typer.Argument(..., help="Second cassette file"),
+) -> None:
+    """Compare two cassettes and highlight divergences in prompt execution and outputs."""
+    try:
+        c1 = Cassette.load(cassette_a, verify_integrity=False)
+        c2 = Cassette.load(cassette_b, verify_integrity=False)
+    except Exception as exc:
+        console.print(f"[bold red]Error loading cassettes for comparison:[/] {exc}")
+        sys.exit(1)
+
+    table = Table(title="Cassette Divergence Diff", show_header=True, header_style="bold cyan")
+    table.add_column("Step", width=6)
+    table.add_column(f"{cassette_a.name}", style="yellow")
+    table.add_column(f"{cassette_b.name}", style="green")
+
+    max_len = max(len(c1.entries), len(c2.entries))
+    for i in range(max_len):
+        e1 = c1.entries[i] if i < len(c1.entries) else None
+        e2 = c2.entries[i] if i < len(c2.entries) else None
+
+        desc1 = f"{e1.entry_type}: {e1.entry_hash[:8]}" if e1 else "[red]<Missing>[/]"
+        desc2 = f"{e2.entry_type}: {e2.entry_hash[:8]}" if e2 else "[red]<Missing>[/]"
+
+        table.add_row(str(i + 1), desc1, desc2)
+
+    console.print(table)
+
+
+@app.command()
+def stats(
+    cassette_path: Path = typer.Argument(..., help="Path to the .jsonl cassette file"),
+) -> None:
+    """Calculate token savings, latency savings, and cost reductions achieved by replaying."""
+    try:
+        cassette = Cassette.load(cassette_path, verify_integrity=False)
+    except Exception as exc:
+        console.print(f"[bold red]Error loading cassette:[/] {exc}")
+        sys.exit(1)
+
+    total_chars = 0
+    http_steps = 0
+    side_effect_steps = 0
+
+    for entry in cassette.entries:
+        if entry.entry_type == "http" and entry.request and entry.response:
+            http_steps += 1
+            total_chars += len(entry.request.body) + len(entry.response.body)
+        elif entry.entry_type == "side_effect":
+            side_effect_steps += 1
+
+    est_tokens = max(1, total_chars // 4)
+    # Estimate based on blend of Claude 3.5 Sonnet / GPT-4o pricing (~$10/M tokens)
+    est_dollars_saved = (est_tokens / 1_000_000) * 10.0
+    # Average live LLM network call takes ~1.8 seconds vs 0.001s replay
+    time_saved_seconds = http_steps * 1.8
+
+    stats_table = Table(
+        title="CI Replay Efficiency & Savings", show_header=True, header_style="bold green"
+    )
+    stats_table.add_column("Metric", style="cyan")
+    stats_table.add_column("Value", style="bold yellow")
+
+    stats_table.add_row("Total Recorded Steps", str(len(cassette.entries)))
+    stats_table.add_row("HTTP LLM Calls Avoided", str(http_steps))
+    stats_table.add_row("Side-Effects Safely Stubbed", str(side_effect_steps))
+    stats_table.add_row("Estimated Tokens Saved", f"{est_tokens:,}")
+    stats_table.add_row("Estimated API Cost Saved (per test run)", f"${est_dollars_saved:.4f}")
+    stats_table.add_row("CI Pipeline Time Saved (per test run)", f"{time_saved_seconds:.1f}s")
+
+    console.print(stats_table)
+
+
+@app.command()
+def play(
+    cassette_path: Path = typer.Argument(..., help="Path to the .jsonl cassette file"),
+) -> None:
+    """Visually step through recorded agent steps in the terminal."""
+    try:
+        cassette = Cassette.load(cassette_path, verify_integrity=False)
+    except Exception as exc:
+        console.print(f"[bold red]Error loading cassette:[/] {exc}")
+        sys.exit(1)
+
+    console.print(
+        Panel(
+            f"[bold green]Replaying {len(cassette.entries)} recorded agent steps...[/]",
+            title="📼 Flight Playback",
+        )
+    )
+
+    for entry in cassette.entries:
+        if entry.entry_type == "http" and entry.request and entry.response:
+            console.print(
+                Panel(
+                    f"[bold yellow]Method:[/] {entry.request.method} {entry.request.url}\n"
+                    f"[bold yellow]Response Code:[/] [green]{entry.response.status_code}[/]\n"
+                    f"[dim]Body Preview:[/] {entry.response.body[:180]}...",
+                    title=f"Step {entry.step}: LLM Network Interaction",
+                    border_style="blue",
+                )
+            )
+        elif entry.entry_type == "side_effect":
+            console.print(
+                Panel(
+                    f"[bold cyan]Function:[/] {entry.side_effect_name}\n"
+                    f"[bold cyan]Result:[/] {entry.side_effect_result}",
+                    title=f"Step {entry.step}: Guarded Side-Effect",
+                    border_style="magenta",
+                )
+            )
+
+
+if __name__ == "__main__":
+    app()

rerunner/integrations/__init__.py

@@ -0,0 +1,13 @@
+"""Official framework integrations and zero-friction client adapters."""
+
+from __future__ import annotations
+
+from rerunner.integrations.anthropic import wrap_anthropic
+from rerunner.integrations.langchain import RerunnerCallbackHandler
+from rerunner.integrations.openai import wrap_openai
+
+__all__ = [
+    "RerunnerCallbackHandler",
+    "wrap_anthropic",
+    "wrap_openai",
+]

rerunner/integrations/anthropic.py

@@ -0,0 +1,35 @@
+"""Zero-friction wrapper for the official Anthropic Claude SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+import httpx
+from rerunner.transport import CassetteTransport
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def wrap_anthropic(
+    client: Any,
+    cassette_path: Path | str,
+    mode: Literal["record", "replay", "fork"] = "replay",
+    fork_step: int | None = None,
+) -> Any:
+    """Attach a Rerunner CassetteTransport to an existing Anthropic client instance.
+
+    Example:
+        import anthropic
+        from rerunner.integrations import wrap_anthropic
+
+        client = wrap_anthropic(anthropic.Anthropic(), "my_run.jsonl", mode="replay")
+    """
+    transport = CassetteTransport(cassette_path=cassette_path, mode=mode, fork_step=fork_step)
+    # The official Anthropic SDK uses an internal httpx._client.Client or _client
+    if hasattr(client, "_client") and hasattr(client._client, "_transport"):
+        client._client._transport = transport
+    else:
+        # Fallback to replacing http_client
+        client._client = httpx.Client(transport=transport)
+
+    return client

rerunner/integrations/langchain.py

@@ -0,0 +1,29 @@
+"""LangChain and LangGraph callback integration for step recording and observability."""
+
+from __future__ import annotations
+
+from typing import Any
+from rerunner.side_effects import set_active_cassette
+
+
+class RerunnerCallbackHandler:
+    """Callback handler compatible with LangChain, LangGraph, and CrewAI pipelines."""
+
+    def __init__(self, cassette_path: str, mode: str = "replay", fork_step: int | None = None) -> None:
+        self.cassette_path = cassette_path
+        self.mode = mode
+        self.fork_step = fork_step
+        self.step_count = 0
+        set_active_cassette(cassette_path, mode=mode, fork_step=fork_step)
+
+    def on_llm_start(self, serialized: dict[str, Any], prompts: list[str], **kwargs: Any) -> None:
+        """Invoked when an LLM call begins in a LangChain chain."""
+        self.step_count += 1
+
+    def on_tool_start(self, serialized: dict[str, Any], input_str: str, **kwargs: Any) -> None:
+        """Invoked when a tool executes in an agent workflow."""
+        self.step_count += 1
+
+    def on_chain_end(self, outputs: dict[str, Any], **kwargs: Any) -> None:
+        """Invoked when a chain completes execution."""
+        pass

rerunner/integrations/openai.py

@@ -0,0 +1,33 @@
+"""Zero-friction wrapper for the official OpenAI SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+import httpx
+from rerunner.transport import CassetteTransport
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def wrap_openai(
+    client: Any,
+    cassette_path: Path | str,
+    mode: Literal["record", "replay", "fork"] = "replay",
+    fork_step: int | None = None,
+) -> Any:
+    """Attach a Rerunner CassetteTransport to an existing OpenAI client instance.
+
+    Example:
+        import openai
+        from rerunner.integrations import wrap_openai
+
+        client = wrap_openai(openai.OpenAI(), "my_run.jsonl", mode="replay")
+    """
+    transport = CassetteTransport(cassette_path=cassette_path, mode=mode, fork_step=fork_step)
+    if hasattr(client, "_client") and hasattr(client._client, "_transport"):
+        client._client._transport = transport
+    else:
+        client._client = httpx.Client(transport=transport)
+
+    return client

rerunner/integrity.py

@@ -0,0 +1,52 @@
+"""Cryptographic tamper-evident hash chaining for cassette verification."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rerunner.models import CassetteEntry
+
+
+def canonical_entry_payload(entry: CassetteEntry) -> str:
+    """Create a deterministic JSON string representing the entry without its hash."""
+    data = entry.model_dump(exclude={"entry_hash"})
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def compute_entry_hash(entry: CassetteEntry, prev_hash: str) -> str:
+    """Compute SHA-256 hash chaining prev_hash with canonical entry payload."""
+    payload = f"{prev_hash}:{canonical_entry_payload(entry)}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def verify_cassette_integrity(entries: list[CassetteEntry]) -> tuple[bool, str | None]:
+    """Verify that every entry in the cassette adheres to the cryptographic hash chain.
+
+    Returns:
+        (True, None) if the chain is fully verified and untampered.
+        (False, error_message) if any link in the chain is broken or modified.
+    """
+    if not entries:
+        return True, None
+
+    expected_prev = "GENESIS"
+    for entry in entries:
+        if entry.prev_hash != expected_prev:
+            return (
+                False,
+                f"Broken chain at step {entry.step}: expected prev_hash '{expected_prev}', got '{entry.prev_hash}'",
+            )
+
+        recomputed_hash = compute_entry_hash(entry, expected_prev)
+        if recomputed_hash != entry.entry_hash:
+            return (
+                False,
+                f"Tampered entry detected at step {entry.step}: recorded hash '{entry.entry_hash}' does not match recomputed '{recomputed_hash}'",
+            )
+
+        expected_prev = entry.entry_hash
+
+    return True, None