Skip to main content
Glama
README.md
# AI Act Governance Layer for Enterprise Architecture

[![CI](https://github.com/Manimaran3101/ai-act-governance/actions/workflows/ci.yml/badge.svg)](https://github.com/Manimaran3101/ai-act-governance/actions/workflows/ci.yml)

A prototype that answers a question every company with AI in production now has to answer:
**"Which of our AI systems fall under the EU AI Act, what do we owe for each one, and where are we not ready?"**

It sits on top of an application inventory, the kind an enterprise architecture tool like SAP LeanIX holds. It does three things:

1. **Classifies** each AI use case into an EU AI Act risk tier with Claude, citing the Article or Annex point.
2. **Measures** that classifier against a keyword baseline on 30 cases I labelled by hand: accuracy, missed high-risk systems, cost per item and latency.
3. **Serves** the result through an **MCP server**, so Claude (or any MCP client) can answer governance questions about the portfolio. Each user only sees their own departments.

> Built by [Manimaran Murugan](https://www.linkedin.com/in/manimaran-murugan-310191), Product Owner (PSPO I), with Claude Code.
> Product thinking behind it: [docs/product-brief.md](docs/product-brief.md)

---

## The problem

- Companies have dozens of AI features spread across HR, finance, customer service and operations. Most were bought, not built, and nobody has a full list.
- The AI Act sets duties by risk tier. Prohibited practices are already banned (since Feb 2025). Duties for high-risk systems in Annex III apply from **2 Dec 2027**, after the Digital Omnibus moved the date.
- EA tools already know *what* applications exist. LeanIX even ships its own MCP server and an AI Agent Hub. What I could not find in their published material is the **regulation layer**: which tier, which Article, which obligations, and which evidence is missing.

## Who it's for

| Persona | Question they bring | What they get |
| --- | --- | --- |
| Compliance officer | "Are we audit-ready for the AI Act?" | Tier per use case with the legal basis, obligations, missing evidence, review queue |
| CIO / enterprise architect | "Where is our AI risk concentrated?" | Exposure by department and tier, prohibited systems still running, retirement overlaps |
| Department head (e.g. HR) | "What do I need to do for *my* systems?" | Same views, limited to their own department |

## How it fits together

```mermaid
flowchart LR
    U[User in Claude / Copilot / Cursor] -->|MCP| EA[EA tool MCP server<br/>e.g. SAP LeanIX:<br/>apps, owners, lifecycle]
    U -->|MCP| G[This server:<br/>AI Act governance]
    G --> P[(Portfolio export<br/>+ assessments + evidence)]
    G --> T[AI Act rules<br/>taxonomy.py]
    G -->|new use case| C[Claude classifier<br/>structured output]
    C -.->|fallback, no key| B[Keyword baseline]
    E[Evaluation<br/>30 labelled cases] --> C
    E --> B
```

All legal rules live in one file, [`src/aiact/taxonomy.py`](src/aiact/taxonomy.py). The classifier prompt, the baseline and the obligations engine all read from it. When the law changes (it already has once, through the Digital Omnibus), I change one file.

## Results

Full report with confusion matrices and every case: [docs/evaluation-report.md](docs/evaluation-report.md).

| System | Accuracy | Clear cases | Tricky cases | Missed high-risk / prohibited | Cost per item | Latency |
| --- | --- | --- | --- | --- | --- | --- |
| Keyword baseline | **67%** | 93% | 40% | **4 of 15** | free | < 1 ms |
| Claude Haiku 5.5 | *run pending* | | | | | |
| Claude Opus 5.5 | *run pending* | | | | | |

The Claude rows need an API key. `python -m aiact.evaluate` runs all three and rewrites the report.

**What the baseline gets wrong is the point of the test set.** Half the cases are traps where the words point one way and the law points the other:

- *Fraud detection on credit card payments* contains "credit", but fraud detection is explicitly excluded from the credit-scoring point, Annex III(5)(b).
- *Face recognition at the office door* sounds high-risk, but 1:1 verification is excluded from Annex III(1).
- *Voice analysis of call-centre agents for stress* has no "high-risk words", but emotion recognition at work is **prohibited**, Art. 5(1)(f).
- *Driver drowsiness detection* is not emotion recognition at all, because fatigue is a physical state (Recital 18).

I track **missed high-risk systems** separately from accuracy. An over-cautious answer costs a review hour. A missed high-risk system costs an audit finding.

## The demo question

> *"Which high-risk AI use cases process personal data, run on applications that retire before 2028, and are missing human-oversight evidence?"*

Claude calls `evidence_gaps(tier="high", processes_personal_data=true, end_of_life_before="2028-01-01", obligation="oversight")` and gets:

| Use case | Application | Owner | Retires | Review status | Readiness |
| --- | --- | --- | --- | --- | --- |
| CV ranking | TalentFlow ATS | k.schmidt | 2027-06-30 | approved | 4/8 obligations evidenced |
| Private leasing credit score | LeaseScore | s.wagner | 2027-12-31 | approved | 5/12 |
| Customer sentiment routing | VoiceCoach | m.fischer | 2027-09-30 | *proposed* | 2/9 |
| Behaviour-based shift allocation | ShiftPlanner | l.hoffmann | 2027-11-30 | approved | 3/8 |
| Targeted job ads | TalentReach | k.schmidt | 2027-04-30 | *proposed* | 0/8 |

The governance insight is in the dates. Several apps retire around the Dec 2027 deadline, so the real decision is *fix or replace*, and a replacement needs the AI Act duties in its requirements. The same portfolio also has **one prohibited system still running** (agent stress detection in VoiceCoach). `portfolio_exposure` puts that at the top.

When the HR Director asks the same question (`AIACT_USER=k.schmidt`), they only get the two HR rows. Asking for a Finance app returns "not found", the same answer as for an app that doesn't exist, so scope doesn't leak.

## MCP tools

| Tool | What it answers |
| --- | --- |
| `whoami` | Who am I and what can I see? |
| `list_applications` | Apps in scope with their highest tier; filter by department, personal data, retirement date |
| `get_application` | Full record: owner, lifecycle, data, AI use cases, assessments |
| `obligations_for_use_case` | Every duty for one use case, the date it applies, and evidence per duty |
| `evidence_gaps` | What's missing, strictest tier first, with the same filters |
| `portfolio_exposure` | Management summary: by tier and department, prohibited in use, review queue |
| `classify_use_case` | Proposed tier for a new use case, marked *proposed* until compliance approves it |

Resource: `aiact://timeline` with the application dates, including the Omnibus changes.

## Try it

```bash
git clone https://github.com/Manimaran3101/ai-act-governance
cd ai-act-governance
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

pytest                                   # 33 tests, no API key needed
python -m aiact.evaluate --systems baseline
python -m aiact.cli --baseline "Chatbot that answers employee questions about holidays"

export ANTHROPIC_API_KEY=...             # then:
python -m aiact.evaluate                 # baseline + Haiku 5.5 + Opus 5.5
python -m aiact.cli "Analyses call recordings to detect stressed employees"
```

**Use it from Claude Desktop.** Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ai-act-governance": {
      "command": "/path/to/ai-act-governance/.venv/bin/python",
      "args": ["-m", "aiact.server"],
      "env": { "AIACT_USER": "j.nowak", "ANTHROPIC_API_KEY": "optional" }
    }
  }
}
```

Switch `AIACT_USER` to `k.schmidt` (HR Director) or `t.yilmaz` (Marketing) to see the scoping. Users are in [`data/users.json`](data/users.json).

## Product decisions

- **The model proposes, a person approves.** Every classification has a status. New ones start as `proposed`, and the review queue is part of the summary. Under the AI Act the company stays accountable, so the tool must not look like it decides.
- **Recall over accuracy.** I report missed high-risk systems on their own, because the cost of errors is asymmetric.
- **Extend LeanIX, don't rebuild it.** LeanIX already has an MCP server for the inventory, and I don't compete on that. This server only adds the regulation layer, so both can run side by side in the same client.
- **Same scope rules as the source system.** Per-user scope mirrors how LeanIX's MCP server works with per-user OAuth. In this prototype the user comes from an env var. In production it would come from the identity provider.
- **Falls back without a key.** With no API key, `classify_use_case` uses the baseline and says so in the `engine` field. A demo never just breaks.

## Limits

- **Not legal advice.** The rules are a simplified working model of Regulation (EU) 2024/1689 as amended. Dates last checked: 15 Nov 2026.
- **Small test set, one labeller.** 30 cases labelled by me, each with a written reason. A real rollout needs a second labeller (legal) and agreement measured between the two.
- **Mock data.** "Acme Mobility AG" and everyone in it are fictional.
- **No write-back.** The server is read-only. Approving an assessment or attaching evidence would be the next step, behind an approval flow.

## What I'd do next

1. Connect to a real LeanIX workspace through its GraphQL API or MCP server instead of the JSON export.
2. Add a second labeller from legal, and measure agreement (Cohen's kappa) before trusting any accuracy number.
3. Add write tools for "approve assessment" and "attach evidence", with an audit log.
4. Pilot with one department (HR has the most Annex III exposure), and measure time to audit-ready compared with spreadsheets.

## Repository map

```
src/aiact/taxonomy.py   AI Act rules: tiers, triggers, obligations, dates
src/aiact/llm.py        Claude classifier (structured output, prompt caching, refusal fallback)
src/aiact/baseline.py   Keyword baseline, built from the wording of the Act
src/aiact/evaluate.py   Evaluation runner and report
src/aiact/portfolio.py  Inventory, per-user scope, obligations and evidence gaps
src/aiact/server.py     MCP server
data/                   Fictional portfolio, users, labelled test set
docs/                   Product brief, evaluation report, demo script
tests/                  33 tests, run in CI on every push
```

TDQS

A3.6/5.0

Scored across 7 tools

Disambiguation4/5

Each tool targets a distinct object: identity (whoami), application list/detail (list_applications, get_application), per-use-case obligation detail (obligations_for_use_case), gap aggregation (evidence_gaps), portfolio rollup (portfolio_exposure), and tier proposal (classify_use_case). The main potential confusion is list_applications vs portfolio_exposure and obligations_for_use_case vs evidence_gaps, but the descriptions clearly mark one as detail and the other as aggregate, so an agent can choose correctly.

Naming Consistency4/5

All names are snake_case and readable, with action tools following verb_noun (list_applications, get_application, classify_use_case) and reporting tools following noun phrases (evidence_gaps, portfolio_exposure, obligations_for_use_case). The split between verb-led and noun-led conventions is a minor deviation, and whoami is a conventional outlier rather than a real inconsistency.

Tool Count5/5

Seven tools is well within the sensible range and each one covers a distinct governance need (identity, inventory, detail, obligations, gaps, rollup, classification). Nothing appears redundant or tacked on for the stated compliance scope.

Completeness3/5

The surface is read-heavy: it can inspect applications, obligations, gaps and exposure, and classify_use_case proposes a tier, but there is no tool to persist that proposal, attach/refresh evidence, or update an application or assessment. This leaves a notable dead end, since the classify tool explicitly says compliance must review before it enters the inventory and no review or write path exists.