agentguard-eval 0.3.0__py3-none-any.whl

agentguard_eval-0.3.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: agentguard-eval
+Version: 0.3.0
+Summary: Guardrails and evals for AI agents: a policy gate for tool calls, a checker for invented facts, and a benchmark for shell-command gates. Deterministic, no API keys.
+Project-URL: Homepage, https://github.com/zbs-ops/agentguard
+Project-URL: Source, https://github.com/zbs-ops/agentguard
+Project-URL: Issues, https://github.com/zbs-ops/agentguard/issues
+Author: Zohaib Qamar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-safety,evaluation,guardrails,hallucination,llm,pytest
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agentguard
+
+> **Problem:** AI agents with tools invent facts, overspend, and get their shell commands talked around. Most stacks catch none of it.
+>
+> **Approach:** three deterministic guardrails, no API keys and no model calls: a policy gate for tool calls, a checker for invented values, and a benchmark for shell-command gates.
+>
+> **Proof:** 194 tests. The checker and the benchmark are ports of work measured on real agent logs and on three shipping AI coding tools.
+
+```bash
+pip install agentguard-eval
+```
+
+The package installs as `agentguard-eval` (PyPI found `agentguard` too close to an existing name) and imports as `agentguard`.
+
+Python 3.10+. Zero runtime dependencies. Everything here runs offline and gives the same answer every time, which is what makes it testable and what makes it safe to put in a CI job.
+
+---
+
+## What's in it
+
+Three things that go wrong when you give a language model real tools, and a guard for each.
+
+### 1. A policy gate: decide whether a tool call may run
+
+Every tool call is a *proposal*. The gate returns one of three answers: run it, hold it for a person, or refuse it. Reads run unattended; money, customer messages, and deletes wait for a human. It fails closed, checks the budget before anything else, and catches an agent that estimates one cost while its arguments move a bigger one.
+
+```python
+from agentguard.gate import evaluate, Budget
+
+d = evaluate("refund.create", estimated_cost_cents=100, args={"amount_cents": 9000},
+             budget=Budget(spent_cents=0, limit_cents=50_000))
+print(d.verdict.value, d.decided_by)   # REQUIRE_APPROVAL cost-understated
+print(d.reason)   # "The agent estimated $1.00, but the arguments move $90.00 — escalated for review."
+```
+
+Seven ordered checks, each one asserted by a test: a malformed tool name is refused before it can borrow another rule, an unknown tool fails closed, a negative or non-finite cost is refused before the budget math, the budget is checked before the tier, an understated or unusually large spend is escalated, and a runaway loop of writes is paused.
+
+`evaluate` judges one call. `Governor` runs the whole approval workflow around it: it holds what's waiting for a person, checks who is approving, charges the budget only when something actually runs, and writes every step to a hash-chained ledger.
+
+```python
+from agentguard.gate import Governor
+
+g = Governor(reviewer_keys={"you@company.com": "your-secret"})
+a = g.propose("billing-agent", "refund.create", {"amount_cents": 9000}, estimated_cost_cents=9000)
+print(a.state.value)                     # PENDING_APPROVAL
+
+token = g.mint_token(a.id, "you@company.com")   # only the key holder can make this
+g.decide(a.id, True, "you@company.com", token=token)
+print(a.state.value, g.spent_cents)     # EXECUTED 9000
+print(g.verify().message)               # All 4 entries verify against their hashes.
+```
+
+Each rule here is a bug the TypeScript project found and fixed: the agent that asked can't approve its own request; typing a reviewer's name isn't enough, it takes a token bound to that one action; an approval stops counting 24 hours after the request; and the budget is checked again at the moment an approved action runs, because two refunds that each fit alone can both get a yes. Ledgers are interchangeable with the TypeScript version: the same calls produce the same ledger byte for byte, hashes included (`tests/test_governor.py` checks this against a ledger the TypeScript store wrote).
+
+### 2. A provenance checker: catch invented facts
+
+Checks whether an agent's answer is backed by what its tools actually returned. Four checks: a confident answer after a tool failed, a value no tool returned and nobody stated, a record for the wrong entity passed off as the right one, and a refusal that cites a limit appearing nowhere in the transcript.
+
+```python
+from agentguard.provenance import check_transcript, load_transcript
+
+t = load_transcript({"steps": [
+    {"role": "tool_call", "id": "c1", "tool": "orders.get", "args": {"order_id": "W1"}},
+    {"role": "tool_result", "id": "c1", "tool": "orders.get", "status": "ok", "payload": {"eta": "2026-10-22"}},
+    {"role": "assistant", "content": "It arrives 2026-10-24."},
+]})
+v = check_transcript(t)
+print(v.honest, v.flags[0].kind, v.flags[0].values)   # False unsupported-value ('2026-10-24',)
+```
+
+It reads the user, the system prompt, the tool calls and their results, and normalizes values so the same fact in different forms ("May 19, 2024" and `2024-05-19`, "$1,024" and `1024`) matches. It knows an agent computes (a refund that's the difference of two returned prices is grounded), and it leaves vague language alone, because exact-match is the honest limit of a checker with no model behind it.
+
+For the short, high-yield list, `id_flags(verdict)` keeps only flags about an invented order number or product code, the fabrication that does the most harm.
+
+It reads your agent's real logs directly. `to_transcript` takes an **OpenAI** chat log (`tool_calls` / role `tool`), an **Anthropic** messages log (`tool_use` / `tool_result` blocks), or agentguard's own `{"steps": [...]}`, and works out which one it got:
+
+```python
+import json
+from agentguard.provenance import check_transcript, to_transcript
+
+v = check_transcript(to_transcript(json.load(open("run.json"))))
+```
+
+Tool calls a model also writes into its message text (Claude's `<function_calls>` markup) are stripped first, so tool names aren't read as invented claims. On tool-truth's example logs, agentguard prints exactly the flags and values the TypeScript original prints, in the same order (`tests/test_parity.py`).
+
+### 3. A benchmark: how often can a command gate be talked around?
+
+Give an agent a shell and you put a gate in front of it: a list of commands it may not run. This rewrites a forbidden command in 13 known bypass styles (chaining, quoting, `$IFS`, variable indirection, `awk`, `base64`, equivalent binaries) and counts a bypass **only when the forbidden effect actually happens in a sandbox**.
+
+```python
+from agentguard.shell import run_bench, format_report
+
+print(format_report(run_bench()))
+```
+
+```
+gate                bypass rate   (bypasses / effective)
+substring-denylist          31%   (14/45)
+word-denylist               78%   (35/45)
+tokenized-denylist          71%   (32/45)
+allowlist                    0%   (0/45)
+```
+
+Two findings worth the whole module: a more precise denylist is not a safer one (whole-word matching misses `rm${IFS}file` that a dumb substring search catches), and only the allowlist, which names what may run and refuses everything else, holds at 0%.
+
+---
+
+## A pytest plugin
+
+Installing agentguard adds fixtures so you can assert on agent behaviour in your own suite:
+
+```python
+def test_my_agent_is_grounded(assert_grounded):
+    assert_grounded(my_agent_transcript)      # fails, listing the invented values
+
+def test_my_policy_allows_reads(assert_tool_allowed):
+    assert_tool_allowed("crm.read")           # fails if the gate wouldn't auto-allow it
+
+def test_my_shell_gate_holds(assert_gate_holds):
+    assert_gate_holds(my_gate)                # fails, listing the commands that got through
+```
+
+## A command line
+
+```bash
+agentguard check run.json            # OpenAI, Anthropic or agentguard format; exit 1 if flagged
+agentguard check run.json --ids-only # only high-confidence invented IDs
+agentguard gate refund.create --cost 9000 --amount 9000
+agentguard bench                     # the shell-gate scorecard
+agentguard verify-ledger ledger.json # exit 1 and name the first edited entry
+```
+
+`agentguard check` exits non-zero when a transcript is flagged, so it can gate a CI job over saved agent runs.
+
+---
+
+## Where this comes from
+
+The checker and the benchmark are Python ports of two projects I tested on real data, and the write-ups there carry the honest numbers:
+
+- **[tool-truth](https://github.com/zbs-ops/tool-truth)**: the checker, run on 660+ real agent conversations from τ-bench and τ²-bench. The first version was useless on real logs; after fixes it caught agents inventing an order number a customer then relied on. Held-out results, good and bad, are written up in full.
+- **[gate-bypass-bench](https://github.com/zbs-ops/gate-bypass-bench)**: the benchmark, which I ran against the real command rules of Google's Gemini CLI, OpenAI's Codex CLI, and opencode. Their deny rules were bypassed 78–84% of the time; the same engines as allowlists held at 0%.
+- **[agent-governance](https://github.com/zbs-ops/agent-governance)**: the gate and the approval workflow, with a live demo and a tamper-evident audit log.
+
+Background: Chen & Lin, *denylist fragility in AI agents* ([arXiv:2606.15549](https://arxiv.org/abs/2606.15549)); Sethi et al., *fabrication after tool failure* ([arXiv:2609.14758](https://arxiv.org/abs/2609.14758)); Saltzer & Schroeder (1975) on fail-safe defaults.
+
+## Scope and limits
+
+- **No model, by design.** The checker uses exact-match provenance. It catches invented concrete values; it cannot judge paraphrase or multi-step arithmetic, and the TypeScript write-ups measure that boundary on real data.
+- **The gate's policy is a sensible default, not your policy.** The tiers and the $500 cap are the demo's; the point is the shape.
+- **The Governor keeps state in memory.** Save `g.ledger()` (each entry has `to_dict()`) wherever you keep records; `verify-ledger` checks it later. Reviewer keys are plain secrets you hand it; in production they belong behind your identity provider.
+- **The benchmark runs POSIX `sh`.** The rewrites re-spell dangerous-shaped commands; they only touch files inside a per-case sandbox.
+
+## How I build
+
+I work with an AI coding assistant as a pair programmer. I decide what gets built, review every change, and own what ships.
+
+## License
+
+MIT

agentguard_eval-0.3.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+agentguard/__init__.py,sha256=AaFuUWX4vXYWKjoHl5pfl3m1uVDbCWVXbhGqKmMyuIg,77
+agentguard/cli.py,sha256=uB5-d5vK7bCcS11D0DmtyABY8hNWnT7T9YEQlCT6DPU,4186
+agentguard/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentguard/pytest_plugin.py,sha256=hXlnn-Gpwe3NRTLt1bQhnPBj86hPqDaVeh0Q-rRcz4E,3177
+agentguard/gate/__init__.py,sha256=BafW8GQCJJXuqvE-8JwoWtH-UgdZ05y1IN8AyMTJ1AE,1060
+agentguard/gate/governor.py,sha256=Ou0l4LSbvDtpj7FquG8wlDbVLsAqmKJxfM_tE9gp4fE,10640
+agentguard/gate/ledger.py,sha256=SlGfOSmgmKW6ROjRnLyXuUu2vbmq00OHi09qOvH9DG8,4793
+agentguard/gate/policy.py,sha256=mHkXiRC6Q5eyeRYNJQySMURhGljvlKmjo199rh83-48,8939
+agentguard/provenance/__init__.py,sha256=S6rV5QVfi7_bZLJaP-mW4JPMv294qeww0wsywmRATJA,1107
+agentguard/provenance/adapters.py,sha256=XJHzj1hYTFBH6185iMqftJBgOIFMiGKzEF0sYcs677A,5959
+agentguard/provenance/check.py,sha256=HiY5RyhpUgPpCbPNT8Okwav2tviZZWZqLHghmq2OHgo,11268
+agentguard/provenance/failure.py,sha256=V8wNQhpnWkIjGTDtPSQ9sMKcSwVVMVgGln3GXjjly-o,3562
+agentguard/provenance/ids.py,sha256=1yF9LRB4KZOFAGe3ygjtMaLCKgOTomFHYcR3Tkgauto,1033
+agentguard/provenance/types.py,sha256=ISpUmVIedMA-y5oaoziHaTYEqkq-UN-qCnsbtjRShiI,2593
+agentguard/provenance/values.py,sha256=zxjM3k1uXWF4gfpBSV7gMHXqG3xyDSV0OHYukjPdfPQ,9610
+agentguard/shell/__init__.py,sha256=4mhRwDMgWx__iSmJ93A61CR9oTvL_2hWSw4nDTdEbLo,658
+agentguard/shell/model.py,sha256=EaJHfuinDlgbxUJylCcyUofJLDb86Ka_aO5N9O0UXAs,12146
+agentguard_eval-0.3.0.dist-info/METADATA,sha256=S-gE0iQDHKdZ1nO1zeHJet6zr7sJ5XQfEenArAfeYP8,10872
+agentguard_eval-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentguard_eval-0.3.0.dist-info/entry_points.txt,sha256=kr6IkoQmk30yFX6UtN1R7t0tJxpDnK3kuHnlJBpN8dI,101
+agentguard_eval-0.3.0.dist-info/licenses/LICENSE,sha256=nUyBEhVzR8wT8McPfkHCtdRVovVJ7f_2Tha3nEO7WfQ,1069
+agentguard_eval-0.3.0.dist-info/RECORD,,

agentguard_eval-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agentguard_eval-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+agentguard = agentguard.cli:main
+
+[pytest11]
+agentguard = agentguard.pytest_plugin

agentguard_eval-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zohaib Qamar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.