Metadata-Version: 2.4
Name: openai-agents-privacy-filter
Version: 0.1.0
Summary: PII redaction guardrails for OpenAI Agents SDK
Project-URL: Homepage, https://github.com/yourusername/privacy-filter-python
Project-URL: Repository, https://github.com/yourusername/privacy-filter-python
Project-URL: Documentation, https://github.com/yourusername/privacy-filter-python/tree/main/openai-agents-hook#readme
License: MIT
Keywords: agents,llm,openai,pii,privacy,redaction,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: privacy-filter
Provides-Extra: openai
Requires-Dist: openai-agents; extra == 'openai'
Description-Content-Type: text/markdown

# openai-agents-privacy-filter

PII redaction guardrails for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/). Automatically redact personally identifiable information from agent inputs and restore original values in outputs.

## Features

- **Input guardrail** — Redact PII from user messages before the agent processes them
- **Output guardrail** — Restore original values from placeholders in agent responses
- **Local processing** — Uses the `openai/privacy-filter` HuggingFace model (no API calls)
- **Configurable** — Adjust confidence thresholds and filter by entity type

## Installation

```bash
pip install openai-agents-privacy-filter
```

Requires:
- Python 3.11+
- `openai-agents` (for guardrail interface)

## Quick Start

```python
from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail
from agents import Agent, Runner

# Create guardrails
input_guardrail = PiiInputGuardrail(min_score=0.8)
output_guardrail = PiiOutputGuardrail()

# Create agent with PII guardrails
agent = Agent(
    name="PII-Safe Agent",
    instructions="You are a helpful assistant.",
    input_guardrails=[input_guardrail],
    output_guardrails=[output_guardrail],
)

# Run — PII is automatically redacted before LLM and restored after
result = await Runner.run(agent, "My email is alice@example.com")
print(result.final_output)  # "Your email is alice@example.com" (not [EMAIL_1])
```

## How It Works

### Input Guardrail
- Runs before the agent sees the user input
- Detects PII using the privacy-filter model
- Replaces PII with placeholders like `[EMAIL_1]`, `[PERSON_2]`
- Stores mappings for later restoration

### Output Guardrail
- Runs after the agent generates a response
- Restores original values from placeholders
- Returns the unredacted content to the user

## Configuration

```python
from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail

input_guardrail = PiiInputGuardrail(
    min_score=0.8,           # Minimum confidence threshold (0.0-1.0)
    entity_types=None,       # Filter to specific entities (None = all)
    cache_dir=None,          # Custom HuggingFace cache directory
)

output_guardrail = PiiOutputGuardrail()
```

## Supported Entity Types

| Entity | Placeholder | Description |
|--------|-------------|-------------|
| `private_email` | `[EMAIL_N]` | Email addresses |
| `private_person` | `[PERSON_N]` | Person names |
| `private_phone` | `[PHONE_N]` | Phone numbers |
| `private_address` | `[ADDRESS_N]` | Physical addresses |
| `private_url` | `[URL_N]` | URLs |
| `private_date` | `[DATE_N]` | Dates |
| `account_number` | `[ACCOUNT_N]` | Account numbers |
| `secret` | `[SECRET_N]` | Passwords, API keys |

## Complete Example

```python
import asyncio
from agents import Agent, Runner
from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail

async def main():
    input_guardrail = PiiInputGuardrail(min_score=0.9)
    output_guardrail = PiiOutputGuardrail()

    agent = Agent(
        name="Assistant",
        instructions="Help the user with their questions.",
        input_guardrails=[input_guardrail],
        output_guardrails=[output_guardrail],
    )

    result = await Runner.run(
        agent,
        "My name is John Doe and my phone is 555-0123"
    )
    print(result.final_output)
    # Output references "John Doe" and "555-0123", not placeholders

if __name__ == "__main__":
    asyncio.run(main())
```

## GuardrailResult Behavior

- **Input guardrail**: Returns `GuardrailResult(output=redacted_text, triggered=True)` — the agent sees redacted text
- **Output guardrail**: Returns `GuardrailResult(output=unredacted_text, triggered=True)` — user sees original values

## Dependencies

- `privacy-filter` — Core PII detection library
- `openai-agents` (optional extra) — OpenAI Agents SDK

## Related

- Core library: [privacy-filter](https://pypi.org/project/privacy-filter/)
- NanoBot integration: [nanobot-privacy-filter-hook](https://pypi.org/project/nanobot-privacy-filter-hook/)
- OpenAI Agents docs: https://openai.github.io/openai-agents-python/

## License

MIT
