Metadata-Version: 2.4
Name: azureaicommunity-agent-pii-middleware
Version: 0.1.0
Summary: PII detection and security middleware for AI agent pipelines
Author-email: Vinoth Rajendran <r.vinoth@live.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Azure-AI-Community/python-Agent-middleware
Project-URL: Repository, https://github.com/Azure-AI-Community/python-Agent-middleware
Project-URL: Issues, https://github.com/Azure-AI-Community/python-Agent-middleware/issues
Keywords: ai,security,middleware,pii,llm,agent,azure,azure-ai,community
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: agent-framework
Requires-Dist: emoji<2.0.0
Requires-Dist: recognizers-text
Requires-Dist: recognizers-text-number
Requires-Dist: recognizers-text-number-with-unit
Requires-Dist: recognizers-text-date-time
Requires-Dist: recognizers-text-sequence

```
┌─────────────────────────────────────────────────────┐
│                                                     │
│   🛡️  AzureAICommunity PII Security Middleware       │
│                                                     │
│   PII detection & blocking for AI agent pipelines  │
│                                                     │
└─────────────────────────────────────────────────────┘
```

[![PyPI version](https://img.shields.io/pypi/v/azureaicommunity-agent-pii-middleware?color=blue&style=flat-square)](https://pypi.org/project/azureaicommunity-agent-pii-middleware/)
[![Python](https://img.shields.io/pypi/pyversions/azureaicommunity-agent-pii-middleware?style=flat-square)](https://pypi.org/project/azureaicommunity-agent-pii-middleware/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![PyPI Downloads](https://img.shields.io/pypi/dm/azureaicommunity-agent-pii-middleware?style=flat-square&color=orange)](https://pypi.org/project/azureaicommunity-agent-pii-middleware/)

**Intercept, detect, and block sensitive personal data before it reaches your LLM — with zero friction.**

[Getting Started](#-installation) · [Profiles](#-security-profiles) · [LLM Validation](#-llm-assisted-validation) · [Contributing](#-contributing)

---

## Overview

`azureaicommunity-agent-pii-middleware` is a plug-and-play security layer for AI agent pipelines built on `agent-framework`. It scans every user message for PII using Microsoft's [Recognizers Text](https://github.com/microsoft/Recognizers-Text) library and can optionally route ambiguous detections through a secondary LLM for a second opinion.

```
User message
     │
     ▼
┌────────────────────┐
│  PII Detection     │  ← emails, phones, credit cards, SSNs…
│  (Recognizers NLP) │
└────────┬───────────┘
         │ blocked entity found?
         ▼
┌────────────────────┐
│  LLM Validation    │  ← optional secondary agent review
│  (allow / block)   │
└────────┬───────────┘
         │
    ┌────┴────┐
    ▼         ▼
 BLOCKED    ALLOWED
 ← 🚫        → LLM
```

---

## ✨ Features

| | Feature |
|---|---|
| 🔍 | **PII detection** — emails, phones, IPs, credit cards, SSNs, dates, numbers, units |
| 🎛️ | **Profile-based config** — one-line setup with `strict`, `standard`, `financial`, `healthcare` |
| 🔧 | **Builder pattern** — fluent API to compose and customize middleware pipelines |
| 🤖 | **LLM validation** — route edge cases through a secondary agent to reduce false positives |
| 🔌 | **Framework integration** — drops directly into `agent-framework` middleware pipelines |

---

## 📦 Installation

```bash
pip install azureaicommunity-agent-pii-middleware
```

---

## 🚀 Quick Start

```python
import asyncio
from agent_framework.ollama import OllamaChatClient
from agent_framework import Agent
from pii_middleware import PIIMiddleware

# Build a middleware pipeline using the "standard" profile
middleware = (
    PIIMiddleware
        .profile("standard")
        .build()
)

async def main():
    client = OllamaChatClient(model="gemma3:4b")
    agent = Agent(client)

    result = await agent.run("My email is user@example.com", middleware=middleware)
    print(result.text)
    # → "Message blocked: sensitive information detected (email)."

asyncio.run(main())
```

---

## 🎛️ Security Profiles

Choose a pre-built profile to get started instantly:

| Profile | Blocked | Allowed |
|---|---|---|
| `strict` | `email` `phone_number` `ip` `credit_card` | `datetime` `number` |
| `standard` | `email` `phone_number` | `datetime` `number` `unit` |
| `financial` | `credit_card` `ssn` `account_number` `email` | `datetime` |
| `healthcare` | `patient_id` `ssn` `email` `phone_number` | `datetime` `unit` |

```python
# Built-in profile
middleware = PIIMiddleware.profile("strict").build()

# Custom profile dict
middleware = (
    PIIMiddleware
        .profile({"block": ["email", "ssn"], "allow": ["datetime"]})
        .build()
)
```

---

## 🔧 Custom Entity Lists

Fine-tune the block/allow lists after applying any profile:

```python
middleware = (
    PIIMiddleware
        .profile("standard")
        .block_entities(["email", "phone_number", "credit_card"])
        .allow_entities(["datetime", "number"])
        .build()
)
```

---

## 🤖 LLM-Assisted Validation

Attach a secondary LLM agent that makes the final allow/block decision when PII is detected:

```python
from agent_framework.ollama import OllamaChatClient
from agent_framework import Agent

validator = Agent(OllamaChatClient(model="gemma3:4b"))

middleware = (
    PIIMiddleware
        .profile("standard")
        .llm_agent(validator)
        .build()
)
```

> The validator receives the message and the list of detected entities, and responds with `allow` or `block`. This significantly reduces false positives on ambiguous inputs like dates or reference numbers.

---

## ⚙️ How It Works

```
1. Intercept   →  middleware captures the last user message
2. Detect      →  Recognizers Text extracts entity types
3. Filter      →  entities not in allow_list are candidates
4. Match       →  candidates matched against block_list
5. Validate    →  (optional) LLM agent makes final decision
6. Block / Pass →  blocked messages short-circuit the pipeline
                   — the primary LLM is never called
```

## 🤝 Contributing

Contributions are welcome! Please open an issue to discuss what you'd like to change before submitting a pull request.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -m 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request

---

## 📄 License

MIT
