PII protection
Unified perimeter protection combining fast regex rules with ONNX token classification.
problem it solves
Prevents sensitive credentials, credit cards, and personal identity data from leaking to cloud APIs.
What it does
What it does: Scans outbound prompts for sensitive personal data and redacts or anonymizes matches pre-send.
What it watches: Emails, SSNs, credit cards, names, street addresses, and phone numbers — in the conversation. A system prompt (Anthropic's top-level `system`, OpenAI's `system` / `developer` messages) is not scanned by default, on any surface: it is the operator's instructions, not user data, so the same request measures the same on every door and a 180k-character system prompt costs the skill nothing. A deployment that keeps user data there opts in with `ACE_PII_SCAN_SYSTEM` (default off, deployment-level), and system spans are then scanned and redacted on every surface, against the same budget.
When it triggers: On any outbound prompt containing matched PII patterns or entity labels.
The learned stage is budgeted. Patterns are linear and always complete. The NER model costs ~28µs a token, so `ACE_PII_NER_BUDGET_MS` (default 50 — the documented skill ceiling; `0` lifts it) is the most it may spend on one request. Turns are scanned oldest first; when the budget runs out, the turns the model finished keep its redactions and the tail carries the patterns' alone, so the bytes of the prefix your provider has cached do not move from one turn to the next. The response says so: `x-ace-pii-skipped: ner_model=budget_exceeded`, `x-ace-pii-stages: ner_regex`.
The whole scan is also under the skill latency ceiling (250 ms per request; 50 ms in shadow) — the caller's clock, which counts time queued for a worker and the decision store's round trip, not only the model's. Past it the request is served on patterns alone and says `ner_model=ceiling_exceeded`; past it on the patterns pass too, `ner_model=<reason>,ner_regex=<reason>` with `x-ace-pii-stages: none`, and the request went upstream unredacted. `loop_stalled` in place of `ceiling_exceeded` means the gateway's event loop, not the scan, held the request. None of these is a quota: each verdict is one request's wall clock, and `GET /api/v1/settings` reads the ceilings back under `skill_ceiling`.
What the model has seen, it remembers. Results are memoized per span of text (offsets and labels, never the text; `ACE_PII_NER_MEMO_ENTRIES`, default 50,000). An agent loop replays every prior turn on every request; with the memo a 40-turn conversation costs the skill ~6ms a turn at any length, the history redacts byte-for-byte as it did on the previous turn, and a retry of a cut request picks up where the last one stopped.
The Action: Replaces detected PII tokens with synthetic placeholders (e.g., [EMAIL_1]) before transmission.
How it recovers: Restores original values in response payloads if deanonymization is configured.
What we need from you
- Stage 1 Regex Enginerequired
In-process pattern matching (<0.1ms latency, zero RAM overhead for emails, SSNs, credit cards).
- Stage 2 ONNX Runtime (Optional)recommended
Requires ~120MB RAM for Stage 2 bert-small model. Stage 1 regex runs standalone if ONNX weights fail to load.
What each mode does
| Mode | Effect on your request | What you can see |
|---|---|---|
| off | Not consulted. Prompts are transmitted with original unredacted text. | No pii_ner stage recorded. |
| shadow | Detects PII entities and logs telemetry without modifying the outbound payload. | Stage with action=would_redact and detected entity counts; `x-ace-pii-would-redact` carries the count and `x-ace-pii-redacted` is 0. |
| prod | Redacts detected PII tokens in-place before dispatching to provider. | `x-ace-pii-redacted` (count), `x-ace-pii-kinds` (`EMAIL=1,PERSON=2`), `x-ace-pii-stages` (`ner_regex`, `ner_model`, `ner_regex+ner_model`); `x-ace-pii-skipped: ner_model=budget_exceeded` when the budget cut the learned stage. Placeholder mapping logged. |
Current policy
| Stage 1 (Regex) | <0.1ms latency | Covers emails, SSNs, credit cards (Luhn validated), phone numbers, IPs. Always completes. |
| Stage 2 (ONNX Model) | bert-small (~2ms p50) | Covers unstructured names, addresses, and bank details. |
| Learned-stage budget | 50ms per request (`ACE_PII_NER_BUDGET_MS`; 0 lifts it) | Cooperative deadline, checked between 256-token windows and between spans, so an over-budget scan stops within one inference. The cut is prefix-safe: oldest turns first, the tail gets patterns only. |
| Span memo | 50,000 entries (`ACE_PII_NER_MEMO_ENTRIES`; 0 disables) | Keyed by the text's hash; stores offsets and labels, never text. A replayed history is a lookup. |
| System prompt | Never scanned | On every surface, including OpenAI `system` / `developer` messages. |
| Placeholder style | [ENTITY_TYPE_N] | Consistent synthetic token replacement. |
Worth knowing before you enable it
- ·A name in your system prompt is the product, not a leak — it is not redacted at the default. If you put user data in the system prompt, it is not covered until the deployment sets `ACE_PII_SCAN_SYSTEM`, which turns system scanning on for every tenant on that process and charges those spans to the same 50ms budget.
- ·The 50ms budget is enforced, and a prompt that routinely exceeds it is served with patterns only for its tail. Watch `x-ace-pii-skipped`, not latency; raise `ACE_PII_NER_BUDGET_MS`, pin `ACE_PII_NER_THREADS`, or narrow `ACE_PII_NER_ENTITIES` if it fires often.
- ·A span the budget cut fell inside gets the pattern result, never a partial model result — its redaction is a function of its text alone.
- ·Over-redaction can occasionally mask valid non-sensitive entity nouns.
- ·Regex stage takes precedence over neural model overlapping detections.
- ·Deanonymization mapping requires stateful session tracking.
What it replaces
- ·Client-side PII scrubbing libraries.
- ·Custom Presidio / SpaCy deployment pipelines.
- ·Manual regex token replacement functions.
Custom PII entity dictionaries and compliance vaults available on enterprise.
- ·Custom regex patterns and custom NER model fine-tuning.
- ·HIPAA / GDPR compliance audit exports.
- ·Local encryption key integration for token vaulting.