standin 0.2.0__py3-none-any.whl

standin/__init__.py

@@ -0,0 +1,42 @@
+"""standin — a stand-in for the real LLM in your tests.
+
+Record real LLM API calls once, then replay them forever: fast, free, offline,
+and deterministic. Provider-agnostic (hooks httpx), streaming and tool-calls
+supported, secrets redacted so cassettes are safe to commit.
+
+    import standin
+
+    with standin.use_cassette("tests/cassettes/summary.json"):
+        resp = openai_client.chat.completions.create(...)   # recorded once, replayed after
+
+Architecture (see ARCHITECTURE.md): a transport-neutral policy **engine** sits
+behind pluggable **interceptors** (httpx today), **matchers**, **redactors**,
+and **stores**, so behavior is easy to reason about and extend.
+"""
+from .config import Config
+from .core import use_cassette
+from .exceptions import CannotReplay, CassetteError, ConfigError, StandinError
+from .matching import DefaultMatcher, FuzzyMatcher, Matcher
+from .models import Mode
+from .redaction import DefaultRedactor, NullRedactor, Redactor
+from .storage import CassetteStore, JSONCassetteStore
+
+__version__ = "0.2.0"
+__all__ = [
+    "use_cassette",
+    "Config",
+    "Mode",
+    "StandinError",
+    "CannotReplay",
+    "CassetteError",
+    "ConfigError",
+    "Redactor",
+    "DefaultRedactor",
+    "NullRedactor",
+    "Matcher",
+    "DefaultMatcher",
+    "FuzzyMatcher",
+    "CassetteStore",
+    "JSONCassetteStore",
+    "__version__",
+]

standin/_codec.py

@@ -0,0 +1,81 @@
+"""Body (de)serialization and canonicalization.
+
+A body is stored as one of ``{"json": ...}``, ``{"text": ...}``, ``{"b64": ...}``
+or ``{"empty": true}`` so cassettes stay human-readable when possible. Canonical
+forms are used only for request matching, never written to disk.
+"""
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+
+def _try_json(raw: bytes, content_type: str) -> Any | None:
+    if "application/json" not in (content_type or ""):
+        # Some providers omit the header; still try if it smells like JSON.
+        stripped = raw[:1]
+        if stripped not in (b"{", b"["):
+            return None
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+
+
+def encode_body(raw: bytes, content_type: str, redactor=None) -> dict[str, Any]:
+    if not raw:
+        return {"empty": True}
+    obj = _try_json(raw, content_type)
+    if obj is not None:
+        if redactor is not None:
+            obj = redactor.redact_obj(obj)
+        return {"json": obj}
+    try:
+        text = raw.decode("utf-8")
+        if redactor is not None:
+            text = redactor.redact_text(text)
+        return {"text": text}
+    except UnicodeDecodeError:
+        return {"b64": base64.b64encode(raw).decode("ascii")}
+
+
+def decode_body(body: dict[str, Any]) -> bytes:
+    if not body or body.get("empty"):
+        return b""
+    if "json" in body:
+        return json.dumps(body["json"], ensure_ascii=False).encode("utf-8")
+    if "text" in body:
+        return body["text"].encode("utf-8")
+    if "b64" in body:
+        return base64.b64decode(body["b64"])
+    return b""
+
+
+def canonical_live(raw: bytes, content_type: str, redactor=None) -> str:
+    """Canonical string for a live (in-flight) request body, for matching."""
+    if not raw:
+        return ""
+    obj = _try_json(raw, content_type)
+    if obj is not None:
+        if redactor is not None:
+            obj = redactor.redact_obj(obj)
+        return json.dumps(obj, sort_keys=True, ensure_ascii=False)
+    try:
+        text = raw.decode("utf-8")
+        return redactor.redact_text(text) if redactor is not None else text
+    except UnicodeDecodeError:
+        return base64.b64encode(raw).decode("ascii")
+
+
+def canonical_stored(body: dict[str, Any]) -> str:
+    """Canonical string for a stored request body, for matching."""
+    if not body or body.get("empty"):
+        return ""
+    if "json" in body:
+        return json.dumps(body["json"], sort_keys=True, ensure_ascii=False)
+    if "text" in body:
+        return body["text"]
+    if "b64" in body:
+        return body["b64"]
+    return ""

standin/cassette.py

@@ -0,0 +1,40 @@
+"""In-memory cassette: the interactions plus the replay cursor."""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .models import Interaction
+
+
+@dataclass
+class Cassette:
+    path: Path
+    interactions: list[Interaction] = field(default_factory=list)
+    dirty: bool = False
+    preexisting: int = 0
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def __post_init__(self):
+        self.preexisting = len(self.interactions)
+
+    def append(self, interaction: Interaction) -> None:
+        with self._lock:
+            self.interactions.append(interaction)
+            self.dirty = True
+
+    def find_unplayed(self, matches, live_request) -> Interaction | None:
+        """Return the first not-yet-played interaction that matches the request.
+
+        `matches(live_request, stored_request) -> bool` is supplied by the
+        matcher, so exact and fuzzy strategies share this loop. Playing in order
+        lets repeated calls (e.g. an agent loop) replay their distinct recorded
+        responses sequentially. Locked so a shared cassette never double-plays.
+        """
+        with self._lock:
+            for interaction in self.interactions:
+                if not interaction.played and matches(live_request, interaction.request):
+                    interaction.played = True
+                    return interaction
+        return None

standin/cli.py

@@ -0,0 +1,112 @@
+"""The `standin` command: inspect and maintain cassettes.
+
+    standin list    cassette.json          # one line per interaction
+    standin show    cassette.json 0        # full request/response of interaction 0
+    standin stats   cassette.json          # summary counts
+    standin scrub   cassette.json          # re-run secret redaction over a cassette
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+from . import __version__
+from .redaction import DefaultRedactor
+from .storage import JSONCassetteStore
+
+
+def _load(path: str):
+    return JSONCassetteStore().load(Path(path))
+
+
+def _redact_body(body: dict, r: DefaultRedactor) -> dict:
+    if "json" in body:
+        return {"json": r.redact_obj(body["json"])}
+    if "text" in body:
+        return {"text": r.redact_text(body["text"])}
+    return body
+
+
+def cmd_list(args) -> int:
+    items = _load(args.cassette)
+    print(f"{len(items)} interaction(s) in {args.cassette}")
+    for i, it in enumerate(items):
+        print(f"  [{i}] {it.request.method:<6} {it.response.status_code}  {it.request.url}")
+    return 0
+
+
+def cmd_show(args) -> int:
+    items = _load(args.cassette)
+    it = items[args.index]
+    print(json.dumps({"request": vars(it.request), "response": vars(it.response)}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_stats(args) -> int:
+    items = _load(args.cassette)
+    print(f"interactions : {len(items)}")
+    print(f"methods      : {dict(Counter(it.request.method for it in items))}")
+    print(f"statuses     : {dict(Counter(it.response.status_code for it in items))}")
+    return 0
+
+
+def cmd_scrub(args) -> int:
+    store = JSONCassetteStore()
+    path = Path(args.cassette)
+    items = store.load(path)
+    r = DefaultRedactor()
+    for it in items:
+        it.request.headers = r.redact_headers(it.request.headers)
+        it.response.headers = r.redact_headers(it.response.headers)
+        it.request.body = _redact_body(it.request.body, r)
+        it.response.body = _redact_body(it.response.body, r)
+    store.save(path, items)
+    print(f"scrubbed {len(items)} interaction(s) in {path}")
+    return 0
+
+
+def main(argv=None) -> int:
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    ap = argparse.ArgumentParser(prog="standin", description="Inspect and maintain standin cassettes.")
+    ap.add_argument("--version", action="version", version=f"standin {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("list", help="list interactions in a cassette")
+    p.add_argument("cassette")
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("show", help="show one interaction as JSON")
+    p.add_argument("cassette")
+    p.add_argument("index", type=int)
+    p.set_defaults(func=cmd_show)
+
+    p = sub.add_parser("stats", help="summary counts for a cassette")
+    p.add_argument("cassette")
+    p.set_defaults(func=cmd_stats)
+
+    p = sub.add_parser("scrub", help="re-run secret redaction over a cassette")
+    p.add_argument("cassette")
+    p.set_defaults(func=cmd_scrub)
+
+    args = ap.parse_args(argv)
+    try:
+        return args.func(args)
+    except FileNotFoundError:
+        print(f"error: cassette not found: {args.cassette}", file=sys.stderr)
+        return 1
+    except IndexError:
+        print("error: interaction index out of range", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

standin/config.py

@@ -0,0 +1,41 @@
+"""Configuration object wiring the pluggable pieces together."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from .exceptions import ConfigError
+from .matching import DEFAULT_MATCH_ON, Matcher
+from .models import Mode
+from .redaction import DefaultRedactor, NullRedactor, Redactor
+from .storage import CassetteStore, JSONCassetteStore
+
+
+@dataclass
+class Config:
+    mode: Mode = Mode.ONCE
+    match_on: Sequence[str] = DEFAULT_MATCH_ON
+    redact: bool = True
+    redactor: Redactor | None = None
+    matcher: Matcher | None = None
+    store: CassetteStore = field(default_factory=JSONCassetteStore)
+
+    def __post_init__(self):
+        if not isinstance(self.mode, Mode):
+            try:
+                self.mode = Mode(self.mode)
+            except ValueError as exc:
+                raise ConfigError(
+                    f"invalid mode {self.mode!r}; choose one of {[m.value for m in Mode]}"
+                ) from exc
+        if self.redactor is None:
+            self.redactor = DefaultRedactor() if self.redact else NullRedactor()
+        # Validate match_on only for the built-in matcher; a custom matcher may
+        # define its own vocabulary.
+        if self.matcher is None:
+            valid = {"method", "url", "body"}
+            unknown = set(self.match_on) - valid
+            if unknown:
+                raise ConfigError(
+                    f"unknown match_on {sorted(unknown)}; valid options are {sorted(valid)}"
+                )

standin/core.py

@@ -0,0 +1,68 @@
+"""Public entry point: the ``use_cassette`` context manager."""
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+
+from .cassette import Cassette
+from .config import Config
+from .engine import Engine
+from .exceptions import ConfigError
+from .interceptors.base import reset_active_engine, set_active_engine
+from .interceptors.httpx_interceptor import HttpxInterceptor
+from .matching import DEFAULT_MATCH_ON, Matcher
+from .models import Mode
+from .redaction import Redactor
+from .storage import CassetteStore
+
+_httpx_interceptor = HttpxInterceptor()
+
+
+@contextmanager
+def use_cassette(
+    path,
+    *,
+    mode: str = "once",
+    match_on: Sequence[str] = DEFAULT_MATCH_ON,
+    redact: bool = True,
+    redactor: Redactor | None = None,
+    matcher: Matcher | None = None,
+    store: CassetteStore | None = None,
+) -> Iterator[Cassette]:
+    """Record LLM/HTTP calls to ``path``, or replay them if already recorded.
+
+    The environment variable ``STANDIN_MODE`` overrides ``mode`` for a whole run
+    (e.g. ``STANDIN_MODE=none pytest`` guarantees no live calls in CI).
+    """
+    mode = os.environ.get("STANDIN_MODE", mode)
+    try:
+        mode_value = mode if isinstance(mode, Mode) else Mode(mode)
+    except ValueError as exc:
+        raise ConfigError(
+            f"invalid mode {mode!r}; choose one of {[m.value for m in Mode]}"
+        ) from exc
+
+    config = Config(
+        mode=mode_value,
+        match_on=match_on,
+        redact=redact,
+        redactor=redactor,
+        matcher=matcher,
+    )
+    if store is not None:
+        config.store = store
+
+    path = Path(path)
+    cassette = Cassette(path=path, interactions=config.store.load(path))
+    engine = Engine(cassette, config)
+
+    _httpx_interceptor.install()
+    token = set_active_engine(engine)
+    try:
+        yield cassette
+    finally:
+        reset_active_engine(token)
+        if cassette.dirty:
+            config.store.save(path, cassette.interactions)

standin/engine.py

@@ -0,0 +1,105 @@
+"""The record/replay policy engine.
+
+The engine is deliberately transport-agnostic: it speaks only ``RawRequest`` /
+``RawResponse`` and a ``do_real`` callback. Interceptors adapt a concrete client
+(httpx today, others later) to this interface, so all the decision logic lives
+here in one testable place.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Callable
+
+from . import _codec
+from .cassette import Cassette
+from .config import Config
+from .exceptions import CannotReplay
+from .matching import DefaultMatcher
+from .models import (
+    Interaction,
+    Mode,
+    RawRequest,
+    RawResponse,
+    RecordedRequest,
+    RecordedResponse,
+)
+from .redaction import DefaultRedactor
+
+SyncReal = Callable[[RawRequest], RawResponse]
+AsyncReal = Callable[[RawRequest], Awaitable[RawResponse]]
+
+
+class Engine:
+    def __init__(self, cassette: Cassette, config: Config):
+        self.cassette = cassette
+        self.config = config
+        # Config.__post_init__ guarantees a redactor; narrow it for the type checker.
+        self.redactor = config.redactor if config.redactor is not None else DefaultRedactor()
+        self.matcher = config.matcher or DefaultMatcher(self.redactor, config.match_on)
+
+    # -- policy -------------------------------------------------------------
+    def _plan(self) -> tuple[bool, bool]:
+        mode = self.config.mode
+        try_replay = mode in (Mode.ONCE, Mode.NONE, Mode.NEW_EPISODES)
+        record_on_miss = (
+            mode in (Mode.ALL, Mode.NEW_EPISODES)
+            or (mode is Mode.ONCE and self.cassette.preexisting == 0)
+        )
+        return try_replay, record_on_miss
+
+    def _find(self, request: RawRequest):
+        return self.cassette.find_unplayed(self.matcher.matches, request)
+
+    def _replay(self, interaction: Interaction) -> RawResponse:
+        r = interaction.response
+        return RawResponse(status_code=r.status_code, headers=dict(r.headers), body=_codec.decode_body(r.body))
+
+    def _record(self, request: RawRequest, response: RawResponse) -> None:
+        self.cassette.append(Interaction(
+            request=RecordedRequest(
+                method=request.method.upper(),
+                url=request.url,
+                headers=self.redactor.redact_headers(request.headers),
+                body=_codec.encode_body(request.body, _ct(request.headers), self.redactor),
+            ),
+            response=RecordedResponse(
+                status_code=response.status_code,
+                headers=self.redactor.redact_headers(response.headers),
+                body=_codec.encode_body(response.body, _ct(response.headers), self.redactor),
+            ),
+        ))
+
+    def _miss(self, request: RawRequest) -> CannotReplay:
+        return CannotReplay(f"standin: no recorded interaction for {request.method} {request.url}")
+
+    # -- entry points -------------------------------------------------------
+    def handle(self, request: RawRequest, do_real: SyncReal) -> RawResponse:
+        try_replay, record_on_miss = self._plan()
+        if try_replay:
+            inter = self._find(request)
+            if inter is not None:
+                return self._replay(inter)
+            if not record_on_miss:
+                raise self._miss(request)
+        response = do_real(request)
+        self._record(request, response)
+        return response
+
+    async def handle_async(self, request: RawRequest, do_real: AsyncReal) -> RawResponse:
+        try_replay, record_on_miss = self._plan()
+        if try_replay:
+            inter = self._find(request)
+            if inter is not None:
+                return self._replay(inter)
+            if not record_on_miss:
+                raise self._miss(request)
+        response = await do_real(request)
+        self._record(request, response)
+        return response
+
+
+def _ct(headers) -> str:
+    for k, v in headers.items():
+        if k.lower() == "content-type":
+            return v
+    return ""

standin/exceptions.py

@@ -0,0 +1,22 @@
+"""Exception hierarchy for standin.
+
+All errors derive from :class:`StandinError` so callers can catch the whole
+library with a single ``except``.
+"""
+from __future__ import annotations
+
+
+class StandinError(Exception):
+    """Base class for every error raised by standin."""
+
+
+class ConfigError(StandinError):
+    """Invalid configuration (bad mode, conflicting options, ...)."""
+
+
+class CassetteError(StandinError):
+    """A cassette file is missing, malformed, or on an unsupported version."""
+
+
+class CannotReplay(StandinError):
+    """Replay-only mode encountered a request with no matching recording."""

standin/interceptors/__init__.py

@@ -0,0 +1,11 @@
+"""Interceptors: pluggable adapters between HTTP clients and the engine."""
+from .base import Interceptor, get_active_engine, reset_active_engine, set_active_engine
+from .httpx_interceptor import HttpxInterceptor
+
+__all__ = [
+    "Interceptor",
+    "HttpxInterceptor",
+    "get_active_engine",
+    "set_active_engine",
+    "reset_active_engine",
+]

standin/interceptors/base.py

@@ -0,0 +1,35 @@
+"""Interceptor abstraction + the active-engine context.
+
+An interceptor knows how to splice into one HTTP client and translate its calls
+into the engine's transport-neutral interface. The active engine is stored in a
+``ContextVar`` so recording is correct under threads and asyncio, and so the
+patch stays inert whenever no cassette is open.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from contextvars import ContextVar, Token
+
+from ..engine import Engine
+
+_active_engine: ContextVar[Engine | None] = ContextVar("standin_active_engine", default=None)
+
+
+def get_active_engine() -> Engine | None:
+    return _active_engine.get()
+
+
+def set_active_engine(engine: Engine) -> Token:
+    return _active_engine.set(engine)
+
+
+def reset_active_engine(token: Token) -> None:
+    _active_engine.reset(token)
+
+
+class Interceptor(ABC):
+    """Splices into an HTTP client and routes its traffic through the engine."""
+
+    @abstractmethod
+    def install(self) -> None:
+        """Patch the client. Must be idempotent and inert with no active engine."""

standin/interceptors/httpx_interceptor.py

@@ -0,0 +1,89 @@
+"""httpx interceptor: routes all httpx traffic through the engine.
+
+Patches ``httpx.HTTPTransport.handle_request`` and the async transport once.
+Because OpenAI, Anthropic, Gemini, Mistral, Cohere, litellm, LangChain and
+LlamaIndex all send over httpx, this single hook covers them.
+"""
+from __future__ import annotations
+
+import threading
+
+import httpx
+
+from ..models import RawRequest, RawResponse
+from .base import Interceptor, get_active_engine
+
+_install_lock = threading.Lock()
+
+# Headers to drop when rebuilding a response from already-decoded bytes, or httpx
+# would try to decompress / re-length it a second time.
+_DROP = {"content-encoding", "content-length", "transfer-encoding"}
+
+
+def _safe_headers(headers):
+    return [(k, v) for k, v in headers.items() if k.lower() not in _DROP]
+
+
+def _to_httpx(raw: RawResponse, request) -> httpx.Response:
+    return httpx.Response(
+        status_code=raw.status_code,
+        headers=_safe_headers(raw.headers),
+        content=raw.body,
+        request=request,
+    )
+
+
+def _to_raw_request(request) -> RawRequest:
+    return RawRequest(request.method, str(request.url), dict(request.headers), request.content or b"")
+
+
+class HttpxInterceptor(Interceptor):
+    _installed = False
+    _orig_sync = None
+    _orig_async = None
+
+    def install(self) -> None:
+        cls = HttpxInterceptor
+        if cls._installed:
+            return
+        with _install_lock:  # double-checked: patch httpx exactly once, thread-safely
+            if cls._installed:
+                return
+            self._patch()
+
+    def _patch(self) -> None:
+        cls = HttpxInterceptor
+        cls._orig_sync = httpx.HTTPTransport.handle_request
+        cls._orig_async = httpx.AsyncHTTPTransport.handle_async_request
+        orig_sync = cls._orig_sync
+        orig_async = cls._orig_async
+
+        def patched_sync(self, request):
+            engine = get_active_engine()
+            if engine is None:
+                return orig_sync(self, request)
+
+            def do_real(_raw):
+                resp = orig_sync(self, request)
+                resp.read()
+                return RawResponse(resp.status_code, dict(resp.headers), resp.content)
+
+            raw_resp = engine.handle(_to_raw_request(request), do_real)
+            return _to_httpx(raw_resp, request)
+
+        async def patched_async(self, request):
+            engine = get_active_engine()
+            if engine is None:
+                return await orig_async(self, request)
+
+            async def do_real(_raw):
+                resp = await orig_async(self, request)
+                await resp.aread()
+                return RawResponse(resp.status_code, dict(resp.headers), resp.content)
+
+            raw_resp = await engine.handle_async(_to_raw_request(request), do_real)
+            return _to_httpx(raw_resp, request)
+
+        httpx.HTTPTransport.handle_request = patched_sync  # type: ignore[method-assign]
+        httpx.AsyncHTTPTransport.handle_async_request = patched_async  # type: ignore[method-assign]
+        cls._installed = True

standin/matching.py

@@ -0,0 +1,89 @@
+"""Request matching.
+
+The `Matcher` protocol is a single predicate, `matches(live, stored)`. Two
+implementations ship:
+
+* ``DefaultMatcher`` — exact match on any subset of method/url/body, and
+  JSON-body matching is key-order-insensitive.
+* ``FuzzyMatcher`` — method/url exact, but the body may differ up to a string
+  similarity threshold, so a reworded or reformatted prompt still replays.
+
+A true embedding/semantic matcher plugs in the same way: implement ``matches``.
+"""
+from __future__ import annotations
+
+import difflib
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from . import _codec
+from .models import RawRequest, RecordedRequest
+from .redaction import Redactor
+
+DEFAULT_MATCH_ON = ("method", "url", "body")
+_SEP = ""
+
+
+@runtime_checkable
+class Matcher(Protocol):
+    def matches(self, live: RawRequest, stored: RecordedRequest) -> bool: ...
+
+
+class DefaultMatcher:
+    """Exact match on the chosen fields (JSON body compared order-insensitively)."""
+
+    def __init__(self, redactor: Redactor, match_on: Sequence[str] = DEFAULT_MATCH_ON):
+        self._redactor = redactor
+        self._match_on = tuple(match_on)
+
+    def live_key(self, request: RawRequest) -> str:
+        parts = []
+        if "method" in self._match_on:
+            parts.append(request.method.upper())
+        if "url" in self._match_on:
+            parts.append(request.url)
+        if "body" in self._match_on:
+            parts.append(_codec.canonical_live(request.body, _content_type(request.headers), self._redactor))
+        return _SEP.join(parts)
+
+    def stored_key(self, request: RecordedRequest) -> str:
+        parts = []
+        if "method" in self._match_on:
+            parts.append(request.method.upper())
+        if "url" in self._match_on:
+            parts.append(request.url)
+        if "body" in self._match_on:
+            parts.append(_codec.canonical_stored(request.body))
+        return _SEP.join(parts)
+
+    def matches(self, live: RawRequest, stored: RecordedRequest) -> bool:
+        return self.live_key(live) == self.stored_key(stored)
+
+
+class FuzzyMatcher:
+    """Tolerate small body drift. method/url must match (per match_on); the body
+    must be at least ``threshold`` similar (difflib ratio, 0..1). Zero deps."""
+
+    def __init__(self, redactor: Redactor, match_on: Sequence[str] = DEFAULT_MATCH_ON, threshold: float = 0.9):
+        self._redactor = redactor
+        self._match_on = tuple(match_on)
+        self.threshold = threshold
+
+    def matches(self, live: RawRequest, stored: RecordedRequest) -> bool:
+        if "method" in self._match_on and live.method.upper() != stored.method.upper():
+            return False
+        if "url" in self._match_on and live.url != stored.url:
+            return False
+        if "body" in self._match_on:
+            lb = _codec.canonical_live(live.body, _content_type(live.headers), self._redactor)
+            sb = _codec.canonical_stored(stored.body)
+            if lb != sb and difflib.SequenceMatcher(None, lb, sb).ratio() < self.threshold:
+                return False
+        return True
+
+
+def _content_type(headers) -> str:
+    for k, v in headers.items():
+        if k.lower() == "content-type":
+            return v
+    return ""

standin/models.py

@@ -0,0 +1,63 @@
+"""Typed data model shared across layers.
+
+Two families of types keep the layers decoupled:
+
+* ``RawRequest`` / ``RawResponse`` are the *transport-neutral* representation an
+  interceptor hands to the engine. They carry raw bytes and never depend on
+  httpx (or any other client).
+* ``RecordedRequest`` / ``RecordedResponse`` / ``Interaction`` are the
+  *on-disk* representation, with bodies encoded into a JSON-friendly shape.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Mode(str, Enum):
+    """Record/replay policy for a cassette."""
+
+    ONCE = "once"  # replay if the cassette exists, else record
+    NONE = "none"  # replay only; error on any unmatched call (use in CI)
+    ALL = "all"  # always re-record, ignoring existing interactions
+    NEW_EPISODES = "new_episodes"  # replay matches, record anything new
+
+
+# -- transport-neutral (in flight) --------------------------------------------
+@dataclass
+class RawRequest:
+    method: str
+    url: str
+    headers: dict[str, str]
+    body: bytes
+
+
+@dataclass
+class RawResponse:
+    status_code: int
+    headers: dict[str, str]
+    body: bytes
+
+
+# -- persisted (on disk) ------------------------------------------------------
+@dataclass
+class RecordedRequest:
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    body: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RecordedResponse:
+    status_code: int
+    headers: dict[str, str] = field(default_factory=dict)
+    body: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Interaction:
+    request: RecordedRequest
+    response: RecordedResponse
+    played: bool = False

standin/py.typed

@@ -0,0 +1 @@
+

standin/pytest_plugin.py

@@ -0,0 +1,37 @@
+"""pytest integration: a ``standin`` fixture and a ``@pytest.mark.standin`` marker.
+
+Cassettes default to ``<test-dir>/cassettes/<test-name>.json``. First run records;
+later runs replay. In CI, set ``STANDIN_MODE=none`` to fail on any un-recorded call.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from .core import use_cassette
+
+
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers",
+        "standin(path=None, mode='once', match_on=None): record/replay LLM HTTP calls for this test",
+    )
+
+
+@pytest.fixture
+def standin(request):
+    marker = request.node.get_closest_marker("standin")
+    opts = dict(marker.kwargs) if marker else {}
+
+    name = opts.get("path") or f"{request.node.name}.json"
+    path = Path(name)
+    if not path.is_absolute():
+        path = Path(request.node.fspath).parent / "cassettes" / path
+
+    kwargs = {"mode": opts.get("mode", "once")}
+    if opts.get("match_on"):
+        kwargs["match_on"] = opts["match_on"]
+
+    with use_cassette(path, **kwargs) as cassette:
+        yield cassette

standin/redaction.py

@@ -0,0 +1,73 @@
+"""Redaction: keep credentials out of committed cassettes.
+
+``Redactor`` is a Protocol so you can drop in your own policy; ``DefaultRedactor``
+covers auth headers and common secret token formats, and ``NullRedactor`` is a
+no-op for when you explicitly want raw cassettes.
+"""
+from __future__ import annotations
+
+import re
+from re import Pattern
+from typing import Any, Protocol, runtime_checkable
+
+PLACEHOLDER = "[REDACTED]"
+
+SENSITIVE_HEADERS = frozenset({
+    "authorization", "x-api-key", "api-key", "openai-api-key", "anthropic-api-key",
+    "x-goog-api-key", "cookie", "set-cookie", "proxy-authorization",
+})
+
+SECRET_PATTERNS: list[Pattern] = [
+    re.compile(r"sk-ant-[A-Za-z0-9\-_]{20,}"),
+    re.compile(r"sk-(?:proj-)?[A-Za-z0-9]{20,}"),
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    re.compile(r"AIza[0-9A-Za-z\-_]{35}"),
+    re.compile(r"gh[pousr]_[A-Za-z0-9]{36,}"),
+    re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"),
+    re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
+]
+
+
+@runtime_checkable
+class Redactor(Protocol):
+    def redact_headers(self, headers: dict[str, str]) -> dict[str, str]: ...
+    def redact_text(self, text: str) -> str: ...
+    def redact_obj(self, obj: Any) -> Any: ...
+
+
+class DefaultRedactor:
+    """Masks sensitive headers and secret-looking tokens in bodies."""
+
+    def __init__(self, extra_headers=(), extra_patterns=()):
+        self._headers = SENSITIVE_HEADERS | {h.lower() for h in extra_headers}
+        self._patterns = list(SECRET_PATTERNS) + [re.compile(p) for p in extra_patterns]
+
+    def redact_headers(self, headers: dict[str, str]) -> dict[str, str]:
+        return {k: (PLACEHOLDER if k.lower() in self._headers else v) for k, v in headers.items()}
+
+    def redact_text(self, text: str) -> str:
+        for rx in self._patterns:
+            text = rx.sub(PLACEHOLDER, text)
+        return text
+
+    def redact_obj(self, obj: Any) -> Any:
+        if isinstance(obj, str):
+            return self.redact_text(obj)
+        if isinstance(obj, dict):
+            return {k: self.redact_obj(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [self.redact_obj(v) for v in obj]
+        return obj
+
+
+class NullRedactor:
+    """No-op redactor (used when redaction is turned off)."""
+
+    def redact_headers(self, headers: dict[str, str]) -> dict[str, str]:
+        return dict(headers)
+
+    def redact_text(self, text: str) -> str:
+        return text
+
+    def redact_obj(self, obj: Any) -> Any:
+        return obj

standin/storage.py

@@ -0,0 +1,82 @@
+"""Cassette persistence.
+
+``CassetteStore`` is a Protocol so alternative formats (YAML, a single-file
+archive, ...) can be added without touching the engine. ``JSONCassetteStore``
+writes indented, reviewable JSON.
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from dataclasses import fields
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .exceptions import CassetteError
+from .models import Interaction, RecordedRequest, RecordedResponse
+
+FORMAT_VERSION = 1
+
+_REQ_FIELDS = {f.name for f in fields(RecordedRequest)}
+_RESP_FIELDS = {f.name for f in fields(RecordedResponse)}
+
+
+@runtime_checkable
+class CassetteStore(Protocol):
+    def load(self, path: Path) -> list[Interaction]: ...
+    def save(self, path: Path, interactions: list[Interaction]) -> None: ...
+
+
+class JSONCassetteStore:
+    def load(self, path: Path) -> list[Interaction]:
+        path = Path(path)
+        if not path.exists():
+            return []
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except ValueError as exc:
+            raise CassetteError(f"cassette {path} is not valid JSON: {exc}") from exc
+        version = data.get("version")
+        if version != FORMAT_VERSION:
+            raise CassetteError(f"cassette {path} has unsupported version {version!r}")
+        out: list[Interaction] = []
+        for idx, item in enumerate(data.get("interactions", [])):
+            try:
+                req = item["request"]
+                resp = item["response"]
+                # Ignore unknown keys so newer cassettes stay loadable (forward-compat).
+                out.append(Interaction(
+                    request=RecordedRequest(**{k: v for k, v in req.items() if k in _REQ_FIELDS}),
+                    response=RecordedResponse(**{k: v for k, v in resp.items() if k in _RESP_FIELDS}),
+                ))
+            except (KeyError, TypeError, AttributeError) as exc:
+                raise CassetteError(f"cassette {path} interaction {idx} is malformed: {exc}") from exc
+        return out
+
+    def save(self, path: Path, interactions: list[Interaction]) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "version": FORMAT_VERSION,
+            "recorded_with": "standin",
+            "interactions": [
+                {
+                    "request": vars(i.request),
+                    "response": vars(i.response),
+                }
+                for i in interactions
+            ],
+        }
+        text = json.dumps(data, indent=2, ensure_ascii=False)
+        # Atomic write: never leave a half-written cassette if interrupted.
+        fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=path.name + ".", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(text)
+            os.replace(tmp, path)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise

standin-0.2.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: standin
+Version: 0.2.0
+Summary: A stand-in for the real LLM in your tests. Record LLM API calls once, replay them forever: fast, free, deterministic, offline.
+Project-URL: Homepage, https://github.com/eeshsaxena/standin
+Project-URL: Source, https://github.com/eeshsaxena/standin
+Project-URL: Issues, https://github.com/eeshsaxena/standin/issues
+Project-URL: Changelog, https://github.com/eeshsaxena/standin/blob/main/CHANGELOG.md
+Author-email: Eesh Saxena <eeshsaxena@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,anthropic,cassette,deterministic,llm,mock,openai,pytest,record,replay,testing,vcr
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.30; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# standin
+
+**A stand-in for the real LLM in your tests.** Record your LLM API calls once, then replay them forever: fast, free, deterministic, and fully offline. One line, any provider.
+
+<p align="center"><img src="demo/standin.gif" alt="standin: record LLM calls once, replay them instantly and offline" width="820"></p>
+
+```python
+import standin
+
+with standin.use_cassette("tests/cassettes/summary.json"):
+    reply = client.chat.completions.create(model="gpt-4o", messages=[...])
+# First run: hits the real API and records it.
+# Every run after: replayed from disk. No network, no cost, same answer.
+```
+
+Your LLM tests are slow, flaky, and cost money because they hit real APIs. `standin` makes them **deterministic and offline** by recording the real HTTP calls once and replaying them after, with the things LLM devs actually need: **streaming**, **tool-calls**, **secret redaction**, and **body-aware matching**.
+
+---
+
+## Why not just VCR.py?
+
+VCR.py is great, but it's a general HTTP tool. `standin` is built for LLMs:
+
+- **Provider-agnostic, zero wiring.** It hooks `httpx` under the hood, so it works with **OpenAI, Anthropic, Gemini, Mistral, Cohere, litellm, LangChain, LlamaIndex** — anything that sends over httpx. No per-SDK adapters.
+- **Streaming just works.** Server-sent event (SSE) responses are recorded and replayed intact.
+- **Safe to commit.** API keys in headers and secret-looking tokens in bodies are **redacted automatically**, so cassettes can live in a public repo.
+- **Body-aware matching.** Requests match on normalized JSON, so key ordering and formatting noise don't break replays. Repeated identical calls (agent loops) replay in order.
+- **One-line pytest fixture**, with sane auto-named cassettes.
+- **Clean, typed, extensible core** (see [ARCHITECTURE.md](ARCHITECTURE.md)) — swap the matcher, redactor, or storage backend.
+
+## Install
+
+```bash
+pip install standin
+```
+
+Python 3.9+ and `httpx` (already a dependency of the major LLM SDKs).
+
+## Quickstart
+
+### With pytest (recommended)
+
+```python
+import pytest
+
+@pytest.mark.standin          # cassette auto-named tests/cassettes/test_summarize.json
+def test_summarize(standin):
+    out = summarize("war and peace")     # your code that calls an LLM
+    assert "Napoleon" in out
+```
+
+First run records against the real API; every run after replays from the cassette. Commit the cassette and teammates (and CI) run the test with **no keys and no network**.
+
+### Anywhere (context manager)
+
+```python
+import standin
+from openai import OpenAI
+
+client = OpenAI()
+with standin.use_cassette("tests/cassettes/haiku.json"):
+    resp = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "haiku about testing"}],
+    )
+```
+
+## Modes
+
+| Mode | Behavior |
+| --- | --- |
+| `once` (default) | Replay if the cassette exists, otherwise record it. |
+| `none` | Replay only. **Errors on any unrecorded call** — use this in CI. |
+| `all` | Always re-record, ignoring existing interactions. |
+| `new_episodes` | Replay what's recorded, record anything new (great for agent loops). |
+
+**In CI**, force replay-only for the whole run so a stray live call fails loudly:
+
+```bash
+STANDIN_MODE=none pytest
+```
+
+## What a cassette looks like
+
+Plain, reviewable JSON, secrets already stripped:
+
+```json
+{
+  "version": 1,
+  "recorded_with": "standin",
+  "interactions": [
+    {
+      "request": {
+        "method": "POST",
+        "url": "https://api.openai.com/v1/chat/completions",
+        "headers": { "authorization": "[REDACTED]" },
+        "body": { "json": { "model": "gpt-4o-mini", "messages": [ ] } }
+      },
+      "response": { "status_code": 200, "body": { "json": { "choices": [ ] } } }
+    }
+  ]
+}
+```
+
+## Extending it
+
+Everything is a small protocol you can replace (see [ARCHITECTURE.md](ARCHITECTURE.md)):
+
+```python
+standin.use_cassette(path, matcher=MyMatcher(), redactor=MyRedactor(), store=MyStore())
+```
+
+- **Matcher** — decide when a live request equals a recorded one. Ships with
+  `DefaultMatcher` (exact) and `FuzzyMatcher` (body may drift up to a similarity
+  threshold, so a reworded prompt still replays):
+
+  ```python
+  from standin import use_cassette, FuzzyMatcher, DefaultRedactor
+  with use_cassette(path, matcher=FuzzyMatcher(DefaultRedactor(), threshold=0.9)):
+      ...
+  ```
+- **Redactor** — control what gets scrubbed before writing.
+- **CassetteStore** — change the on-disk format.
+
+## Command line
+
+```bash
+standin list  tests/cassettes/summary.json     # one line per interaction
+standin show  tests/cassettes/summary.json 0   # full request/response
+standin stats tests/cassettes/summary.json     # counts by method/status
+standin scrub tests/cassettes/summary.json     # re-run secret redaction in place
+```
+
+## Roadmap
+
+- Embedding-based semantic matching (a `Matcher` you drop in; `FuzzyMatcher`
+  already covers string-similarity drift today).
+- `requests` / `aiohttp` interceptors (the engine is already transport-neutral).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run the suite with `pytest`, lint with `ruff`, type-check with `mypy`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

standin-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+standin/__init__.py,sha256=0el2rfz9vyDhB98fAvvXaebp9rxON6NlB53RxkTGirA,1361
+standin/_codec.py,sha256=UD9B1waw36wAartWf_Rl2b7-NVLlXj82NjtgeSp2j10,2658
+standin/cassette.py,sha256=OzY9477oB4Pcr1XXFIV_1gR6JbF4au0dN_y6ZAG2gUM,1468
+standin/cli.py,sha256=Xa7YixVGXU2CWF2f47KlW-uy8XY-RZwVh1IN0OaMHYg,3611
+standin/config.py,sha256=vyUS827KzCMa2of236_Y2MPBF1hw0kawB9-TK4mm-3M,1527
+standin/core.py,sha256=nJUOvqkVE3CsoRu-B65tuT0TdEJwyIKZ9g4DrYpVJH0,2044
+standin/engine.py,sha256=vRyq-n9l5tEC5CvOBKSr1cHtPyFkQOPQG-nXbiOrXQU,3968
+standin/exceptions.py,sha256=favxY3MwMVMkEhlF1JDP_zEksUtI0gr53AJK3QcxfJE,609
+standin/matching.py,sha256=xdEl7XPK9FwjmAsdVqzOgbgIuMgF8EH5s8ef_1CbY1U,3250
+standin/models.py,sha256=OeO6n-kXP7j8yd9vmfVVDdkRbQ6q4wGYKJOKEpL8U_0,1733
+standin/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+standin/pytest_plugin.py,sha256=ysmYQXY7jcM47R1lV8-B8jf5YZyA9gtRYHH4RSBfNvg,1079
+standin/redaction.py,sha256=ZvSucGoZNITk2LJ9e9TRhDY16KfFWUIFUXfEMnN_lYg,2500
+standin/storage.py,sha256=_rslSlrM0UA7TWpEleY7WS11hZBNOalHhhcycMU2_dE,3070
+standin/interceptors/__init__.py,sha256=GVcw1j7vas4I-mCFV7SRnH_ltLw1NIcO-PEEZmXJfDQ,348
+standin/interceptors/base.py,sha256=OyOBd9lmte4DhaWJzcWaZMdh2ZtEkz3Is_C6tKAEmI0,1072
+standin/interceptors/httpx_interceptor.py,sha256=Uy9d4nEzfAW5KJO6_1hrB_gggB1Xo-v5fnWRUzHTHsc,3041
+standin-0.2.0.dist-info/METADATA,sha256=cc9ysMQ9hpUTz48PX3ljDIsm2-oxh_RRlEFuafQuEW8,6818
+standin-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+standin-0.2.0.dist-info/entry_points.txt,sha256=Ir7NvIREgtd5MUgDU53ARxmMUSSNDMSg4WKP6Rjz5gQ,89
+standin-0.2.0.dist-info/licenses/LICENSE,sha256=N2YCKaHPyHHbKbWBXzYv8QsWzFPmj_IRoqhL6NSn7QQ,1068
+standin-0.2.0.dist-info/RECORD,,

standin-0.2.0.dist-info/WHEEL

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

standin-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+standin = standin.cli:main
+
+[pytest11]
+standin = standin.pytest_plugin

standin-0.2.0.dist-info/licenses/LICENSE

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