docs: trim README#47
Conversation
Compact, factual README. Drops marketing prose, triadic framings, and cluster-vocabulary tells. Lede states what the library does mechanically. Names Microsoft's Agent Governance Toolkit as the broader alternative. Substance lives in COMPLIANCE.md and docs/formal_specification.md; README points to it. AI Act framing demoted from identity to optional output (regulatory mapping is one consumer of the audit stream, not the library's identity). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe README has been substantially condensed, removing extensive sections on compliance mapping, EU governance, ML classifiers, and framework integrations. The core product description is rewritten to emphasize tool-call interception, conformal risk intervals, and audit capabilities, while the Quick Start example is simplified and a new "Where things live" section guides readers to detailed documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
README.md (2)
27-27: Consider adding a docs-check guard to keep README claims aligned with packaging metadata.The "Zero runtime deps" claim on line 27 is currently accurate—
pyproject.tomlshowsdependencies = []with optional dependencies isolated under[project.optional-dependencies]. However, this guard would prevent accidental drift if someone adds dependencies without updating the README.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 27, Add a docs-check CI guard that verifies the README claim "Zero runtime deps" stays in sync with the package metadata: implement a small check (e.g., scripts/validate_readme.py or a workflow step) that reads pyproject.toml's [project].dependencies and [project.optional-dependencies] and fails if README.md contains "Zero runtime deps" while pyproject.toml lists non-empty runtime dependencies; wire this check into your CI workflow (job name like "docs-check" or "readme-meta-guard") so PRs break until README and pyproject.toml agree.
44-47: Distinguish ESCALATE from DENY in the quick-start example.Lines 41–44 currently collapse both rejected outcomes into a single else clause. Since
result.decisionprovides three distinct states (ALLOW/ESCALATE/DENY), the quick-start should show explicit handling:Proposed README tweak
if result.allowed: pipeline.report_outcome(result.action_id, outcome_severity=0.0) +elif result.decision == "escalate": + print(f"Escalate: {result.reason}") else: - print(result.reason) + print(f"Deny: {result.reason}")This reduces integration ambiguity by making it clear that ESCALATE (human review) and DENY (automatic block) require different downstream handling.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 44 - 47, Update the quick-start example to explicitly branch on the three possible result.decision values (ALLOW, ESCALATE, DENY) instead of using a single else; locate the snippet that calls report_outcome and prints result.reason and replace the single else handler with three distinct branches that handle ALLOW (proceed normally and call report_outcome with success), ESCALATE (route to human review workflow and call report_outcome with an “escalated_for_review” outcome), and DENY (block the action, log/notify denial, and call report_outcome with a “denied” outcome) so integrators can see how to treat human-review vs automatic block differently while still printing result.reason.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 51-52: Update the README entry describing COMPLIANCE.md so the EU
AI Act articles list matches the compliance engine: add "Article 17" to the
parenthetical list (so it reads "Articles 9, 11 to 15, 17, 61"), ensuring
consistency with the compliance engine implementation (engine.py) that documents
support for Article 17.
---
Nitpick comments:
In `@README.md`:
- Line 27: Add a docs-check CI guard that verifies the README claim "Zero
runtime deps" stays in sync with the package metadata: implement a small check
(e.g., scripts/validate_readme.py or a workflow step) that reads
pyproject.toml's [project].dependencies and [project.optional-dependencies] and
fails if README.md contains "Zero runtime deps" while pyproject.toml lists
non-empty runtime dependencies; wire this check into your CI workflow (job name
like "docs-check" or "readme-meta-guard") so PRs break until README and
pyproject.toml agree.
- Around line 44-47: Update the quick-start example to explicitly branch on the
three possible result.decision values (ALLOW, ESCALATE, DENY) instead of using a
single else; locate the snippet that calls report_outcome and prints
result.reason and replace the single else handler with three distinct branches
that handle ALLOW (proceed normally and call report_outcome with success),
ESCALATE (route to human review workflow and call report_outcome with an
“escalated_for_review” outcome), and DENY (block the action, log/notify denial,
and call report_outcome with a “denied” outcome) so integrators can see how to
treat human-review vs automatic block differently while still printing
result.reason.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| - [docs/formal_specification.md](docs/formal_specification.md): math. MWU regret bound O(sqrt(T log N)), conformal coverage guarantees, security properties. | ||
| - [COMPLIANCE.md](COMPLIANCE.md): Article-level evidence mapping for EU AI Act (Articles 9, 11 to 15, 61) and DORA (Articles 10, 12, 13). Eval numbers, threshold sweeps, PAIR adversarial calibration. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== README statement =="
rg -nP 'EU AI Act|Articles?' README.md
echo
echo "== COMPLIANCE.md article references =="
rg -nP 'Article|Articles|EU AI Act' COMPLIANCE.md
echo
echo "== Engine-supported framework/article statement =="
rg -nP 'EU AI Act|Articles 9|11-15|17|61|DORA' src/vaara/compliance/engine.py -n -C2Repository: vaaraio/vaara
Length of output: 4638
Update README.md line 52 to include Article 17 in the EU AI Act articles list.
Line 52 lists EU AI Act Articles 9, 11–15, 61, but src/vaara/compliance/engine.py line 14 documents the framework as supporting Articles 9, 11–15, 17, 61. Update the README to match the engine's actual scope.
Current README.md line 52
- [COMPLIANCE.md](COMPLIANCE.md): Article-level evidence mapping for EU AI Act (Articles 9, 11 to 15, 61) and DORA (Articles 10, 12, 13). Eval numbers, threshold sweeps, PAIR adversarial calibration.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 51 - 52, Update the README entry describing
COMPLIANCE.md so the EU AI Act articles list matches the compliance engine: add
"Article 17" to the parenthetical list (so it reads "Articles 9, 11 to 15, 17,
61"), ensuring consistency with the compliance engine implementation (engine.py)
that documents support for Article 17.
1 participant
61 lines instead of 320. Pointers to COMPLIANCE.md and docs/formal_specification.md.
Summary by CodeRabbit
Release Notes