grudge-cli 0.1.0__py3-none-any.whl

grudge/recorder/adapters/raw_sdk.py

@@ -0,0 +1,159 @@
+"""Typed boundary for recording plain SDK tool-calling loops.
+
+The adapter intentionally accepts the small mapping-shaped events commonly
+produced by SDK wrappers.  It keeps SDK-specific response classes out of the
+recorder while preserving the loop's original event order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, TypeAlias, cast
+
+from grudge.recorder.recorder import Recorder
+from grudge.schema.trace import Step
+
+RawEvent: TypeAlias = Mapping[str, Any]
+RawLoop: TypeAlias = Iterable[RawEvent] | Callable[[], Iterable[RawEvent]]
+
+
+def record_raw_sdk(recorder: Recorder, events: RawLoop) -> list[Step]:
+    """Record raw SDK events or the result of a zero-argument event loop.
+
+    Events use ``kind`` (or the equivalent ``type``) with one of the Phase 1
+    values: ``model_call``, ``tool_call``, ``tool_result``, ``state_diff``, or
+    ``final_answer``.  Event-specific fields are passed through to the typed
+    recorder methods, and the returned list contains the newly recorded steps.
+    """
+
+    source = events() if callable(events) else events
+    recorded: list[Step] = []
+    for event in source:
+        kind = event.get("kind", event.get("type"))
+        if not isinstance(kind, str):
+            raise ValueError("raw SDK event must include a string kind")
+        if kind == "model_call":
+            step = cast(
+                Step,
+                recorder.record_model_call(
+                    model=_optional_str(event, "model"),
+                    messages=_optional_messages(event.get("messages")),
+                    prompt=_optional_str(event, "prompt"),
+                    response=event.get("response"),
+                    parent_idx=_optional_int(event, "parent_idx"),
+                    meta=_optional_mapping(event.get("meta")),
+                ),
+            )
+        elif kind == "tool_call":
+            args = event.get("args", event.get("arguments", {}))
+            step = cast(
+                Step,
+                recorder.record_tool_call(
+                    _required_str(event, "tool", alternative="name"),
+                    _required_mapping(args, "tool call args"),
+                    _optional_str(event, "call_id"),
+                    parent_idx=_optional_int(event, "parent_idx"),
+                    meta=_optional_mapping(event.get("meta")),
+                ),
+            )
+        elif kind == "tool_result":
+            step = cast(
+                Step,
+                recorder.record_tool_result(
+                    _required_str(event, "call_id", alternative="tool_call_id"),
+                    event.get("content"),
+                    _optional_str(event, "error"),
+                    parent_idx=_optional_int(event, "parent_idx"),
+                    meta=_optional_mapping(event.get("meta")),
+                ),
+            )
+        elif kind == "state_diff":
+            step = cast(
+                Step,
+                recorder.record_state_diff(
+                    _required_mapping(event.get("diff", {}), "state diff"),
+                    parent_idx=_optional_int(event, "parent_idx"),
+                    meta=_optional_mapping(event.get("meta")),
+                ),
+            )
+        elif kind == "final_answer":
+            step = cast(
+                Step,
+                recorder.record_final_answer(
+                    _optional_str(event, "answer"),
+                    parent_idx=_optional_int(event, "parent_idx"),
+                    meta=_optional_mapping(event.get("meta")),
+                ),
+            )
+        else:
+            raise ValueError(f"unsupported raw SDK event kind: {kind}")
+        recorded.append(step)
+    return recorded
+
+
+def _required_str(
+    event: RawEvent,
+    key: str,
+    *,
+    alternative: str | None = None,
+) -> str:
+    """Read a required string field, with an SDK naming alias."""
+
+    value = event.get(key)
+    if value is None and alternative is not None:
+        value = event.get(alternative)
+    if not isinstance(value, str) or not value:
+        label = f"{key}/{alternative}" if alternative else key
+        raise ValueError(f"raw SDK event requires non-empty string {label}")
+    return value
+
+
+def _optional_str(event: RawEvent, key: str) -> str | None:
+    """Read an optional string field."""
+
+    value = event.get(key)
+    if value is not None and not isinstance(value, str):
+        raise ValueError(f"raw SDK event field {key} must be a string")
+    return value
+
+
+def _optional_int(event: RawEvent, key: str) -> int | None:
+    """Read an optional integer field."""
+
+    value = event.get(key)
+    invalid = value is not None and (
+        isinstance(value, bool) or not isinstance(value, int)
+    )
+    if invalid:
+        raise ValueError(f"raw SDK event field {key} must be an integer")
+    return value
+
+
+def _optional_mapping(value: Any) -> Mapping[str, Any] | None:
+    """Read an optional mapping field."""
+
+    if value is not None and not isinstance(value, Mapping):
+        raise ValueError("raw SDK event metadata must be a mapping")
+    return value
+
+
+def _required_mapping(value: Any, label: str) -> Mapping[str, Any]:
+    """Read a required mapping field."""
+
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be a mapping")
+    return value
+
+
+def _optional_messages(value: Any) -> list[dict[str, Any]] | None:
+    """Validate the Phase 1 message-list shape without SDK dependencies."""
+
+    if value is None:
+        return None
+    valid = isinstance(value, list) and all(isinstance(item, dict) for item in value)
+    if not valid:
+        raise ValueError("raw SDK event messages must be a list of mappings")
+    return cast(list[dict[str, Any]], value)
+
+
+__all__ = ["RawEvent", "RawLoop", "record_raw_sdk"]

grudge/recorder/recorder.py

@@ -0,0 +1,374 @@
+"""Capture an agent run as an ordered, canonical Phase 1 trace.
+
+The recorder keeps steps in memory until the run is complete.  This lets the
+JSONL header contain the final outcome while the output itself is still
+written append-only: once a record is written it is never sought, rewritten,
+or truncated.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from functools import wraps
+from io import TextIOBase
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Literal, TypeVar, cast
+
+from grudge.schema.trace import (
+    FinalAnswer,
+    ModelCall,
+    StateDiff,
+    Step,
+    ToolCall,
+    ToolResult,
+    Trace,
+)
+
+Output = str | Path | TextIOBase
+ReturnT = TypeVar("ReturnT")
+
+
+class JsonlWriter:
+    """Write JSON objects to a text sink without rewriting earlier records."""
+
+    def __init__(self, output: Output) -> None:
+        self._owned = isinstance(output, str | Path)
+        if self._owned:
+            stream = Path(cast(str | Path, output)).open("a", encoding="utf-8")
+            self._stream: TextIOBase = stream
+        else:
+            self._stream = cast(TextIOBase, output)
+        self._closed = False
+
+    def append(self, record: Mapping[str, Any]) -> None:
+        """Append one canonical JSON object and flush it to the sink."""
+
+        if self._closed:
+            raise RuntimeError("cannot append to a closed JSONL writer")
+        line = json.dumps(
+            dict(record),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            default=str,
+        )
+        self._stream.write(line + "\n")
+        self._stream.flush()
+
+    def close(self) -> None:
+        """Close an owned file, leaving caller-owned streams open."""
+
+        if self._closed:
+            return
+        self._stream.flush()
+        if self._owned:
+            self._stream.close()
+        self._closed = True
+
+
+class Recorder:
+    """Record one agent run and persist it as canonical JSONL.
+
+    ``Recorder`` is normally used as a context manager.  Steps receive a
+    strictly increasing index at the moment they are recorded, and an
+    exception escaping the context produces a failed trace before being
+    re-raised to the caller.
+    """
+
+    def __init__(
+        self,
+        output: Output,
+        *,
+        run_id: str,
+        agent_version: str = "unknown",
+        task: str = "",
+    ) -> None:
+        self.output = output
+        self.run_id = run_id
+        self.agent_version = agent_version
+        self.task = task
+        self._steps: list[Step] = []
+        self._next_idx = 0
+        self._trace: Trace | None = None
+        self._writer: JsonlWriter | None = None
+        self.exception: BaseException | None = None
+
+    def __enter__(self) -> Recorder:
+        """Start a recording context."""
+
+        if self._trace is not None:
+            raise RuntimeError("a recorder can only be entered once")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        """Persist the trace and re-raise any exception from the context."""
+
+        if exc_value is not None:
+            self.exception = exc_value
+        self.close(outcome="failed" if exc_value is not None else "ok")
+        return False
+
+    @property
+    def steps(self) -> tuple[Step, ...]:
+        """Return the recorded steps in their original order."""
+
+        return tuple(self._steps)
+
+    @property
+    def trace(self) -> Trace:
+        """Return the finalized trace, or raise while recording is active."""
+
+        if self._trace is None:
+            raise RuntimeError("trace is available after Recorder.close()")
+        return self._trace
+
+    def record_step(self, step: Step) -> Step:
+        """Append a pre-built Phase 1 step at the next monotonic index."""
+
+        if self._trace is not None:
+            raise RuntimeError("cannot record after the recorder is closed")
+        if step.run_id != self.run_id:
+            raise ValueError("step run_id must match recorder run_id")
+        if step.idx != self._next_idx:
+            raise ValueError(f"step idx must be {self._next_idx}, received {step.idx}")
+        self._steps.append(step)
+        self._next_idx += 1
+        return step
+
+    def record_model_call(
+        self,
+        *,
+        model: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        prompt: str | None = None,
+        response: Any = None,
+        parent_idx: int | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> ModelCall:
+        """Record a model request or response."""
+
+        return cast(
+            ModelCall,
+            self.record_step(
+                ModelCall(
+                    idx=self._next_idx,
+                    ts=_now(),
+                    run_id=self.run_id,
+                    parent_idx=parent_idx,
+                    meta=dict(meta or {}),
+                    model=model,
+                    messages=messages,
+                    prompt=prompt,
+                    response=response,
+                )
+            ),
+        )
+
+    def record_tool_call(
+        self,
+        tool: str,
+        args: Mapping[str, Any] | None = None,
+        call_id: str | None = None,
+        *,
+        parent_idx: int | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> ToolCall:
+        """Record a tool invocation, generating a call id when omitted."""
+
+        return cast(
+            ToolCall,
+            self.record_step(
+                ToolCall(
+                    idx=self._next_idx,
+                    ts=_now(),
+                    run_id=self.run_id,
+                    parent_idx=parent_idx,
+                    meta=dict(meta or {}),
+                    tool=tool,
+                    args=dict(args or {}),
+                    call_id=call_id or f"call-{self._next_idx}",
+                )
+            ),
+        )
+
+    def record_tool_result(
+        self,
+        call_id: str,
+        content: Any,
+        error: str | None = None,
+        *,
+        parent_idx: int | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> ToolResult:
+        """Record a tool result, including a tool-level error when present."""
+
+        return cast(
+            ToolResult,
+            self.record_step(
+                ToolResult(
+                    idx=self._next_idx,
+                    ts=_now(),
+                    run_id=self.run_id,
+                    parent_idx=parent_idx,
+                    meta=dict(meta or {}),
+                    call_id=call_id,
+                    content=content,
+                    error=error,
+                )
+            ),
+        )
+
+    def record_state_diff(
+        self,
+        diff: Mapping[str, Any] | None = None,
+        *,
+        parent_idx: int | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> StateDiff:
+        """Record a structured state change."""
+
+        return cast(
+            StateDiff,
+            self.record_step(
+                StateDiff(
+                    idx=self._next_idx,
+                    ts=_now(),
+                    run_id=self.run_id,
+                    parent_idx=parent_idx,
+                    meta=dict(meta or {}),
+                    diff=dict(diff or {}),
+                )
+            ),
+        )
+
+    def record_final_answer(
+        self,
+        answer: str | None,
+        *,
+        parent_idx: int | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> FinalAnswer:
+        """Record the agent's terminal answer."""
+
+        return cast(
+            FinalAnswer,
+            self.record_step(
+                FinalAnswer(
+                    idx=self._next_idx,
+                    ts=_now(),
+                    run_id=self.run_id,
+                    parent_idx=parent_idx,
+                    meta=dict(meta or {}),
+                    answer=answer,
+                )
+            ),
+        )
+
+    # Short aliases make the recording API convenient in plain SDK loops.
+    model_call = record_model_call
+    tool_call = record_tool_call
+    tool_result = record_tool_result
+    state_diff = record_state_diff
+    final_answer = record_final_answer
+
+    def close(self, *, outcome: Literal["ok", "failed"] = "ok") -> Trace:
+        """Finalize and append the trace header and steps to the output."""
+
+        if self._trace is not None:
+            return self._trace
+        trace = Trace(
+            run_id=self.run_id,
+            agent_version=self.agent_version,
+            task=self.task,
+            steps=list(self._steps),
+            outcome=outcome,
+        )
+        writer = JsonlWriter(self.output)
+        try:
+            for line in trace.to_jsonl().splitlines():
+                writer.append(json.loads(line))
+        finally:
+            writer.close()
+        self._writer = writer
+        self._trace = trace
+        return trace
+
+
+def _now() -> datetime:
+    """Return an aware UTC timestamp for a trace step."""
+
+    return datetime.now(UTC)
+
+
+def record_run(
+    output: Output,
+    *,
+    run_id: str,
+    agent_version: str = "unknown",
+    task: str = "",
+) -> Recorder:
+    """Create a recorder; use it as ``with record_run(...) as recorder``."""
+
+    return Recorder(
+        output,
+        run_id=run_id,
+        agent_version=agent_version,
+        task=task,
+    )
+
+
+def record(
+    output: Output,
+    *,
+    run_id: str,
+    agent_version: str = "unknown",
+    task: str = "",
+) -> Callable[[Callable[..., ReturnT]], Callable[..., ReturnT]]:
+    """Decorate a recorder-aware function with a recording context.
+
+    The wrapped function receives ``recorder=...`` when its signature accepts
+    that keyword.  Functions that do not accept it still get outcome capture.
+    """
+
+    def decorate(function: Callable[..., ReturnT]) -> Callable[..., ReturnT]:
+        def wrapped(*args: Any, **kwargs: Any) -> ReturnT:
+            with Recorder(
+                output,
+                run_id=run_id,
+                agent_version=agent_version,
+                task=task,
+            ) as recorder:
+                accepts_recorder = _accepts_keyword(function, "recorder")
+                if accepts_recorder:
+                    kwargs = {**kwargs, "recorder": recorder}
+                return function(*args, **kwargs)
+
+        return cast(Callable[..., ReturnT], wraps(function)(wrapped))
+
+    return decorate
+
+
+def _accepts_keyword(function: Callable[..., Any], name: str) -> bool:
+    """Check whether a callable can receive a named recorder argument."""
+
+    try:
+        signature = inspect.signature(function)
+    except (TypeError, ValueError):
+        return False
+    parameter = signature.parameters.get(name)
+    return parameter is not None or any(
+        item.kind is inspect.Parameter.VAR_KEYWORD
+        for item in signature.parameters.values()
+    )
+
+
+__all__ = ["JsonlWriter", "Recorder", "record", "record_run"]

grudge/recorder/redact.py

@@ -0,0 +1,105 @@
+"""Small, dependency-free redaction helpers for recorded trace values."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import TypeVar, cast
+
+
+@dataclass(frozen=True, slots=True)
+class RedactionRule:
+    """A regular expression and replacement used by :func:`redact_text`."""
+
+    pattern: str | re.Pattern[str]
+    replacement: str = "[REDACTED]"
+    flags: int = 0
+
+    def compiled(self) -> re.Pattern[str]:
+        """Return the rule's compiled regular expression."""
+        if isinstance(self.pattern, str):
+            return re.compile(self.pattern, self.flags)
+        if self.flags:
+            raise ValueError("flags cannot be used with a compiled pattern")
+        return self.pattern
+
+
+DEFAULT_REDACTION_RULES: tuple[RedactionRule, ...] = (
+    RedactionRule(r"\bFAKE_KEY_[A-Za-z0-9_-]+\b"),
+    RedactionRule(r"\b(?:sk-ant-|sk-)[A-Za-z0-9_-]{12,}\b"),
+    RedactionRule(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b"),
+    RedactionRule(r"\b(?:ghp|gho|ghs|ghr)_[A-Za-z0-9]{20,}\b"),
+    RedactionRule(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),
+    RedactionRule(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"),
+    RedactionRule(
+        r"(?i)\b(?:api[_-]?key|access[_-]?token|secret|token|password)"
+        r"(\s*[:=]\s*)['\"]?[A-Za-z0-9_./+=-]{8,}['\"]?",
+        replacement=r"\1[REDACTED]",
+    ),
+)
+
+# A short alias keeps the public rule list convenient to discover.
+DEFAULT_RULES = DEFAULT_REDACTION_RULES
+
+_T = TypeVar("_T")
+_RuleLike = RedactionRule | str | re.Pattern[str]
+
+
+def _as_rule(rule: _RuleLike) -> RedactionRule:
+    """Normalize a shorthand regex into a standard redaction rule."""
+    if isinstance(rule, RedactionRule):
+        return rule
+    return RedactionRule(rule)
+
+
+def redact_text(
+    text: str,
+    *,
+    rules: Sequence[_RuleLike] | None = None,
+    enabled: bool = True,
+) -> str:
+    """Redact key-like substrings in ``text`` using rules in list order.
+
+    Passing ``enabled=False`` is an intentional no-op for tests that need to
+    inspect the original trace.  Passing an empty rule sequence also disables
+    the default rules while leaving redaction enabled.
+    """
+    if not enabled:
+        return text
+
+    selected_rules = DEFAULT_REDACTION_RULES if rules is None else rules
+    redacted = text
+    for rule in selected_rules:
+        normalized = _as_rule(rule)
+        redacted = normalized.compiled().sub(normalized.replacement, redacted)
+    return redacted
+
+
+def redact_trace(
+    trace: _T,
+    *,
+    rules: Sequence[_RuleLike] | None = None,
+    enabled: bool = True,
+) -> _T:
+    """Return ``trace`` with string values redacted recursively.
+
+    Mappings, lists, and tuples are copied so the supplied trace is not
+    mutated.  Other values pass through unchanged.  With ``enabled=False``
+    the original object is returned untouched.
+    """
+    if not enabled:
+        return trace
+
+    def redact_value(value: object) -> object:
+        if isinstance(value, str):
+            return redact_text(value, rules=rules)
+        if isinstance(value, Mapping):
+            return {key: redact_value(item) for key, item in value.items()}
+        if isinstance(value, list):
+            return [redact_value(item) for item in value]
+        if isinstance(value, tuple):
+            return tuple(redact_value(item) for item in value)
+        return value
+
+    return cast(_T, redact_value(trace))

grudge/registry/__init__.py

@@ -0,0 +1 @@
+"""Scar registry package; persistent storage remains a roadmap stub."""

grudge/registry/db.py

@@ -0,0 +1,10 @@
+"""Registry database boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def open_registry() -> NoReturn:
+    """Open the registry when the database stretch stage is implemented."""
+    roadmap("registry.db")

grudge/registry/fingerprint.py

@@ -0,0 +1,10 @@
+"""Scar fingerprint boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def fingerprint() -> NoReturn:
+    """Compute a fingerprint when registry work is implemented."""
+    roadmap("registry.fingerprint")

grudge/registry/flakiness.py

@@ -0,0 +1,10 @@
+"""Flakiness tracking boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def score_flakiness() -> NoReturn:
+    """Score flakiness when registry work is implemented."""
+    roadmap("registry.flakiness")

grudge/registry/retirement.py

@@ -0,0 +1,10 @@
+"""Scar retirement boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def retire() -> NoReturn:
+    """Retire a scar when registry work is implemented."""
+    roadmap("registry.retirement")