Metadata-Version: 2.4
Name: nanobot-privacy-filter-hook
Version: 0.1.0
Summary: NanoBot AgentHook that redacts PII before LLM inference
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/nanobot-hook#readme
License: MIT
Keywords: llm,nanobot,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: nanobot
Requires-Dist: nanobot-ai; extra == 'nanobot'
Description-Content-Type: text/markdown

# nanobot-privacy-filter-hook

PII redaction guardrail for [NanoBot](https://github.com/HKUDS/nanobot). Automatically redact personally identifiable information before LLM calls and restore original values in responses.

## Features

- **Automatic PII detection** — Uses the `openai/privacy-filter` model locally
- **Pre/post processing** — Redact before LLM sees text, unredact in the response
- **Message format support** — Works with string and OpenAI vision-style list content
- **Configurable** — Adjust confidence thresholds and filter by entity type

## Installation

```bash
pip install nanobot-privacy-filter-hook
```

Requires:
- Python 3.11+
- `nanobot-ai` (for AgentHook interface)

## Quick Start

```python
from nanobot_hook import PrivacyFilterHook

# Create hook
hook = PrivacyFilterHook(min_score=0.8)

# Register with NanoBot's CompositeHook
from nanobot.agent.hook import CompositeHook

composite = CompositeHook([hook, other_hook])
# Pass composite to your NanoBot agent runner
```

## How It Works

1. `before_iteration()` — Creates a fresh `PiiStore`, redacts all text content in user/system messages
2. `finalize_content()` — Restores original values from placeholders in the LLM response

## Configuration

```python
from nanobot_hook import PrivacyFilterHook

hook = PrivacyFilterHook(
    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
)
```

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

## Example: Full Integration

```python
from nanobot.agent.hook import CompositeHook, AgentHookContext
from nanobot_hook import PrivacyFilterHook

# Create and register hook
pii_hook = PrivacyFilterHook(min_score=0.9)
composite = CompositeHook([pii_hook])

# The hook automatically processes messages before each LLM iteration
# and unredacts content before returning to the user
```

## Dependencies

- `privacy-filter` — Core PII detection library
- `nanobot-ai` (optional extra) — NanoBot AgentHook framework

## Related

- Core library: [privacy-filter](https://pypi.org/project/privacy-filter/)
- OpenAI Agents integration: [openai-agents-privacy-filter](https://pypi.org/project/openai-agents-privacy-filter/)

## License

MIT
