agentcassette 0.1.0__py3-none-any.whl

agentcassette/__init__.py

@@ -0,0 +1,83 @@
+"""
+agentcassette — Deterministic agent test recorder and replayer.
+
+Zero dependencies. Pure Python stdlib.
+
+Testing agents is painful: live LLM calls are expensive, non-deterministic, and
+slow. agentcassette records a real run once, then replays it forever from a JSON
+"cassette" — no network, no cost, fully deterministic.
+
+Quick start
+-----------
+Wrap the callable(s) you want captured once (your model-call function, and
+optionally your tools), then drive recording and replay with context managers::
+
+    import agentcassette
+    from agentcassette import record, replay
+
+    call_model = agentcassette.intercept(call_model, kind="llm")
+
+    # Record a real run:
+    with record("cassettes/flight_search.json"):
+        my_agent.run("Find flights to NYC under $300")
+
+    # Replay it in a test — no API calls happen:
+    def test_flight_search():
+        with replay("cassettes/flight_search.json"):
+            result = my_agent.run("Find flights to NYC under $300")
+        assert result.success
+
+Catch regressions with strict replay::
+
+    from agentcassette import replay, DivergenceError
+
+    with replay("cassettes/flight_search.json", strict=True):
+        my_agent.run("Find flights to NYC under $300")   # DivergenceError on drift
+
+Inspect and diff cassettes::
+
+    from agentcassette import Cassette, diff_cassettes
+
+    c = Cassette.load("cassettes/flight_search.json")
+    c.num_steps, c.total_input_tokens, c.total_output_tokens
+    c.redact("api_key")                       # scrub secrets before committing
+
+    delta = diff_cassettes("cassettes/v1.json", "cassettes/v2.json")
+    delta.new_calls, delta.dropped_calls, delta.token_delta
+
+See the project README for the full cassette format and API reference.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from ._cassette import Cassette
+from ._diff import CassetteDiff, diff_cassettes
+from ._errors import (
+    AgentCassetteError,
+    CassetteNotFound,
+    DivergenceError,
+    ReplayExhausted,
+)
+from ._session import Player, Recorder, intercept, record, replay
+
+__all__ = [
+    "record",
+    "replay",
+    "intercept",
+    "Cassette",
+    "Recorder",
+    "Player",
+    "diff_cassettes",
+    "CassetteDiff",
+    "AgentCassetteError",
+    "CassetteNotFound",
+    "ReplayExhausted",
+    "DivergenceError",
+]
+
+try:
+    __version__ = _version("agentcassette")
+except PackageNotFoundError:  # running from a source tree without install metadata
+    __version__ = "0.0.0"

agentcassette/_cassette.py

@@ -0,0 +1,169 @@
+"""The Cassette: agentcassette's on-disk recording format.
+
+A cassette is a plain, human-readable JSON file — readable in a diff, safe to
+commit to git, and portable across machines. Its shape:
+
+    {
+      "version": 1,
+      "recorded_at": "2026-06-30T12:00:00Z",
+      "model": "claude-sonnet-4-6",      # optional label
+      "duration_ms": 1832.4,             # wall time of the whole recorded run
+      "steps": [
+        {
+          "index": 0,
+          "type": "llm",                 # "llm" | "tool" | "call"
+          "name": "call_model",
+          "arguments": {"args": [...], "kwargs": {...}},
+          "result": {...},
+          "input_tokens": 420,
+          "output_tokens": 88,
+          "duration_ms": 512.0
+        }
+      ]
+    }
+
+Every intercepted call becomes one step, in the exact order it happened.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from ._errors import CassetteNotFound
+
+CASSETTE_VERSION = 1
+REDACTION_PLACEHOLDER = "****"
+
+
+def to_jsonable(obj: Any) -> Any:
+    """Coerce an arbitrary value into something ``json.dumps`` accepts.
+
+    JSON-native values pass through unchanged. Sets and tuples become lists.
+    Objects are reduced to their ``__dict__`` when available, otherwise their
+    ``repr`` wrapped in a marker so the cassette stays valid JSON.
+    """
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, dict):
+        return {str(k): to_jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set, frozenset)):
+        return [to_jsonable(v) for v in obj]
+    # Common SDK response objects expose their fields via model_dump()/dict().
+    for method in ("model_dump", "dict", "to_dict"):
+        fn = getattr(obj, method, None)
+        if callable(fn):
+            try:
+                return to_jsonable(fn())
+            except Exception:  # pragma: no cover - defensive
+                break
+    data = getattr(obj, "__dict__", None)
+    if isinstance(data, dict) and data:
+        return {"__type__": type(obj).__name__, **{str(k): to_jsonable(v) for k, v in data.items()}}
+    return {"__repr__": repr(obj)}
+
+
+def _redact_in_place(obj: Any, key: str, replacement: str) -> None:
+    if isinstance(obj, dict):
+        for k in list(obj.keys()):
+            if k == key:
+                obj[k] = replacement
+            else:
+                _redact_in_place(obj[k], key, replacement)
+    elif isinstance(obj, list):
+        for item in obj:
+            _redact_in_place(item, key, replacement)
+
+
+class Cassette:
+    """An ordered recording of intercepted calls.
+
+    Usually produced by :func:`agentcassette.record` and consumed by
+    :func:`agentcassette.replay`, but can also be loaded directly for inspection.
+    """
+
+    def __init__(
+        self,
+        steps: list[dict] | None = None,
+        *,
+        model: str | None = None,
+        recorded_at: str | None = None,
+        duration_ms: float = 0.0,
+        version: int = CASSETTE_VERSION,
+    ) -> None:
+        self.version = version
+        self.recorded_at = recorded_at
+        self.model = model
+        self.duration_ms = duration_ms
+        self.steps: list[dict] = steps if steps is not None else []
+
+    # ---- persistence ----------------------------------------------------
+    @classmethod
+    def from_dict(cls, data: dict) -> "Cassette":
+        return cls(
+            steps=list(data.get("steps", [])),
+            model=data.get("model"),
+            recorded_at=data.get("recorded_at"),
+            duration_ms=data.get("duration_ms", 0.0),
+            version=data.get("version", CASSETTE_VERSION),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "recorded_at": self.recorded_at,
+            "model": self.model,
+            "duration_ms": self.duration_ms,
+            "steps": self.steps,
+        }
+
+    @classmethod
+    def load(cls, path: str | os.PathLike) -> "Cassette":
+        """Load a cassette from disk. Raises :class:`CassetteNotFound` if absent."""
+        if not os.path.exists(path):
+            raise CassetteNotFound(f"No cassette at {os.fspath(path)!r}")
+        with open(path, "r", encoding="utf-8") as fh:
+            return cls.from_dict(json.load(fh))
+
+    def save(self, path: str | os.PathLike) -> None:
+        """Write the cassette to disk as pretty-printed JSON, creating dirs."""
+        parent = os.path.dirname(os.fspath(path))
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(self.to_dict(), fh, indent=2, ensure_ascii=False)
+            fh.write("\n")
+
+    # ---- inspection -----------------------------------------------------
+    @property
+    def num_steps(self) -> int:
+        return len(self.steps)
+
+    @property
+    def total_input_tokens(self) -> int:
+        return sum(int(s.get("input_tokens", 0)) for s in self.steps)
+
+    @property
+    def total_output_tokens(self) -> int:
+        return sum(int(s.get("output_tokens", 0)) for s in self.steps)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.total_input_tokens + self.total_output_tokens
+
+    def redact(self, key: str, replacement: str = REDACTION_PLACEHOLDER) -> "Cassette":
+        """Replace every value stored under ``key`` (at any depth). Returns self."""
+        for step in self.steps:
+            _redact_in_place(step, key, replacement)
+        return self
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+    def __repr__(self) -> str:
+        return (
+            f"Cassette(steps={self.num_steps}, "
+            f"input_tokens={self.total_input_tokens}, "
+            f"output_tokens={self.total_output_tokens})"
+        )

agentcassette/_diff.py

@@ -0,0 +1,70 @@
+"""Diff two cassettes to spot behavioral drift between agent versions."""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+from typing import Union
+
+from ._cassette import Cassette
+
+
+class CassetteDiff:
+    """The delta between two cassettes (``a`` = baseline, ``b`` = new).
+
+    Attributes:
+        new_calls: Call names that appear more often in ``b`` than ``a``.
+        dropped_calls: Call names that appear more often in ``a`` than ``b``.
+        changed_calls: Steps at the same index whose name/arguments/result differ.
+        token_delta: ``b`` total tokens minus ``a`` total tokens.
+        input_token_delta / output_token_delta: the same, split by direction.
+        step_delta: ``b`` step count minus ``a`` step count.
+    """
+
+    def __init__(self, a: Cassette, b: Cassette) -> None:
+        names_a = Counter(s.get("name") for s in a.steps)
+        names_b = Counter(s.get("name") for s in b.steps)
+
+        self.new_calls: list[str] = sorted((names_b - names_a).elements())
+        self.dropped_calls: list[str] = sorted((names_a - names_b).elements())
+
+        self.changed_calls: list[dict] = []
+        for i in range(min(len(a.steps), len(b.steps))):
+            sa, sb = a.steps[i], b.steps[i]
+            if (
+                sa.get("name") != sb.get("name")
+                or sa.get("arguments") != sb.get("arguments")
+                or sa.get("result") != sb.get("result")
+            ):
+                self.changed_calls.append({"index": i, "a": sa, "b": sb})
+
+        self.input_token_delta = b.total_input_tokens - a.total_input_tokens
+        self.output_token_delta = b.total_output_tokens - a.total_output_tokens
+        self.token_delta = b.total_tokens - a.total_tokens
+        self.step_delta = b.num_steps - a.num_steps
+
+    @property
+    def identical(self) -> bool:
+        """True when the two cassettes have the same calls, args, and results."""
+        return (
+            not self.new_calls
+            and not self.dropped_calls
+            and not self.changed_calls
+            and self.step_delta == 0
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"CassetteDiff(new={self.new_calls}, dropped={self.dropped_calls}, "
+            f"changed={len(self.changed_calls)}, token_delta={self.token_delta})"
+        )
+
+
+def diff_cassettes(
+    a: Union[str, os.PathLike, Cassette],
+    b: Union[str, os.PathLike, Cassette],
+) -> CassetteDiff:
+    """Compare two cassettes given as paths or already-loaded :class:`Cassette`s."""
+    cassette_a = a if isinstance(a, Cassette) else Cassette.load(a)
+    cassette_b = b if isinstance(b, Cassette) else Cassette.load(b)
+    return CassetteDiff(cassette_a, cassette_b)

agentcassette/_errors.py

@@ -0,0 +1,35 @@
+"""Exception types raised by agentcassette."""
+
+from __future__ import annotations
+
+
+class AgentCassetteError(Exception):
+    """Base class for all agentcassette errors."""
+
+
+class CassetteNotFound(AgentCassetteError):
+    """Raised when a cassette file does not exist during replay."""
+
+
+class ReplayExhausted(AgentCassetteError):
+    """Raised when the agent makes more intercepted calls than the cassette recorded."""
+
+
+class DivergenceError(AgentCassetteError):
+    """Raised during a strict replay when a call does not match the recording.
+
+    Attributes:
+        step_index: Position of the diverging call in the cassette.
+        expected: The recorded ``{"name", "arguments"}`` at that position.
+        actual: The ``{"name", "arguments"}`` the agent produced instead.
+    """
+
+    def __init__(self, step_index: int, expected: dict, actual: dict) -> None:
+        self.step_index = step_index
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"Replay diverged at step {step_index}: "
+            f"expected {expected.get('name')!r} with {expected.get('arguments')!r}, "
+            f"got {actual.get('name')!r} with {actual.get('arguments')!r}"
+        )

agentcassette/_session.py

@@ -0,0 +1,249 @@
+"""Recording and replaying of intercepted calls.
+
+The design is a deliberate, honest seam rather than monkey-patching: you wrap
+the callables you want captured once with :func:`intercept`. A thread-local
+"active session" then decides what happens each time a wrapped callable runs:
+
+* No active session  → the real function runs (production is unaffected).
+* Inside ``record()`` → the real function runs and the call is taped.
+* Inside ``replay()`` → the recorded result is returned; the real function is
+  never called (no network, no cost, fully deterministic).
+
+This keeps agentcassette provider-agnostic and truly zero-dependency: it works
+with OpenAI, Anthropic, a raw ``requests`` call, or a local model equally.
+
+Both synchronous and ``async def`` callables are supported — :func:`intercept`
+detects coroutine functions and returns an awaitable wrapper for them.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import threading
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterator
+
+from ._cassette import Cassette, to_jsonable
+from ._errors import DivergenceError, ReplayExhausted
+from ._tokens import count_tokens
+
+_local = threading.local()
+
+
+def _current_session() -> "Recorder | Player | None":
+    return getattr(_local, "session", None)
+
+
+def _set_session(session: "Recorder | Player | None") -> None:
+    _local.session = session
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _normalize_args(args: tuple, kwargs: dict) -> dict:
+    return {"args": to_jsonable(list(args)), "kwargs": to_jsonable(dict(kwargs))}
+
+
+# ---------------------------------------------------------------------------
+# The interception seam
+# ---------------------------------------------------------------------------
+def intercept(
+    fn: Callable | None = None,
+    *,
+    name: str | None = None,
+    kind: str = "call",
+) -> Callable:
+    """Mark a callable as recordable/replayable.
+
+    Usable as ``intercept(fn)``, ``intercept(fn, name=..., kind="llm")``, or as a
+    decorator ``@intercept`` / ``@intercept(kind="tool")``. Works on both regular
+    functions and ``async def`` coroutine functions.
+
+    Outside of a ``record``/``replay`` block the wrapped callable behaves exactly
+    like the original, so it is safe to leave in production code.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        call_name = name or getattr(func, "__name__", "call")
+
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                session = _current_session()
+                if session is None:
+                    return await func(*args, **kwargs)
+                return await session.handle_async(call_name, kind, func, args, kwargs)
+
+            async_wrapper.__agentcassette_intercepted__ = True  # type: ignore[attr-defined]
+            return async_wrapper
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            session = _current_session()
+            if session is None:
+                return func(*args, **kwargs)
+            return session.handle(call_name, kind, func, args, kwargs)
+
+        wrapper.__agentcassette_intercepted__ = True  # type: ignore[attr-defined]
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Recorder
+# ---------------------------------------------------------------------------
+class Recorder:
+    """Captures each intercepted call into an ordered list of steps."""
+
+    def __init__(self, *, model: str | None = None) -> None:
+        self.model = model
+        self.steps: list[dict] = []
+        self.cassette: Cassette | None = None  # populated after the block exits
+
+    def _append(
+        self, name: str, kind: str, args: tuple, kwargs: dict, result: Any, duration_ms: float
+    ) -> Any:
+        arguments = _normalize_args(args, kwargs)
+        jresult = to_jsonable(result)
+        input_tokens, output_tokens = count_tokens(arguments, jresult)
+        self.steps.append(
+            {
+                "index": len(self.steps),
+                "type": kind,
+                "name": name,
+                "arguments": arguments,
+                "result": jresult,
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "duration_ms": round(duration_ms, 3),
+            }
+        )
+        return result  # the live run still gets the real object
+
+    def handle(self, name: str, kind: str, func: Callable, args: tuple, kwargs: dict) -> Any:
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        return self._append(name, kind, args, kwargs, result, (time.perf_counter() - start) * 1000)
+
+    async def handle_async(
+        self, name: str, kind: str, func: Callable, args: tuple, kwargs: dict
+    ) -> Any:
+        start = time.perf_counter()
+        result = await func(*args, **kwargs)
+        return self._append(name, kind, args, kwargs, result, (time.perf_counter() - start) * 1000)
+
+
+# ---------------------------------------------------------------------------
+# Player
+# ---------------------------------------------------------------------------
+class Player:
+    """Serves recorded results back in order, without calling the real function."""
+
+    def __init__(self, steps: list[dict], *, strict: bool = False) -> None:
+        self._steps = steps
+        self.strict = strict
+        self._cursor = 0
+        self.divergences: list[dict] = []
+
+    @property
+    def cursor(self) -> int:
+        return self._cursor
+
+    @property
+    def remaining(self) -> int:
+        return len(self._steps) - self._cursor
+
+    def _serve(self, name: str, kind: str, args: tuple, kwargs: dict) -> Any:
+        if self._cursor >= len(self._steps):
+            raise ReplayExhausted(
+                f"cassette recorded {len(self._steps)} calls but the agent asked for more "
+                f"(next was {name!r})"
+            )
+        step = self._steps[self._cursor]
+        self._cursor += 1
+
+        actual = {"name": name, "arguments": _normalize_args(args, kwargs)}
+        expected = {"name": step.get("name"), "arguments": step.get("arguments")}
+        if expected != actual:
+            if self.strict:
+                raise DivergenceError(step.get("index", self._cursor - 1), expected, actual)
+            self.divergences.append(
+                {"index": step.get("index"), "expected": expected, "actual": actual}
+            )
+        return step.get("result")
+
+    def handle(self, name: str, kind: str, func: Callable, args: tuple, kwargs: dict) -> Any:
+        return self._serve(name, kind, args, kwargs)
+
+    async def handle_async(
+        self, name: str, kind: str, func: Callable, args: tuple, kwargs: dict
+    ) -> Any:
+        return self._serve(name, kind, args, kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Context managers
+# ---------------------------------------------------------------------------
+@contextmanager
+def record(
+    path,
+    *,
+    model: str | None = None,
+    redact: "list[str] | None" = None,
+) -> Iterator[Recorder]:
+    """Record every intercepted call made inside the block to a cassette file.
+
+    The cassette is written on clean exit only; if the block raises, nothing is
+    saved. Pass ``redact=["api_key", ...]`` to scrub those keys before writing.
+    """
+    if _current_session() is not None:
+        raise RuntimeError("agentcassette: a record/replay session is already active")
+    recorder = Recorder(model=model)
+    _set_session(recorder)
+    start = time.perf_counter()
+    try:
+        yield recorder
+    except BaseException:
+        _set_session(None)
+        raise
+    _set_session(None)
+
+    duration_ms = (time.perf_counter() - start) * 1000
+    cassette = Cassette(
+        steps=recorder.steps,
+        model=model,
+        recorded_at=_now_iso(),
+        duration_ms=round(duration_ms, 3),
+    )
+    for key in redact or []:
+        cassette.redact(key)
+    cassette.save(path)
+    recorder.cassette = cassette
+
+
+@contextmanager
+def replay(path, *, strict: bool = False) -> Iterator[Player]:
+    """Replay a cassette: intercepted calls return recorded results, no real work.
+
+    With ``strict=True`` any call whose name or arguments differ from the
+    recording raises :class:`DivergenceError`. With ``strict=False`` (default)
+    divergences are collected on the yielded player's ``divergences`` list.
+    """
+    if _current_session() is not None:
+        raise RuntimeError("agentcassette: a record/replay session is already active")
+    cassette = Cassette.load(path)
+    player = Player(cassette.steps, strict=strict)
+    _set_session(player)
+    try:
+        yield player
+    finally:
+        _set_session(None)

agentcassette/_tokens.py

@@ -0,0 +1,86 @@
+"""Token accounting for recorded steps.
+
+agentcassette has zero dependencies, so it cannot call a real tokenizer
+(``tiktoken`` and friends are third-party). Instead it:
+
+1. Prefers exact counts when the recorded response carries a usage block
+   (OpenAI ``usage.prompt_tokens`` / Anthropic ``usage.input_tokens`` etc.).
+2. Falls back to a character-length heuristic (~4 chars per token), which is
+   accurate enough for budgeting and regression comparisons.
+
+The heuristic is intentionally simple and deterministic so cassettes recorded
+on one machine reproduce identical counts on another.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+# Common usage-block key spellings across providers, mapped to (input, output).
+_INPUT_KEYS = ("input_tokens", "prompt_tokens")
+_OUTPUT_KEYS = ("output_tokens", "completion_tokens")
+
+_CHARS_PER_TOKEN = 4
+
+
+def estimate_tokens(obj: Any) -> int:
+    """Estimate token count for an arbitrary JSON-able object via char heuristic."""
+    if obj is None:
+        return 0
+    if isinstance(obj, str):
+        text = obj
+    else:
+        try:
+            text = json.dumps(obj, sort_keys=True, default=str)
+        except (TypeError, ValueError):
+            text = str(obj)
+    if not text:
+        return 0
+    # Round up so any non-empty payload counts as at least one token.
+    return max(1, -(-len(text) // _CHARS_PER_TOKEN))
+
+
+def _find_usage(obj: Any) -> dict | None:
+    """Return the first dict named 'usage' found anywhere in a nested structure."""
+    if isinstance(obj, dict):
+        usage = obj.get("usage")
+        if isinstance(usage, dict):
+            return usage
+        for value in obj.values():
+            found = _find_usage(value)
+            if found is not None:
+                return found
+    elif isinstance(obj, (list, tuple)):
+        for item in obj:
+            found = _find_usage(item)
+            if found is not None:
+                return found
+    return None
+
+
+def _pick(usage: dict, keys: tuple) -> int | None:
+    for key in keys:
+        value = usage.get(key)
+        if isinstance(value, (int, float)):
+            return int(value)
+    return None
+
+
+def count_tokens(request: Any, response: Any) -> tuple[int, int]:
+    """Return ``(input_tokens, output_tokens)`` for a recorded call.
+
+    Uses an exact usage block from the response when present, otherwise falls
+    back to the character heuristic over the request (input) and response
+    (output) payloads.
+    """
+    usage = _find_usage(response)
+    if usage is not None:
+        input_tokens = _pick(usage, _INPUT_KEYS)
+        output_tokens = _pick(usage, _OUTPUT_KEYS)
+        if input_tokens is not None or output_tokens is not None:
+            return (
+                input_tokens if input_tokens is not None else estimate_tokens(request),
+                output_tokens if output_tokens is not None else estimate_tokens(response),
+            )
+    return estimate_tokens(request), estimate_tokens(response)

agentcassette-0.1.0.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: agentcassette
+Version: 0.1.0
+Summary: Deterministic agent test recorder and replayer. Record live runs, replay as mocks. Zero dependencies.
+Project-URL: Homepage, https://github.com/aenealabs/agentcassette
+Project-URL: Repository, https://github.com/aenealabs/agentcassette
+Project-URL: Issues, https://github.com/aenealabs/agentcassette/issues
+Project-URL: Changelog, https://github.com/aenealabs/agentcassette/blob/main/CHANGELOG.md
+Author-email: LaVon Rutledge <32437530+lavrut@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,cassette,deterministic,llm,mocking,record,replay,testing,vcr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentcassette
+
+[![PyPI](https://img.shields.io/pypi/v/agentcassette?color=blue)](https://pypi.org/project/agentcassette/)
+[![Python](https://img.shields.io/pypi/pyversions/agentcassette)](https://pypi.org/project/agentcassette/)
+[![CI](https://img.shields.io/github/actions/workflow/status/aenealabs/agentcassette/ci.yml?label=CI)](https://github.com/aenealabs/agentcassette/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+
+**Deterministic agent test recorder and replayer.**
+
+Record a real agent run once, replay it forever as a mock — no network, no cost, fully deterministic. Like VCR/pytest-recording, but purpose-built for LLM agents and with zero dependencies.
+
+```python
+import agentcassette
+from agentcassette import record, replay
+
+call_model = agentcassette.intercept(call_model, kind="llm")
+
+# Record a real run once:
+with record("cassettes/flight_search.json"):
+    my_agent.run("Find flights to NYC under $300")
+
+# Replay it in tests — no API calls, no tokens spent, same result every time:
+def test_flight_search():
+    with replay("cassettes/flight_search.json"):
+        result = my_agent.run("Find flights to NYC under $300")
+    assert result.success
+```
+
+## Why agentcassette?
+
+Testing agents is painful. Live LLM calls are **expensive** (every test run costs money), **non-deterministic** (a different answer each time), and **slow** (seconds per call). So most teams either skip agent testing or maintain a costly, flaky integration suite.
+
+agentcassette records the real calls an agent makes into a plain-JSON **cassette**, then replays them on demand. Your tests become fast, free, and deterministic — and you can assert on exactly what the agent did.
+
+Unlike VCR-style tools that monkey-patch the HTTP layer, agentcassette uses an explicit, honest seam: you wrap the callables you want captured. That keeps it **provider-agnostic** (OpenAI, Anthropic, Gemini, a raw `requests` call, or a local model all work identically) and **truly zero-dependency**.
+
+## Installation
+
+```bash
+pip install agentcassette
+```
+
+Requires Python 3.9+. No other dependencies, ever.
+
+## Quick Start
+
+### 1. Wrap what you want captured
+
+Wrap your model-call function once (and any tools you want taped). Outside a record/replay block, wrapped callables behave exactly like the original — safe to leave in production code.
+
+```python
+import agentcassette
+
+# As a wrapper:
+call_model = agentcassette.intercept(call_model, kind="llm")
+
+# Or as a decorator:
+@agentcassette.intercept(kind="tool")
+def search_web(query: str) -> list[str]:
+    ...
+```
+
+### 2. Record a real run
+
+```python
+from agentcassette import record
+
+with record("cassettes/flight_search.json", model="claude-sonnet-4-6"):
+    my_agent.run("Find flights to NYC under $300")
+# Cassette is written on clean exit.
+```
+
+### 3. Replay it in your tests
+
+```python
+from agentcassette import replay
+
+def test_flight_search():
+    with replay("cassettes/flight_search.json"):
+        result = my_agent.run("Find flights to NYC under $300")
+    assert result.success
+```
+
+During replay, every intercepted call returns its recorded result and the real function is **never called**.
+
+## Async agents
+
+`intercept` detects `async def` callables and returns an awaitable wrapper, so async agents work the same way — including a mix of async and sync tools in one run:
+
+```python
+import agentcassette
+from agentcassette import record, replay
+
+acall_model = agentcassette.intercept(acall_model, kind="llm")  # an async def
+
+async def agent(task):
+    plan = await acall_model(f"plan: {task}")
+    ...
+
+with record("cassettes/run.json"):
+    asyncio.run(agent("book a trip"))
+
+with replay("cassettes/run.json"):
+    asyncio.run(agent("book a trip"))   # awaited calls served from the cassette
+```
+
+## Catching regressions with strict replay
+
+By default, replay serves recorded results best-effort and collects any divergences. With `strict=True`, a call whose name or arguments differ from the recording raises `DivergenceError` — turning your cassette into a behavioral contract.
+
+```python
+from agentcassette import replay, DivergenceError
+
+with replay("cassettes/flight_search.json", strict=True):
+    my_agent.run("Find flights to NYC under $300")   # raises on drift
+```
+
+Best-effort mode exposes what changed without failing:
+
+```python
+with replay("cassettes/flight_search.json") as player:
+    my_agent.run("Find flights to NYC under $300")
+
+for d in player.divergences:
+    print(d["index"], d["expected"], "->", d["actual"])
+```
+
+## Inspecting cassettes
+
+```python
+from agentcassette import Cassette
+
+c = Cassette.load("cassettes/flight_search.json")
+c.num_steps            # number of intercepted calls
+c.total_input_tokens   # summed across steps
+c.total_output_tokens
+c.total_tokens
+c.duration_ms          # wall time of the original run
+
+c.redact("api_key")    # scrub secrets before committing to git
+c.save("cassettes/flight_search.json")
+```
+
+Token counts use exact usage blocks when the recorded response carries one (OpenAI `usage.prompt_tokens`, Anthropic `usage.input_tokens`, …), falling back to a deterministic ~4-chars-per-token heuristic otherwise.
+
+## Redacting secrets
+
+Scrub sensitive keys either when recording or after loading:
+
+```python
+# At record time:
+with record("cassettes/run.json", redact=["api_key", "authorization"]):
+    my_agent.run(task)
+
+# Or later:
+Cassette.load("cassettes/run.json").redact("api_key").save("cassettes/run.json")
+```
+
+## Diffing runs
+
+Compare two cassettes to see how an agent's behavior drifted between versions:
+
+```python
+from agentcassette import diff_cassettes
+
+delta = diff_cassettes("cassettes/v1.json", "cassettes/v2.json")
+delta.new_calls          # call names in v2 but not v1
+delta.dropped_calls      # call names in v1 but not v2
+delta.changed_calls      # same-position steps whose args/results changed
+delta.token_delta        # total token change (v2 - v1)
+delta.identical          # True if nothing changed
+```
+
+## Cassette format
+
+Cassettes are plain, human-readable JSON — diffable and safe to commit:
+
+```json
+{
+  "version": 1,
+  "recorded_at": "2026-06-30T12:00:00Z",
+  "model": "claude-sonnet-4-6",
+  "duration_ms": 1832.4,
+  "steps": [
+    {
+      "index": 0,
+      "type": "llm",
+      "name": "call_model",
+      "arguments": {"args": ["plan the task"], "kwargs": {}},
+      "result": {"text": "...", "usage": {"input_tokens": 420, "output_tokens": 88}},
+      "input_tokens": 420,
+      "output_tokens": 88,
+      "duration_ms": 512.0
+    }
+  ]
+}
+```
+
+Every intercepted call becomes one step, in the exact order it happened.
+
+## API Reference
+
+### `intercept(fn=None, *, name=None, kind="call")`
+
+Marks a callable as recordable/replayable. Usable as `intercept(fn)`, `intercept(fn, kind="llm")`, or as a decorator. Works on both regular functions and `async def` coroutine functions (async callables get an awaitable wrapper). `kind` is a free-form label stored on each step (e.g. `"llm"`, `"tool"`). Outside a session, the wrapped callable is a transparent pass-through.
+
+### `record(path, *, model=None, redact=None)`
+
+Context manager. Records every intercepted call made inside the block to `path`, written on clean exit only. `redact` is a list of key names to scrub before saving. Yields the `Recorder`.
+
+### `replay(path, *, strict=False)`
+
+Context manager. Serves recorded results for intercepted calls without running the real functions. `strict=True` raises `DivergenceError` on any mismatch. Yields the `Player` (with `.divergences`, `.remaining`, `.cursor`).
+
+### `Cassette`
+
+| Member | Description |
+|---|---|
+| `Cassette.load(path)` | Load from disk (raises `CassetteNotFound`) |
+| `.save(path)` | Write pretty-printed JSON, creating parent dirs |
+| `.num_steps` | Number of recorded steps |
+| `.total_input_tokens` / `.total_output_tokens` / `.total_tokens` | Token totals |
+| `.duration_ms` | Wall time of the recorded run |
+| `.redact(key, replacement="****")` | Scrub every value under `key`, at any depth |
+
+### `diff_cassettes(a, b) -> CassetteDiff`
+
+Compare two cassettes (paths or `Cassette` objects). Returns a `CassetteDiff` with `new_calls`, `dropped_calls`, `changed_calls`, `token_delta`, `input_token_delta`, `output_token_delta`, `step_delta`, and `identical`.
+
+### Exceptions
+
+All inherit from `AgentCassetteError`:
+
+| Exception | Raised when |
+|---|---|
+| `CassetteNotFound` | Replaying a path that doesn't exist |
+| `ReplayExhausted` | The agent makes more calls than the cassette recorded |
+| `DivergenceError` | A strict replay sees a call that differs from the recording |
+
+## Notes & limitations
+
+- **Replayed results are JSON.** Recorded values round-trip through JSON, so on replay you get plain dicts/lists/primitives, not the original SDK objects. For typical LLM responses (dicts) this is exactly what you want.
+- **Ordering matters.** Calls replay in the order they were recorded. agentcassette matches sequentially, which is deterministic and mirrors how an agent actually executes. Truly concurrent calls (e.g. `asyncio.gather`) are recorded in completion order; if that order isn't stable across runs, replay matching is best-effort — record such sections sequentially if you need strict determinism.
+- **Sync and async.** Both `def` and `async def` callables are supported. `record`/`replay` are thread-local and cover the event loop running on that thread; wrap per-thread if your agent fans out across OS threads.
+- **Streaming responses** (token iterators) are not specially handled yet — wrap at a boundary where the response is already materialized.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+Part of the [aenealabs](https://github.com/aenealabs) AI agent toolkit.

agentcassette-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agentcassette/__init__.py,sha256=WdBqiRG9OfsoSWGGBzAYVg5ik9SxmhNRRc5ClpzpggU,2513
+agentcassette/_cassette.py,sha256=SEk9cd5f5BR8YNJTkWU512yBIiAAOsd4G0iZBJOr5jU,5779
+agentcassette/_diff.py,sha256=_mcod434ty-O3m-AG1GQEETVGx4pmXq7-ETo9mi3PIA,2707
+agentcassette/_errors.py,sha256=tsI34kUVRvd8GDKc6-kdnXkal5jpUh0bD6fjsopTfD8,1217
+agentcassette/_session.py,sha256=sr9kxFxVRO2SVs2rqiQ34wp_c1DGzTJk8kA55YpU0Kk,9017
+agentcassette/_tokens.py,sha256=x3S2BEaa0YYkE6gouTmpPKEWuJdTAqrLEb0PCWLLceE,2985
+agentcassette/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentcassette-0.1.0.dist-info/METADATA,sha256=RCFPSZDRK12pp_8hC2lVxY_BQa-hwRn-M3QHfQXjnAk,11418
+agentcassette-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentcassette-0.1.0.dist-info/licenses/LICENSE,sha256=MYtxdpJgHsIGUqnc1UYrqDff94Vn7SDKXTxLhqOyCi8,1071
+agentcassette-0.1.0.dist-info/RECORD,,

agentcassette-0.1.0.dist-info/WHEEL

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

agentcassette-0.1.0.dist-info/licenses/LICENSE

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