azureaicommunity-agent-pii-middleware 0.1.0

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

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 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

📦 Installation

pip install azureaicommunity-agent-pii-middleware

🚀 Quick Start

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:

# 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:

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:

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