# agent-shield

**Compliance middleware for AI agents.** PII redaction, audit logging, consent management, and DPIA generation — in 3 lines of code.

```python
from agent_shield import Shield

shield = Shield()
result = shield.scan("Contact me at john@example.com or 08034567890")

print(result.pii_found)   # {'EMAIL': 1, 'PHONE_NG': 1}
print(result.redacted)     # "Contact me at [EMAIL_REDACTED] or [PHONE_REDACTED]"
```

Every AI agent processes personal data. Almost none of them handle it compliantly. **agent-shield** fixes that.

---

## Why this exists

AI agents are being deployed everywhere — customer support, document processing, sales, internal tools. They all process personal data. Under GDPR, the EU AI Act, and Nigeria's NDPA, that processing has legal requirements:

- You need to know what personal data your agent handles
- You need audit trails of every LLM call
- You need consent management per user
- You need a Data Protection Impact Assessment
- You need to document where data flows (especially cross-border)

**Nobody builds these features.** LangChain doesn't. CrewAI doesn't. The Vercel AI SDK doesn't. Your custom agent definitely doesn't.

agent-shield adds all of it as middleware. No framework lock-in. Works with any LLM provider.

## Features

| Feature | What it does |
|---------|-------------|
| **PII Detection** | Regex-based scanner for emails, phones (Nigerian, UK, international), BVN, NIN, NI numbers, credit cards, DOB, IP addresses, IBAN, SSN |
| **PII Redaction** | Replace detected PII with typed labels (`[EMAIL_REDACTED]`, `[PHONE_REDACTED]`) before sending to LLM providers |
| **Audit Logging** | Tamper-evident log of every LLM call — input, output, PII detected, tokens, user, purpose. Hash-chain integrity verification |
| **Consent Management** | Per-user consent tracking — grant, withdraw, check, export. Full history for data subject requests |
| **DPIA Generator** | Auto-generates a Data Protection Impact Assessment skeleton from your audit logs — risks, data flows, mitigations |
| **Data Flow Mapper** | Markdown table + Mermaid diagram showing where personal data flows to which providers in which countries |
| **User Reports** | One-call export of all data for a specific user — for GDPR/NDPA data subject access requests |

## Install

```bash
pip install agent-shield
```

Zero dependencies for core features. Optional provider integrations:

```bash
pip install agent-shield[openai]      # OpenAI wrapper
pip install agent-shield[anthropic]   # Anthropic wrapper
```

## Quick start

### Scan text for PII

```python
from agent_shield import Shield

shield = Shield()

result = shield.scan("My email is ade@company.ng and BVN: 12345678901")
print(result.pii_found)    # {'EMAIL': 1, 'BVN': 1}
print(result.redacted)     # "My email is [EMAIL_REDACTED] and [BVN_REDACTED]"
print(result.has_pii)      # True
```

### Wrap an OpenAI call

```python
from openai import OpenAI
from agent_shield import Shield

client = OpenAI()
shield = Shield(redact_by_default=True)

result = shield.call_openai(
    client=client,
    messages=[{"role": "user", "content": "My email is test@example.com, help me"}],
    model="gpt-4",
    purpose="customer_support",
    user_id="user_123",
)

# PII was redacted before reaching OpenAI
# The call is logged in the audit trail
# You can generate a DPIA from the logs
```

### Wrap an Anthropic call

```python
from anthropic import Anthropic
from agent_shield import Shield

client = Anthropic()
shield = Shield(redact_by_default=True)

result = shield.call_anthropic(
    client=client,
    messages=[{"role": "user", "content": "Process my order, phone 08012345678"}],
    purpose="order_processing",
    user_id="customer_456",
)
```

### Wrap any LLM (generic)

```python
from agent_shield import Shield

shield = Shield()

def my_llm(text):
    # Your custom LLM call
    return f"Response to: {text}"

result = shield.call(
    my_llm,
    input_text="My NI number is AB123456C",
    provider="custom_llm",
    purpose="data_analysis",
    user_id="analyst_1",
)
```

### Manage consent

```python
shield = Shield()

# Record consent
shield.consent.grant("user_123", "customer_support", method="explicit")
shield.consent.grant("user_123", "marketing", method="opt_in")

# Check before processing
if shield.consent.check("user_123", "customer_support"):
    # Proceed
    ...

# User withdraws
shield.consent.withdraw("user_123", "marketing")

# Export for data subject request
history = shield.consent.export("user_123")
```

### Generate a DPIA

```python
shield = Shield()

# ... after running your agent with shield wrapping calls ...

dpia = shield.generate_dpia(
    system_name="Customer Support Agent",
    controller_name="Your Company Ltd",
    dpo_contact="dpo@yourcompany.com",
)

with open("DPIA.md", "w") as f:
    f.write(dpia)
```

The generated DPIA includes:
- Processing description (auto-detected from audit logs)
- PII types processed
- External providers and countries (cross-border transfer documentation)
- Risk assessment
- Mitigation checklist
- Sign-off section

### Generate a data flow map

```python
shield = Shield()

# Markdown table
print(shield.generate_dataflow())

# Mermaid diagram (paste into any renderer)
print(shield.generate_dataflow_diagram("My Agent"))
```

Output:
```
graph LR
    APP[My Agent]
    P0[openai<br/>United States]
    APP -->|EMAIL, PHONE_NG| P0
    P1[anthropic<br/>United States]
    APP -->|data| P1
```

### Verify audit trail integrity

```python
shield = Shield()

valid, count = shield.verify_audit()
print(f"Chain: {'intact' if valid else 'TAMPERED'} ({count} entries)")
```

### Handle a data subject access request

```python
shield = Shield()

# One call gets everything for a user
report = shield.user_report("user_123")

print(report["audit_entries"])    # All LLM calls involving this user
print(report["consent_history"])  # Full consent timeline
print(report["active_consents"]) # Current consent state
```

## PII types detected

| Type | Pattern | Example |
|------|---------|---------|
| `EMAIL` | Standard email format | `john@example.com` |
| `PHONE_NG` | Nigerian mobile numbers | `08034567890` |
| `PHONE_UK` | UK phone numbers | `01234 567890` |
| `PHONE_INTL` | International format | `+234 803 456 7890` |
| `BVN` | Nigerian Bank Verification Number | `BVN: 12345678901` |
| `NIN_NG` | Nigerian National ID (11 digits) | `12345678901` |
| `NI_NUMBER_UK` | UK National Insurance | `AB123456C` |
| `CREDIT_CARD` | Card numbers | `4111-1111-1111-1111` |
| `DATE_OF_BIRTH` | DOB with context | `DOB: 15/03/1990` |
| `IP_ADDRESS` | IPv4 addresses | `192.168.1.100` |
| `IBAN` | International bank account | `GB29NWBK60161331926819` |
| `SSN_US` | US Social Security Number | `123-45-6789` |

## Regulatory context

**GDPR** (EU/UK) — Articles 5, 6, 13-22, 25, 30, 35. If your agent processes EU personal data, you need lawful basis, transparency, DPIAs for high-risk processing, and records of processing activities. agent-shield generates the evidence.

**EU AI Act** — High-risk AI obligations apply from August 2, 2026. Transparency, documentation, and human oversight requirements. The audit trail and DPIA generator help satisfy documentation obligations.

**NDPA** (Nigeria) — Nigeria Data Protection Act 2023. DPO requirements, annual CAR filing, cross-border transfer safeguards. agent-shield's data flow mapper documents every international transfer.

For detailed compliance guidance:
- [Do I Need a DPIA for My AI System?](https://januscompliance.co.uk/blog/do-i-need-a-dpia-for-my-ai-system)
- [GDPR-Compliant AI Chatbot Guide](https://januscompliance.co.uk/blog/how-to-build-a-gdpr-compliant-ai-chatbot)
- [Nigeria Data Protection Act 2023 Guide](https://januscompliance.co.uk/blog/nigeria-data-protection-act-2023-complete-business-guide)
- [Cross-Border Data Transfers from Nigeria](https://januscompliance.co.uk/blog/cross-border-data-transfers-nigeria-how-to-comply)

## Architecture

```
agent_shield/
    __init__.py     # Shield class — main interface
    pii.py          # PII detection & redaction (zero dependencies)
    audit.py        # Tamper-evident audit logger (hash-chain)
    consent.py      # Per-user consent state management
    wrapper.py      # LLM call wrappers (OpenAI, Anthropic, generic)
    dpia.py         # DPIA skeleton generator
    dataflow.py     # Data flow mapper (Markdown + Mermaid)
```

**Zero dependencies** for core features. Pure Python. No ML models, no spaCy, no torch. Installs in 2 seconds.

## Limitations

- PII detection is regex-based, not ML-based. It catches structured PII (emails, phones, IDs) but may miss unstructured PII (names in running text, addresses without clear formatting). For production use, consider layering ML-based NER on top.
- The DPIA generator produces a skeleton (~60% of a DPIA), not a finished assessment. It needs human review, legal assessment, and sign-off. agent-shield doesn't replace a qualified DPO — it gives them a head start.
- Audit log integrity depends on file system security. For production, consider storing logs in an append-only database or write-once storage.

## Contributing

Issues and PRs welcome. If you're adding PII patterns for a new jurisdiction, include test cases.

## License

MIT — use it however you want.

## Credits

Built by [Janus Compliance](https://januscompliance.co.uk) — we build compliant AI systems and provide data protection advisory services across the UK, Ireland, and Nigeria.

Need professional compliance help? [Get in touch](https://januscompliance.co.uk/contact).
