grudge-cli 0.1.0__py3-none-any.whl

grudge/schema/predicate.py

@@ -0,0 +1,263 @@
+"""Phase 1 predicate AST contracts for describing agent behaviour.
+
+The models in this module are data contracts only.  They describe call shapes,
+ordering, taint flow, and run outcomes for later deterministic checkers; they
+do not evaluate a trace themselves.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Annotated, Any, Literal, TypeAlias
+
+from pydantic import AliasChoices, ConfigDict, Field, model_validator
+
+from grudge.schema.cassette import _SchemaModel
+
+
+def _arguments_text(arguments: dict[str, Any]) -> str:
+    """Render argument matching data deterministically for descriptions."""
+
+    return json.dumps(
+        arguments,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(", ", ": "),
+    )
+
+
+class CallShape(_SchemaModel):
+    """A tool call shape identified by tool name and matching arguments."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    kind: Literal["call_shape"] = "call_shape"
+    tool: str = Field(min_length=1)
+    args: dict[str, Any] = Field(
+        default_factory=dict,
+        validation_alias=AliasChoices("args", "arguments"),
+    )
+
+    def describe(self) -> str:
+        """Return a plain-English description of this call shape."""
+
+        arguments = _arguments_text(self.args)
+        return f"Call `{self.tool}` with arguments matching {arguments}."
+
+
+class Ordering(_SchemaModel):
+    """A relationship requiring one tool call to precede another."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    kind: Literal["ordering"] = "ordering"
+    before: str = Field(
+        min_length=1,
+        validation_alias=AliasChoices("before", "first"),
+    )
+    after: str = Field(
+        min_length=1,
+        validation_alias=AliasChoices("after", "then"),
+    )
+
+    def describe(self) -> str:
+        """Return a plain-English description of this ordering rule."""
+
+        return f"Call `{self.before}` before calling `{self.after}`."
+
+
+class TaintFlow(_SchemaModel):
+    """A flow relationship from a source tool to a sink tool."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    kind: Literal["taint_flow"] = "taint_flow"
+    source: str = Field(min_length=1)
+    sink: str = Field(min_length=1)
+    source_field: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("source_field", "from_field"),
+    )
+    sink_field: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("sink_field", "to_field"),
+    )
+
+    def describe(self) -> str:
+        """Return a plain-English description of this taint flow."""
+
+        source = self.source
+        sink = self.sink
+        if self.source_field is not None:
+            source = f"{source}.{self.source_field}"
+        if self.sink_field is not None:
+            sink = f"{sink}.{self.sink_field}"
+        return f"Data from `{source}` must not flow to `{sink}`."
+
+
+class FilteredTaintFlow(_SchemaModel):
+    """A taint rule narrowed by filters on its source call's arguments."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+    kind: Literal["filtered_taint_flow"] = "filtered_taint_flow"
+    flow: TaintFlow
+    source_args: dict[str, Any] = Field(default_factory=dict)
+
+    def describe(self) -> str:
+        """Describe the prohibited data flow and any source-call filter."""
+
+        description = self.flow.describe()
+        if self.source_args:
+            conditions = []
+            words = {
+                "$eq": "equals",
+                "$contains": "contains",
+                "$under": "is under",
+                "$not_under": "is not under",
+            }
+            for field, value in sorted(self.source_args.items()):
+                operator = "equals"
+                if isinstance(value, dict) and len(value) == 1:
+                    key = next(iter(value))
+                    if key in words:
+                        operator, value = words[key], value[key]
+                conditions.append(
+                    f"{field} {operator} " + json.dumps(value, ensure_ascii=False)
+                )
+            description += (
+                " The source call must satisfy: " + "; ".join(conditions) + "."
+            )
+        return description
+
+
+class Outcome(_SchemaModel):
+    """The Phase 1 run-outcome data contract used by predicate ASTs.
+
+    This model records the expected terminal outcome value.  It intentionally
+    contains no checker or trace-evaluation behaviour; that belongs to a later
+    predicate implementation stage.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    kind: Literal["outcome"] = "outcome"
+    outcome: Literal["ok", "failed"] = Field(
+        validation_alias=AliasChoices("outcome", "status", "value"),
+    )
+
+    def describe(self) -> str:
+        """Return a plain-English description of the expected outcome."""
+
+        return f"The run must finish with outcome `{self.outcome}`."
+
+
+class PredicateSet(_SchemaModel):
+    """A logical combination of predicate AST nodes."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    kind: Literal["all_of", "any_of", "not"]
+    predicates: list[Predicate] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_arity(self) -> PredicateSet:
+        """Ensure each logical operator has the appropriate number of terms."""
+
+        if self.kind in {"all_of", "any_of"} and not self.predicates:
+            raise ValueError(f"{self.kind} requires at least one predicate")
+        if self.kind == "not" and len(self.predicates) != 1:
+            raise ValueError("not requires exactly one predicate")
+        return self
+
+    @staticmethod
+    def _items(
+        predicates: tuple[Predicate | Sequence[Predicate], ...],
+    ) -> list[Predicate]:
+        """Accept either a sequence or variadic predicate arguments."""
+
+        if (
+            len(predicates) == 1
+            and isinstance(predicates[0], Sequence)
+            and not isinstance(predicates[0], str | bytes)
+        ):
+            return list(predicates[0])
+        return list(predicates)  # type: ignore[arg-type]
+
+    @classmethod
+    def all_of(
+        cls,
+        *predicates: Predicate | Sequence[Predicate],
+    ) -> PredicateSet:
+        """Combine predicates that must all hold."""
+
+        return cls(kind="all_of", predicates=cls._items(predicates))
+
+    @classmethod
+    def any_of(
+        cls,
+        *predicates: Predicate | Sequence[Predicate],
+    ) -> PredicateSet:
+        """Combine predicates where at least one must hold."""
+
+        return cls(kind="any_of", predicates=cls._items(predicates))
+
+    @classmethod
+    def not_(cls, predicate: Predicate) -> PredicateSet:
+        """Negate one predicate.
+
+        ``not`` is a Python keyword, so the public Python spelling is
+        ``PredicateSet.not_`` while the serialized AST kind remains ``not``.
+        """
+
+        return cls(kind="not", predicates=[predicate])
+
+    def describe(self) -> str:
+        """Return a plain-English description of this logical combination."""
+
+        descriptions = [predicate.describe() for predicate in self.predicates]
+        if self.kind == "not":
+            return f"The following must not be true: {descriptions[0]}"
+        joined = " ".join(descriptions)
+        if self.kind == "all_of":
+            return f"All of the following must be true: {joined}"
+        return f"At least one of the following must be true: {joined}"
+
+
+Predicate: TypeAlias = Annotated[
+    CallShape | Ordering | TaintFlow | FilteredTaintFlow | Outcome | PredicateSet,
+    Field(discriminator="kind"),
+]
+
+PredicateSet.model_rebuild()
+
+
+__all__ = [
+    "CallShape",
+    "FilteredTaintFlow",
+    "Ordering",
+    "Outcome",
+    "Predicate",
+    "PredicateSet",
+    "TaintFlow",
+]

grudge/schema/scar.py

@@ -0,0 +1,113 @@
+"""Phase 1 Scar contracts and persistence for admitted regression failures."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any, TypeAlias
+
+from pydantic import ConfigDict, Field
+
+from grudge.errors import SchemaError
+from grudge.schema.cassette import Cassette, _SchemaModel
+from grudge.schema.predicate import Predicate
+
+
+class AdmissionRecord(_SchemaModel):
+    """The admission evidence recorded alongside a Scar."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    admitted: bool
+    reasons: list[str] = Field(default_factory=list)
+    bad_runs: int = Field(default=0, ge=0)
+    good_runs: int = Field(default=0, ge=0)
+    checked_at: datetime | None = None
+
+
+SeedPredicate: TypeAlias = Predicate | str
+
+
+class Scar(_SchemaModel):
+    """A cassette, behavioural predicate, and provenance metadata."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    id: str = Field(min_length=1)
+    cassette: Cassette
+    predicate: Predicate
+    seed_predicate: SeedPredicate
+    source_trace_hash: str = Field(min_length=1)
+    agent_version_failed: str = Field(min_length=1)
+    agent_version_fixed: str = Field(min_length=1)
+    created_at: datetime
+    admission: AdmissionRecord | None = None
+    fingerprint: str = Field(min_length=1)
+
+    @staticmethod
+    def _check_path(path: str | Path) -> Path:
+        """Validate and normalize the required Scar filename convention."""
+
+        target = Path(path)
+        if target.name.endswith(".scar.json") is False:
+            raise SchemaError("Scar files must use the *.scar.json filename suffix")
+        return target
+
+    def write(self, path: str | Path) -> Path:
+        """Write this Scar as canonical, human-readable JSON."""
+
+        target = self._check_path(path)
+        try:
+            target.write_text(
+                self.model_dump_json(indent=2) + "\n",
+                encoding="utf-8",
+            )
+        except OSError as exc:
+            raise SchemaError(f"could not write Scar file {target}: {exc}") from exc
+        return target
+
+    def save(self, path: str | Path) -> Path:
+        """Alias for :meth:`write` used by callers that prefer persistence verbs."""
+
+        return self.write(path)
+
+    def to_file(self, path: str | Path) -> Path:
+        """Alias for :meth:`write`."""
+
+        return self.write(path)
+
+    @classmethod
+    def read(cls, path: str | Path) -> Scar:
+        """Read and validate a ``*.scar.json`` file."""
+
+        target = cls._check_path(path)
+        try:
+            payload = target.read_text(encoding="utf-8")
+            data: Any = json.loads(payload)
+        except (OSError, json.JSONDecodeError, UnicodeError) as exc:
+            raise SchemaError(f"could not read Scar file {target}: {exc}") from exc
+        return cls.model_validate(data)
+
+    @classmethod
+    def load(cls, path: str | Path) -> Scar:
+        """Alias for :meth:`read`."""
+
+        return cls.read(path)
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> Scar:
+        """Alias for :meth:`read` for explicit file-oriented call sites."""
+
+        return cls.read(path)
+
+
+__all__ = ["AdmissionRecord", "Scar", "SeedPredicate"]

grudge/schema/trace.py

@@ -0,0 +1,243 @@
+"""Phase 1 trace contracts for the recorder-to-shrinker pipeline.
+
+The module defines the ordered, discriminated step language shared by later
+pipeline stages.  JSONL is deliberately canonical: the first record carries
+trace metadata and each following record is one step in the original order.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from datetime import datetime
+from typing import Annotated, Any, Literal, Self, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from grudge.errors import SchemaError
+
+
+class _SchemaModel(BaseModel):
+    """Base model that exposes schema failures as Grudge errors."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    def __init__(self, **data: Any) -> None:
+        try:
+            super().__init__(**data)
+        except ValidationError as exc:
+            raise SchemaError(str(exc)) from exc
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: Any,
+        *,
+        strict: bool | None = None,
+        extra: Literal["allow", "ignore", "forbid"] | None = None,
+        from_attributes: bool | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        try:
+            return super().model_validate(
+                obj,
+                strict=strict,
+                extra=extra,
+                from_attributes=from_attributes,
+                context=context,
+                by_alias=by_alias,
+                by_name=by_name,
+            )
+        except ValidationError as exc:
+            raise SchemaError(str(exc)) from exc
+
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        extra: Literal["allow", "ignore", "forbid"] | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self:
+        try:
+            return super().model_validate_json(
+                json_data,
+                strict=strict,
+                extra=extra,
+                context=context,
+                by_alias=by_alias,
+                by_name=by_name,
+            )
+        except (ValidationError, ValueError) as exc:
+            raise SchemaError(str(exc)) from exc
+
+
+class _StepBase(_SchemaModel):
+    """Fields shared by every trace step."""
+
+    idx: int = Field(ge=0)
+    ts: datetime
+    run_id: str = Field(min_length=1)
+    parent_idx: int | None = Field(default=None, ge=0)
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class ModelCall(_StepBase):
+    """A model request or response observed during an agent run."""
+
+    kind: Literal["model_call"] = "model_call"
+    model: str | None = None
+    messages: list[dict[str, Any]] | None = None
+    prompt: str | None = None
+    response: Any = None
+
+
+class ToolCall(_StepBase):
+    """A request for an external tool."""
+
+    kind: Literal["tool_call"] = "tool_call"
+    tool: str = Field(min_length=1)
+    args: dict[str, Any]
+    call_id: str = Field(min_length=1)
+
+
+class ToolResult(_StepBase):
+    """The result, or error, returned for a tool call."""
+
+    kind: Literal["tool_result"] = "tool_result"
+    call_id: str = Field(min_length=1)
+    content: Any
+    error: str | None = None
+
+
+class StateDiff(_StepBase):
+    """A structured change to the agent or world state."""
+
+    kind: Literal["state_diff"] = "state_diff"
+    diff: dict[str, Any] = Field(default_factory=dict)
+
+
+class FinalAnswer(_StepBase):
+    """The agent's terminal natural-language answer."""
+
+    kind: Literal["final_answer"] = "final_answer"
+    answer: str | None = None
+
+
+Step: TypeAlias = Annotated[
+    ModelCall | ToolCall | ToolResult | StateDiff | FinalAnswer,
+    Field(discriminator="kind"),
+]
+
+
+class Trace(_SchemaModel):
+    """An ordered run of an agent, suitable for stable JSONL persistence."""
+
+    run_id: str = Field(min_length=1)
+    agent_version: str = Field(min_length=1)
+    task: str
+    steps: list[Step] = Field(default_factory=list)
+    outcome: Literal["ok", "failed"]
+
+    @model_validator(mode="after")
+    def _validate_step_identity(self) -> Self:
+        indexes = [step.idx for step in self.steps]
+        if len(indexes) != len(set(indexes)):
+            raise ValueError("steps must have unique idx values")
+        mismatched = [step.idx for step in self.steps if step.run_id != self.run_id]
+        if mismatched:
+            raise ValueError(
+                f"step run_id must match trace run_id (idx values: {mismatched})"
+            )
+        return self
+
+    def tool_calls(self) -> list[ToolCall]:
+        """Return tool calls in their original trace order."""
+
+        return [step for step in self.steps if isinstance(step, ToolCall)]
+
+    def results_for(self, call_id: str) -> list[ToolResult]:
+        """Return all results for ``call_id`` in their original trace order."""
+
+        return [
+            step
+            for step in self.steps
+            if isinstance(step, ToolResult) and step.call_id == call_id
+        ]
+
+    def slice(self, idxs: Iterable[int]) -> Trace:
+        """Return a trace containing selected steps, preserving list order."""
+
+        selected = set(idxs)
+        return self.model_copy(
+            update={"steps": [step for step in self.steps if step.idx in selected]}
+        )
+
+    def to_jsonl(self) -> str:
+        """Serialize this trace to canonical metadata-plus-steps JSONL."""
+
+        records: list[dict[str, Any]] = [
+            {
+                "type": "trace",
+                "run_id": self.run_id,
+                "agent_version": self.agent_version,
+                "task": self.task,
+                "outcome": self.outcome,
+            }
+        ]
+        records.extend(step.model_dump(mode="json") for step in self.steps)
+        return (
+            "\n".join(
+                json.dumps(
+                    record,
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                )
+                for record in records
+            )
+            + "\n"
+        )
+
+    @classmethod
+    def from_jsonl(cls, payload: str) -> Trace:
+        """Parse canonical JSONL and translate malformed input to ``SchemaError``."""
+
+        try:
+            if not isinstance(payload, str):
+                raise SchemaError("trace JSONL must be text")
+            lines = [line for line in payload.split("\n") if line.strip()]
+            if not lines:
+                raise SchemaError("trace JSONL is empty")
+            header = json.loads(lines[0])
+            if not isinstance(header, dict) or header.get("type") != "trace":
+                raise SchemaError("trace JSONL must begin with a trace header")
+            step_payloads = [json.loads(line) for line in lines[1:]]
+            if not all(isinstance(step, dict) for step in step_payloads):
+                raise SchemaError("each trace JSONL step must be an object")
+            header.pop("type", None)
+            return cls.model_validate({**header, "steps": step_payloads})
+        except SchemaError:
+            raise
+        except (json.JSONDecodeError, TypeError, ValueError) as exc:
+            raise SchemaError(f"invalid trace JSONL: {exc}") from exc
+
+
+__all__ = [
+    "FinalAnswer",
+    "ModelCall",
+    "StateDiff",
+    "Step",
+    "ToolCall",
+    "ToolResult",
+    "Trace",
+]

grudge/shrinker/__init__.py

@@ -0,0 +1,12 @@
+"""Phase 5 cassette shrinker: oracle evaluation and two-level minimization."""
+
+from grudge.shrinker.cassette_builder import ShrinkResult, build_minimal_cassette
+from grudge.shrinker.oracle import Oracle, OracleResult, PredicateOracle
+
+__all__ = [
+    "Oracle",
+    "OracleResult",
+    "PredicateOracle",
+    "ShrinkResult",
+    "build_minimal_cassette",
+]