tracefork-agent 0.1.0__tar.gz

tracefork_agent-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# TraceFork local state
+.tracefork/
+site/
+
+# Editors
+.idea/
+.vscode/

tracefork_agent-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: tracefork-agent
+Version: 0.1.0
+Summary: Replay AI agent failures locally and turn them into regression tests.
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27; extra == 'httpx'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# tracefork-core
+
+Framework-independent core engine for TraceFork: trace domain models, the
+recording engine, the boundary abstraction, canonicalization and matching, and
+the hermetic replay engine.
+
+This package must never depend on an agent framework. Framework support lives
+in adapter packages (`tracefork-openai`, `tracefork-langgraph`, ...).

tracefork_agent-0.1.0/README.md

@@ -0,0 +1,8 @@
+# tracefork-core
+
+Framework-independent core engine for TraceFork: trace domain models, the
+recording engine, the boundary abstraction, canonicalization and matching, and
+the hermetic replay engine.
+
+This package must never depend on an agent framework. Framework support lives
+in adapter packages (`tracefork-openai`, `tracefork-langgraph`, ...).

tracefork_agent-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "tracefork-agent"
+version = "0.1.0"
+description = "Replay AI agent failures locally and turn them into regression tests."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = ["pydantic>=2.7", "pyyaml>=6.0", "rich>=13.7", "typer>=0.12"]
+
+[project.optional-dependencies]
+openai = ["openai>=1.40"]
+httpx = ["httpx>=0.27"]
+
+[project.scripts]
+tracefork = "tracefork.cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracefork"]

tracefork_agent-0.1.0/src/tracefork/__init__.py

@@ -0,0 +1,9 @@
+"""TraceFork core: record, replay and diff AI agent executions."""
+
+from tracefork.adapters import ToolBox
+from tracefork.recording import Recording, record, span
+from tracefork.redaction import RedactionEngine, redactor
+
+__version__ = "0.1.0"
+
+__all__ = ["Recording", "RedactionEngine", "ToolBox", "__version__", "record", "redactor", "span"]

tracefork_agent-0.1.0/src/tracefork/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Adapters connecting the boundary runtime to concrete technologies."""
+
+from tracefork.adapters.python_tools import (
+    TOOL_BOUNDARY_TYPE,
+    PythonToolHandler,
+    ToolBox,
+    WrappedTool,
+    canonicalize_argument,
+)
+
+__all__ = [
+    "TOOL_BOUNDARY_TYPE",
+    "PythonToolHandler",
+    "ToolBox",
+    "WrappedTool",
+    "canonicalize_argument",
+]

tracefork_agent-0.1.0/src/tracefork/adapters/httpx.py

@@ -0,0 +1,210 @@
+"""httpx adapter (TF-080..082).
+
+An ``httpx.AsyncClient`` transport that routes every request through the
+boundary runtime, so HTTP traffic is recorded and replayed hermetically.
+Secret headers are redacted before anything is persisted (TF-081). Async-only
+in v0.1: the boundary runtime is async-first.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+from typing import Any
+
+import httpx
+
+from tracefork.boundaries import BoundaryRuntime
+from tracefork.boundaries.base import LiveCall
+from tracefork.errors import AdapterError
+from tracefork.models import BoundaryRequest, BoundaryResponse
+
+HTTPX_BOUNDARY_TYPE = "http.httpx"
+
+REDACTED = "[REDACTED]"
+
+# Secret-safe defaults (TF-081): matched case-insensitively.
+_SECRET_HEADERS = {"authorization", "cookie", "set-cookie", "x-api-key", "proxy-authorization"}
+
+# Content-coding headers describe the WIRE encoding, but transports hand us
+# decoded payloads. Recording them makes the replayed httpx.Response try to
+# decompress already-decompressed content (found by the live smoke), so they
+# are stripped on both directions.
+_CONTENT_CODING_HEADERS = {"content-encoding", "content-length", "transfer-encoding"}
+
+
+class HTTPXHandler:
+    """Translates httpx request/response objects to and from canonical data."""
+
+    async def execute(self, request: BoundaryRequest, call_live: LiveCall) -> BoundaryResponse:
+        response: httpx.Response = await call_live()
+        await response.aread()  # live responses stream; reading is a no-op otherwise
+        return BoundaryResponse(
+            response=_response_payload(request.request, response),
+            metadata={"status_code": response.status_code},
+        )
+
+    def restore(self, response: dict[str, Any], metadata: dict[str, Any]) -> httpx.Response:
+        recorded_request = response["request"]
+        request = httpx.Request(
+            method=recorded_request["method"],
+            url=recorded_request["url"],
+            headers=_plain_headers(recorded_request["headers"]),
+            content=_request_content(recorded_request),
+        )
+        status: int = response["status_code"]
+        return httpx.Response(
+            status_code=status,
+            headers=_plain_headers(response["headers"]),
+            content=_response_content(response),
+            request=request,
+        )
+
+
+class TraceForkAsyncTransport(httpx.AsyncBaseTransport):
+    """httpx transport that routes requests through the boundary runtime.
+
+    Wrap the real transport::
+
+        client = httpx.AsyncClient(
+            transport=TraceForkAsyncTransport(inner=httpx.AsyncTransport(), runtime=runtime)
+        )
+    """
+
+    def __init__(self, inner: httpx.AsyncBaseTransport, runtime: BoundaryRuntime) -> None:
+        self._inner = inner
+        self._runtime = runtime
+        runtime.registry.register(HTTPX_BOUNDARY_TYPE, HTTPXHandler())
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        payload = _request_payload(request)
+        name = f"{request.method} {request.url.path}"
+
+        async def call_live() -> httpx.Response:
+            return await self._inner.handle_async_request(request)
+
+        response: httpx.Response = await self._runtime.invoke(
+            HTTPX_BOUNDARY_TYPE, name, payload, call_live
+        )
+        return response
+
+
+class TraceForkTransport(httpx.BaseTransport):
+    """Sync httpx transport that routes requests through the boundary runtime.
+
+    Each call is executed in a fresh event loop (the sync SDK path cannot
+    await); using it inside a running loop raises ``AdapterError`` — use
+    :class:`TraceForkAsyncTransport` from async code.
+    """
+
+    def __init__(self, inner: httpx.BaseTransport, runtime: BoundaryRuntime) -> None:
+        self._inner = inner
+        self._runtime = runtime
+        runtime.registry.register(HTTPX_BOUNDARY_TYPE, HTTPXHandler())
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            msg = "sync httpx transport used inside a running event loop; use AsyncClient"
+            raise AdapterError(msg)
+
+        async def call_live() -> httpx.Response:
+            response = self._inner.handle_request(request)
+            response.read()  # buffer now; aread() later is a no-op
+            return response
+
+        response: httpx.Response = asyncio.run(
+            self._runtime.invoke(
+                HTTPX_BOUNDARY_TYPE,
+                f"{request.method} {request.url.path}",
+                _request_payload(request),
+                call_live,
+            )
+        )
+        return response
+
+
+def _request_payload(request: httpx.Request) -> dict[str, Any]:
+    headers = {
+        key: value
+        for key, value in _safe_headers(request.headers).items()
+        if key not in _CONTENT_CODING_HEADERS
+    }
+    payload: dict[str, Any] = {
+        "method": request.method,
+        "url": str(request.url),
+        "headers": headers,
+    }
+    body = _decode_body(request.headers.get("content-type"), request.content)
+    if body is not None:
+        payload.update(body)
+    return payload
+
+
+def _response_payload(request_payload: dict[str, Any], response: httpx.Response) -> dict[str, Any]:
+    headers = {
+        key: value
+        for key, value in _safe_headers(response.headers).items()
+        if key not in _CONTENT_CODING_HEADERS
+    }
+    payload: dict[str, Any] = {
+        "request": request_payload,
+        "status_code": response.status_code,
+        "headers": headers,
+    }
+    body = _decode_body(response.headers.get("content-type"), response.content)
+    if body is not None:
+        payload.update(body)
+    return payload
+
+
+def _decode_body(content_type: str | None, content: bytes) -> dict[str, Any] | None:
+    if not content:
+        return None
+    if content_type and "application/json" in content_type:
+        try:
+            return {"json": json.loads(content)}
+        except json.JSONDecodeError:
+            pass
+    try:
+        return {"content": content.decode("utf-8")}
+    except UnicodeDecodeError:
+        # Binary bodies are stored base64 so replays are byte-identical
+        # (errors="replace" would silently corrupt them).
+        return {"content_base64": base64.b64encode(content).decode("ascii")}
+
+
+def _request_content(recorded_request: dict[str, Any]) -> bytes:
+    if "json" in recorded_request:
+        return str(json.dumps(recorded_request["json"])).encode("utf-8")
+    if "content" in recorded_request:
+        return str(recorded_request["content"]).encode("utf-8")
+    if "content_base64" in recorded_request:
+        return base64.b64decode(recorded_request["content_base64"])
+    return b""
+
+
+def _response_content(recorded_response: dict[str, Any]) -> bytes:
+    if "json" in recorded_response:
+        return str(json.dumps(recorded_response["json"])).encode("utf-8")
+    if "content" in recorded_response:
+        return str(recorded_response["content"]).encode("utf-8")
+    if "content_base64" in recorded_response:
+        return base64.b64decode(recorded_response["content_base64"])
+    return b""
+
+
+def _safe_headers(headers: Any) -> dict[str, str]:
+    """Lower-case header map with secret headers redacted (TF-081)."""
+    return {
+        str(key).lower(): REDACTED if str(key).lower() in _SECRET_HEADERS else str(value)
+        for key, value in headers.items()
+    }
+
+
+def _plain_headers(headers: dict[str, str]) -> list[tuple[str, str]]:
+    return list(headers.items())

tracefork_agent-0.1.0/src/tracefork/adapters/openai.py

@@ -0,0 +1,179 @@
+"""OpenAI Responses API adapter (TF-070..074).
+
+Routes ``client.responses.create`` (sync and async, streaming and not) through
+the boundary runtime. The adapter only translates:
+
+- native kwargs → canonical request payload,
+- SDK response/stream objects → canonical payloads (with usage metadata),
+- recorded payloads → SDK objects rebuilt via the SDK's own construction
+  machinery, so application code keeps working unchanged in replay.
+
+The live callable is supplied by the instrumentation and is structurally
+unreachable on the replay path (ADR 0004, ADR 0003).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Any
+
+from openai import AsyncOpenAI, OpenAI
+from openai._models import construct_type
+from openai.types.responses import Response
+from openai.types.responses.response_stream_event import ResponseStreamEvent
+
+from tracefork.adapters import canonicalize_argument
+from tracefork.boundaries import BoundaryRuntime
+from tracefork.boundaries.base import LiveCall
+from tracefork.errors import AdapterError
+from tracefork.models import BoundaryRequest, BoundaryResponse
+
+LLM_OPENAI_BOUNDARY_TYPE = "llm.openai"
+
+
+class OpenAIHandler:
+    """Translates Responses API traffic between native and canonical shapes."""
+
+    async def execute(self, request: BoundaryRequest, call_live: LiveCall) -> BoundaryResponse:
+        started = time.perf_counter()
+        if request.metadata.get("stream"):
+            stream = await _call(call_live)
+            if hasattr(stream, "__aiter__"):
+                events = [event.model_dump(mode="json") async for event in stream]
+            else:
+                events = [event.model_dump(mode="json") for event in stream]
+            terminal_types = ("response.completed", "response.incomplete")
+            terminal = next((e for e in reversed(events) if e.get("type") in terminal_types), None)
+            usage = _usage_metadata((terminal or {}).get("response", {}).get("usage"))
+            return BoundaryResponse(
+                response={"__stream__": True, "events": events},
+                metadata={
+                    "stream": True,
+                    "usage": usage,
+                    "finish_reason": terminal.get("type").removeprefix("response.")
+                    if terminal
+                    else None,
+                    "latency_ms": _latency_ms(started),
+                },
+            )
+        response = await _call(call_live)
+        payload = response.model_dump(mode="json")
+        return BoundaryResponse(
+            response=payload,
+            metadata={
+                "stream": False,
+                "usage": _usage_metadata(payload.get("usage")),
+                "finish_reason": payload.get("status"),
+                "latency_ms": _latency_ms(started),
+            },
+        )
+
+    def restore(self, response: Any, metadata: dict[str, Any]) -> Any:
+        if metadata.get("stream"):
+            events = [
+                construct_type(type_=ResponseStreamEvent, value=event)
+                for event in response["events"]
+            ]
+            return _ReplayedStream(events)
+        return construct_type(type_=Response, value=response)
+
+
+class _ReplayedStream:
+    """In-memory stream replays a recorded event sequence.
+
+    Buffers the full event list (also done at record time); supports both the
+    sync and async iteration protocols, matching whichever client is used.
+    """
+
+    def __init__(self, events: list[Any]) -> None:
+        self._events = events
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._events)
+
+    def __aiter__(self) -> AsyncIterator[Any]:
+        async def _gen() -> AsyncIterator[Any]:
+            for event in self._events:
+                yield event
+
+        return _gen()
+
+
+def instrument_openai(client: OpenAI | AsyncOpenAI, runtime: BoundaryRuntime) -> None:
+    """Route ``client.responses.create`` through the boundary runtime, in place.
+
+    Registers the shared OpenAI handler on the runtime's registry. Recording,
+    matching and replay semantics remain in the core runtime.
+    """
+    runtime.registry.register(LLM_OPENAI_BOUNDARY_TYPE, OpenAIHandler())
+    original = client.responses.create
+    is_async = isinstance(client, AsyncOpenAI)
+
+    if is_async:
+
+        async def create_async(**kwargs: Any) -> Any:
+            return await _invoke(runtime, original, kwargs, sync_client=False)
+
+        client.responses.create = create_async  # type: ignore[method-assign]
+        return
+
+    def create_sync(**kwargs: Any) -> Any:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            msg = "sync OpenAI client used inside a running event loop; use AsyncOpenAI"
+            raise AdapterError(msg)
+        return asyncio.run(_invoke(runtime, original, kwargs, sync_client=True))
+
+    client.responses.create = create_sync  # type: ignore[method-assign]
+
+
+async def _invoke(
+    runtime: BoundaryRuntime,
+    original: Callable[..., Any],
+    kwargs: dict[str, Any],
+    *,
+    sync_client: bool,
+) -> Any:
+    model = kwargs.get("model") or "responses.create"
+    stream = bool(kwargs.get("stream"))
+    request_payload = {str(key): canonicalize_argument(value) for key, value in kwargs.items()}
+
+    async def call_live() -> Any:
+        result = original(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    return await runtime.invoke(
+        LLM_OPENAI_BOUNDARY_TYPE,
+        model,
+        request_payload,
+        call_live,
+        metadata={"stream": stream, "sync": sync_client},
+    )
+
+
+async def _call(call_live: LiveCall) -> Any:
+    return await call_live()
+
+
+def _usage_metadata(usage: dict[str, Any] | None) -> dict[str, Any]:
+    if not usage:
+        return {}
+    input_details = usage.get("input_tokens_details") or {}
+    return {
+        "input_tokens": usage.get("input_tokens"),
+        "output_tokens": usage.get("output_tokens"),
+        "total_tokens": usage.get("total_tokens"),
+        "cached_tokens": input_details.get("cached_tokens"),
+    }
+
+
+def _latency_ms(started: float) -> int:
+    return int((time.perf_counter() - started) * 1000)

tracefork_agent-0.1.0/src/tracefork/adapters/python_tools.py

@@ -0,0 +1,190 @@
+"""Python function tool adapter (TF-060..063).
+
+Python tools are ordinary functions routed through the boundary runtime, so
+recording, matching and replay semantics live entirely in the core (ADR 0004).
+The adapter only translates: argument canonicalization on the way in, the
+recorded response on the way out.
+
+Usage::
+
+    runtime = BoundaryRuntime(registry=registry)
+    tools = ToolBox(runtime)
+
+    @tools.tool()
+    async def search_orders(customer_id: int) -> dict:
+        ...
+
+    result = await search_orders(customer_id=912)   # recorded or replayed
+"""
+
+import dataclasses
+import functools
+import inspect
+from collections.abc import Callable
+from datetime import UTC, date, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from tracefork.boundaries import BoundaryRuntime
+from tracefork.boundaries.base import LiveCall
+from tracefork.canonicalization import canonical_json
+from tracefork.errors import AdapterError
+from tracefork.models import BoundaryRequest, BoundaryResponse
+
+TOOL_BOUNDARY_TYPE = "tool.python"
+
+
+class PythonToolHandler:
+    """Generic boundary handler for Python tools: run live, restore verbatim."""
+
+    async def execute(self, request: BoundaryRequest, call_live: LiveCall) -> BoundaryResponse:
+        return BoundaryResponse(response=await call_live(), metadata={})
+
+    def restore(self, response: Any, metadata: dict[str, Any]) -> Any:
+        return response
+
+
+def canonicalize_argument(value: Any) -> Any:
+    """Convert a tool argument to a canonical, JSON-ready value (TF-063).
+
+    Supports primitives, datetimes, UUIDs, enums, dataclasses, Pydantic
+    models, mappings and sequences (including deterministically ordered sets).
+    Anything else raises ``AdapterError`` — objects are never silently
+    stringified.
+    """
+    if value is None or isinstance(value, str | bool):
+        return value
+    if isinstance(value, int | float):
+        return value  # finite check happens in canonicalization.json
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=UTC)
+        return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, Enum):
+        return canonicalize_argument(value.value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            field.name: canonicalize_argument(getattr(value, field.name))
+            for field in dataclasses.fields(value)
+        }
+    if isinstance(value, BaseModel):
+        return canonicalize_argument(value.model_dump(mode="python"))
+    if isinstance(value, dict):
+        return {str(key): canonicalize_argument(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [canonicalize_argument(item) for item in value]
+    if isinstance(value, set | frozenset):
+        items = [canonicalize_argument(item) for item in value]
+        return sorted(items, key=canonical_json)
+    msg = (
+        f"tool argument of type {type(value).__name__} cannot be canonicalized; "
+        "pass JSON-compatible data, dataclasses, Pydantic models, enums, "
+        "datetimes, UUIDs or collections thereof"
+    )
+    raise AdapterError(msg)
+
+
+class WrappedTool:
+    """A Python function routed through the boundary runtime.
+
+    Calling the wrapper records the call (RECORD mode), replays it
+    (REPLAY + policy REPLAY), or executes it live per the active context. The
+    real function body is unreachable on the replay path (TF-062).
+    """
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        runtime: BoundaryRuntime,
+        name: str | None = None,
+        boundary_type: str = TOOL_BOUNDARY_TYPE,
+    ) -> None:
+        self._func = func
+        self._runtime = runtime
+        self.tool_name = name if name is not None else f"{func.__module__}.{func.__qualname__}"
+        self._boundary_type = boundary_type
+        functools.update_wrapper(self, func, updated=())
+
+    @property
+    def boundary_type(self) -> str:
+        return self._boundary_type
+
+    @property
+    def func(self) -> Callable[..., Any]:
+        return self._func
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        request = {
+            "args": [canonicalize_argument(arg) for arg in args],
+            "kwargs": {str(key): canonicalize_argument(value) for key, value in kwargs.items()},
+        }
+
+        async def call_live() -> Any:
+            result = self._func(*args, **kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+            return result
+
+        return await self._runtime.invoke(self.boundary_type, self.tool_name, request, call_live)
+
+
+class ToolBox:
+    """Binds tool decorators to a boundary runtime and registers the handler.
+
+    Dependency-injected by design: there is no global registry and no hidden
+    mutation. The shared :class:`PythonToolHandler` is registered once.
+    """
+
+    def __init__(self, runtime: BoundaryRuntime) -> None:
+        self._runtime = runtime
+        self._handler_registered = False
+
+    def tool(
+        self, *, name: str | None = None, boundary_type: str = TOOL_BOUNDARY_TYPE
+    ) -> Callable[[Callable[..., Any]], WrappedTool]:
+        """Decorate an async or sync function as a TraceFork tool.
+
+        ``boundary_type`` re-labels the boundary family (e.g. ``llm.demo`` for
+        a scripted LLM); it decides the span kind and replay family.
+        """
+
+        def decorator(func: Callable[..., Any]) -> WrappedTool:
+            return self.wrap(func, name=name, boundary_type=boundary_type)
+
+        return decorator
+
+    def wrap(
+        self,
+        func: Callable[..., Any],
+        *,
+        name: str | None = None,
+        boundary_type: str = TOOL_BOUNDARY_TYPE,
+    ) -> WrappedTool:
+        """Wrap an existing function as a TraceFork tool."""
+        self._ensure_handler(boundary_type)
+        return WrappedTool(func, self._runtime, name=name, boundary_type=boundary_type)
+
+    def _ensure_handler(self, boundary_type: str) -> None:
+        if boundary_type == TOOL_BOUNDARY_TYPE:
+            if not self._handler_registered:
+                self._runtime.registry.register(boundary_type, PythonToolHandler())
+                self._handler_registered = True
+            return
+        # Custom boundary types get their own handler registration.
+        self._runtime.registry.register(boundary_type, PythonToolHandler())
+
+
+__all__ = [
+    "TOOL_BOUNDARY_TYPE",
+    "PythonToolHandler",
+    "ToolBox",
+    "WrappedTool",
+    "canonicalize_argument",
+]