grudge-cli 0.1.0__py3-none-any.whl

grudge/guard/import_session.py

@@ -0,0 +1,106 @@
+# OWNER: lane-b
+"""Import redacted Phase 16 hook JSONL into the Python Trace contract.
+
+The Node recorder stores one compact event per tool invocation.  The engine's
+trace language models the request and response separately, so each valid log
+line becomes an adjacent ``ToolCall``/``ToolResult`` pair while preserving the
+original event order.  Corrupt or non-object lines are ignored deliberately:
+session capture is diagnostic and must not make later analysis unavailable.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal, cast
+from uuid import uuid4
+
+from grudge.schema import Step, ToolCall, ToolResult, Trace
+
+
+def _timestamp(value: Any) -> datetime:
+    if isinstance(value, str):
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+        except ValueError:
+            pass
+    return datetime.fromtimestamp(0, tz=UTC)
+
+
+def import_session(
+    source: str | Path,
+    *,
+    run_id: str | None = None,
+    agent_version: str = "grudge-hook",
+    task: str = "Imported Grudge session",
+    outcome: str = "ok",
+) -> Trace:
+    """Load a session JSONL file into a validated :class:`~grudge.schema.Trace`."""
+
+    session_id = run_id or Path(source).stem or str(uuid4())
+    steps: list[Step] = []
+    with Path(source).open(encoding="utf-8") as handle:
+        for event_index, line in enumerate(handle):
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(event, dict):
+                continue
+            tool = event.get("tool")
+            if not isinstance(tool, str) or not tool:
+                continue
+            args = event.get("args", {})
+            if not isinstance(args, dict):
+                args = {}
+            call_id = f"{session_id}:{event_index}"
+            timestamp = _timestamp(event.get("timestamp"))
+            steps.append(
+                ToolCall(
+                    idx=len(steps),
+                    tool=tool,
+                    args=args,
+                    call_id=call_id,
+                    ts=timestamp,
+                    run_id=session_id,
+                    meta={"session_event": event_index},
+                )
+            )
+            result = event.get("result", "")
+            if (
+                not isinstance(result, str | int | float | bool | list | dict)
+                and result is not None
+            ):
+                result = str(result)
+            steps.append(
+                ToolResult(
+                    idx=len(steps),
+                    call_id=call_id,
+                    content=result,
+                    error=(
+                        event.get("error")
+                        if isinstance(event.get("error"), str)
+                        else None
+                    ),
+                    ts=timestamp,
+                    run_id=session_id,
+                    meta={"session_event": event_index},
+                )
+            )
+    normalized_outcome = cast(
+        Literal["ok", "failed"], outcome if outcome in {"ok", "failed"} else "ok"
+    )
+    return Trace(
+        run_id=session_id,
+        agent_version=agent_version,
+        task=task,
+        steps=steps,
+        outcome=normalized_outcome,
+    )
+
+
+__all__ = ["import_session"]

grudge/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integration package for pytest and GitHub; both integrations are stubs."""

grudge/integrations/github_comment.py

@@ -0,0 +1,10 @@
+"""GitHub comment boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def publish_github_comment() -> NoReturn:
+    """Publish a regression comment when the integration is implemented."""
+    roadmap("integrations.github_comment")

grudge/integrations/pytest_plugin.py

@@ -0,0 +1,10 @@
+"""Pytest integration boundary; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def install_pytest_plugin() -> NoReturn:
+    """Install pytest scar collection when the integration is implemented."""
+    roadmap("integrations.pytest_plugin")

grudge/llm/__init__.py

@@ -0,0 +1,6 @@
+"""Offline-first, provider-neutral completion and disk-cache boundary."""
+
+from grudge.llm.cache import Completion, DiskCache, cached_completion
+from grudge.llm.client import Provider, complete
+
+__all__ = ["Completion", "DiskCache", "Provider", "cached_completion", "complete"]

grudge/llm/cache.py

@@ -0,0 +1,92 @@
+"""Deterministic, prompt-addressed completion storage."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from grudge import config
+
+
+@dataclass(frozen=True)
+class Completion:
+    """Text returned by the completion boundary and its provenance."""
+
+    text: str
+    source: Literal["llm", "cache", "fallback"]
+
+    @property
+    def cache_hit(self) -> bool:
+        return self.source == "cache"
+
+    @property
+    def fallback_used(self) -> bool:
+        return self.source == "fallback"
+
+
+class DiskCache:
+    """Store UTF-8 completion text under the SHA-256 of the exact prompt."""
+
+    def __init__(self, directory: Path | str | None = None) -> None:
+        self.directory = Path(directory) if directory is not None else config.CACHE_DIR
+
+    def _path(self, prompt: str) -> Path:
+        digest = hashlib.sha256(prompt.encode("utf-8")).hexdigest()
+        return self.directory / f"{digest}.json"
+
+    def get(self, prompt: str) -> str | None:
+        try:
+            payload = json.loads(self._path(prompt).read_text(encoding="utf-8"))
+        except (FileNotFoundError, UnicodeDecodeError, json.JSONDecodeError):
+            return None
+        if isinstance(payload, dict) and isinstance(payload.get("text"), str):
+            return str(payload["text"])
+        return None
+
+    def put(self, prompt: str, text: str) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({"text": text}, ensure_ascii=False, sort_keys=True) + "\n"
+        # A complete entry becomes visible atomically, including to parallel readers.
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", newline="\n", dir=self.directory, delete=False
+        ) as stream:
+            temporary = Path(stream.name)
+            stream.write(payload)
+        try:
+            os.replace(temporary, self._path(prompt))
+        finally:
+            temporary.unlink(missing_ok=True)
+
+
+def cached_completion(
+    prompt: str,
+    request: Callable[[str], str | Completion] | None = None,
+    *,
+    cache_dir: Path | str | None = None,
+    fallback: str,
+) -> Completion:
+    """Read first; invoke ``request`` only on a miss, or return local fallback.
+
+    Fallback text is never cached as model output, so a later online invocation
+    can still synthesize a rule for the same evidence.
+    """
+
+    cache = DiskCache(cache_dir)
+    text = cache.get(prompt)
+    if text is not None:
+        return Completion(text, "cache")
+    if request is None:
+        return Completion(fallback, "fallback")
+    response = request(prompt)
+    completion = (
+        response if isinstance(response, Completion) else Completion(response, "llm")
+    )
+    if not completion.fallback_used:
+        cache.put(prompt, completion.text)
+    return completion

grudge/llm/client.py

@@ -0,0 +1,82 @@
+"""Offline-first boundary for any OpenAI-compatible completion provider."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Protocol
+
+import httpx
+
+from grudge import config
+from grudge.llm.cache import Completion, cached_completion
+
+DEMO_DSL = "never call send_http where body tainted_by read_file()"
+
+
+class Provider(Protocol):
+    """An injectable adapter, independent of any provider SDK."""
+
+    def __call__(self, prompt: str, *, api_key: str, model: str) -> str: ...
+
+
+def is_offline(offline: bool | None = None) -> bool:
+    """Resolve explicit mode, then the environment, then offline-safe defaults."""
+
+    if offline is not None:
+        return offline
+    value = os.getenv("GRUDGE_OFFLINE")
+    if value is None:
+        return config.OFFLINE
+    return value.strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _http_completion(prompt: str, *, api_key: str, model: str) -> str:
+    url = os.getenv("GRUDGE_LLM_URL")
+    if not url:
+        raise ValueError("online completion requires GRUDGE_LLM_URL")
+    response = httpx.post(
+        url,
+        headers={"Authorization": f"Bearer {api_key}"},
+        json={
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+        },
+        timeout=30.0,
+    )
+    response.raise_for_status()
+    text = response.json()["choices"][0]["message"]["content"]
+    if not isinstance(text, str):
+        raise ValueError("completion provider returned non-text content")
+    return text
+
+
+def complete(
+    prompt: str,
+    *,
+    offline: bool | None = None,
+    cache_dir: Path | str | None = None,
+    provider: Provider | None = None,
+    fallback: str = DEMO_DSL,
+) -> Completion:
+    """Return cached, generated, or fallback text without eager credential reads.
+
+    ``GRUDGE_LLM_API_KEY`` and ``GRUDGE_MODEL`` are consulted only for an online
+    cache miss. The HTTP adapter accepts the full chat-completions endpoint in
+    ``GRUDGE_LLM_URL``; callers may instead inject another provider adapter.
+    """
+
+    def request(text: str) -> str:
+        api_key = os.getenv("GRUDGE_LLM_API_KEY")
+        if not api_key:
+            raise ValueError("online completion requires GRUDGE_LLM_API_KEY")
+        model = os.getenv("GRUDGE_MODEL", config.DEFAULT_MODEL)
+        return (provider or _http_completion)(text, api_key=api_key, model=model)
+
+    return cached_completion(
+        prompt,
+        None if is_offline(offline) else request,
+        cache_dir=cache_dir,
+        fallback=fallback,
+    )

grudge/locator/__init__.py

@@ -0,0 +1 @@
+"""Fault-locator stage; both locator algorithms are roadmap stubs."""

grudge/locator/fork.py

@@ -0,0 +1,10 @@
+"""Fork a run at a decision point; this Phase 13 stretch item is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def fork_run() -> NoReturn:
+    """Fork an agent run once the locator stretch stage is implemented."""
+    roadmap("locator.fork")

grudge/locator/point_of_no_return.py

@@ -0,0 +1,10 @@
+"""Locate the earliest irreversible failure point; this is a stub."""
+
+from typing import NoReturn
+
+from grudge._stubs import roadmap
+
+
+def find_point_of_no_return() -> NoReturn:
+    """Find the earliest successful alternative in the future locator stage."""
+    roadmap("locator.point_of_no_return")

grudge/predicates/__init__.py

@@ -0,0 +1,25 @@
+"""Phase 6 deterministic predicate parsing and checking public interface."""
+
+from grudge.predicates.compiler import Checker, PredicateResult, compile_predicate
+from grudge.predicates.dsl import (
+    FilteredTaintFlow,
+    PredicateAST,
+    PredicateGroup,
+    PredicateParseError,
+    parse,
+    parse_predicate,
+    pretty_print,
+)
+
+__all__ = [
+    "Checker",
+    "FilteredTaintFlow",
+    "PredicateAST",
+    "PredicateGroup",
+    "PredicateParseError",
+    "PredicateResult",
+    "compile_predicate",
+    "parse",
+    "parse_predicate",
+    "pretty_print",
+]

grudge/predicates/call_shape.py

@@ -0,0 +1,116 @@
+"""Phase 6 call matching: exact JSON subsets and explicit text/path operators.
+
+Paths are compared lexically (including .. and separator normalization), without
+filesystem access or symlink resolution. Missing arguments never match a filter.
+"""
+
+from __future__ import annotations
+
+import math
+import posixpath
+from dataclasses import dataclass
+from typing import Any
+
+from grudge.predicates.compiler import PredicateResult
+from grudge.schema.predicate import CallShape
+from grudge.schema.trace import ToolCall, Trace
+
+_OPERATORS = {"$eq", "$contains", "$under", "$not_under"}
+
+
+def _json_value(value: Any) -> bool:
+    if value is None or isinstance(value, str | bool | int):
+        return True
+    if isinstance(value, float):
+        return math.isfinite(value)
+    if isinstance(value, list):
+        return all(_json_value(item) for item in value)
+    if isinstance(value, dict):
+        return all(isinstance(k, str) and _json_value(v) for k, v in value.items())
+    return False
+
+
+def validate_arguments(arguments: dict[str, Any]) -> None:
+    """Reject non-JSON values and malformed explicit operator expressions."""
+    if not isinstance(arguments, dict):
+        raise TypeError("call arguments must be a dictionary")
+    for field, value in arguments.items():
+        if not isinstance(field, str) or not field:
+            raise TypeError("argument names must be nonempty strings")
+        if not _json_value(value):
+            raise TypeError(f"argument {field!r} must contain finite JSON values")
+        if isinstance(value, dict) and any(key.startswith("$") for key in value):
+            if len(value) != 1 or next(iter(value)) not in _OPERATORS:
+                raise TypeError(f"argument {field!r} has an unknown/ambiguous operator")
+            operator = next(iter(value))
+            if operator != "$eq" and not isinstance(value[operator], str):
+                raise TypeError(f"operator {operator} requires a string")
+            if operator in {"$under", "$not_under"} and not value[operator]:
+                raise TypeError("path root must not be empty")
+
+
+def _equal(left: Any, right: Any) -> bool:
+    if isinstance(left, bool) != isinstance(right, bool):
+        return False
+    if isinstance(left, dict) and isinstance(right, dict):
+        return left.keys() == right.keys() and all(
+            _equal(left[k], right[k]) for k in left
+        )
+    if isinstance(left, list) and isinstance(right, list):
+        return len(left) == len(right) and all(
+            _equal(a, b) for a, b in zip(left, right, strict=True)
+        )
+    return bool(left == right)
+
+
+def _under(path: str, root: str) -> bool:
+    path = posixpath.normpath(path.replace("\\", "/"))
+    root = posixpath.normpath(root.replace("\\", "/"))
+    if root == ".":
+        return not (
+            path.startswith(("/", "../")) or path == ".." or ":" in path.split("/")[0]
+        )
+    return path == root or path.startswith(root.rstrip("/") + "/")
+
+
+def _matches(value: Any, expected: Any) -> bool:
+    if isinstance(expected, dict) and len(expected) == 1:
+        operator = next(iter(expected))
+        operand = expected[operator]
+        if operator == "$eq":
+            return _equal(value, operand)
+        if operator in {"$contains", "$under", "$not_under"}:
+            if not isinstance(value, str):
+                return False
+            if operator == "$contains":
+                return operand in value
+            inside = _under(value, operand)
+            return not inside if operator == "$not_under" else inside
+    return _equal(value, expected)
+
+
+def matches_call(call: ToolCall, predicate: CallShape) -> bool:
+    """Match tool name and supplied arguments; unspecified arguments are allowed."""
+    return call.tool == predicate.tool and all(
+        field in call.args and _matches(call.args[field], expected)
+        for field, expected in predicate.args.items()
+    )
+
+
+@dataclass(frozen=True)
+class CallShapeChecker:
+    predicate: CallShape
+
+    def check(self, trace: Trace) -> PredicateResult:
+        matches = [
+            call for call in trace.tool_calls() if matches_call(call, self.predicate)
+        ]
+        return PredicateResult(
+            violated=not matches,
+            evidence=list(matches),
+            explanation=(
+                f"Found {len(matches)} matching call(s) to {self.predicate.tool}."
+                if matches
+                else f"Required call to {self.predicate.tool} was not found."
+            ),
+        )

grudge/predicates/compiler.py

@@ -0,0 +1,116 @@
+"""Phase 6 deterministic AST-to-checker boundary; no LLM or I/O is involved.
+
+CallShape requires a matching call, Ordering requires a prior call at each
+target, and TaintFlow prohibits a flow. Logical groups combine rule satisfaction
+(not violation flags). Evidence always references the original trace objects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from grudge.predicates.dsl import FilteredTaintFlow, PredicateAST, PredicateGroup
+from grudge.schema.predicate import (
+    CallShape,
+    Ordering,
+    Outcome,
+    PredicateSet,
+    TaintFlow,
+)
+from grudge.schema.trace import Step, Trace
+
+
+class PredicateResult(BaseModel):
+    """A rule verdict with exact supporting steps, never synthesized evidence."""
+
+    model_config = ConfigDict(extra="forbid")
+    violated: bool
+    evidence: list[Step] = Field(default_factory=list)
+    explanation: str
+
+
+class Checker(Protocol):
+    """A compiled rule that deterministically evaluates a trace."""
+
+    def check(self, trace: Trace) -> PredicateResult: ...
+
+
+@dataclass(frozen=True)
+class _GroupChecker:
+    kind: str
+    children: tuple[Checker, ...]
+
+    def check(self, trace: Trace) -> PredicateResult:
+        results = [child.check(trace) for child in self.children]
+        if self.kind == "not":
+            violated = not results[0].violated
+            selected = results
+        elif self.kind == "all_of":
+            violated = any(result.violated for result in results)
+            selected = [r for r in results if r.violated == violated]
+        else:
+            violated = all(result.violated for result in results)
+            selected = [r for r in results if r.violated == violated]
+        indexes = {step.idx for result in selected for step in result.evidence}
+        return PredicateResult(
+            violated=violated,
+            evidence=[step for step in trace.steps if step.idx in indexes],
+            explanation=f"{self.kind}: " + " ".join(r.explanation for r in selected),
+        )
+
+
+def compile_predicate(predicate: PredicateAST) -> Checker:
+    """Type-check and snapshot an AST; unsupported/ill-typed input is rejected.
+
+    Outcome remains a roadmap stub and is rejected at compilation, rather than
+    pretending to have checked a run. Use parse_predicate explicitly for text.
+    """
+    from grudge.predicates.call_shape import CallShapeChecker, validate_arguments
+    from grudge.predicates.ordering import OrderingChecker
+    from grudge.predicates.outcome import check_outcome
+    from grudge.predicates.taint_flow import TaintFlowChecker
+
+    if isinstance(predicate, CallShape):
+        if not isinstance(predicate.tool, str) or not predicate.tool:
+            raise TypeError("call tool must be a nonempty string")
+        validate_arguments(predicate.args)
+        return CallShapeChecker(predicate.model_copy(deep=True))
+    if isinstance(predicate, Ordering):
+        if not all(
+            isinstance(v, str) and v for v in (predicate.before, predicate.after)
+        ):
+            raise TypeError("ordering tools must be nonempty strings")
+        return OrderingChecker(predicate.model_copy(deep=True))
+    if isinstance(predicate, FilteredTaintFlow):
+        validate_arguments(predicate.source_args)
+        flow = predicate.flow
+        source_args = predicate.source_args
+    elif isinstance(predicate, TaintFlow):
+        flow = predicate
+        source_args = {}
+    elif isinstance(predicate, Outcome):
+        check_outcome()
+    elif isinstance(predicate, PredicateSet | PredicateGroup):
+        if predicate.kind not in {"all_of", "any_of", "not"}:
+            raise TypeError("unknown predicate group operator")
+        if not predicate.predicates or (
+            predicate.kind == "not" and len(predicate.predicates) != 1
+        ):
+            raise TypeError("groups require children; not requires exactly one")
+        return _GroupChecker(
+            predicate.kind, tuple(compile_predicate(p) for p in predicate.predicates)
+        )
+    else:
+        raise TypeError(f"unsupported predicate type: {type(predicate).__name__}")
+    if not all(isinstance(v, str) and v for v in (flow.source, flow.sink)):
+        raise TypeError("taint tools must be nonempty strings")
+    if any(
+        v is not None and (not isinstance(v, str) or not v)
+        for v in (flow.source_field, flow.sink_field)
+    ):
+        raise TypeError("taint fields must be nonempty strings or None")
+    source = CallShape(tool=flow.source, args=source_args)
+    return TaintFlowChecker(flow.model_copy(deep=True), source.model_copy(deep=True))