agentcassette 0.1.0__py3-none-win_amd64.whl

agentcassette-0.1.0.data/purelib/agentcassette/__init__.py

@@ -0,0 +1,24 @@
+"""Python runtime hooks for AgentCassette."""
+
+from .openai_hook import (
+    OpenAIHookError,
+    OpenAIReplayDivergenceError,
+    OpenAIReplayError,
+    record_agent_step,
+    recording_openai,
+    recording_tool,
+    replaying_openai,
+)
+from .openai_session import openai_client, openai_session
+
+__all__ = [
+    "OpenAIHookError",
+    "OpenAIReplayDivergenceError",
+    "OpenAIReplayError",
+    "openai_client",
+    "openai_session",
+    "record_agent_step",
+    "recording_openai",
+    "recording_tool",
+    "replaying_openai",
+]

agentcassette-0.1.0.data/purelib/agentcassette/cassette_writer.py

@@ -0,0 +1,169 @@
+"""Minimal JSONL cassette writer for Python runtime hooks."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from .hashing import hash_value
+from .privacy import PrivacyMode, sanitize_event
+
+SCHEMA_VERSION = "0.1"
+
+ALLOWED_EVENTS = {
+    "trace.start",
+    "llm.call",
+    "llm.response",
+    "tool.call",
+    "tool.response",
+    "retrieval.call",
+    "retrieval.response",
+    "agent.step",
+    "error",
+    "trace.end",
+}
+
+
+class CassetteWriter:
+    """Write compact, flushed JSONL cassette events with a stable schema."""
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        privacy: PrivacyMode = "safe",
+        sanitizer: Callable[[Any], Any] | None = None,
+    ) -> None:
+        self.path = Path(path)
+        self.privacy = privacy
+        self.sanitizer = sanitizer
+        self._file = None
+
+    def __enter__(self) -> "CassetteWriter":
+        return self.open()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def open(self) -> "CassetteWriter":
+        if self._file is not None:
+            return self
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(
+            self.path,
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            0o600,
+        )
+        self._file = os.fdopen(fd, "w", encoding="utf-8", newline="\n")
+        return self
+
+    def write_event(self, fields: Mapping[str, Any]) -> dict[str, Any]:
+        if self._file is None:
+            raise RuntimeError("cassette writer is not open")
+
+        event = sanitize_event(fields, mode=self.privacy, sanitizer=self.sanitizer)
+        event.setdefault("schema_version", SCHEMA_VERSION)
+        _refresh_hash_fields(event, privacy=self.privacy)
+        _validate_event(event)
+
+        json.dump(
+            event,
+            self._file,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        )
+        self._file.write("\n")
+        self._file.flush()
+        return event
+
+    def close(self) -> None:
+        if self._file is None:
+            return
+        file_obj = self._file
+        self._file = None
+        file_obj.close()
+
+
+def _validate_event(event: Mapping[str, Any]) -> None:
+    version = event.get("schema_version")
+    if version != SCHEMA_VERSION:
+        raise ValueError(f"unsupported schema_version {version!r}")
+
+    event_type = event.get("event")
+    if not isinstance(event_type, str) or not event_type:
+        raise ValueError("event must be a non-empty string")
+    if event_type not in ALLOWED_EVENTS:
+        raise ValueError(f"unknown event type {event_type!r}")
+
+    if event_type == "trace.start":
+        _require_string(event, "trace_id")
+        _require_string(event, "name")
+    elif event_type == "llm.call":
+        _require_string(event, "span_id")
+        _require_string(event, "provider")
+        _require_string(event, "model")
+        _require_string(event, "input_hash")
+    elif event_type == "llm.response":
+        _require_string(event, "span_id")
+        _require_any(event, ("output", "output_hash", "error"))
+    elif event_type == "tool.call":
+        _require_string(event, "span_id")
+        _require_string(event, "name")
+    elif event_type == "tool.response":
+        _require_string(event, "span_id")
+        _require_any(event, ("output", "error"))
+    elif event_type == "retrieval.call":
+        _require_string(event, "span_id")
+        _require_any(event, ("query", "input_hash"))
+    elif event_type == "retrieval.response":
+        _require_string(event, "span_id")
+        _require_any(event, ("documents", "output_hash"))
+    elif event_type == "agent.step":
+        _require_string(event, "name")
+    elif event_type == "error":
+        _require_string(event, "message")
+    elif event_type == "trace.end":
+        _require_string(event, "trace_id")
+        _require_string(event, "status")
+
+
+def _refresh_hash_fields(event: dict[str, Any], *, privacy: PrivacyMode) -> None:
+    if privacy == "hide_all":
+        for field in ("output_hash",):
+            event.pop(field, None)
+        return
+
+    if "input" in event:
+        event["input_hash"] = hash_value(event["input"])
+    if "output" in event:
+        event["output_hash"] = hash_value(event["output"])
+    if "documents" in event:
+        event["output_hash"] = hash_value(event["documents"])
+
+
+def _require_string(event: Mapping[str, Any], field: str) -> None:
+    value = event.get(field)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{field} must be a non-empty string")
+
+
+def _require_any(event: Mapping[str, Any], fields: tuple[str, ...]) -> None:
+    for field in fields:
+        if field not in event:
+            continue
+        value = event[field]
+        if field == "documents":
+            if isinstance(value, list):
+                return
+            raise ValueError("documents must be an array")
+        if value is None:
+            raise ValueError(f"{field} must not be null")
+        if isinstance(value, str) and not value:
+            raise ValueError(f"{field} must not be empty")
+        return
+    raise ValueError(f"missing one of: {fields}")

agentcassette-0.1.0.data/purelib/agentcassette/cli.py

@@ -0,0 +1,29 @@
+"""Launcher for the AgentCassette Go CLI bundled in the Python package."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from importlib.resources import files
+
+
+def binary_path() -> os.PathLike[str]:
+    name = "agentcassette.exe" if os.name == "nt" else "agentcassette"
+    return files("agentcassette").joinpath("bin", name)
+
+
+def main() -> None:
+    binary = binary_path()
+    if not binary.is_file():
+        raise SystemExit(
+            "AgentCassette CLI binary is missing from this installation. "
+            "Install an official platform wheel instead of a source distribution."
+        )
+
+    result = subprocess.run([os.fspath(binary), *sys.argv[1:]], check=False)
+    raise SystemExit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

agentcassette-0.1.0.data/purelib/agentcassette/hashing.py

@@ -0,0 +1,47 @@
+"""Canonical JSON hashing compatible with the Go cassette package."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+HASH_PREFIX = "sha256:"
+
+_GO_JSON_ESCAPES = {
+    ord("<"): "\\u003c",
+    ord(">"): "\\u003e",
+    ord("&"): "\\u0026",
+    ord("\u2028"): "\\u2028",
+    ord("\u2029"): "\\u2029",
+}
+
+
+def canonical_json(value: Any) -> str:
+    """Return compact, key-sorted JSON for a JSON-serializable value."""
+
+    try:
+        encoded = json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        )
+        return encoded.translate(_GO_JSON_ESCAPES)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"canonicalize JSON for hash: {exc}") from exc
+
+
+def hash_value(value: Any) -> str:
+    canonical = canonical_json(value)
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return f"{HASH_PREFIX}{digest}"
+
+
+def hash_json(raw: str | bytes | bytearray) -> str:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"decode JSON for hash: {exc}") from exc
+    return hash_value(value)