agenttape 0.1.0__py3-none-any.whl

agenttape/__init__.py

@@ -0,0 +1,74 @@
+"""AgentTape — deterministic record/replay for AI agents.
+
+Deterministic record / replay of an agent's external interactions (LLM calls and
+tool calls) into human-readable cassettes, so agent tests run offline, for free,
+with zero side effects.
+
+Quickstart::
+
+    import agenttape
+
+    with agenttape.use_cassette("hello", mode="record"):
+        run_agent()                      # records real calls
+
+    with agenttape.use_cassette("hello", mode="none"):
+        run_agent()                      # replays, zero network, deterministic
+"""
+
+from __future__ import annotations
+
+from .boundaries import memory_read, memory_write, record_call, retrieval, tool
+from .callbacks import AgentTape
+from .config import Config
+from .errors import (
+    AgentTapeError,
+    CassetteCorruptError,
+    CassetteNotFoundError,
+    ConfigError,
+    DeterminismDriftWarning,
+    SchemaVersionError,
+    StreamingNotRecordedWarning,
+    StreamingReplayError,
+    UnmatchedInteractionError,
+)
+from .recorder import Session, active_session, record, replay, use_cassette
+from .schema import Cassette, Interaction
+
+try:  # populated from package metadata when installed
+    from importlib.metadata import version as _version
+
+    __version__ = _version("agenttape")
+except Exception:  # pragma: no cover - editable/source tree fallback
+    __version__ = "0.1.0"
+
+__all__ = [  # noqa: RUF022 - grouped by concern for readability, not alphabetised
+    "__version__",
+    # Core API
+    "use_cassette",
+    "record",
+    "replay",
+    "Session",
+    "active_session",
+    # Boundary helpers
+    "tool",
+    "retrieval",
+    "memory_read",
+    "memory_write",
+    "record_call",
+    # Callback object
+    "AgentTape",
+    # Data model
+    "Cassette",
+    "Interaction",
+    "Config",
+    # Errors
+    "AgentTapeError",
+    "UnmatchedInteractionError",
+    "CassetteCorruptError",
+    "CassetteNotFoundError",
+    "SchemaVersionError",
+    "ConfigError",
+    "DeterminismDriftWarning",
+    "StreamingReplayError",
+    "StreamingNotRecordedWarning",
+]

agenttape/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m agenttape``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agenttape/_box.py

@@ -0,0 +1,59 @@
+"""A tiny attribute-accessible mapping used to rehydrate replayed responses.
+
+When a cassette is replayed offline, recorded responses come back as plain dicts.
+Many SDKs (OpenAI, etc.) hand callers objects with attribute access
+(``resp.choices[0].message.content``). :class:`Box` lets replayed dicts support
+both ``obj.attr`` and ``obj["attr"]`` so user code behaves identically whether or
+not the original SDK is installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+class Box(dict):  # type: ignore[type-arg]
+    """A dict that also supports attribute access, recursively."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return _wrap(self[name])
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self[name] = value
+
+    def __iter__(self) -> Iterator[Any]:  # pragma: no cover - dict default suffices
+        return super().__iter__()
+
+    def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        return {k: _unwrap(v) for k, v in self.items()}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: _unwrap(v) for k, v in self.items()}
+
+
+def _wrap(value: Any) -> Any:
+    if isinstance(value, Box):
+        return value
+    if isinstance(value, dict):
+        return Box(value)
+    if isinstance(value, list):
+        return [_wrap(v) for v in value]
+    return value
+
+
+def _unwrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: _unwrap(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_unwrap(v) for v in value]
+    return value
+
+
+def box(data: Any) -> Any:
+    """Recursively wrap ``data`` so dicts gain attribute access."""
+
+    return _wrap(data)

agenttape/adapters/__init__.py

@@ -0,0 +1,68 @@
+"""Adapter registry and bulk install/uninstall.
+
+The registry is populated at import time with the built-in adapters. A
+:class:`~agenttape.recorder.Session` installs every *available* adapter on enter
+and uninstalls them on exit.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import Adapter, RefCountedPatch
+from .http import HttpxAdapter, RequestsAdapter
+from .langgraph import LangGraphAdapter
+from .openai import OpenAIAdapter
+
+_REGISTRY: list[Adapter] = []
+
+
+def register(adapter: Adapter) -> None:
+    """Register an adapter so sessions will install it when its library is present."""
+
+    _REGISTRY.append(adapter)
+
+
+def registry() -> list[Adapter]:
+    return list(_REGISTRY)
+
+
+def install_all(session: Any) -> list[Adapter]:
+    installed: list[Adapter] = []
+    for adapter in _REGISTRY:
+        try:
+            if adapter.available():
+                adapter.install(session)
+                installed.append(adapter)
+        except Exception:  # pragma: no cover - never let an adapter break a session
+            continue
+    return installed
+
+
+def uninstall_all(adapters: list[Adapter]) -> None:
+    for adapter in reversed(adapters):
+        try:
+            adapter.uninstall()
+        except Exception:  # pragma: no cover
+            continue
+
+
+# Built-in adapters. Order matters only for cosmetic install order.
+register(OpenAIAdapter())
+register(LangGraphAdapter())
+register(HttpxAdapter())
+register(RequestsAdapter())
+
+
+__all__ = [
+    "Adapter",
+    "HttpxAdapter",
+    "LangGraphAdapter",
+    "OpenAIAdapter",
+    "RefCountedPatch",
+    "RequestsAdapter",
+    "install_all",
+    "register",
+    "registry",
+    "uninstall_all",
+]

agenttape/adapters/base.py

@@ -0,0 +1,76 @@
+"""Adapter base class and the documented extension interface.
+
+An adapter translates a framework's native events into AgentTape's internal schema
+by routing boundary crossings through the active session's engine. Adapters keep
+their third-party imports lazy so the core stays dependency-free, and patch their
+target libraries with **reference-counted** install/uninstall so nested sessions
+share a single patch and route to whichever session is active at call time.
+
+To add an adapter:
+
+1. Subclass :class:`Adapter`.
+2. Implement :meth:`available` (is the target library importable?), :meth:`install`
+   and :meth:`uninstall`.
+3. Register it via ``agenttape.adapters.register(MyAdapter())``.
+
+Inside your patched callable, fetch ``agenttape.active_session()``; if it is
+``None`` call the original (pass-through), otherwise call
+``session.engine.intercept(kind, request, boundary=..., executor=...)``.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+
+class Adapter:
+    """Base class for framework adapters."""
+
+    name: str = "adapter"
+
+    def available(self) -> bool:
+        """Return True if this adapter's target library is importable."""
+
+        return False
+
+    def install(self, session: Any) -> None:
+        """Patch the target library to route through ``session``'s engine."""
+
+    def uninstall(self) -> None:
+        """Restore the target library to its original state."""
+
+
+class RefCountedPatch:
+    """Helper to install a patch once across nested sessions and restore on last exit."""
+
+    def __init__(self) -> None:
+        self._count = 0
+        self._restores: list[Any] = []
+        # Guards the refcount + restore list so concurrent session enter/exit (across
+        # threads) can't corrupt the count and leak or prematurely drop the patch.
+        self._lock = threading.RLock()
+
+    @property
+    def active(self) -> bool:
+        with self._lock:
+            return self._count > 0
+
+    def acquire(self, install_fn: Any) -> None:
+        with self._lock:
+            if self._count == 0:
+                self._restores = install_fn() or []
+            self._count += 1
+
+    def release(self) -> None:
+        with self._lock:
+            if self._count == 0:
+                return
+            self._count -= 1
+            if self._count == 0:
+                for restore in reversed(self._restores):
+                    try:
+                        restore()
+                    except Exception:  # pragma: no cover - defensive cleanup
+                        pass
+                self._restores = []

agenttape/adapters/http.py

@@ -0,0 +1,269 @@
+"""Raw HTTP fallback adapters for ``httpx`` and ``requests``.
+
+These patch the transport layer so that *any* SDK built on httpx/requests — even
+ones AgentTape has no dedicated adapter for — is captured and replayed. Matching is
+based on method + URL + body plus non-volatile headers; secret and volatile headers
+(``Authorization``, ``Cookie``, ``User-Agent`` …) are dropped from the recorded
+request so they neither leak to disk nor destabilise matching.
+"""
+
+from __future__ import annotations
+
+import base64
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from ..recorder import active_session
+from .base import Adapter, RefCountedPatch
+
+# Headers dropped from the *recorded request* (secret or volatile).
+_DROP_REQUEST_HEADERS = frozenset(
+    {
+        "authorization",
+        "proxy-authorization",
+        "cookie",
+        "x-api-key",
+        "openai-api-key",
+        "api-key",
+        "user-agent",
+        "date",
+        "content-length",
+        "host",
+        "connection",
+        "accept-encoding",
+        "x-request-id",
+        "x-stainless-arch",
+        "x-stainless-os",
+        "x-stainless-runtime",
+        "x-stainless-runtime-version",
+        "x-stainless-package-version",
+        "x-stainless-lang",
+        "traceparent",
+    }
+)
+
+
+def _clean_headers(headers: Any) -> dict[str, str]:
+    out: dict[str, str] = {}
+    try:
+        items = headers.items()
+    except AttributeError:
+        items = dict(headers).items()
+    for key, value in items:
+        if str(key).lower() in _DROP_REQUEST_HEADERS:
+            continue
+        out[str(key)] = str(value)
+    return out
+
+
+def _encode_body(content: bytes | None) -> dict[str, Any]:
+    if not content:
+        return {}
+    try:
+        return {"text": content.decode("utf-8")}
+    except UnicodeDecodeError:
+        return {"body_b64": base64.b64encode(content).decode("ascii")}
+
+
+def _decode_body(payload: dict[str, Any]) -> bytes:
+    if "text" in payload:
+        return str(payload["text"]).encode("utf-8")
+    if "content" in payload:
+        return str(payload["content"]).encode("utf-8")
+    if "body_b64" in payload:
+        return base64.b64decode(payload["body_b64"])
+    return b""
+
+
+# --------------------------------------------------------------------------- #
+# httpx
+# --------------------------------------------------------------------------- #
+
+
+class HttpxAdapter(Adapter):
+    name = "httpx"
+
+    def __init__(self) -> None:
+        self._patch = RefCountedPatch()
+
+    def available(self) -> bool:
+        try:
+            import httpx  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def install(self, session: Any) -> None:
+        self._patch.acquire(self._do_install)
+
+    def uninstall(self) -> None:
+        self._patch.release()
+
+    def _do_install(self) -> list[Callable[[], None]]:
+        import httpx
+
+        restores: list[Callable[[], None]] = []
+        orig_sync = httpx.Client.send
+        orig_async = httpx.AsyncClient.send
+
+        @functools.wraps(orig_sync)
+        def sync_send(client: Any, request: Any, **kwargs: Any) -> Any:
+            session = active_session()
+            if session is None:
+                return orig_sync(client, request, **kwargs)
+            req = _httpx_request(request)
+            boundary = request.url.host or "http"
+
+            def executor() -> Any:
+                resp = orig_sync(client, request, **kwargs)
+                resp.read()
+                return _httpx_dump(resp)
+
+            recorded = session.engine.intercept("http", req, boundary=boundary, executor=executor)
+            return _httpx_build(httpx, recorded, request)
+
+        @functools.wraps(orig_async)
+        async def async_send(client: Any, request: Any, **kwargs: Any) -> Any:
+            session = active_session()
+            if session is None:
+                return await orig_async(client, request, **kwargs)
+            req = _httpx_request(request)
+            boundary = request.url.host or "http"
+
+            async def executor() -> Any:
+                resp = await orig_async(client, request, **kwargs)
+                await resp.aread()
+                return _httpx_dump(resp)
+
+            recorded = await session.engine.aintercept(
+                "http", req, boundary=boundary, executor=executor
+            )
+            return _httpx_build(httpx, recorded, request)
+
+        httpx.Client.send = sync_send  # type: ignore[method-assign]
+        httpx.AsyncClient.send = async_send  # type: ignore[method-assign]
+        restores.append(lambda: setattr(httpx.Client, "send", orig_sync))
+        restores.append(lambda: setattr(httpx.AsyncClient, "send", orig_async))
+        return restores
+
+
+def _httpx_request(request: Any) -> dict[str, Any]:
+    body = bytes(request.content) if request.content else b""
+    return {
+        "method": request.method,
+        "url": str(request.url),
+        "headers": _clean_headers(request.headers),
+        **_encode_body(body),
+    }
+
+
+def _httpx_dump(resp: Any) -> dict[str, Any]:
+    return {
+        "status_code": resp.status_code,
+        "headers": dict(resp.headers),
+        **_encode_body(resp.content),
+    }
+
+
+def _httpx_build(httpx_mod: Any, payload: dict[str, Any], request: Any) -> Any:
+    return httpx_mod.Response(
+        status_code=int(payload.get("status_code", 200)),
+        headers=payload.get("headers", {}),
+        content=_decode_body(payload),
+        request=request,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# requests
+# --------------------------------------------------------------------------- #
+
+
+class RequestsAdapter(Adapter):
+    name = "requests"
+
+    def __init__(self) -> None:
+        self._patch = RefCountedPatch()
+
+    def available(self) -> bool:
+        try:
+            import requests  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def install(self, session: Any) -> None:
+        self._patch.acquire(self._do_install)
+
+    def uninstall(self) -> None:
+        self._patch.release()
+
+    def _do_install(self) -> list[Callable[[], None]]:
+        import requests
+        from requests.adapters import HTTPAdapter
+
+        orig_send = HTTPAdapter.send
+
+        @functools.wraps(orig_send)
+        def send(adapter: Any, request: Any, **kwargs: Any) -> Any:
+            session = active_session()
+            if session is None:
+                return orig_send(adapter, request, **kwargs)
+            req = _requests_request(request)
+            boundary = _host_of(request.url)
+
+            def executor() -> Any:
+                resp = orig_send(adapter, request, **kwargs)
+                return _requests_dump(resp)
+
+            recorded = session.engine.intercept("http", req, boundary=boundary, executor=executor)
+            return _requests_build(requests, recorded, request)
+
+        HTTPAdapter.send = send  # type: ignore[method-assign]
+        return [lambda: setattr(HTTPAdapter, "send", orig_send)]
+
+
+def _requests_request(request: Any) -> dict[str, Any]:
+    body = request.body
+    if isinstance(body, str):
+        body_bytes = body.encode("utf-8")
+    elif isinstance(body, bytes):
+        body_bytes = body
+    else:
+        body_bytes = b""
+    return {
+        "method": request.method,
+        "url": request.url,
+        "headers": _clean_headers(request.headers),
+        **_encode_body(body_bytes),
+    }
+
+
+def _requests_dump(resp: Any) -> dict[str, Any]:
+    return {
+        "status_code": resp.status_code,
+        "headers": dict(resp.headers),
+        "reason": getattr(resp, "reason", ""),
+        **_encode_body(resp.content),
+    }
+
+
+def _requests_build(requests_mod: Any, payload: dict[str, Any], request: Any) -> Any:
+    resp = requests_mod.models.Response()
+    resp.status_code = int(payload.get("status_code", 200))
+    resp._content = _decode_body(payload)
+    resp.headers = requests_mod.structures.CaseInsensitiveDict(payload.get("headers", {}))
+    resp.url = request.url
+    resp.reason = payload.get("reason", "")
+    resp.request = request
+    return resp
+
+
+def _host_of(url: str) -> str:
+    try:
+        from urllib.parse import urlparse
+
+        return urlparse(url).hostname or "http"
+    except Exception:  # pragma: no cover
+        return "http"

agenttape/adapters/langgraph.py

@@ -0,0 +1,108 @@
+"""LangGraph adapter — graph-state checkpoint capture.
+
+LangGraph runs a graph of nodes; LLM and tool calls inside nodes already flow
+through the OpenAI / httpx transport adapters (so they replay for free). This
+adapter adds the piece unique to LangGraph:
+
+* **Graph-state checkpoints** — each ``Pregel.invoke`` / ``.stream`` call is wrapped
+  and its result recorded as a ``memory_write`` interaction (boundary
+  ``graph_state``), enabling state/memory diffs between runs.
+
+The implementation is defensive: it adapts to the installed LangGraph version and
+never raises into user code. If the internal API differs, it degrades to capturing
+LLM/tool calls via the transport adapters only.
+
+For frameworks that expose callbacks instead of patch points, use the
+:class:`agenttape.AgentTape` callback object documented in ``callbacks.py``.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from ..recorder import active_session
+from .base import Adapter, RefCountedPatch
+
+
+class LangGraphAdapter(Adapter):
+    name = "langgraph"
+
+    def __init__(self) -> None:
+        self._patch = RefCountedPatch()
+
+    def available(self) -> bool:
+        try:
+            import langgraph  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def install(self, session: Any) -> None:
+        self._patch.acquire(self._do_install)
+
+    def uninstall(self) -> None:
+        self._patch.release()
+
+    def _do_install(self) -> list[Callable[[], None]]:
+        restores: list[Callable[[], None]] = []
+        restores += self._patch_pregel()
+        return restores
+
+    def _patch_pregel(self) -> list[Callable[[], None]]:
+        """Wrap ``Pregel.invoke`` / ``.stream`` to checkpoint state as memory_write."""
+
+        try:
+            from langgraph.pregel import Pregel  # type: ignore
+        except Exception:
+            return []
+
+        restores: list[Callable[[], None]] = []
+        for method_name in ("invoke", "stream"):
+            original = getattr(Pregel, method_name, None)
+            if original is None:
+                continue
+
+            @functools.wraps(original)  # type: ignore
+            def wrapper(  # type: ignore
+                self_obj: Any,
+                *args: Any,
+                __orig: Callable[..., Any] = original,
+                __name: str = method_name,
+                **kwargs: Any,
+            ) -> Any:
+                session = active_session()
+                if session is None:
+                    return __orig(self_obj, *args, **kwargs)
+                inputs = args[0] if args else kwargs.get("input")
+                request = {"node": "__graph__", "input": _safe(inputs)}
+
+                def executor() -> Any:
+                    return __orig(self_obj, *args, **kwargs)
+
+                # Record the final state as a memory_write so runs are diffable.
+                result = session.engine.intercept(
+                    "memory_write",
+                    request,
+                    boundary="graph_state",
+                    executor=executor,
+                )
+                return result
+
+            setattr(Pregel, method_name, wrapper)
+            restores.append(_restorer(Pregel, method_name, original))
+        return restores
+
+
+def _safe(obj: Any) -> Any:
+    from ..engine import _to_jsonable
+
+    return _to_jsonable(obj)
+
+
+def _restorer(cls: Any, name: str, original: Any) -> Callable[[], None]:
+    def restore() -> None:
+        setattr(cls, name, original)
+
+    return restore