Metadata-Version: 2.4
Name: privacy-filter
Version: 0.1.0
Summary: PII redaction using the openai/privacy-filter token-classification model
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/privacy-filter#readme
License: MIT
Keywords: gdpr,hipaa,llm,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
Classifier: Topic :: Text Processing :: Filters
Requires-Python: >=3.11
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.40.0
Provides-Extra: examples
Requires-Dist: openai; extra == 'examples'
Requires-Dist: openai-agents; extra == 'examples'
Requires-Dist: python-dotenv; extra == 'examples'
Description-Content-Type: text/markdown

# privacy-filter

PII redaction for Python using the OpenAI privacy-filter model. Detect and redact personally identifiable information (PII) from text before sending to LLMs or storing in logs.

## Features

- **Local PII detection** — Uses the `openai/privacy-filter` HuggingFace model (runs locally, no API calls)
- **Reversible redaction** — Replace PII with placeholders like `[EMAIL_1]`, `[PERSON_2]`, then restore original values later
- **Entity types** — Email, phone, address, person names, URLs, dates, account numbers, secrets
- **Configurable thresholds** — Adjust confidence scores and filter by entity type
- **Thread-safe** — Lazy-loaded singleton pipeline with double-checked locking

## Installation

```bash
pip install privacy-filter
```

Requires Python 3.11+.

## Quick Start

```python
from privacy_filter import get_classifier, redact_text, unredact_text, PiiStore

# Load model (first run downloads ~50MB, cached after)
classifier = get_classifier()

# Detect PII
text = "My email is alice@example.com and my name is Alice Smith"
entities = classifier(text)

# Redact
store = PiiStore()
redacted = redact_text(text, entities, store)
print(redacted)  # "My email is [EMAIL_1] and my name is [PERSON_1]"

# Unredact (restore original values)
restored = unredact_text(redacted, store)
print(restored)  # "My email is alice@example.com and my name is Alice Smith"
```

## API Reference

### `get_classifier(cache_dir=None)`
Returns a HuggingFace token-classification pipeline. First call downloads the model (~50MB). Thread-safe singleton.

### `redact_text(text, entities, store, min_score=0.8, entity_types=None)`
Replaces detected entities with placeholders. Populates `store.forward` with placeholder → original mappings.

### `unredact_text(text, store)`
Restores original values from placeholders using regex substitution.

### `PiiStore`
Dataclass holding `forward` (placeholder→value dict) and `counters` (per-type counters).

## Supported Entity Types

| Entity | Placeholder Prefix | Description |
|--------|-------------------|-------------|
| `private_email` | `EMAIL` | Email addresses |
| `private_person` | `PERSON` | Person names |
| `private_phone` | `PHONE` | Phone numbers |
| `private_address` | `ADDRESS` | Physical addresses |
| `private_url` | `URL` | URLs |
| `private_date` | `DATE` | Dates |
| `account_number` | `ACCOUNT` | Account numbers |
| `secret` | `SECRET` | Passwords, API keys, tokens |

## Advanced Usage

### Filter by entity type
```python
entities = classifier(text)
redacted = redact_text(text, entities, store, entity_types=["private_email", "private_phone"])
```

### Adjust confidence threshold
```python
redacted = redact_text(text, entities, store, min_score=0.95)
```

### Custom cache directory
```python
classifier = get_classifier(cache_dir="/path/to/cache")
```

## Integrations

- **NanoBot** — `pip install nanobot-privacy-filter-hook`
- **OpenAI Agents SDK** — `pip install openai-agents-privacy-filter`

## License

MIT
