Configuration
All settings are environment variables prefixed PALENA_PSEUDONYMIZER_. The service validates them on startup and refuses to boot on invalid config. The full list is in the Environment variables reference; this page covers the choices that matter most.
Entities
PALENA_PSEUDONYMIZER_PRESIDIO_ENTITIES=PERSON,ORGANIZATION # defaultLOCATION is off by default. Masking a city (Paris → Riverside) replaces one real place with another real-sounding place, and the model then reasons from the wrong geography — wrong weather, wrong currency, "which Riverside do you mean?". Person and organization names are pure identity and safe to swap; place names carry semantics the model needs. Add LOCATION back only if your threat model requires geography masking.
You can enable any entity type Presidio detects — add structured PII such as credit cards, national IDs, emails or phone numbers:
PALENA_PSEUDONYMIZER_PRESIDIO_ENTITIES=PERSON,ORGANIZATION,CREDIT_CARD,US_SSN,EMAIL_ADDRESSHow each type is substituted depends on its strategy.
Substitution strategy
Not all PII should be masked the same way. A fake name for a credit card is meaningless, and the model rarely needs the real digits — it just needs to know a value was there. So there are two strategies:
| Strategy | Output | Right for |
|---|---|---|
pool | a realistic fictional value (Alice Johnson → Jordan Avery) | nominal identities the model reasons about: PERSON, ORGANIZATION, LOCATION |
token | a consistent reversible placeholder (4111… → <CREDIT_CARD_1>) | structured PII: CREDIT_CARD, US_SSN, IBAN_CODE, EMAIL_ADDRESS, phone numbers, insurance / ID numbers, custom types |
# Default strategy for enabled types that aren't nominal identities:
PALENA_PSEUDONYMIZER_ENTITY_STRATEGY_DEFAULT=token # token | pool
# Per-type overrides (comma-separated TYPE:strategy):
PALENA_PSEUDONYMIZER_ENTITY_STRATEGY=PHONE_NUMBER:pool,CREDIT_CARD:tokenResolution order for a given entity type:
- an explicit
ENTITY_STRATEGYoverride, else poolif the type isPERSON/ORGANIZATION/LOCATION, elseENTITY_STRATEGY_DEFAULT(token).
So simply adding CREDIT_CARD to PRESIDIO_ENTITIES tokenizes it automatically — no strategy config needed for the common case. Tokens are <TYPE_N> where N is a per-type, per-session counter, so the same value maps to the same token across a conversation and reverses back to the exact original (case and all).
Detecting structured / country-specific PII
Presidio recognises many types out of the box (CREDIT_CARD, US_SSN, IBAN_CODE, EMAIL_ADDRESS, PHONE_NUMBER, US_PASSPORT, UK_NHS, …). Country-specific IDs (national identity cards, insurance numbers) usually need a custom recognizer — add a regex or deny-list recognizer the same way you add the organization deny-list.
Detection engine
DETECTION_ENGINE (chart config.detectionEngine, default ner in the chart, presidio for the bare service) picks how names are found:
| Engine | Names (PERSON) | Pattern types (email, phone, IBAN, card, IP, …) | Languages |
|---|---|---|---|
ner | NER service: one multilingual span model (GLiNER2-PII) | Presidio's pattern recognizers | Any — no language detection |
presidio | Presidio's spaCy NER, one model per language | Presidio | PRESIDIO_LANGUAGE(S) |
With ner, every line of a text (a gateway that joins a conversation puts one message per line) is analyzed on its own, and a line longer than NER_CHUNK_CHARS (1000) characters is cut into windows overlapping by NER_CHUNK_OVERLAP (150). The model is trained on short inputs: given a whole conversation at once it stops finding names, and its memory grows with the square of the input length. Spans need a confidence of NER_THRESHOLD (0.9); ENTITY_SCORE_THRESHOLD overrides that per type.
NER_ENTITY_LABELS maps entity types to the model's labels (default PERSON:person|full_name|first_name|last_name,ORGANIZATION:organization). A type is taken from the NER service only when it is also in PRESIDIO_ENTITIES; every other enabled type goes to Presidio, always analyzed in PRESIDIO_LANGUAGE. ORGANIZATION through the zero-shot organization label is experimental.
On a hand-labelled en/de/fr/it/hu test set, the model behind the ner engine reached an F1 of 0.87 for person names, against 0.76 for the presidio engine with per-language spaCy models (on Hungarian, which the multilingual analyzer has no model for, 0.87 against 0.52). Extended to 15 European languages (plus es pt nl pl cs sv da ro fi el) it stayed at 0.88.
Each pod keeps a cache of what the model found in a line (NER_CACHE_ENTRIES, default 500000 — about 100 MiB full; NER_CACHE_TTL, default 1h): a gateway that sends the whole conversation every turn then only costs model time for the new lines. Only SHA-256 digests of the lines are kept, never the text.
The model runs on CPU and answers one batch at a time per pod, so the first look at a long conversation (hundreds of lines of pasted logs or code) can take a while: send batches in parallel with NER_PARALLEL and run as many NER replicas. Each batch is cached as soon as it returns, so a request the gateway gives up on still leaves its progress for the next turn. Give the gateway's guardrail call enough time (in Wäg: the guardrail item's timeout_ms, default 2500 — 10000 or more is safer); a caller that gives up mid-call is logged as caller_canceled, not as the NER service being down.
Known gaps: product names in English chat (add them to the allow-list), nouns that are also surnames (Kowal, Pekař), and heavily inflected names where only part clears the threshold (Kovács Péternek → only Kovács).
Languages
This section applies to DETECTION_ENGINE=presidio; the ner engine needs no language setting.
Presidio's name detection is per language: German text analyzed as English misses most German names and tags ordinary words ("Bitte") as organizations. List the languages your users write in:
PALENA_PSEUDONYMIZER_PRESIDIO_LANGUAGES=en,de,fr,itEach message is classified among the listed languages (offline, with lingua-go) and analyzed in its own language; text too short or ambiguous to classify uses the first one. With one language nothing is classified.
Presidio needs an NLP model for every listed language. The stock presidio-analyzer image ships English only; the chart switches to ghcr.io/palenaai/palena-presidio-analyzer (Presidio plus the German, French and Italian models) as soon as config.languages holds anything but English, and renders the analyzer's NLP, recognizer and language config to match. Each extra language needs roughly 800Mi more analyzer memory.
Score thresholds per entity type
PRESIDIO_SCORE_THRESHOLD (0.7) applies to every type unless ENTITY_SCORE_THRESHOLD overrides it:
PALENA_PSEUDONYMIZER_ENTITY_SCORE_THRESHOLD=PHONE_NUMBER:0.4,EMAIL_ADDRESS:0.9Presidio's phone recognizer scores every match 0.4, which is why the default lowers PHONE_NUMBER only: under 0.7 no phone number would ever be masked.
Allow-list
Terms that should never be pseudonymized, even when they are detected:
PALENA_PSEUDONYMIZER_ALLOW_LIST=Palena,Acme Rockets,Ada Lovelace,Alexa,SiriMatched case-insensitively against the detected span, also with a short inflection ending (up to five letters, optionally after - or '): Linux covers Linuxra, Linuxon, Linux's. A span that contains the term among other words (Siri Johnson) is still pseudonymized — it may be a person.
A built-in list of product, platform and tool names (ChatGPT, Bitwarden, KeePassXC, 1Password, Proton Pass, Linux, Docker, Kubernetes, Heroku, GitHub, Excel, …) is added unless ALLOW_LIST_BUILTIN=false. It leaves out names that are also people's names — Alexa, Siri, Claude, Jenkins, Kafka, Render — because allow-listing those would leak a person with that name; add them yourself when your traffic is about the products.
Use the allow-list for:
- your own brand / product names — you don't want "Palena" swapped for a fake org in every prompt;
- public figures or well-known entities that carry no client PII;
- words Presidio over-tags — e.g. the generic NER tagging "SSN" as an
ORGANIZATION(a false positive you saw in testing).
Separately from the allow-list, a PERSON span is ignored when it cannot be a name: no letters, more than five words, four or more words all in lower case (hi which passwd mgr), or a single lower-case word of three letters or fewer (mgr, brb).
It's the symmetric counterpart to the deny-lists below: a deny-list adds detections, the allow-list suppresses them. Allow-listed terms are also excluded from first/last-name decomposition, so an allow-listed surname never leaks a sub-mapping.
Deny-lists
Terms that should always be pseudonymized, as a given entity type, whether or not Presidio's NER would find them — client names, project code names, internal people. Set them in the chart (they become exact-match Presidio recognizers in every configured language):
presidio:
analyzer:
denyLists:
- entity: ORGANIZATION
terms: [Contoso Ltd, Fabrikam]
- entity: PERSON
terms: [Project Falcon]The entity type must also be in config.entities. With the ner engine the types the NER model serves (PERSON, and ORGANIZATION when enabled) never reach Presidio, so the service matches their lists itself — the same way: exactly, case-insensitively, as whole words. The chart passes them as PALENA_PSEUDONYMIZER_DENY_LISTS (JSON); you set nothing extra. The older presidio.analyzer.organizations list still works and is the same as an ORGANIZATION entry.
Deterministic pseudonyms
By default a real name gets the next free pool pseudonym per session, so the same person may map to different pseudonyms in different conversations. Set a secret to make pool assignment deterministic — the same real value maps to the same pool pseudonym across every session:
PALENA_PSEUDONYMIZER_DETERMINISTIC_SECRET=<random-secret>The pseudonym is chosen by a keyed HMAC-SHA256(secret, name) over the pool, probing forward on a within-session collision. This gives stable, portable pseudonyms — useful when you correlate pseudonymized data across sessions or want reproducibility after a Redis flush. Trade-offs:
- Reversal still uses the session store (HMAC is one-way) — this changes which pseudonym is picked, not whether state is stored.
- Cross-session determinism means a fixed name↔pseudonym relationship, i.e. less per-session unlinkability. Only enable it if that's what you want.
- Applies to the pool strategy only; token entities keep their per-session counter. Treat the secret like any other credential.
Pseudonym pools
Each entity type draws pseudonyms from a pool:
PALENA_PSEUDONYMIZER_POOL_PERSON=Jordan Avery,Taylor Morgan,Alex Rivera,...
PALENA_PSEUDONYMIZER_POOL_ORGANIZATION=Acme Corp,Birch Industries,...The default PERSON pool is gender-neutral on purpose. A pseudonym carries an implied gender the model reasons from — map a female name to "Thomas" and the model writes "he", leaking a wrong attribute. Unisex names (Jordan, Taylor, Alex, Riley…) give the model no strong prior, so it says "they" or asks. This is pure pool curation; there is no gender logic in the service.
Person-name decomposition
PALENA_PSEUDONYMIZER_DECOMPOSE_PERSON_NAMES=true # defaultWhen on, mapping "Alice Johnson → Jordan Avery" also records "Alice → Jordan" and "Johnson → Avery", so a model that refers to just the first name still reverses correctly and later turns stay consistent. A real surname that is also a common noun (e.g. "Baker") can over-match; set this to false if your inputs contain many such names.
Images
PALENA_PSEUDONYMIZER_NON_TEXT_PII_ACTION=redact # redact | block | passthrough- redact (default) — forward a redacted copy of the image.
- block — reject the request with a user-facing message.
- passthrough — forward the original untouched (not recommended).
Failure behaviour
The guardrail is fail-closed on the way to the model: if Presidio or Redis is unreachable during the pre-call phase, the request is blocked so real names cannot leak. On the post-call phase it is best-effort — a reversal failure never turns a successful LLM response into an error.
Operators control the final policy with LiteLLM's unreachable_fallback (fail_closed recommended).
Authentication
PALENA_PSEUDONYMIZER_API_KEY=<shared-secret>When set, clients (i.e. the LiteLLM proxy) must send it as an x-api-key header. When empty, the service accepts any request — fine for a private in-cluster deployment, not for an exposed one.
Session erasure
Mappings expire on their own via the Redis TTL, but you can erase one on demand — e.g. to honour a GDPR right-to-erasure request or tear down a finished conversation:
curl -X DELETE http://pseudonymizer:8080/sessions/<session_id> \
-H "x-api-key: $PALENA_PSEUDONYMIZER_API_KEY"Returns 200 {"deleted": true|false} — deleted reports whether a mapping existed (the call is idempotent). The endpoint is guarded by the same API_KEY shared secret as the guardrail endpoint; leave the key unset only in a trusted, in-cluster deployment.