aiactguard 0.1.0__tar.gz

aiactguard-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Something in AIActGuard isn't working as expected
+title: ""
+labels: bug
+---
+
+**What happened**
+
+**What you expected**
+
+**Minimal reproduction** (a `watch()`-wrapped function or adapter setup that shows the issue)
+
+```python
+
+```
+
+**Environment**
+- AIActGuard version:
+- Python version:
+- Framework + version (LangChain/CrewAI/Claude Agent SDK), if relevant:

aiactguard-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: A module, adapter, or capability AIActGuard doesn't have yet
+title: ""
+labels: enhancement
+---
+
+**What's missing**
+
+**Which Article/module does it map to** (if applicable — see the README's module roadmap table)
+
+**Would this be a good fit as a community plugin instead of core?**
+See `aiactguard.plugins.Plugin` and [examples/plugins/example_gxp_plugin.py](../../examples/plugins/example_gxp_plugin.py) — jurisdiction- or industry-specific modules are usually a better fit as a plugin than as a core addition.

aiactguard-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+**What this changes and why**
+
+**Checklist**
+- [ ] `pytest -q` passes locally
+- [ ] New behavior has test coverage
+- [ ] If this adds a module that drafts/flags/checks something: it's honest about what it can't infer (see the README's Scope section) rather than fabricating an answer
+- [ ] README/CHANGELOG updated if this changes public behavior

aiactguard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[langchain,crewai,claude-agent-sdk,dev]"
+      - name: Run tests
+        run: pytest -q

aiactguard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: python -m pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aiactguard
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC) — no API token needed
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aiactguard-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+*.db
+.DS_Store
+.env

aiactguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] — Unreleased
+
+Initial build: all 19 modules from the original project plan.
+
+### Phase 1 — Core
+- Risk classification engine against a configurable EU AI Act Annex III taxonomy
+- Immutable, append-only audit trail (SQLite-backed by default)
+- Human-in-the-loop approval gates with a multi-approver escalation chain and reasoned-override logging
+- Explainability capture (chain-of-thought/rationale attached to audit records)
+- Policy-as-code (YAML gate rules)
+- Framework adapters: LangChain, CrewAI, Claude Agent SDK
+- `@watch` decorator for framework-agnostic integration
+
+### Phase 2 — Documentation & assessment tooling
+- Technical documentation generator (Art. 11 / Annex IV)
+- Conformity readiness checklist (Art. 43)
+- FRIA template generator (Art. 27)
+- Post-market monitoring plan generator (Art. 72)
+- EU database registration data prep (Art. 71)
+
+### Phase 3 — Robustness & incident tooling
+- Adversarial/red-team test harness (Art. 15)
+- Bias & fairness scan (Art. 10)
+- Serious incident report drafter (Art. 73)
+- GPAI transparency card generator (Art. 53)
+
+### Phase 4 — Multi-agent & multi-standard extensions
+- Composite-system risk aggregation across multi-step pipelines
+- NIST AI RMF mapping layer
+- ISO/IEC 42001 mapping layer
+- Plugin architecture (`aiactguard.plugins`) with entry-point discovery for community modules

aiactguard-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to AIActGuard
+
+## Setup
+
+```bash
+git clone https://github.com/NavikkumarModi/AIActGuard.git
+cd AIActGuard
+python3 -m venv .venv
+.venv/bin/pip install -e ".[langchain,crewai,claude-agent-sdk,dev]"
+```
+
+## Running tests
+
+```bash
+.venv/bin/pytest -q
+```
+
+Tests for the CrewAI and Claude Agent SDK adapters are duck-typed against those frameworks' object shapes, so they run without the frameworks installed. Tests that need a real framework install (see `tests/*_live.py`) skip themselves via `pytest.importorskip` if it's missing locally — CI installs everything so they always run there.
+
+## Design principles (read before adding a module)
+
+- **Draft, flag, or check — never certify.** Every module in this project is explicit that it doesn't perform a legal or formal determination (conformity assessment, prohibited-practice determination, etc.). See the README's Scope section for the current boundary list.
+- **Show what you can't infer, don't fabricate it.** Report generators take a `questionnaire` dict for fields the code can't know (system description, who's affected, intended purpose) and render a visible `NEEDS INPUT` marker when one's missing — see `aiactguard/core/questionnaire.py`. Follow this pattern for new report-style modules.
+- **Dependency-light.** Core (`aiactguard/core/`, `aiactguard/policy/`, `aiactguard/storage/`) has no framework dependencies. Adapters for specific frameworks (`aiactguard/adapters/`) are duck-typed against the target framework's object shapes where possible (see `crewai_adapter.py`, `claude_agent_sdk_adapter.py`) rather than hard-importing it, so the rest of the library stays installable without every framework pulled in.
+- **Reuse `GuardCore`.** Any new integration surface that needs to classify → gate → log an action should go through `aiactguard.core.guard.GuardCore`, not reimplement that sequence — see how the existing adapters use it.
+
+## Adding a jurisdiction- or industry-specific module
+
+Most likely this belongs as a **plugin**, not a core addition — see the README's "Writing a plugin" section and [examples/plugins/example_gxp_plugin.py](examples/plugins/example_gxp_plugin.py). Core stays scoped to the EU AI Act; plugins are where GxP, financial-services, or other domain-specific modules live.
+
+## Before submitting a PR
+
+- Open an issue first for anything non-trivial, so we can agree on scope before you write code.
+- Run the full test suite.
+- Update the README's module roadmap table or Contributing section if you're adding user-facing behavior.

aiactguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIActGuard Contributors
+
+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.

aiactguard-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: aiactguard
+Version: 0.1.0
+Summary: Drop-in EU AI Act compliance middleware for agentic AI frameworks — audit trails, risk classification, and human-approval gates in one decorator.
+Project-URL: Homepage, https://github.com/NavikkumarModi/AIActGuard
+Project-URL: Issues, https://github.com/NavikkumarModi/AIActGuard/issues
+Project-URL: Changelog, https://github.com/NavikkumarModi/AIActGuard/blob/main/CHANGELOG.md
+Author-email: Navik Modi <navikkumarmodi@googlemail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-ai,audit,compliance,eu-ai-act,governance,langchain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-agent-sdk'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.70; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AIActGuard
+
+**Drop-in EU AI Act compliance for any agent framework — audit trails, risk classification, and human-approval gates in one decorator.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#)
+
+AIActGuard is a lightweight middleware layer that any existing agent stack can adopt without ripping out its framework. It is **not** another agent orchestrator — it makes the one you already use (LangChain, CrewAI, AutoGen, ...) compliant.
+
+> Each module logs, drafts, tests, or flags something concrete. None of them certify compliance on their own — that's a legal determination. See [Scope](#scope) below.
+
+## Install
+
+```bash
+pip install aiactguard[langchain]
+```
+
+## Quickstart
+
+```python
+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/](examples/) for full runnable examples: [LangChain](examples/langchain_quickstart.py), [CrewAI](examples/crewai_quickstart.py), [Claude Agent SDK](examples/claude_agent_sdk_quickstart.py), the framework-agnostic [`@watch` decorator with an escalation chain + override](examples/watch_with_escalation.py), [generating all five Phase 2 compliance reports](examples/generate_reports.py) from an audit trail, [running the red-team scenario harness](examples/red_team_scan.py), [a fairness scan](examples/fairness_scan.py), [drafting an incident report + GPAI transparency card](examples/incident_and_transparency_reports.py), [composite-system risk aggregation](examples/composite_risk_pipeline.py), [NIST/ISO mappings](examples/generate_mappings.py), and [a worked community plugin](examples/plugins/example_gxp_plugin.py).
+
+## Module roadmap
+
+All 19 modules from the original project plan are built — see [Scope](#scope) for what's deliberately excluded.
+
+### Core (Phase 1)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 1 | Risk classification engine | Art. 6, Annex III | Tags each agent action/tool call against EU AI Act risk tiers using a configurable taxonomy across all eight Annex III high-risk categories | ✅ |
+| 2 | Immutable audit trail | Art. 12 | Every decision, tool call, input/output, model version, and timestamp logged to an append-only store | ✅ |
+| 3 | Human-in-the-loop approval gates | Art. 14 | Configurable interrupt points that pause execution before a high-risk action fires, with an escalation chain of approvers and reasoned-override logging | ✅ |
+| 4 | Explainability capture | Art. 13 | Structures the agent's chain-of-thought/tool-selection rationale into an auditor-readable format | ✅ |
+| 5 | Framework adapters | — | LangChain ✅, CrewAI ✅, Claude Agent SDK ✅ — LangGraph, AutoGen, OpenAI Agents SDK pending | 🚧 |
+| 6 | Policy-as-code | — | YAML rules defining what counts as high-risk for a given org and what triggers a human gate | ✅ |
+
+### Documentation & assessment tooling (Phase 2)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 7 | Technical documentation generator | Art. 11, Annex IV | Auto-drafts the Annex IV technical file from audit logs + a guided questionnaire | ✅ |
+| 8 | Conformity readiness checklist | Art. 43 | Gap-analysis against Annex IV/VI requirements — a pre-assessment aid, not the assessment itself | ✅ |
+| 9 | FRIA template generator | Art. 27 | Pre-fills a Fundamental Rights Impact Assessment draft from risk classification and deployment context | ✅ |
+| 10 | Post-market monitoring plan generator | Art. 72 | Monitoring plan template scaffolded from risk tier and logged incident categories | ✅ |
+| 11 | EU database registration data prep | Art. 71 | Auto-compiles the metadata the Art. 71 registration form requires — filing stays manual | ✅ |
+
+### Robustness & incident tooling (Phase 3)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 12 | Adversarial/red-team test harness | Art. 15 | Runs prompt-injection, jailbreak, and edge-case scenarios against your agent — heuristic detection, not semantic judgment | ✅ |
+| 13 | Bias & fairness scan | Art. 10 | Statistical checks on agent decisions across a caller-supplied protected-characteristic proxy, at runtime | ✅ |
+| 14 | Serious incident report drafter | Art. 73 | Turns a flagged incident into a structured draft for human review before filing | ✅ |
+| 15 | GPAI transparency card generator | Art. 53 | Auto-generates a model transparency summary from config + usage patterns | ✅ |
+
+### Multi-agent & multi-standard extensions (Phase 4 — differentiators)
+
+| # | Module | What it does | Status |
+|---|---|---|---|
+| 16 | Composite-system risk aggregation | Flags when multiple individually low-risk agents, composed into a pipeline, cross into high-risk territory as a system | ✅ |
+| 17 | NIST AI RMF mapping layer | Maps audit/risk data to NIST AI RMF's Govern/Map/Measure/Manage functions | ✅ |
+| 18 | ISO/IEC 42001 mapping layer | Maps the same data to ISO 42001 AI management system clauses | ✅ |
+| 19 | Plugin architecture for community modules | Defined interface for jurisdiction- or industry-specific community modules | ✅ |
+
+## Scope
+
+**Explicitly out of scope, and why:**
+
+- **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
+
+## 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](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`:
+
+```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](LICENSE).

aiactguard-0.1.0/README.md

@@ -0,0 +1,109 @@
+# AIActGuard
+
+**Drop-in EU AI Act compliance for any agent framework — audit trails, risk classification, and human-approval gates in one decorator.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#)
+
+AIActGuard is a lightweight middleware layer that any existing agent stack can adopt without ripping out its framework. It is **not** another agent orchestrator — it makes the one you already use (LangChain, CrewAI, AutoGen, ...) compliant.
+
+> Each module logs, drafts, tests, or flags something concrete. None of them certify compliance on their own — that's a legal determination. See [Scope](#scope) below.
+
+## Install
+
+```bash
+pip install aiactguard[langchain]
+```
+
+## Quickstart
+
+```python
+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/](examples/) for full runnable examples: [LangChain](examples/langchain_quickstart.py), [CrewAI](examples/crewai_quickstart.py), [Claude Agent SDK](examples/claude_agent_sdk_quickstart.py), the framework-agnostic [`@watch` decorator with an escalation chain + override](examples/watch_with_escalation.py), [generating all five Phase 2 compliance reports](examples/generate_reports.py) from an audit trail, [running the red-team scenario harness](examples/red_team_scan.py), [a fairness scan](examples/fairness_scan.py), [drafting an incident report + GPAI transparency card](examples/incident_and_transparency_reports.py), [composite-system risk aggregation](examples/composite_risk_pipeline.py), [NIST/ISO mappings](examples/generate_mappings.py), and [a worked community plugin](examples/plugins/example_gxp_plugin.py).
+
+## Module roadmap
+
+All 19 modules from the original project plan are built — see [Scope](#scope) for what's deliberately excluded.
+
+### Core (Phase 1)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 1 | Risk classification engine | Art. 6, Annex III | Tags each agent action/tool call against EU AI Act risk tiers using a configurable taxonomy across all eight Annex III high-risk categories | ✅ |
+| 2 | Immutable audit trail | Art. 12 | Every decision, tool call, input/output, model version, and timestamp logged to an append-only store | ✅ |
+| 3 | Human-in-the-loop approval gates | Art. 14 | Configurable interrupt points that pause execution before a high-risk action fires, with an escalation chain of approvers and reasoned-override logging | ✅ |
+| 4 | Explainability capture | Art. 13 | Structures the agent's chain-of-thought/tool-selection rationale into an auditor-readable format | ✅ |
+| 5 | Framework adapters | — | LangChain ✅, CrewAI ✅, Claude Agent SDK ✅ — LangGraph, AutoGen, OpenAI Agents SDK pending | 🚧 |
+| 6 | Policy-as-code | — | YAML rules defining what counts as high-risk for a given org and what triggers a human gate | ✅ |
+
+### Documentation & assessment tooling (Phase 2)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 7 | Technical documentation generator | Art. 11, Annex IV | Auto-drafts the Annex IV technical file from audit logs + a guided questionnaire | ✅ |
+| 8 | Conformity readiness checklist | Art. 43 | Gap-analysis against Annex IV/VI requirements — a pre-assessment aid, not the assessment itself | ✅ |
+| 9 | FRIA template generator | Art. 27 | Pre-fills a Fundamental Rights Impact Assessment draft from risk classification and deployment context | ✅ |
+| 10 | Post-market monitoring plan generator | Art. 72 | Monitoring plan template scaffolded from risk tier and logged incident categories | ✅ |
+| 11 | EU database registration data prep | Art. 71 | Auto-compiles the metadata the Art. 71 registration form requires — filing stays manual | ✅ |
+
+### Robustness & incident tooling (Phase 3)
+
+| # | Module | Article(s) | What it does | Status |
+|---|---|---|---|---|
+| 12 | Adversarial/red-team test harness | Art. 15 | Runs prompt-injection, jailbreak, and edge-case scenarios against your agent — heuristic detection, not semantic judgment | ✅ |
+| 13 | Bias & fairness scan | Art. 10 | Statistical checks on agent decisions across a caller-supplied protected-characteristic proxy, at runtime | ✅ |
+| 14 | Serious incident report drafter | Art. 73 | Turns a flagged incident into a structured draft for human review before filing | ✅ |
+| 15 | GPAI transparency card generator | Art. 53 | Auto-generates a model transparency summary from config + usage patterns | ✅ |
+
+### Multi-agent & multi-standard extensions (Phase 4 — differentiators)
+
+| # | Module | What it does | Status |
+|---|---|---|---|
+| 16 | Composite-system risk aggregation | Flags when multiple individually low-risk agents, composed into a pipeline, cross into high-risk territory as a system | ✅ |
+| 17 | NIST AI RMF mapping layer | Maps audit/risk data to NIST AI RMF's Govern/Map/Measure/Manage functions | ✅ |
+| 18 | ISO/IEC 42001 mapping layer | Maps the same data to ISO 42001 AI management system clauses | ✅ |
+| 19 | Plugin architecture for community modules | Defined interface for jurisdiction- or industry-specific community modules | ✅ |
+
+## Scope
+
+**Explicitly out of scope, and why:**
+
+- **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
+
+## 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](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`:
+
+```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](LICENSE).

aiactguard-0.1.0/agentguard-project-plan.md

@@ -0,0 +1,162 @@
+# AIActGuard — Compliance & Governance Middleware for Agentic AI
+
+**Working tagline:** *"Drop-in EU AI Act compliance for any agent framework — audit trails, risk classification, and human-approval gates in one decorator."*
+
+---
+
+## 1. Why this, why now
+
+- The EU AI Act's obligations for high-risk AI systems became fully enforceable on **August 2, 2026** — three days before this doc was written. Every enterprise running agentic AI in HR, healthcare, finance, critical infrastructure, or (like GSK) pharma supply chain now has a live legal obligation and almost no open-source tooling to meet it.
+- The agentic AI GitHub landscape is saturated at the orchestration layer (LangChain, CrewAI, AutoGen, Dify, Langflow all have 50k–150k+ stars). Nobody has claimed the **governance/compliance layer** that sits *alongside* those frameworks.
+- "Picks and shovels" repos that solve a boring, urgent, universally-needed problem (not a flashy demo) have a track record of steady, durable star growth rather than one viral spike that fades.
+- This is also the most credible repo for your career narrative: Principal AI Architect at a regulated pharma enterprise, shipping the compliance tooling the whole industry now needs. It's a stronger signal to a VP/Head of AI hiring panel than a generic agent framework would be.
+
+## 2. What it is (and isn't)
+
+**Is:** A lightweight middleware/wrapper layer that any existing agent stack can adopt without ripping out its framework.
+
+**Isn't:** Another agent orchestrator. You are not competing with LangChain/CrewAI — you're making them compliant.
+
+## 3. Full module coverage (expanded scope)
+
+Each module is scoped honestly: it logs, drafts, tests, or flags something concrete — none of them claim to *certify* compliance on their own, since that's a legal determination. That honesty is what makes a broad feature set credible instead of overreaching.
+
+### Core (Phase 1)
+
+| # | Module | Article(s) | What it does |
+|---|---|---|---|
+| 1 | **Risk classification engine** | Art. 6, Annex III | Tags each agent action/tool call against EU AI Act risk tiers (minimal / limited / high / unacceptable) using a configurable taxonomy across all eight Annex III high-risk categories (biometrics, critical infrastructure, education, employment, essential services, law enforcement, migration, justice/democracy) |
+| 2 | **Immutable audit trail** | Art. 12 | Every decision, tool call, input/output, model version, and timestamp logged to an append-only store |
+| 3 | **Human-in-the-loop approval gates** | Art. 14 | Configurable interrupt points that pause execution before a high-risk action fires, routing to a human approver, with escalation and override logging |
+| 4 | **Explainability capture** | Art. 13 | Structures the agent's chain-of-thought/tool-selection rationale into an auditor-readable format |
+| 5 | **Framework adapters** | — | LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Claude Agent SDK |
+| 6 | **Policy-as-code** | — | YAML rules defining what counts as high-risk for a given org and what triggers a human gate |
+
+### Documentation & assessment tooling (Phase 2)
+
+| # | Module | Article(s) | What it does |
+|---|---|---|---|
+| 7 | **Technical documentation generator** | Art. 11, Annex IV | Auto-drafts the Annex IV technical file (system description, design choices, data used, performance metrics) from audit logs + a guided questionnaire for the parts code can't infer |
+| 8 | **Conformity readiness checklist** | Art. 43 | A gap-analysis tool that checks your logged evidence against each Annex IV/VI requirement and flags what's missing — a pre-assessment aid, not the assessment itself |
+| 9 | **Fundamental Rights Impact Assessment (FRIA) template generator** | Art. 27 | Pre-fills an FRIA draft from your system's risk classification and deployment context — required for deployers in banking, insurance, and public-service high-risk use cases |
+| 10 | **Post-market monitoring plan generator** | Art. 72 | Produces a monitoring plan template scaffolded from the system's risk tier and logged incident categories |
+| 11 | **EU database registration data prep** | Art. 71 | Auto-compiles the information fields the Art. 71 registration form requires from your system's metadata — the actual filing stays manual, but the tedious data-gathering is automated |
+
+### Robustness & incident tooling (Phase 3)
+
+| # | Module | Article(s) | What it does |
+|---|---|---|---|
+| 12 | **Adversarial/red-team test harness** | Art. 15 | Runs a library of prompt-injection, jailbreak, and edge-case scenarios against your agent and reports pass/fail with logs |
+| 13 | **Bias & fairness scan** | Art. 10 | Statistical checks on agent decisions across protected-characteristic proxies in the input data it processes at runtime (not training-data governance, which is out of scope) |
+| 14 | **Serious incident report drafter** | Art. 73 | Turns a flagged incident (a gate override, an anomalous action, a user-reported harm) into a structured draft matching the incident-report format, for human review before filing |
+| 15 | **GPAI transparency card generator** | Art. 53 | For teams building on top of general-purpose models, auto-generates a model transparency summary (capabilities, limitations, known risks) from config + your usage patterns |
+
+### Multi-agent & multi-standard extensions (Phase 4 — differentiators)
+
+| # | Module | What it does |
+|---|---|---|
+| 16 | **Composite-system risk aggregation** | A genuinely novel piece: flags when multiple individually low-risk agents, composed into a pipeline, cross into high-risk territory as a system — something no existing tool checks for, and a natural fit for your RL/systems background |
+| 17 | **NIST AI RMF mapping layer** | Maps the same audit/risk data to NIST AI RMF's Govern/Map/Measure/Manage functions — widens the addressable market to US enterprises without EU exposure |
+| 18 | **ISO/IEC 42001 mapping layer** | Same data, mapped to ISO 42001 AI management system clauses — relevant for any org pursuing certification |
+| 19 | **Plugin architecture for community modules** | A defined interface so the community can contribute jurisdiction-specific or industry-specific modules (e.g., a pharma/GxP module, a financial services module) over time — this is also a strong organic-growth mechanism: contributors who add a module have a reason to promote the repo themselves |
+
+### What stays explicitly out of scope (and why)
+
+- **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
+
+This boundary list should live prominently in the README — it's what makes the broad feature set credible rather than overreaching.
+
+## 4. Architecture (high level)
+
+```
+Your existing agent (LangChain / CrewAI / etc.)
+            │
+      @aiactguard.watch  ← decorator/callback, no framework replacement
+            │
+   ┌────────┴─────────┐
+   │   AIActGuard Core  │
+   │  - Risk classifier │
+   │  - Policy engine    │
+   │  - Audit logger     │
+   └────────┬─────────┘
+            │
+   Audit store (SQLite default, Postgres for prod)
+            │
+   Report generator ──► compliance-report.md / .pdf
+   Dashboard (optional, Streamlit) ──► live view of gated/logged actions
+```
+
+## 5. Realistic build roadmap (part-time, alongside a full-time role)
+
+The full 19-module scope above is the destination, not the launch state — launching with real depth in Phase 1 and a visible, documented roadmap for Phases 2–4 is what actually drives sustained stars (people star ambitious, clearly-planned projects and come back for releases; they don't star a repo that ships everything half-finished on day one).
+
+- **Weeks 1–2 — Phase 1 core:** Risk classifier + audit logger + LangChain adapter + policy-as-code
+- **Weeks 3–4 — Phase 1 complete:** Human-approval gates + explainability capture + CrewAI and Claude Agent SDK adapters
+- **Week 5 — Launch prep:** Docs site, quickstart per framework, README with the full module roadmap visible (this is your public commitment device and your changelog-driven visibility engine)
+- **Week 6 — Launch**
+- **Weeks 7–10 — Phase 2:** Technical documentation generator, conformity readiness checklist, FRIA generator
+- **Weeks 11–14 — Phase 3:** Red-team harness, bias scan, incident report drafter, GPAI transparency card
+- **Ongoing — Phase 4:** Composite-risk aggregation (your strongest technical differentiator — worth prioritizing earlier if you want a research-flavored angle sooner), NIST/ISO mapping layers, plugin architecture opened to contributors
+
+Each phase completion is a natural release/announcement moment — this turns one launch into 4–5 visibility events instead of one.
+
+## 6. Visibility / star-growth plan (this is where most repos fail, not the code)
+
+- **Timed launch** explicitly anchored to the EU AI Act enforcement date — "the compliance gap every agent team now has."
+- **Show HN**, r/MachineLearning, r/LocalLLaMA, and LinkedIn — post from your own account leveraging your GSK/pharma + PhD credibility, not an anonymous repo drop.
+- **Submit to the existing "awesome-agentic-ai" curated lists** as a PR — free distribution into an audience that's already primed.
+- **One technical blog post**: "Why agentic AI needs compliance-by-design under the EU AI Act" — this slots directly into the thought-leadership work you already have in motion (the pharma supply-chain resilience piece and the JEPA/bandit piece).
+- **Framework-specific quickstarts** as separate short posts/gists ("Add EU AI Act compliance to your LangChain agent in 5 minutes") — lowers adoption friction and gives you multiple distinct pieces of shareable content from one project.
+- **A "compliance-checked" badge** projects can add to their own README once integrated — this is a viral distribution loop, similar to how CI/coverage badges spread.
+- Target compliance/legal-tech communities in addition to ML ones — this is a rare repo with two distinct audiences, which doubles your reach.
+
+## 7. Name — confirmed: AIActGuard
+
+Literal and high-intent for SEO ("EU AI Act" + "compliance"/"agent"), and it reads clearly as a governance layer rather than another orchestration framework.
+
+## 8. License
+
+**MIT.** Best fit here — max adoption, no copyleft friction for enterprises evaluating it (the exact audience you're targeting), and it's the norm across nearly all the comparable repos referenced earlier (LangChain, CrewAI, Guardrails AI).
+
+## 9. Claude Code kickoff prompt
+
+Since you'll build this in Claude Code, here's a ready-to-paste prompt to start the Phase 1 scaffold. Drop this plan file into the project directory first so Claude Code has the full spec as context.
+
+```
+I'm building AIActGuard, an MIT-licensed Python library that adds EU AI Act
+technical-obligation tooling (audit logging, risk classification, human
+approval gates) as middleware around existing agent frameworks — not a new
+orchestrator. Full spec is in agentguard-project-plan.md in this directory.
+
+Scaffold the Phase 1 MVP:
+1. Package structure: aiactguard/ with core/, adapters/, policy/, storage/
+2. core/risk_classifier.py — classifies actions against a configurable
+   Annex III risk taxonomy (YAML-driven, ship a default taxonomy file)
+3. core/audit_logger.py — append-only audit log, SQLite backend by default,
+   schema covering timestamp, action, inputs/outputs, model version, risk tier
+4. adapters/langchain_adapter.py — a callback/decorator that wraps a
+   LangChain agent's tool calls and routes them through the risk classifier
+   and audit logger with minimal integration code required
+5. policy/schema.py + a default policy.yaml — defines what triggers a
+   human-approval gate per org config
+6. A working example in examples/langchain_quickstart.py showing a full
+   wrapped agent in under 20 lines
+7. pyproject.toml, MIT LICENSE file, and a README.md skeleton (I'll refine
+   the README content separately, but scaffold the standard sections:
+   badges, install, quickstart, module roadmap table, contributing, license)
+8. Basic test coverage for risk_classifier and audit_logger
+
+Keep it dependency-light — no framework lock-in beyond what's needed for
+the LangChain adapter itself. Ask me before adding any new dependency
+beyond langchain, pyyaml, and pytest.
+```
+
+## 10. Next steps
+
+1. Register the GitHub repo under `AIActGuard`, MIT LICENSE
+2. Open Claude Code in the repo directory with this plan file present, paste the kickoff prompt above
+3. Come back here for the README launch copy, the LinkedIn/Show HN posts, and the framework-specific quickstart write-ups once Phase 1 is working code — that content lands better once there's a real repo to point at

aiactguard-0.1.0/aiactguard/__init__.py

@@ -0,0 +1,7 @@
+from .core.audit_logger import AuditLogger
+from .core.risk_classifier import RiskClassifier, RiskTier
+from .core.watch import watch
+from .policy.schema import PolicyConfig
+
+__all__ = ["watch", "RiskClassifier", "RiskTier", "AuditLogger", "PolicyConfig"]
+__version__ = "0.1.0"