aiactguard

---

Recorded from examples/demo.py — real code, real gate decisions (one approval, one denial), real audit records, real report generated from both. The denial scenario shows LangChain's own internal warning when the callback raises — that's the block genuinely propagating through LangChain's real machinery, not this script claiming it worked. Two things are staged for the recording, not faked: the pacing between lines, and the approvers — canned functions playing the reviewer's role so the recording doesn't sit waiting on a keypress, not a live human typing an answer. See examples/langchain_quickstart.py for the input()-driven version an actual reviewer would use.

---

Install

pip install aiactguard[langchain]

Other extras: crewai, claude-agent-sdk, langgraph, autogen, openai-agents, postgres (for PostgresAuditStore), audit-priority (for the audit prioritization & drift diagnostics module) — mix and match, e.g. pip install aiactguard[langgraph,postgres].

Verify it installed correctly:

python -c "from aiactguard import watch; print('aiactguard OK')"

Quickstart

from aiactguard.adapters.langchain_adapter import AIActGuardCallbackHandler
from aiactguard.core.approval import ApprovalContext, ApprovalDecision


def compliance_officer(ctx: ApprovalContext) -> ApprovalDecision:
    approved = input(f"Approve {ctx.action} ({ctx.risk_tier.value})? [y/N] ").lower() == "y"
    return ApprovalDecision(approved=approved, approver_id="compliance_officer")


guard = AIActGuardCallbackHandler(
    category="essential_services",
    approvers=[compliance_officer],  # an escalation chain — add more to route to a fallback
)

agent_executor.invoke({"input": "..."}, config={"callbacks": [guard]})

See examples/ for full runnable examples: LangChain, CrewAI, Claude Agent SDK, LangGraph (using LangGraph's own interrupt() for human-in-the-loop), AutoGen, OpenAI Agents SDK, the framework-agnostic @watch decorator with an escalation chain + override, generating all five Phase 2 compliance reports from an audit trail, running the red-team scenario harness, a fairness scan, drafting an incident report + GPAI transparency card, composite-system risk aggregation, NIST/ISO mappings, using the Postgres storage backend, a worked community plugin, the script that recorded the demo above, and audit prioritization + the drift diagnostic report.

Why this exists

The agentic AI ecosystem is saturated at the orchestration layer — LangChain, CrewAI, AutoGen, and the rest all do that job well. None of them were built to satisfy Article 12 (audit trails), Article 13 (explainability), or Article 14 (human oversight), because that isn't what they're for. AIActGuard sits alongside whichever of those you already run, not in place of it.

flowchart LR
    A["Your agent<br/>(LangChain / CrewAI / ...)"] --> B["AIActGuard adapter<br/>or @watch"]
    B --> C{"Risk classifier<br/>+ policy-as-code"}
    C -->|"below gate threshold"| D["Action runs"]
    C -->|"gated"| E["Approver chain"]
    E -->|"approved"| D
    E -->|"denied"| F["Blocked — never runs"]
    D --> G[("Audit trail<br/>SQLite / Postgres")]
    F --> G
    G --> H["Report generators<br/>(checklist, FRIA, incident report, ...)"]

Every module drafts, flags, tests, or logs something concrete. None of them certify compliance on their own — that's a legal determination. See Scope below for the explicit boundary.

Module roadmap

All 19 modules from the original project plan are built.

Core (Phase 1)

Documentation & assessment tooling (Phase 2)

Robustness & incident tooling (Phase 3)

Multi-agent & multi-standard extensions (Phase 4 — differentiators)

Audit prioritization & drift diagnostics

Additional scope beyond the 19 modules above, contributed from the user's own research on adaptively-routed agent systems (paper forthcoming — no citation added yet since it isn't posted).

The research's core statistical method is an anytime-valid confidence sequence over a bin's true violation rate, built from accumulating human audit findings. The research itself also describes using that method to automatically stop requiring approval for certain actions once the statistics say a context is safe enough. AIActGuard deliberately does not implement that part — every gate here always defers to a human, with no exception. What's built instead is the same statistical method repurposed for two things that never remove a human from a decision:

• aiactguard.audit_priority — ranks pending/completed audit records by how statistically uncertain the evidence still is for their confidence bin, so a compliance reviewer works down a prioritized list instead of reviewing randomly or chronologically. A bin nobody's reviewed yet ranks at the top by default; a bin with enough accumulated evidence of being safe ranks lower automatically as that evidence comes in.
• aiactguard.reports.drift_diagnostic — a monitoring report (not a gate) decomposing where "silent risk mass" concentrates across confidence bins, and checking whether the agent shows an elevated preference for high-exposure actions specifically in bins the classifier tends to miss.

Both require ground-truth findings from actual human review (aiactguard.audit_priority.findings.AuditFindingStore) to produce anything beyond "not enough evidence yet" — see examples/audit_priority_demo.py for a full worked example. Requires pip install aiactguard[audit-priority].

[!NOTE] The confidence-sequence computation is ported from the confseq package (MIT license, Steve Howard with Ian Waudby-Smith and Aaditya Ramdas) — only the one code path this module needs, not the full library. The published PyPI package requires a compiled CMake build that failed on the machine this was built on and can't be relied on to install cleanly for everyone; this path is pure NumPy.

Scope

[!IMPORTANT] Explicitly out of scope, and why — this boundary is what makes the rest of this list credible instead of overreaching:

• Prohibited-practice determination (Title II) — legal judgment call, not a runtime check
• Conformity assessment / CE marking itself — requires formal procedures, sometimes a notified body; the toolkit preps evidence, it doesn't perform the assessment
• Quality management system (Art. 17) — an organizational process, not code
• GPAI systemic-risk evaluation (Art. 55) — applies to frontier model providers, not agent builders
• Actual legal filing/registration submission — data prep is automated, submission is not

[!NOTE] classifier_confidence (logged on every audit record) is rule-match strength from a keyword/category classifier, not a calibrated probability of true risk. This project doesn't have a trained model behind it, and doesn't claim to.

Running the tests

git clone https://github.com/NavikkumarModi/AIActGuard.git
cd AIActGuard
python3 -m venv .venv
.venv/bin/pip install -e ".[langchain,crewai,claude-agent-sdk,langgraph,autogen,openai-agents,postgres,dev]"
.venv/bin/pytest -q
# 117 passed

tests/test_postgres_store.py needs a reachable Postgres database (AIACTGUARD_TEST_POSTGRES_DSN, defaults to postgresql:///aiactguard_test) — it skips cleanly if none is available rather than failing the suite; CI runs a real Postgres service so it's exercised there either way. See CONTRIBUTING.md for the full setup and design principles.

Contributing

Contributions are welcome, especially jurisdiction- or industry-specific modules. Open an issue to discuss before submitting a large PR.

Writing a plugin: implement aiactguard.plugins.Plugin — a name, a description, and a generate(logger, *, questionnaire=None, **kwargs) -> str method (the same shape every built-in report/mapping already has). See examples/plugins/example_gxp_plugin.py for a worked example. To publish one for others to auto-discover, register it under the aiactguard.plugins entry-point group in your own package's pyproject.toml:

[project.entry-points."aiactguard.plugins"]
gxp = "aiactguard_gxp_plugin:plugin"

Callers pick it up with aiactguard.plugins.discover_entry_points().

License

MIT — see LICENSE.