# Pseudonymisation
> Names, addresses and identifiers leave your workspace as placeholders, and the answer comes back with the real values. The replacing is pure algorithm, without a model in the path, and it learns from what a model in your own network finds.
When the AI Assistant answers, the question goes to the model of the provider you connected. With pseudonymisation switched on, that model never sees your customers' names, their e-mail addresses or their IBANs. The nexxus AI gateway swaps each of them for a placeholder such as `Person 1` or `Firma 1` before the request leaves, and puts the real values back into the answer before you read it.
Take Brandt & Söhne again, the installation company from [Connect your AI](/setup/connect-ai/). Their everyday model runs at IONOS, a cloud in the EU, where pseudonymisation is on by default. An employee asks for a payment reminder to a customer. IONOS writes the reminder to `Person 1` at `Firma 1`, and the employee reads it addressed to Erika Musterfrau at Musterbau GmbH.
## No model in the path
What the gateway replaces, it finds by table lookup and fixed patterns. No model decides whether a word is a name, and nothing is guessed: the same text gives the same placeholders every time. Replacing costs no tokens, and a request does not wait for a second model.
### What is recognised without a model
| Kind | Recognised by | Placeholder |
|---|---|---|
| People | Partners, contacts and employees in nexxus. A name after "Herr" or "Frau". | `Person 1` |
| Companies | Partners in nexxus. A name in front of a legal form such as GmbH or AG. | `Firma 1` |
| E-mail | The format. File names such as `logo@2x.png` stay. | `E-Mail 1` |
| Phone | International numbers (`+49`, `0049`) and national ones with separators. A bare run of digits only as a German mobile number or after "Tel.", "Fax" and the like. An amount (`%`, `€`) is no phone number. | `Telefon 1` |
| IBAN | The length for the country and the ISO 13616 check (mod 97). | `IBAN 1` |
| Addresses | A German street with house number (Straße, Weg, Gasse, Platz, Allee, Ring, Damm, Ufer), with postcode and town if they follow. | `Adresse 1` |
| Identifiers | Tax ID (check digit ISO 7064 MOD 11,10, spaced as the tax office prints it or after a label), social insurance number (check digit), health insurance number (check digit, after a label), payment card (card network and Luhn check, grouped as on the card or after a label). Your own patterns. | `Nummer 1` |
| Birth dates | A date only after a label such as "geboren am" or "Geburtsdatum". Deadlines and appointments stay. | `Geburtsdatum 1` |
| Terms | Your term rules, for example internal project names. | `Begriff 1` |
Tool results get the same treatment, and one more: fields that hold a first name, a last name, an e-mail address, a phone number or a tax number are replaced whole, and their values then wherever else they occur in the same request.
The detectors would rather miss a value than catch a wrong one. A false hit breaks the answer: an amount or a deadline that turned into `Telefon 1` is useless to the model. A miss is what the learning check below is for.
### How the placeholders behave
- **Readable words, numbered per kind** in the order they first appear: `Person 1`, `Person 2`, `Firma 1`. The model reads them as names and writes them back. The words are German in every language, because the gateway uses one set of labels.
- **Stable for the whole conversation.** `Firma 1` stays `Firma 1` in every turn, and a number once given never goes to a second value. Different spellings of the same value ("0171 1234567", "0171/1234567") share one placeholder.
- **Restored however the model writes them**: `FIRMA 1`, `Firma1`, `[Firma 1]` and the genitive `Firma 1s` all come back as the real value. The gateway also restores them in tool calls before a tool runs, so a search for `Person 1` searches for the real name.
- **A number the table does not know stays visible.** If the model invents `Person 7`, you read `Person 7`.
## It learns by itself
Rules cannot know every name. Someone mentions a supplier that is not in nexxus yet, or a customer number in a format no detector knows. To find those gaps, nexxus runs a check on a model you trust: one in your own network, or at Privatemode, where the model computes in an encrypted environment (confidential computing). That model never sits between your people and the provider. It only reads along afterwards, and what it finds becomes rules that again run without a model.
### What the check does
Every ten minutes the check takes a sample of the chat messages people wrote in the last 24 hours (25 % by default, only messages of at least 20 characters). The model of the check lists what in them it would protect, and nexxus compares that list with what the gateway replaced:
- **Recognised:** the gateway had replaced it. This is the share the hub shows.
- **Missed:** the gateway left it in the text. The miss becomes a question, together with the rule that would have caught it. If the request went out pseudonymised to a cloud provider, the miss is also a warning.
- **Too much:** the gateway replaced something the model did not list, for example a product name that looks like a company. That becomes a question for less protection.
Before a question is shown, nexxus tests its rule against all checked texts, so the question says how often it would hit (hits in 3 texts). Findings that need the same rule are merged into one question.
### Who answers
- **The person whose message it was** sees a card under that message in the chat: Quick question about pseudonymisation, with Yes, replace, No and Stop asking. A yes adds the term, spelling or pattern at once. More protection needs no administrator.
- **Administrators** decide everything in the hub, also what the chat cannot: less protection (an exception) and rules for a record field, which reach across all records.
- **Nobody**, for spellings of known records. If the check finds "Muster-Bau" for the partner Musterbau GmbH, the spelling becomes a rule without asking, because it only adds protection. You can switch that off with Adopt spellings of known records without asking.
### The protection prompt
In the tab Protection prompt you write in your own words what must never go out: "Our project names Falcon and Lighthouse are internal. Patient numbers look like P-123456." Suggest rules reads the text once with the model of the check and marks each passage: becomes a rule, check only (no fixed rule possible, the check watches for it) or exists already. You adopt the suggestions you want. That is the only model run. After it, the rules work without a model, and normal requests cost no tokens for them.
### The number and the next steps
The overview shows how much of what the check found the rules recognise: of the data found recognised automatically. The target is 95 %. Until the check has read texts there is no number, only Nothing checked yet, so a new workspace never starts with an estimate.
Below it, the card How recognition goes up lists what to do, in this order:
1. What keeps the check from measuring: pseudonymisation switched off, no safe model, none chosen or the chosen one no longer set up, the check switched off, today's budget used up.
2. Too few values found for a reliable number (it needs 10). A higher sample share gets there sooner.
3. Open questions to answer.
4. The kinds with the most misses, at most three, each with the step that fits: a partner or a term rule for names, a pattern rule for numbers with a fixed layout, the protection prompt for internal terms. If the misses are spread so thin that no kind stands out, the step is a higher sample share.
5. A protection prompt, if there is none yet, and spellings that wait for an answer.
Each step has a button that leads to where it is done. Once 95 % are reached, only the blockers remain.
## Before you start
- The admin role. The hub is for administrators only, because it can show the replaced values.
- At least one connected provider, see [Connect your AI](/setup/connect-ai/).
- For the learning check: a model in your own network (an OpenAI-compatible endpoint on a private host, for example Ollama or vLLM) or a model at Privatemode. Without one, replacing works all the same, but the check measures nothing.
## Switch it on
1. Open and there the tab Settings. In the section Pseudonymisation, set Pseudonymise AI requests to On and click Save.
Set to Count only, every request goes out in plain text and the gateway only counts what it would have replaced.
2. Leave Always pseudonymise providers outside the EU on. It is on from the start and puts every provider outside the EU on Always, also one set to Never or Off by default.
3. Open and a provider. Under Pseudonymisation, choose how it applies:
| Setting | In the chat |
|---|---|
| Always | Recognised names and identifiers go out as placeholders only. Cannot be switched off in the chat. |
| On by default | New chats start pseudonymised. Each person can switch it off for a conversation. |
| Off by default | New chats start in plain text. Each person can switch it on. |
| Never | The model always sees plain text. Meant for models in your own network. |
| Automatic | Follows where the provider computes, see below. |
Automatic is the starting value of every provider:
| Where the provider computes | Automatic means |
|---|---|
| A cloud outside the EU: OpenAI, Anthropic, Google and every other cloud, OpenAI-compatible cloud endpoints included | Always |
| A cloud in the EU: IONOS, Scaleway | On by default |
| Privatemode | Off by default |
| Your own network | Never |
4. In the tab Settings, choose the model under Model of the check and save. Only models in your network and at Privatemode can be chosen. nexxus takes exactly this model for the check, the protection prompt suggestions and the sandbox comparison, and no other. As long as none is chosen, the check pauses.
Optionally, under Automatic check you set:
- Check on
- Tokens per day, 50,000 by default
- Sample of messages, 25 % by default
- Adopt spellings of known records without asking
5. Switch to the tab Overview. The status reads Protection on. Work through How recognition goes up from the top.
6. Write the protection prompt in the tab Protection prompt, click Suggest rules and adopt the suggestions.
## What your team sees in the chat
In the chat's input area, a chip shows how the conversation goes out: Pseudonymised, Plain text or Own network. Where the provider is on On by default or Off by default, a click switches it for this conversation.
Every answer carries its data path. For a pseudonymised turn the gateway stop says "Replaces recognised names and identifiers with placeholders and restores them in the answer", and Replaced counts what was swapped. Placeholders do not show in the chat, because the answer arrives already restored. How to read an answer is described in [Working with the AI Assistant](/use/assistant/#read-an-answer).
## The hub
brings everything together on one page with eight tabs. The menu entry counts open questions and warnings, so they do not wait until someone opens the page.
| Tab | What you find there |
|---|---|
| Overview | The share recognised, the Learning curve (share per day, with a mark where the protection prompt changed), today's numbers (pseudonymised today, replaced too much, went out in plain text, open questions, check budget today), the share per kind and the next steps. Export report saves it as a file, for an auditor for example. |
| Questions | What the check found and votes from chats, each with its rule and how often it would hit. Adopt or Reject; for less protection Stop replacing or Keep replacing. Check now starts a check run at once. |
| Warnings | Data that went in plain text to a model outside your network although pseudonymisation was on: still in the request after replacing, or found by the check with no rule that knew it. |
| Rules | What nexxus replaces without asking a model, with origin and hits in 30 days. The built-in ones say Built in, always applies. Add rule, Archive, Export. |
| Replaced | What was replaced in the last 30 days. The values stay hidden until Show values, and showing them is logged. Entries disappear with their conversation. |
| Protection prompt | Your own words, the suggested rules and earlier versions under History. |
| Sandbox | Paste a text and see what the model would get. Nothing goes to a model unless you click Compare: then the same question runs once in plain text and once pseudonymised on the model of the check, and you see whether the answer gets worse. |
| Settings | The two switches of pseudonymisation, the model of the check and how much it reads. Nothing is stored until Save; Discard brings back the saved state. |
### Rules you add yourself
Add rule offers three kinds:
- **Term:** a word or a phrase, for example a project name.
- **Pattern:** for codes with a fixed layout. `#` is a digit, `A` an upper-case letter, `a` a lower-case letter, `*` a letter or a digit, and everything else stands for itself: `KD-#####` catches `KD-20417`. A pattern has 3 to 40 characters with at least three of these signs. nexxus never sends a regular expression to the gateway, so no rule can slow it down.
- **Exception:** a value that is never replaced, even when a pattern or a record matches. It means less protection, and the dialog says so.
A rule applies to the whole workspace. Spellings of records and rules for record fields come from the questions, not from this dialog. A spelling shares the placeholder of its record.
## What happens behind the scenes
- **One table per conversation.** The gateway keeps the pairs of value and placeholder next to the conversation's history, so a later turn restores placeholders from earlier turns.
- **No unprotected fallback.** If replacing fails, the request fails, rather than going out in plain text. If nexxus cannot be reached for the dictionary, the gateway uses the last one it fetched.
- **A second look before sending.** After replacing, the gateway scans the request again for protected values. Whatever it still finds becomes a warning in the hub.
- **Count only means count only.** In that mode the gateway runs the same work on a scratch copy, counts what it would have replaced and sends the request unchanged.
- **Images and files are not pseudonymised.** The gateway counts them and passes them through. Text in an image reaches the model as it is.
- **The check stays on the chosen model.** Before every call nexxus checks again that it runs in your network or at Privatemode. Once it is no longer set up there, the check pauses instead of moving to another model. It also stops when the day's token budget is used up.
## When something goes wrong
- **The overview says Nothing checked yet.** The card How recognition goes up names the reason. Most often: "The check needs a model in your network or at Privatemode. None is set up, so nothing is measured." Set up such a model as described in [Models on your own server](/setup/connect-ai/#models-on-your-own-server).
- **"No model is chosen for the check yet. Until one is, nothing is measured."** Choose it in the tab Settings under Model of the check.
- **"The chosen model of the check is no longer set up in your network or at Privatemode."** The provider was switched off, deleted or no longer runs in your network. Choose another model under Settings, or set the provider up again. Until then the check, the protection prompt suggestions and the sandbox comparison pause.
- **"Today's check budget is used up. It goes on tomorrow, or you allow more tokens per day."** Raise Tokens per day under Settings, or wait for the next day.
- **A name went out in plain text.** It shows in Warnings. To the question leads to the rule that would catch it. If there is no question, add a term rule, or create the person as a contact in nexxus, then nexxus recognises the name by itself.
- **Too much is replaced**, for example a product name with a legal form in it. Answer the question with Stop replacing, or add an exception.
- **The answer shows a placeholder** such as `Person 7`. The model wrote a number the table does not know. Ask again, or check in the Sandbox what the model got.
- **"Pseudonymisation could not be switched"** in the chat. The text after the colon gives the reason. Reload the page and switch again.
## Next steps