agentguard-eval 0.3.0__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1,3 @@
+"""agentguard: guardrails and evals for AI agents."""
+
+__version__ = "0.3.0"

agentguard/cli.py

@@ -0,0 +1,101 @@
+"""The ``agentguard`` command line.
+
+- ``agentguard check <log.json>``: check an agent transcript (agentguard, OpenAI or Anthropic format) for invented values. Exit code 1
+  when it's flagged, so it can gate a CI job over saved runs. ``--ids-only`` keeps only
+  high-confidence invented-ID flags.
+- ``agentguard gate <tool> [--cost C] [--amount A] [--limit L] [--spent S]``: ask the policy
+  gate what it would do with a proposed tool call.
+- ``agentguard bench``: run the shell-command gate benchmark and print the scorecard.
+- ``agentguard verify-ledger <ledger.json>``: recompute every hash in an approval ledger and
+  name the first entry that was edited, cut or reordered. Exit code 1 if it doesn't verify.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from agentguard.gate import Budget, evaluate, load_entries, verify_chain
+from agentguard.provenance import check_transcript, id_flags, to_transcript
+from agentguard.shell import format_report, run_bench
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    with open(args.log, encoding="utf-8") as fh:
+        transcript = to_transcript(json.load(fh))
+    verdict = check_transcript(transcript)
+    flags = id_flags(verdict) if args.ids_only else list(verdict.flags)
+    if not flags:
+        print("honest: no ungrounded values found.")
+        return 0
+    for flag in flags:
+        values = f" [{', '.join(flag.values)}]" if flag.values else ""
+        print(f"{flag.kind}: {flag.message}{values}")
+    return 1
+
+
+def _cmd_gate(args: argparse.Namespace) -> int:
+    call_args: dict[str, object] = {}
+    if args.amount is not None:
+        call_args["amount_cents"] = args.amount
+    decision = evaluate(
+        args.tool,
+        estimated_cost_cents=args.cost,
+        args=call_args,
+        budget=Budget(spent_cents=args.spent, limit_cents=args.limit),
+    )
+    print(f"{decision.verdict.value}  ({decision.decided_by})")
+    for reason in decision.reasons:
+        print(f"  - {reason}")
+    return 0 if decision.verdict.value == "ALLOW" else 1
+
+
+def _cmd_bench(_args: argparse.Namespace) -> int:
+    print(format_report(run_bench()))
+    return 0
+
+
+def _cmd_verify_ledger(args: argparse.Namespace) -> int:
+    with open(args.ledger, encoding="utf-8") as fh:
+        try:
+            chain = load_entries(json.load(fh))
+        except ValueError as exc:
+            print(f"not a ledger: {exc}")
+            return 2
+    result = verify_chain(chain)
+    print(("valid: " if result.valid else "BROKEN: ") + result.message)
+    return 0 if result.valid else 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="agentguard", description="Guardrails and evals for AI agents.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="check an agent transcript (JSON) for invented values")
+    p_check.add_argument("log", help="path to a transcript JSON file")
+    p_check.add_argument("--ids-only", action="store_true", help="keep only high-confidence invented-ID flags")
+    p_check.set_defaults(func=_cmd_check)
+
+    p_gate = sub.add_parser("gate", help="ask the policy gate about a proposed tool call")
+    p_gate.add_argument("tool")
+    p_gate.add_argument("--cost", type=int, default=0, help="the agent's estimated cost, in cents")
+    p_gate.add_argument("--amount", type=int, default=None, help="amount_cents the call would move")
+    p_gate.add_argument("--limit", type=int, default=50_000, help="budget cap, in cents")
+    p_gate.add_argument("--spent", type=int, default=0, help="cents already spent")
+    p_gate.set_defaults(func=_cmd_gate)
+
+    p_bench = sub.add_parser("bench", help="run the shell-command gate benchmark")
+    p_bench.set_defaults(func=_cmd_bench)
+
+    p_ledger = sub.add_parser("verify-ledger", help="check an approval ledger for tampering")
+    p_ledger.add_argument("ledger", help="path to a ledger JSON file (a list, or an object with 'chain')")
+    p_ledger.set_defaults(func=_cmd_verify_ledger)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentguard/gate/__init__.py

@@ -0,0 +1,50 @@
+"""The policy gate: decide whether an agent's tool call may run, then run the approval workflow."""
+
+from __future__ import annotations
+
+from agentguard.gate.governor import (
+    APPROVAL_TTL_SECONDS,
+    ApprovalAuthError,
+    GatedAction,
+    Governor,
+    SelfApprovalError,
+    State,
+    mint_approval_token,
+    verify_approval_token,
+)
+from agentguard.gate.ledger import ChainVerification, Entry, load_entries, verify_chain
+from agentguard.gate.policy import (
+    POLICY,
+    UNATTENDED_WINDOW_SECONDS,
+    UNATTENDED_WRITE_LIMIT,
+    Budget,
+    Decision,
+    History,
+    Verdict,
+    evaluate,
+    money,
+)
+
+__all__ = [
+    "APPROVAL_TTL_SECONDS",
+    "POLICY",
+    "UNATTENDED_WINDOW_SECONDS",
+    "UNATTENDED_WRITE_LIMIT",
+    "ApprovalAuthError",
+    "Budget",
+    "ChainVerification",
+    "Decision",
+    "Entry",
+    "GatedAction",
+    "Governor",
+    "History",
+    "SelfApprovalError",
+    "State",
+    "Verdict",
+    "evaluate",
+    "load_entries",
+    "mint_approval_token",
+    "money",
+    "verify_approval_token",
+    "verify_chain",
+]

agentguard/gate/governor.py

@@ -0,0 +1,256 @@
+"""The approval workflow around the policy gate.
+
+``evaluate`` says what *should* happen to one call. A ``Governor`` makes it happen over time:
+it holds the actions waiting for a person, checks who is approving, charges the budget only
+when something actually runs, and writes every step to a tamper-evident ledger.
+
+The rules carried over from ``agent-governance``, each one a bug that project fixed:
+
+- The agent that proposed an action can't approve it.
+- An approval needs a token only the named reviewer's key can make, bound to that action.
+- An approval only counts for 24 hours after the request (configurable).
+- The budget is checked again at the moment an approved action would run, because other
+  actions may have spent while it waited.
+- A loop of unattended writes from one agent gets slowed down to "ask a person".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from agentguard.gate.ledger import ChainVerification, Entry, append_entry, verify_chain
+from agentguard.gate.policy import UNATTENDED_WINDOW_SECONDS, Budget, Decision, History, Verdict, evaluate, money
+
+__all__ = [
+    "APPROVAL_TTL_SECONDS",
+    "ApprovalAuthError",
+    "GatedAction",
+    "Governor",
+    "SelfApprovalError",
+    "State",
+    "mint_approval_token",
+    "verify_approval_token",
+]
+
+APPROVAL_TTL_SECONDS = 24 * 60 * 60
+
+
+class State(str, Enum):
+    PENDING_APPROVAL = "PENDING_APPROVAL"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    AUTO_ALLOWED = "AUTO_ALLOWED"
+    BLOCKED = "BLOCKED"
+    EXECUTED = "EXECUTED"
+
+
+class SelfApprovalError(Exception):
+    """The agent that proposed an action tried to approve it."""
+
+
+class ApprovalAuthError(Exception):
+    """An approval arrived without a valid token for the named reviewer."""
+
+
+def _norm(name: str) -> str:
+    return name.strip().lower()
+
+
+def mint_approval_token(key: str, proposal_id: str, reviewer: str) -> str:
+    """HMAC that binds one reviewer to one proposal. Same bytes as the TypeScript version."""
+    message = f"{proposal_id}:{_norm(reviewer)}".encode()
+    return hmac.new(key.encode(), message, hashlib.sha256).hexdigest()
+
+
+def verify_approval_token(keys: Mapping[str, str], proposal_id: str, reviewer: str, token: str | None) -> bool:
+    if token is None:
+        return False
+    key = {_norm(k): v for k, v in keys.items()}.get(_norm(reviewer))
+    if key is None:
+        return False
+    return hmac.compare_digest(mint_approval_token(key, proposal_id, reviewer), token)
+
+
+@dataclass
+class GatedAction:
+    id: str
+    agent: str
+    tool: str
+    args: dict[str, Any]
+    estimated_cost_cents: int
+    created_at: float
+    decision: Decision
+    state: State
+    reviewed_by: str | None = None
+    review_note: str | None = None
+
+
+def _iso(ts: float) -> str:
+    # Millisecond ISO-8601 in UTC with a Z, matching JavaScript's Date.toISOString().
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.") + f"{int(ts * 1000) % 1000:03d}Z"
+
+
+@dataclass
+class Governor:
+    """Run agent tool calls through the gate, a human approval step, and a ledger.
+
+    ``reviewer_keys`` maps each person allowed to approve to their secret. ``clock`` returns
+    seconds since the epoch; tests pass a fake one.
+    """
+
+    budget_limit_cents: int = 50_000
+    reviewer_keys: Mapping[str, str] = field(default_factory=dict)
+    approval_ttl_seconds: float = APPROVAL_TTL_SECONDS
+    clock: Callable[[], float] = time.time
+    spent_cents: int = 0
+    _actions: list[GatedAction] = field(default_factory=list, repr=False)
+    _ledger: list[Entry] = field(default_factory=list, repr=False)
+
+    # -- reading state ---------------------------------------------------------------------
+    @property
+    def budget(self) -> Budget:
+        return Budget(spent_cents=self.spent_cents, limit_cents=self.budget_limit_cents)
+
+    def actions(self) -> list[GatedAction]:
+        return list(self._actions)
+
+    def pending(self) -> list[GatedAction]:
+        return [a for a in self._actions if a.state is State.PENDING_APPROVAL]
+
+    def get(self, action_id: str) -> GatedAction | None:
+        return next((a for a in self._actions if a.id == action_id), None)
+
+    def ledger(self) -> list[Entry]:
+        return list(self._ledger)
+
+    def verify(self) -> ChainVerification:
+        return verify_chain(self._ledger)
+
+    def mint_token(self, action_id: str, reviewer: str) -> str:
+        """A token for a reviewer whose key this governor holds (what your UI would call)."""
+        key = {_norm(k): v for k, v in self.reviewer_keys.items()}.get(_norm(reviewer))
+        if key is None:
+            raise ApprovalAuthError(f"{reviewer!r} is not a registered reviewer.")
+        return mint_approval_token(key, action_id, reviewer)
+
+    # -- the workflow ----------------------------------------------------------------------
+    def propose(
+        self, agent: str, tool: str, args: dict[str, Any] | None = None, *, estimated_cost_cents: int = 0
+    ) -> GatedAction:
+        now = self.clock()
+        action_id = f"act_{len(self._actions) + 1:04d}"
+        args = dict(args or {})
+        self._record("PROPOSED", agent, action_id, {"tool": tool, "estimated": _money_or_raw(estimated_cost_cents)})
+        decision = evaluate(
+            tool,
+            estimated_cost_cents=estimated_cost_cents,
+            args=args,
+            budget=self.budget,
+            history=History(recent_unattended_writes=self._recent_unattended_writes(agent, now)),
+        )
+        self._record(
+            "POLICY_EVALUATED",
+            "policy-engine",
+            action_id,
+            {"verdict": decision.verdict.value, "tier": decision.tier, "decidedBy": decision.decided_by},
+        )
+        action = GatedAction(action_id, agent, tool, args, estimated_cost_cents, now, decision, State.PENDING_APPROVAL)
+        if decision.verdict is Verdict.DENY:
+            action.state = State.BLOCKED
+            self._record("BLOCKED", "policy-engine", action_id, {"why": decision.reason})
+        elif decision.verdict is Verdict.ALLOW:
+            action.state = State.AUTO_ALLOWED
+            self._execute(action)
+        self._actions.append(action)
+        return action
+
+    def decide(
+        self, action_id: str, approve: bool, reviewer: str, *, note: str | None = None, token: str | None = None
+    ) -> GatedAction | None:
+        """Approve or reject a pending action. Returns None if there's no such pending action."""
+        action = self.get(action_id)
+        if action is None or action.state is not State.PENDING_APPROVAL:
+            return None
+        # Separation of duties, checked before anything is written. Withdrawing your own is fine.
+        if approve and _norm(reviewer) == _norm(action.agent):
+            raise SelfApprovalError(f"{action.agent!r} proposed this action, so it can't also approve it.")
+        if approve and not verify_approval_token(self.reviewer_keys, action_id, reviewer, token):
+            raise ApprovalAuthError(f"{reviewer!r} did not present a valid approval token.")
+
+        # Only a yes expires: rejecting a stale request is how the queue gets cleared. Checked
+        # after authentication, so a forged attempt can't change anything.
+        waited = self.clock() - action.created_at
+        if approve and waited > self.approval_ttl_seconds:
+            why = (
+                f"This request expired: it was made {int(waited // 3600)}h ago, and an approval only counts "
+                f"within {_hours(self.approval_ttl_seconds)}h. Ask the agent to propose it again."
+            )
+            action.reviewed_by, action.review_note = reviewer, note
+            self._block(action, why, "approval-expired", extra={"reviewer": reviewer})
+            return action
+
+        action.reviewed_by, action.review_note = reviewer, note
+        if not approve:
+            action.state = State.REJECTED
+            self._record("REJECTED", reviewer, action_id, {"note": note})
+            return action
+
+        action.state = State.APPROVED
+        self._record("APPROVED", reviewer, action_id, {"note": note})
+        # The cap was checked at proposal time, but other actions may have spent since.
+        projected = self.spent_cents + action.decision.cost_cents
+        if projected > self.budget_limit_cents:
+            why = (
+                f"Budget changed while this waited: {money(action.decision.cost_cents)} would bring spend to "
+                f"{money(projected)}, over the {money(self.budget_limit_cents)} cap."
+            )
+            self._block(action, why, "budget-exceeded-at-approval")
+            return action
+        self._execute(action)
+        return action
+
+    # -- internals -------------------------------------------------------------------------
+    def _recent_unattended_writes(self, agent: str, now: float) -> int:
+        return sum(
+            1
+            for a in self._actions
+            if a.agent == agent
+            and a.decision.verdict is Verdict.ALLOW
+            and a.decision.tier == 2
+            and now - a.created_at < UNATTENDED_WINDOW_SECONDS
+        )
+
+    def _execute(self, action: GatedAction) -> None:
+        # Spend is counted only when something runs, and it's the gate's cost, not the estimate.
+        self.spent_cents += action.decision.cost_cents
+        action.state = State.EXECUTED
+        self._record("EXECUTED", "runtime", action.id, {"tool": action.tool, "cost": money(action.decision.cost_cents)})
+
+    def _block(self, action: GatedAction, why: str, decided_by: str, extra: dict[str, Any] | None = None) -> None:
+        action.state = State.BLOCKED
+        action.decision = replace(
+            action.decision, verdict=Verdict.DENY, reasons=(*action.decision.reasons, why), decided_by=decided_by
+        )
+        self._record("BLOCKED", "policy-engine", action.id, {"why": why, **(extra or {})})
+
+    def _record(self, event: str, actor: str, action_id: str, detail: dict[str, Any]) -> None:
+        append_entry(self._ledger, at=_iso(self.clock()), event=event, actor=actor, proposal_id=action_id, detail=detail)
+
+
+def _money_or_raw(cents: object) -> object:
+    # A malformed estimate is logged as given; the gate refuses it a moment later.
+    if isinstance(cents, int) and not isinstance(cents, bool):
+        return money(cents)
+    return repr(cents)
+
+
+def _hours(seconds: float) -> str:
+    hours = seconds / 3600
+    return str(int(hours)) if hours.is_integer() else str(hours)

agentguard/gate/ledger.py

@@ -0,0 +1,143 @@
+"""A tamper-evident audit ledger.
+
+Every entry carries the hash of the entry before it, so the ledger is a chain. Change one
+field in one old entry and its hash stops matching, and every entry after it is orphaned. You
+can append to history, but you can't quietly rewrite it.
+
+Entries serialize with the same field names and the same hashed bytes as the TypeScript
+``agent-governance`` project, so a ledger written by either one verifies in the other.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["GENESIS", "ChainVerification", "Entry", "append_entry", "hash_entry", "load_entries", "verify_chain"]
+
+GENESIS = "GENESIS"
+
+EVENTS = ("PROPOSED", "POLICY_EVALUATED", "APPROVED", "REJECTED", "EXECUTED", "BLOCKED")
+
+
+@dataclass
+class Entry:
+    """One line in the ledger. ``hash`` is SHA-256 over every other field."""
+
+    seq: int
+    at: str
+    event: str
+    actor: str
+    proposal_id: str
+    detail: dict[str, Any] = field(default_factory=dict)
+    prev_hash: str = GENESIS
+    hash: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "seq": self.seq,
+            "at": self.at,
+            "event": self.event,
+            "actor": self.actor,
+            "proposalId": self.proposal_id,
+            "detail": self.detail,
+            "prevHash": self.prev_hash,
+            "hash": self.hash,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> Entry:
+        return cls(
+            seq=data["seq"],
+            at=data["at"],
+            event=data["event"],
+            actor=data["actor"],
+            proposal_id=data["proposalId"],
+            detail=dict(data["detail"]),
+            prev_hash=data["prevHash"],
+            hash=data["hash"],
+        )
+
+
+@dataclass(frozen=True)
+class ChainVerification:
+    valid: bool
+    length: int
+    #: The first sequence number where the chain stops adding up.
+    broken_at: int | None
+    message: str
+
+
+def _canonical(entry: Entry) -> str:
+    # The same bytes JavaScript's JSON.stringify produces for this array. Field order is fixed:
+    # change it and every ledger ever written stops verifying, which is the point.
+    return json.dumps(
+        [entry.seq, entry.at, entry.event, entry.actor, entry.proposal_id, entry.detail, entry.prev_hash],
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    )
+
+
+def hash_entry(entry: Entry) -> str:
+    return hashlib.sha256(_canonical(entry).encode("utf-8")).hexdigest()
+
+
+def append_entry(
+    chain: list[Entry], *, at: str, event: str, actor: str, proposal_id: str, detail: dict[str, Any]
+) -> Entry:
+    """Seal a new entry onto the end of ``chain`` and return it."""
+    if event not in EVENTS:
+        raise ValueError(f"unknown ledger event {event!r}")
+    previous = chain[-1] if chain else None
+    entry = Entry(
+        seq=len(chain) + 1,
+        at=at,
+        event=event,
+        actor=actor,
+        proposal_id=proposal_id,
+        detail=detail,
+        prev_hash=previous.hash if previous else GENESIS,
+    )
+    entry.hash = hash_entry(entry)
+    chain.append(entry)
+    return entry
+
+
+def verify_chain(chain: Iterable[Entry]) -> ChainVerification:
+    """Recompute every hash. Reports the first entry that doesn't add up, not just that one doesn't."""
+    entries = list(chain)
+    expected_prev = GENESIS
+    for entry in entries:
+        if entry.prev_hash != expected_prev:
+            return ChainVerification(
+                False,
+                len(entries),
+                entry.seq,
+                f"Entry #{entry.seq} points at the wrong parent. The chain was cut or reordered here.",
+            )
+        if hash_entry(entry) != entry.hash:
+            return ChainVerification(
+                False,
+                len(entries),
+                entry.seq,
+                f"Entry #{entry.seq} was edited after it was written. Its contents no longer match its hash.",
+            )
+        expected_prev = entry.hash
+    message = "Empty ledger." if not entries else f"All {len(entries)} entries verify against their hashes."
+    return ChainVerification(True, len(entries), None, message)
+
+
+def load_entries(data: Any) -> list[Entry]:
+    """Read a ledger from parsed JSON: a list of entries, or an object with a ``chain`` list."""
+    if isinstance(data, Mapping):
+        data = data.get("chain")
+    if not isinstance(data, list):
+        raise ValueError("a ledger is a JSON list of entries (or an object with a 'chain' list)")
+    try:
+        return [Entry.from_dict(item) for item in data]
+    except (KeyError, TypeError) as exc:
+        raise ValueError(f"ledger entry is missing a field: {exc}") from exc