Metadata-Version: 2.4
Name: ag-pii-vault
Version: 0.6.0
Summary: PII tokenization SDK and proxy for AI pipelines
License: MIT
Author: Adnan Ghribi
Author-email: aghribi@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Provides-Extra: all
Provides-Extra: anthropic
Provides-Extra: openai
Requires-Dist: anthropic (>=0.40,<3) ; extra == "anthropic" or extra == "all"
Requires-Dist: httpx (>=0.27,<1)
Requires-Dist: openai (>=1.55.3,<2) ; extra == "openai" or extra == "all"
Requires-Dist: phonenumbers (>=8.13,<9.0)
Requires-Dist: preshed (!=3.0.14)
Requires-Dist: presidio-analyzer (>=2.2,<3.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: spacy (>=3.7,<4.0)
Project-URL: Homepage, https://github.com/aghribi/ag-pii-vault
Project-URL: Repository, https://github.com/aghribi/ag-pii-vault
Description-Content-Type: text/markdown

# ag-pii-vault

PII tokenization for LLM pipelines.

Detects personal data (names, emails, phone numbers and other Presidio entities), replaces it with deterministic HMAC tokens before text is sent to an LLM, and restores it in the response. Token mappings live in a local SQLite vault or in the hosted vault.

## Install

```sh
pip install "ag-pii-vault[all]"
npm install ag-pii-vault
```

Extras: `openai`, `anthropic`, `all`. Detection uses the spaCy model `en_core_web_lg`: `python -m spacy download en_core_web_lg`.

## Usage

```python
from ag_pii_vault import Detector, LocalVault, Tokenizer

detector = Detector()
tokenizer = Tokenizer(vault=LocalVault(path=":memory:"), key="my-hmac-secret")

text = "Contact John Smith at john@acme.com"
safe = tokenizer.tokenize(text, detector.analyze(text))
print(safe)                        # PII replaced by tokens
print(tokenizer.dehydrate(safe))   # original text restored
```

Output:

```
Contact PERSON_353fcd26 at EMAIL_9abc0eb1
Contact John Smith at john@acme.com
```

`SafeOpenAI` and `SafeAnthropic` wrap the official clients: messages are tokenized on the way out and restored on the way back.

The TypeScript package `ag-pii-vault` is a port of the core classes.

## Self-hosted API

`HostedVault` stores the token mappings in a self-run [ag-platform](https://github.com/aghribi/ag-platform) deployment instead of local SQLite. Pass `hosted_api_key` and `hosted_vault_url` to `SafeOpenAI` or `SafeAnthropic` (TypeScript: `new HostedVault({ apiKey, vaultUrl })`). There is no default endpoint.

## Development

```sh
cd packages/python && pip install -e ".[all]" && pytest
cd packages/typescript && npm ci && npm test
```

## License

MIT, Copyright (c) 2026 Adnan Ghribi.

