promptecho 0.1.0__py3-none-any.whl

promptecho/__init__.py

@@ -0,0 +1,81 @@
+"""promptecho — record & replay for LLM API calls.
+
+Public API:
+    promptecho.use_cassette(path, mode="once", match_on=None)   # decorator + context manager
+    promptecho.Mode                                             # record modes
+"""
+
+from __future__ import annotations
+
+import functools
+from contextlib import contextmanager
+
+from .cassette import Cassette
+from .transport import Mode
+
+__all__ = ["use_cassette", "Mode", "Cassette"]
+__version__ = "0.1.0"
+
+
+@contextmanager
+def _activate(cassette: Cassette, mode: Mode):
+    """Patch httpx for the duration of the block, then restore and flush.
+
+    While active, every httpx-based client (Anthropic, OpenAI, raw httpx) routes
+    through the record/replay decision (see patch.py / DESIGN.md §1).
+    """
+    from .patch import install, uninstall
+
+    if mode is Mode.ALL:
+        cassette.interactions.clear()  # re-record from scratch
+        cassette._dirty = True
+
+    saved = install(cassette, mode)
+    try:
+        yield cassette
+    finally:
+        uninstall(saved)
+        cassette.save()
+
+
+class _UseCassette:
+    """Works as both a decorator and a context manager (like vcrpy.use_cassette)."""
+
+    def __init__(self, path: str, mode: str | Mode = Mode.ONCE, match_on=None):
+        self.path = path
+        self.mode = Mode(mode)
+        self.match_on = match_on
+
+    def _load(self) -> Cassette:
+        return Cassette.load(self.path, match_on=self.match_on)
+
+    def __enter__(self):
+        self._cm = _activate(self._load(), self.mode)
+        return self._cm.__enter__()
+
+    def __exit__(self, *exc):
+        return self._cm.__exit__(*exc)
+
+    def __call__(self, func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            with _activate(self._load(), self.mode):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+
+def use_cassette(path: str, mode: str | Mode = Mode.ONCE, match_on=None) -> _UseCassette:
+    """Record on first run, replay forever after.
+
+    Usage as a decorator::
+
+        @promptecho.use_cassette("cassettes/foo.yaml")
+        def test_foo(): ...
+
+    or as a context manager::
+
+        with promptecho.use_cassette("cassettes/foo.yaml", mode="none"):
+            client.messages.create(...)
+    """
+    return _UseCassette(path, mode=mode, match_on=match_on)

promptecho/cassette.py

@@ -0,0 +1,138 @@
+"""Cassette: the on-disk record of interactions. Human-readable YAML.
+
+A cassette is a list of (request, response) interactions keyed by request
+fingerprint. It is designed to diff cleanly in PRs and to be safe to commit
+(secrets are redacted before anything reaches disk).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+from dataclasses import dataclass, field
+
+import yaml
+
+from .matcher import DEFAULT_MATCH_ON, fingerprint
+
+REDACTED = "REDACTED"
+REDACT_HEADERS = {"authorization", "x-api-key", "openai-organization"}
+
+
+@dataclass
+class Response:
+    status: int
+    headers: dict
+    streaming: bool = False
+    body: object | None = None          # non-streaming body: JSON, str, or base64 str when binary
+    events: list[str] = field(default_factory=list)  # ordered raw SSE events
+    binary: bool = False                # if True, body is base64-encoded raw bytes
+
+
+@dataclass
+class Interaction:
+    method: str
+    url: str
+    match_key: str
+    matched_on: list[str]
+    body: dict
+    response: Response
+
+
+@dataclass
+class Cassette:
+    path: str
+    match_on: list[str] = field(default_factory=lambda: list(DEFAULT_MATCH_ON))
+    interactions: list[Interaction] = field(default_factory=list)
+    _dirty: bool = False
+
+    # --- lookup -----------------------------------------------------------
+    def find(self, key: str) -> Interaction | None:
+        for ix in self.interactions:
+            if ix.match_key == key:
+                return ix
+        return None
+
+    def record(self, method: str, url: str, body: dict, response: Response) -> None:
+        key = fingerprint(body, self.match_on)
+        self.interactions.append(
+            Interaction(
+                method=method,
+                url=url,
+                match_key=key,
+                matched_on=list(self.match_on),
+                body=body,
+                response=_redact_response(response),
+            )
+        )
+        self._dirty = True
+
+    # --- persistence ------------------------------------------------------
+    @classmethod
+    def load(cls, path: str, match_on: list[str] | None = None) -> "Cassette":
+        mo = match_on or list(DEFAULT_MATCH_ON)
+        if not os.path.exists(path):
+            return cls(path=path, match_on=mo)
+        with open(path) as f:
+            raw = yaml.safe_load(f) or {}
+        interactions = [_interaction_from_dict(d) for d in raw.get("interactions", [])]
+        return cls(path=path, match_on=raw.get("match_on", mo), interactions=interactions)
+
+    def save(self) -> None:
+        if not self._dirty:
+            return
+        os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
+        doc = {
+            "version": 1,
+            "match_on": self.match_on,
+            "interactions": [_interaction_to_dict(ix) for ix in self.interactions],
+        }
+        with open(self.path, "w") as f:
+            yaml.safe_dump(doc, f, sort_keys=False, allow_unicode=True, width=100)
+        self._dirty = False
+
+
+# --- (de)serialization helpers -------------------------------------------
+def _redact_response(resp: Response) -> Response:
+    headers = {k: (REDACTED if k.lower() in REDACT_HEADERS else v) for k, v in resp.headers.items()}
+    return dataclasses.replace(resp, headers=headers)
+
+
+def _interaction_to_dict(ix: Interaction) -> dict:
+    r = ix.response
+    response = {"status": r.status, "headers": r.headers, "streaming": r.streaming}
+    if r.binary:
+        response["binary"] = True
+    if r.streaming:
+        response["events"] = r.events
+    else:
+        response["body"] = r.body
+    return {
+        "request": {
+            "method": ix.method,
+            "url": ix.url,
+            "match_key": ix.match_key,
+            "matched_on": ix.matched_on,
+            "body": ix.body,
+        },
+        "response": response,
+    }
+
+
+def _interaction_from_dict(d: dict) -> Interaction:
+    req, resp = d["request"], d["response"]
+    return Interaction(
+        method=req["method"],
+        url=req["url"],
+        match_key=req["match_key"],
+        matched_on=req.get("matched_on", list(DEFAULT_MATCH_ON)),
+        body=req.get("body", {}),
+        response=Response(
+            status=resp["status"],
+            headers=resp.get("headers", {}),
+            streaming=resp.get("streaming", False),
+            body=resp.get("body"),
+            events=resp.get("events", []),
+            binary=resp.get("binary", False),
+        ),
+    )

promptecho/matcher.py

@@ -0,0 +1,115 @@
+"""Request fingerprinting — the deterministic core of replay matching.
+
+We match on a *normalized fingerprint* of the request fields that actually
+determine the response, never on raw bytes (see DESIGN.md §2).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+DEFAULT_MATCH_ON = [
+    "model", "messages", "system", "tools", "tool_choice",
+    # Reasoning-model knobs that change the response without changing the prompt:
+    # OpenAI o-series, Anthropic extended thinking, OpenRouter unified field.
+    # If these aren't matched, "reasoning_effort=high" and "low" tests collide.
+    "reasoning_effort", "reasoning", "thinking",
+]
+
+
+def canonical_json(obj: object) -> str:
+    """Stable serialization: sorted keys, no insignificant whitespace.
+
+    Ensures re-serialization of the same logical request can't change the key.
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def pick(body: dict, match_on: list[str]) -> dict:
+    """Keep only the load-bearing fields, in a stable shape."""
+    return {k: body[k] for k in match_on if k in body}
+
+
+def fingerprint(body: dict, match_on: list[str] | None = None) -> str:
+    """Map a request body to the cassette key for the recording it should replay.
+
+    The same logical request always yields the same key; volatile fields that
+    aren't in ``match_on`` cannot affect it.
+    """
+    fields = pick(body, match_on or DEFAULT_MATCH_ON)
+    digest = hashlib.sha256(canonical_json(fields).encode("utf-8")).hexdigest()
+    return digest[:16]
+
+
+def diff_fields(incoming: dict, recorded: dict, match_on: list[str]) -> list[str]:
+    """Names of top-level matched fields whose values differ. Cheap pointer; for the
+    human-readable leaf-level diff used in cassette-miss errors, see :func:`diff_request`."""
+    return [k for k in match_on if incoming.get(k) != recorded.get(k)]
+
+
+_MISSING = object()  # sentinel for "field/element not present on this side"
+
+
+def _walk_diff(incoming, recorded, path: str):
+    """Yield (path, recorded_value, incoming_value) for each leaf-level difference.
+
+    Walks both structures in parallel. dicts are compared by key (sorted for stable
+    output); lists by index, with extras flagged. Anything else is a leaf — emit and
+    stop. Recursion depth is bounded by request shape (chat messages rarely nest deep).
+    """
+    if incoming == recorded:
+        return
+    if type(incoming) is not type(recorded):
+        yield path, recorded, incoming
+        return
+    if isinstance(incoming, dict):
+        for k in sorted(set(incoming) | set(recorded)):
+            sub = f"{path}.{k}" if path else k
+            i_val = incoming.get(k, _MISSING)
+            r_val = recorded.get(k, _MISSING)
+            if i_val is _MISSING or r_val is _MISSING:
+                yield sub, r_val, i_val
+            else:
+                yield from _walk_diff(i_val, r_val, sub)
+        return
+    if isinstance(incoming, list):
+        for i in range(max(len(incoming), len(recorded))):
+            sub = f"{path}[{i}]"
+            if i >= len(incoming):
+                yield sub, recorded[i], _MISSING
+            elif i >= len(recorded):
+                yield sub, _MISSING, incoming[i]
+            else:
+                yield from _walk_diff(incoming[i], recorded[i], sub)
+        return
+    yield path, recorded, incoming
+
+
+def _truncate(v, limit: int = 80) -> str:
+    if v is _MISSING:
+        return "<not present>"
+    s = v if isinstance(v, str) else canonical_json(v)
+    return s if len(s) <= limit else s[: limit - 3] + "..."
+
+
+def diff_request(incoming: dict, recorded: dict, match_on: list[str]) -> str:
+    """Multi-line, human-readable field-level diff of two request bodies.
+
+    Restricted to ``match_on`` fields — volatile fields outside the match set are
+    intentionally hidden, since they can't have caused the miss. Returns the empty
+    string when no matched fields differ; callers should treat that as "no diff."
+    """
+    lines = []
+    for field in match_on:
+        i_val = incoming.get(field, _MISSING)
+        r_val = recorded.get(field, _MISSING)
+        if i_val is _MISSING and r_val is _MISSING:
+            continue
+        if i_val == r_val:
+            continue
+        for path, r, i in _walk_diff(i_val, r_val, field):
+            lines.append(f"  {path}:")
+            lines.append(f"    recorded: {_truncate(r)}")
+            lines.append(f"    incoming: {_truncate(i)}")
+    return "\n".join(lines)

promptecho/normalizers.py

@@ -0,0 +1,160 @@
+"""Per-provider request normalization.
+
+Different providers (and even one SDK across versions) express the *same logical
+prompt* in different shapes:
+
+  - Anthropic puts the system prompt in a top-level ``system`` param; OpenAI puts
+    it in a ``system``/``developer`` role message.
+  - Message content may be a bare string or a list of typed content blocks.
+  - Tool defs differ: Anthropic ``{name, description, input_schema}`` vs OpenAI
+    ``{type: function, function: {name, description, parameters}}``.
+
+``normalize()`` maps a raw request body into one canonical shape, so logically
+identical calls produce the same fingerprint. This is the thing a raw-bytes HTTP
+VCR fundamentally cannot do.
+
+The canonical body is also what gets written to the cassette — a provider-agnostic
+view of the call, which is arguably more readable than the raw provider JSON.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+CANONICAL_ROLES_AS_SYSTEM = ("system", "developer")
+
+
+# --- detection ------------------------------------------------------------
+def detect(url: str, body: dict) -> str:
+    """Best-effort provider detection: URL host first, then body shape."""
+    host = (urlsplit(url).hostname or "").lower()
+    if "anthropic" in host:
+        return "anthropic"
+    if "openai" in host or "azure" in host:
+        return "openai"
+
+    # Shape fallback (covers localhost / proxies / gateways).
+    if "system" in body:
+        return "anthropic"
+    messages = body.get("messages") or []
+    if any(isinstance(m, dict) and m.get("role") in CANONICAL_ROLES_AS_SYSTEM for m in messages):
+        return "openai"
+    tools = body.get("tools") or []
+    if any(isinstance(t, dict) and "input_schema" in t for t in tools):
+        return "anthropic"
+    if any(isinstance(t, dict) and "function" in t for t in tools):
+        return "openai"
+    return "generic"
+
+
+# --- shared canonicalizers ------------------------------------------------
+def _canon_content(content):
+    """Collapse a single text block to a bare string; canonicalize text blocks."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        blocks = [_canon_block(b) for b in content]
+        if len(blocks) == 1 and isinstance(blocks[0], dict) and blocks[0].get("type") == "text":
+            return blocks[0]["text"]
+        return blocks
+    return content
+
+
+def _canon_block(block):
+    if isinstance(block, dict) and block.get("type") == "text" and "text" in block:
+        return {"type": "text", "text": block["text"]}
+    return block
+
+
+def _canon_message(message):
+    if not isinstance(message, dict):
+        return message
+    out = dict(message)
+    if "content" in out:
+        out["content"] = _canon_content(out["content"])
+    return out
+
+
+def _canon_system(system):
+    if isinstance(system, list):
+        texts = [b.get("text", "") for b in system
+                 if isinstance(b, dict) and b.get("type") == "text"]
+        if texts:
+            return "\n".join(texts)
+    return system
+
+
+def _canon_tool(tool):
+    if not isinstance(tool, dict):
+        return tool
+    if isinstance(tool.get("function"), dict):          # OpenAI shape
+        fn = tool["function"]
+        canon = {"name": fn.get("name"), "description": fn.get("description"),
+                 "parameters": fn.get("parameters")}
+    else:                                               # Anthropic / generic
+        canon = {"name": tool.get("name"), "description": tool.get("description"),
+                 "parameters": tool.get("input_schema", tool.get("parameters"))}
+    return {k: v for k, v in canon.items() if v is not None}
+
+
+def _canon_tool_choice(choice):
+    if isinstance(choice, str):
+        return {"mode": choice}
+    if isinstance(choice, dict):
+        if isinstance(choice.get("function"), dict):    # OpenAI
+            return {"mode": "tool", "name": choice["function"].get("name")}
+        if "type" in choice:                            # Anthropic
+            out = {"mode": choice["type"]}
+            if choice.get("name"):
+                out["name"] = choice["name"]
+            return out
+    return choice
+
+
+def _apply_common(out: dict) -> dict:
+    if "messages" in out:
+        out["messages"] = [_canon_message(m) for m in out["messages"]]
+    if "tools" in out:
+        out["tools"] = [_canon_tool(t) for t in out["tools"]]
+    if "tool_choice" in out:
+        out["tool_choice"] = _canon_tool_choice(out["tool_choice"])
+    return out
+
+
+# --- per-provider ---------------------------------------------------------
+def _anthropic(body: dict) -> dict:
+    out = dict(body)
+    if "system" in out:
+        out["system"] = _canon_system(out["system"])
+    return _apply_common(out)
+
+
+def _openai(body: dict) -> dict:
+    out = dict(body)
+    system_parts, rest = [], []
+    for m in out.get("messages", []):
+        if isinstance(m, dict) and m.get("role") in CANONICAL_ROLES_AS_SYSTEM:
+            c = m.get("content", "")
+            system_parts.append(c if isinstance(c, str) else _canon_content(c))
+        else:
+            rest.append(m)
+    if system_parts and "system" not in out:
+        out["system"] = "\n".join(p for p in system_parts if isinstance(p, str))
+    out["messages"] = rest
+    if "max_completion_tokens" in out and "max_tokens" not in out:
+        out["max_tokens"] = out.pop("max_completion_tokens")
+    return _apply_common(out)
+
+
+def _generic(body: dict) -> dict:
+    return _apply_common(dict(body))
+
+
+_NORMALIZERS = {"anthropic": _anthropic, "openai": _openai, "generic": _generic}
+
+
+def normalize(url: str, body: dict) -> dict:
+    """Map a raw provider request body into the canonical shape used for matching."""
+    if not isinstance(body, dict):
+        return body
+    return _NORMALIZERS[detect(url, body)](body)

promptecho/patch.py

@@ -0,0 +1,134 @@
+"""httpx interception — the wiring that makes record/replay real.
+
+We monkeypatch ``httpx.HTTPTransport.handle_request`` (and the async twin) so
+every client built on httpx — Anthropic, OpenAI, raw httpx — routes through the
+record/replay decision in :mod:`promptecho.transport`. This is the same approach
+respx and vcrpy's httpx stub use. See DESIGN.md §1.
+
+On record we read the full upstream response, capture it, and return a fresh
+buffered response so the SDK can consume it normally. Streaming (SSE) responses
+are captured as their ordered events and re-emitted byte-for-byte on replay.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+import httpx
+
+from .cassette import Response as Rec
+from .normalizers import normalize
+from .transport import decide, parse_body
+
+# Hop-by-hop / encoding headers that won't match our re-encoded body on replay.
+_DROP_HEADERS = {"content-encoding", "content-length", "transfer-encoding"}
+
+
+def _request_body(request: httpx.Request) -> dict:
+    try:
+        raw = request.content
+    except httpx.RequestNotRead:
+        raw = request.read()
+    return parse_body(raw)
+
+
+def _clean_headers(headers: httpx.Headers) -> dict:
+    return {k: v for k, v in dict(headers).items() if k.lower() not in _DROP_HEADERS}
+
+
+def _split_sse(text: str) -> list[str]:
+    """Split an SSE body into individual events (kept readable in the cassette)."""
+    return [part + "\n\n" for part in text.split("\n\n") if part.strip()]
+
+
+def _is_binary_content_type(ct: str) -> bool:
+    """Content types we must not decode as text — images, audio, video, octet-stream.
+
+    Anything text/* or application/json|xml|...+json round-trips cleanly through
+    YAML; everything else (image/png, audio/wav, application/octet-stream, etc.)
+    gets base64-encoded to preserve bytes exactly.
+    """
+    ct = ct.split(";", 1)[0].strip().lower()
+    if not ct:
+        return False
+    if ct.startswith(("image/", "audio/", "video/")):
+        return True
+    if ct in {"application/octet-stream", "application/pdf", "application/zip"}:
+        return True
+    return False
+
+
+def _capture(status: int, headers: httpx.Headers, data: bytes) -> Rec:
+    clean = _clean_headers(headers)
+    content_type = clean.get("content-type", "")
+    if "text/event-stream" in content_type:
+        return Rec(status=status, headers=clean, streaming=True,
+                   events=_split_sse(data.decode("utf-8", "replace")))
+    if _is_binary_content_type(content_type):
+        return Rec(status=status, headers=clean, streaming=False,
+                   body=base64.b64encode(data).decode("ascii"), binary=True)
+    try:
+        body = json.loads(data) if data else None
+    except ValueError:
+        body = data.decode("utf-8", "replace")
+    return Rec(status=status, headers=clean, streaming=False, body=body)
+
+
+def _to_httpx(rec: Rec, request: httpx.Request) -> httpx.Response:
+    if rec.streaming:
+        content = "".join(rec.events).encode("utf-8")
+    elif rec.binary and isinstance(rec.body, str):
+        content = base64.b64decode(rec.body)
+    elif isinstance(rec.body, (dict, list)):
+        content = json.dumps(rec.body).encode("utf-8")
+    elif isinstance(rec.body, str):
+        content = rec.body.encode("utf-8")
+    else:
+        content = b""
+    return httpx.Response(
+        status_code=rec.status,
+        headers=httpx.Headers(rec.headers),
+        content=content,
+        request=request,
+    )
+
+
+def _make_sync(cassette, mode, real_fn):
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        body = normalize(str(request.url), _request_body(request))
+        decision = decide(mode, cassette, body)
+        if decision.response is not None:                      # REPLAY (no network)
+            return _to_httpx(decision.response, request)
+        real = real_fn(self, request)                          # PASS THROUGH
+        rec = _capture(real.status_code, real.headers, real.read())
+        cassette.record(request.method, str(request.url), body, rec)  # RECORD
+        return _to_httpx(rec, request)
+
+    return handle_request
+
+
+def _make_async(cassette, mode, real_fn):
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        body = normalize(str(request.url), _request_body(request))
+        decision = decide(mode, cassette, body)
+        if decision.response is not None:
+            return _to_httpx(decision.response, request)
+        real = await real_fn(self, request)
+        rec = _capture(real.status_code, real.headers, await real.aread())
+        cassette.record(request.method, str(request.url), body, rec)
+        return _to_httpx(rec, request)
+
+    return handle_async_request
+
+
+def install(cassette, mode):
+    """Patch httpx; returns a token to pass back to :func:`uninstall`."""
+    saved = (httpx.HTTPTransport.handle_request, httpx.AsyncHTTPTransport.handle_async_request)
+    httpx.HTTPTransport.handle_request = _make_sync(cassette, mode, saved[0])
+    httpx.AsyncHTTPTransport.handle_async_request = _make_async(cassette, mode, saved[1])
+    return saved
+
+
+def uninstall(saved) -> None:
+    httpx.HTTPTransport.handle_request, httpx.AsyncHTTPTransport.handle_async_request = saved

promptecho/pytest_plugin.py

@@ -0,0 +1,29 @@
+"""pytest integration: an auto-named cassette per test.
+
+    def test_summarize(promptecho_cassette):   # -> cassettes/test_summarize.yaml
+        client.messages.create(...)
+
+Mode defaults to ``once`` locally and ``none`` in CI (when the CI env var is set),
+so a forgotten recording fails the build instead of making a live call.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from . import use_cassette
+from .transport import Mode
+
+
+def _default_mode() -> Mode:
+    return Mode.NONE if os.environ.get("CI") else Mode.ONCE
+
+
+@pytest.fixture
+def promptecho_cassette(request):
+    cassette_dir = os.path.join(os.path.dirname(request.fspath), "cassettes")
+    path = os.path.join(cassette_dir, f"{request.node.name}.yaml")
+    with use_cassette(path, mode=_default_mode()) as cassette:
+        yield cassette

promptecho/transport.py

@@ -0,0 +1,89 @@
+"""The replay/record decision logic, isolated from httpx patching mechanics.
+
+This module is pure and unit-testable: given a mode, a cassette, and a parsed
+request, it decides whether to replay a recorded response or pass through to the
+network and record. The actual httpx wiring (next to TODOs) lives at the bottom.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+
+from .cassette import Cassette, Response
+from .matcher import diff_request, fingerprint
+
+
+class Mode(str, Enum):
+    ONCE = "once"            # record if absent, replay if present (default)
+    NONE = "none"           # replay only; error on miss (CI-safe)
+    NEW_EPISODES = "new_episodes"  # replay existing, record new
+    ALL = "all"             # always re-record
+
+
+class CassetteMiss(Exception):
+    """Raised in mode=none when an incoming request has no recording."""
+
+
+def parse_body(raw: bytes) -> dict:
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except (ValueError, UnicodeDecodeError):
+        return {}
+
+
+class Decision:
+    """Outcome of looking at one request: either replay `response`, or `record`."""
+
+    def __init__(self, *, response: Response | None = None, record: bool = False):
+        self.response = response
+        self.record = record
+
+
+def decide(mode: Mode, cassette: Cassette, body: dict) -> Decision:
+    """Core branch. No I/O — caller performs the network call / persistence."""
+    key = fingerprint(body, cassette.match_on)
+    existing = cassette.find(key)
+
+    if mode is Mode.ALL:
+        return Decision(record=True)
+
+    if mode is Mode.NONE:
+        if existing is None:
+            raise CassetteMiss(_miss_message(cassette, body))
+        return Decision(response=existing.response)
+
+    # ONCE and NEW_EPISODES: replay if we have it, otherwise record.
+    if existing is not None:
+        return Decision(response=existing.response)
+    return Decision(record=True)
+
+
+def _miss_message(cassette: Cassette, body: dict) -> str:
+    nearest = cassette.interactions[-1] if cassette.interactions else None
+    if nearest is None:
+        return (
+            f"Cassette miss: {cassette.path!r} has no recordings and mode=none.\n"
+            f"Re-record with mode='once' (or delete and re-run the test)."
+        )
+    diff = diff_request(body, nearest.body, cassette.match_on)
+    if not diff:
+        return (
+            f"Cassette miss in {cassette.path!r} (mode=none): a matched field has a "
+            f"non-equal value the diff walker couldn't pinpoint. Re-record to refresh."
+        )
+    return (
+        f"Cassette miss in {cassette.path!r} (mode=none).\n"
+        f"The incoming request differs from the nearest recording on these fields:\n\n"
+        f"{diff}\n\n"
+        f"If the change is intentional, re-record with mode='once' (or delete the "
+        f"cassette and re-run). If not, fix the call so it matches the recorded "
+        f"fingerprint."
+    )
+
+
+# The httpx wiring that turns these decisions into real interception lives in
+# patch.py (sync + async). This module stays pure so the branch logic above is
+# unit-testable without a network stack.

promptecho-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: promptecho
+Version: 0.1.0
+Summary: Record & replay for LLM API calls — like vcrpy/nock, built for LLM traffic.
+License-Expression: MIT
+Keywords: anthropic,llm,mock,openai,pytest,record-replay,testing,vcr
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: anthropic; extra == 'dev'
+Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# promptecho
+
+**Record & replay for LLM API calls.** Like [`vcrpy`](https://github.com/kevin1024/vcrpy) / [`nock`](https://github.com/nock/nock), but built for the way LLM traffic actually behaves.
+
+Your LLM tests have three problems: they're **flaky** (non-deterministic outputs), **slow** (real network round-trips), and **expensive** (burning tokens in CI on every run). promptecho records each real API call once to a cassette file, then replays it forever — deterministically, instantly, for free.
+
+```python
+import promptecho
+from anthropic import Anthropic
+
+@promptecho.use_cassette("cassettes/summarize.yaml")
+def test_summarize():
+    client = Anthropic()
+    msg = client.messages.create(
+        model="claude-opus-4-8",
+        max_tokens=100,
+        messages=[{"role": "user", "content": "Summarize: the cat sat on the mat."}],
+    )
+    assert "cat" in msg.content[0].text.lower()
+```
+
+First run: one real call, recorded to `cassettes/summarize.yaml`.
+Every run after: replayed from disk. No network, no tokens, no flake.
+
+> **Proof, not marketing.** The end-to-end test that gates every release records against a local server, **shuts the server down**, then replays. Same response, zero network. If the response can come back with the upstream gone, the cassette is genuinely doing the work — not a partial proxy. See [`tests/test_record_replay.py`](tests/test_record_replay.py).
+
+---
+
+## Why not just use vcrpy?
+
+You can — at the HTTP layer, vcrpy works on LLM calls today. promptecho exists because LLM traffic breaks vcrpy's assumptions in five specific ways:
+
+1. **Matching.** vcrpy matches on raw request bytes. LLM bodies carry volatile fields (client-injected IDs, reordered tools, whitespace) that change the bytes without changing the *meaning* — so byte-matching misses on replay. promptecho matches on a **normalized fingerprint** of the fields that determine the response, and **canonicalizes across providers**: it knows `content: "hi"` equals `content: [{"type":"text","text":"hi"}]`, an Anthropic top-level `system` equals an OpenAI `system`-role message, and an Anthropic `input_schema` tool def equals an OpenAI `function.parameters`. A raw-bytes VCR can't.
+2. **Streaming.** Most LLM calls are SSE streams. promptecho records the event stream and faithfully re-emits it on replay, so `stream=True` and token-by-token iteration work identically against a cassette — including reasoning deltas.
+3. **Binary / multimodal responses.** vcrpy's text-based cassettes silently corrupt raw `image/*` / `audio/*` / `octet-stream` bodies. promptecho detects them by `Content-Type` and base64-encodes them in the cassette, so image-out and audio-out responses round-trip byte-exact.
+4. **Debuggable CI failures.** When a vcrpy cassette miss happens, you get *"no match"*. promptecho prints the exact path that changed: `messages[1].content: recorded "summarize the cat" / incoming "summarize the dog"`. Test failures are actionable, not detective work.
+5. **Secrets.** API keys live in headers on every call. promptecho redacts them by default — a cassette is safe to commit.
+
+## What promptecho is *not*
+
+- **Not a cache.** Replay matching is exact/normalized and deterministic, on purpose. It does **not** semantically match "different prompt, close enough" — that would put non-determinism back into the harness you're using to remove it. (A separate opt-in fuzzy mode is on the roadmap as a dev-loop convenience; it will never be the default and never used in CI.)
+- **Not an eval.** It freezes a response so your *surrounding code* is testable. Judging whether the response is *good* is a different tool (see roadmap: `toMatchLLMSnapshot()`).
+
+---
+
+## What it covers
+
+promptecho intercepts at the `httpx` transport layer. **If the SDK uses httpx, promptecho sees the call** — which is almost everything modern.
+
+| You're calling | Covered? |
+|---|---|
+| Anthropic, OpenAI, Mistral, Cohere, `google-genai` SDKs | ✅ |
+| **OpenAI SDK with custom `base_url`** → OpenRouter, Together, Fireworks, Cerebras, Groq, DeepInfra, Perplexity | ✅ |
+| **Self-hosted vLLM / TGI / SGLang / LM Studio / Ollama** (OpenAI-compatible mode) | ✅ |
+| Your **own fine-tune** behind any of the above | ✅ |
+| **Reasoning models** — o1/o3, Claude extended thinking, DeepSeek-R1 | ✅ (incl. `reasoning_effort` / `thinking` in default match-on) |
+| **Multimodal** — base64-in-JSON (vision, Claude image-out, GPT-4o) and raw binary (`image/*`, `audio/*`) | ✅ (byte-exact round-trip) |
+| Bedrock via boto3, HF `InferenceClient`, in-process `transformers` | ❌ (see workarounds in [SUPPORT.md](SUPPORT.md)) |
+
+Full matrix with caveats and workarounds: [**SUPPORT.md**](SUPPORT.md). For practical recipes by scenario (startup / enterprise / research), see [**TUTORIAL.md**](TUTORIAL.md).
+
+### Hosted open-source via the OpenAI SDK
+
+This is the dominant pattern for non-Anthropic/non-OpenAI usage, and it Just Works:
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key="...")
+
+@promptecho.use_cassette("cassettes/openrouter.yaml")
+def test_via_openrouter():
+    r = client.chat.completions.create(
+        model="meta-llama/llama-3.1-70b-instruct",
+        messages=[{"role": "user", "content": "hi"}],
+    )
+    assert r.choices[0].message.content
+```
+
+Detection falls back to body shape when the host is unknown, so localhost gateways, in-house proxies, and self-hosted vLLM/TGI behave the same way as the brand-name hosts.
+
+---
+
+## Install
+
+```bash
+pip install promptecho   # not yet on PyPI — install from source for now
+```
+
+```bash
+git clone <repo> && cd promptecho
+pip install -e .
+```
+
+Requires Python ≥ 3.9 and `httpx ≥ 0.24`.
+
+---
+
+## Usage
+
+### Decorator
+```python
+@promptecho.use_cassette("cassettes/foo.yaml")
+def test_foo(): ...
+```
+
+### Context manager
+```python
+with promptecho.use_cassette("cassettes/foo.yaml"):
+    client.messages.create(...)
+```
+
+### pytest fixture (auto-named per test)
+```python
+def test_bar(promptecho_cassette):   # records to cassettes/test_bar.yaml
+    client.messages.create(...)
+```
+
+The fixture defaults to `mode="once"` locally and `mode="none"` when `CI=true` — so a forgotten recording fails the build instead of making a live call.
+
+### Record modes
+Borrowed from vcrpy, so the mental model is free:
+
+| mode | absent cassette | present cassette | use for |
+|------|-----------------|------------------|---------|
+| `once` *(default)* | record | replay | normal dev |
+| `none` | **error** | replay | **CI** — guarantees no live calls |
+| `new_episodes` | record | replay + record new | evolving tests |
+| `all` | record | re-record everything | refreshing fixtures |
+
+```python
+@promptecho.use_cassette("cassettes/foo.yaml", mode="none")
+```
+
+### Choosing what to match on
+
+Defaults to `["model", "messages", "system", "tools", "tool_choice", "reasoning_effort", "reasoning", "thinking"]` — everything that determines the response for a chat-shaped call, including reasoning-model knobs.
+
+```python
+@promptecho.use_cassette(
+    "cassettes/foo.yaml",
+    match_on=["model", "messages", "system", "temperature"],  # add temperature
+)
+```
+
+For non-chat shapes (raw TGI `/generate`, embeddings) you'll want to override, e.g. `match_on=["model", "input"]` for an embeddings endpoint. See [SUPPORT.md → Request shapes](SUPPORT.md#request-shapes).
+
+### Async
+
+Works identically with `httpx.AsyncClient` and the async surfaces of Anthropic / OpenAI / Mistral SDKs — the async transport is patched the same way as sync.
+
+---
+
+## Cassette format
+
+Human-readable YAML, designed to diff cleanly in PRs:
+
+```yaml
+version: 1
+match_on: [model, messages, system, tools, tool_choice, reasoning_effort, reasoning, thinking]
+interactions:
+  - request:
+      method: POST
+      url: https://api.anthropic.com/v1/messages
+      match_key: ef43f6acaed95b2f        # fingerprint of matched fields
+      matched_on: [model, messages, system, tools, tool_choice]
+      body:                              # canonical (provider-normalized) body
+        model: claude-opus-4-8
+        messages:
+          - {role: user, content: "Summarize: the cat sat on the mat."}
+    response:
+      status: 200
+      headers: {content-type: application/json}
+      streaming: false
+      body:
+        content: [{type: text, text: "A cat sat on a mat."}]
+        usage: {input_tokens: 14, output_tokens: 8}
+```
+
+- **Streamed** responses store the ordered SSE events under `response.events` with `streaming: true`; replay re-emits them in order.
+- **Binary** responses (image/audio/octet-stream) get `binary: true` and the body is base64-encoded; replay decodes and returns the original bytes.
+- **The stored body is the canonical, provider-normalized shape** — not the raw provider JSON. That makes cassettes provider-agnostic and easier to skim in code review.
+
+Auto-redacted on record: `authorization`, `x-api-key`, `openai-organization`. Configurable.
+
+See [`examples/cassettes/example.yaml`](examples/cassettes/example.yaml) for a real one.
+
+---
+
+## Status
+
+**v0.1.0, working core. 19 tests, all green.** Not yet on PyPI.
+
+Records and replays real httpx traffic — sync, async, SSE streaming, binary responses, cross-provider request shapes — verified end-to-end against a local server that gets shut down between record and replay.
+
+### Roadmap (build-in-public)
+
+Done:
+- [x] httpx sync + async transport interception
+- [x] SSE streaming record/replay
+- [x] pytest plugin + auto-naming
+- [x] Per-provider request normalizers (Anthropic / OpenAI / generic)
+- [x] Reasoning-model match defaults (`reasoning_effort`, `thinking`, `reasoning`)
+- [x] Binary response round-trip (image/audio/octet-stream — base64 in cassette)
+- [x] Field-level diff on cassette miss (CI `mode=none` errors pinpoint the changed path, not just the field name)
+
+Next:
+- [ ] `requests` / `urllib3` interception backend — unlocks boto3-Bedrock and HF `InferenceClient`
+- [ ] `promptecho lint` — find un-recorded calls in a test suite
+- [ ] **`toMatchLLMSnapshot()` sibling** — semantic snapshot assertions on top of recorded calls
+
+## Design
+
+For the why-not-the-other-way decisions — fingerprint vs raw bytes, why semantic matching is fenced off, how SSE re-emission works, how cross-provider normalization is structured — see [DESIGN.md](DESIGN.md).
+
+## License
+
+MIT

promptecho-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+promptecho/__init__.py,sha256=6SokaWIYwu6dZm0Vin2psxevz8jcNuLDsDM3h12kMwg,2309
+promptecho/cassette.py,sha256=uzJh084L4gk8zr-H6psWxd9oDMKP0glfNzJlcIEaHCA,4445
+promptecho/matcher.py,sha256=t_5kBPphChTwYe_0WAjkcTPLYDqO7tKaYgGbRTpwnlg,4484
+promptecho/normalizers.py,sha256=0X9oItnIolaS_62-sB3D-h6yYduAAbcsK23tYWI3ZlI,5807
+promptecho/patch.py,sha256=Xc5D37Odj0pElVxfon-7HT-sktBBZn0VeRkOq-3ihKE,5223
+promptecho/pytest_plugin.py,sha256=oVF3vzqVHoG_Vk-WjpVo_Wota-CpgV0YVahReJbwVFM,827
+promptecho/transport.py,sha256=g6bYMwOV5b0LVqGLjwQ1dJyfNKLnE4HiQegzpLjqSSg,3147
+promptecho-0.1.0.dist-info/METADATA,sha256=zh0KRAXXMl-hoWYUJLQU3wx2bjSRkpMeWOt9EulAahU,10858
+promptecho-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+promptecho-0.1.0.dist-info/entry_points.txt,sha256=bw3ZMfD4yiP33qS4WOOV11TerOvgYXOS8FL70k6pYHM,49
+promptecho-0.1.0.dist-info/RECORD,,

promptecho-0.1.0.dist-info/WHEEL

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

promptecho-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+promptecho = promptecho.pytest_plugin