Persoonsgegevens verbergen voor het model¶

Schakel de capability pseudonymisation in om persoonsgegevens te vervangen voordat de modelleverancier de tekst van een beurt krijgt. Core zoekt namen, e-mailadressen, telefoonnummers, IBAN's, creditcardnummers en BSN's op in alles wat naar het model gaat, vervangt elke vondst door een plaatshouder als <PERSON_1>, en zet de oorspronkelijke waarden terug in alles wat jij terugkrijgt.

graph LR
    A[jouw applicatie] -->|jouw tekst| C[Artific Core]
    C -->|tekst met plaatshouders| M[model]
    M -->|antwoord met plaatshouders| C
    C -->|antwoord met jouw tekst| A

Alleen de modelleverancier ziet een plaatshouder. Het antwoord, de gestreamde fragmenten en de opgeslagen berichten van het gesprek bevatten je eigen tekst.

pseudonymisation heeft geen andere capability nodig. Een aanroep zonder opslag wordt net zo goed gepseudonimiseerd; threads zorgt er alleen voor dat de vertaaltabel na de beurt blijft bestaan, zodat een volgende beurt dezelfde persoon op dezelfde manier verbergt.

Instellen¶

De capability moet door je organisatie zijn toegestaan én op je sleutel zijn ingeschakeld. Je beheerder stelt per sleutel drie dingen in:

entities bevat standaard PERSON, EMAIL_ADDRESS, PHONE_NUMBER, IBAN_CODE, CREDIT_CARD en NL_BSN -- NL_BSN vindt iets in alle vijf talen, want het is een controlegetal over cijfers en geen kenmerk van de omringende taal. Vijf typen staan standaard uit en vraag je per sleutel aan: LOCATION (plaatsnamen en adressen vervangen kost een model veel van zijn bruikbaarheid), IP_ADDRESS, en de nationale identificatienummers die alleen bij hun eigen taal iets vinden -- DE_TAX_ID (Duitse Steuer-ID) en ES_NIF/ES_NIE (Spaanse identiteitsnummers). Een Franse tekst kent geen eigen identificatienummer: Core detecteert er alleen de taalneutrale typen.

entities noemt minstens één type. Een sleutel met een lege lijst wordt bij het opslaan geweigerd met 422 op capabilities.pseudonymisation.entities; wil je geen persoonsgegevens meer verbergen, zet dan de capability op de sleutel uit.

Een lagere score_threshold verbergt meer tekst en levert meer valse treffers op; een hogere laat twijfelgevallen door naar het model. GET /key geeft de instellingen terug die nu gelden:

{
  "capabilities": {
    "threads": {},
    "pseudonymisation": {
      "language": "nl",
      "entities": ["PERSON", "EMAIL_ADDRESS", "PHONE_NUMBER", "IBAN_CODE", "CREDIT_CARD", "NL_BSN"],
      "score_threshold": 0.5
    }
  }
}

Staat pseudonymisation niet in dat antwoord, dan gaat je tekst onveranderd naar de leverancier.

Per tool en per soort media¶

Het model krijgt altijd plaatshouders. Wat een tool krijgt die iets naar een andere partij stuurt, stel je per tool in met edges; wat er met afbeeldingen, opnames en spraak gebeurt met media:

"pseudonymisation": {
  "edges": [
    {"tools": "builtin:web_search", "mode": "clear"},
    {"tools": "mcp:crm", "mode": "detect", "arguments": ["note"]}
  ],
  "media": {"images": "allow", "audio": "self_hosted", "speech": "refuse"}
}

tools noemt builtin:web_search, builtin:web_fetch, builtin:generate_image, builtin:transcribe_audio (de prompt), builtin:computer, api:<connector>, sql:<connector>, mail:<connector>, mcp:<server>, script:<naam>, tool:<toolnaam> (een alias ook) of *; de meest specifieke regel geldt. arguments beperkt de regel tot die argumenten. Zonder regel geldt wat altijd gold: de web-, afbeeldings- en transcriptietools krijgen plaatshouders, elke andere tool de echte waarden. Tools van Core zelf (kennis, geheugen, datastores, bestanden) kun je niet instellen: ze sturen niets naar een andere partij. Een beslismodel (builtin__decide__<model>, POST /decisions) krijgt altijd plaatshouders, net als het chatmodel, en een spreektool (builtin__speak__<model>) volgt media.speech.

media zegt per soort allow (versturen zoals het is), self_hosted (alleen naar een model dat de beheerder van de omgeving als zelf gedraaid heeft aangemerkt) of refuse. Standaard gaan afbeeldingen en opnames gewoon mee en wordt spraak geweigerd. Een geweigerde afbeelding of opname is een 403 op het verzoek, of Denied by policy. voor de tool die haar zou versturen. Een afbeelding die al eerder in het gesprek staat, krijgt het model dan niet meer: het leest [image unavailable] op haar plek.

Je organisatie kan in haar beleidsdocument een ondergrens zetten, settings.pseudonymisation_floor, in dezelfde vorm; die geldt voor elke sleutel eronder die persoonsgegevens verbergt, en een sleutel kan alleen strenger zijn. De auditgebeurtenis pseudonymisation.applied noemt per tool wat die kreeg: edges, één regel per tool met aantallen, nooit een waarde.

Wat de detectie vindt¶

De detectie draait binnen Core en leest elke tekst zoals hij geschreven is, in de language van de sleutel. Met de standaard score_threshold van 0.5 mag je dit verwachten:

• Telefoonnummers die geschreven zijn zoals hun land ze schrijft worden verborgen, met of zonder een woord als "telefoon" in de buurt: 0612345678, 06-12345678, 06 1234 5678, 020-1234567, +31 6 12345678, en de nationale schrijfwijzen van België, Duitsland, Frankrijk, het Verenigd Koninkrijk en de Verenigde Staten. Een nummer uit een ander land wordt gevonden als het internationaal geschreven is, beginnend met + of 00. Andere cijfers, zoals een datum, een postcode met huisnummer of een ordernummer dat aaneen geschreven is zonder 0 vooraan, blijven staan, tenzij er een woord als "telefoon", "bellen" of "mobiel" bij staat. Een kenmerk dat als een telefoonnummer geschreven is, wordt als telefoonnummer verborgen: tien cijfers beginnend met 0, of tien cijfers in groepen zoals 2025-123-456.
• Namen worden gevonden door een naamherkenner voor de language van de sleutel. Die leest een volledige naam in een zin goed en mist sommige namen, en kan van een naam met een woord in kleine letters erin, zoals "van", alleen een deel vinden, zodat de rest leesbaar blijft. Een naam na een aanspreekvorm wordt daarnaast op schrijfwijze gevonden, en dus ook verborgen waar de herkenner hem miste: "mevrouw De Jong", "dhr. P. van der Meer", "de heer El Idrissi", "prof. dr. Hoekstra" op een Nederlandse sleutel; "Mr.", "Mrs.", "Ms.", "Dr." op een Engelse; "Herr", "Frau" op een Duitse; "M.", "Mme", "monsieur" op een Franse; "Sr.", "Sra.", "señor" op een Spaanse. De plaatshouder staat alleen voor de naam; de aanspreekvorm blijft in de tekst staan. Alleen de aanspreekvormen van de taal van de sleutel worden gelezen: "Mrs. Smith" op een Nederlandse sleutel hangt dus alleen van de herkenner af. Voluit geschreven titels worden ook gelezen: "dokter", "professor", "meester", "dominee", "zuster" en "broeder" op een Nederlandse sleutel, "Mister", "Doctor" en "Professor" op een Engelse. Op een Nederlandse sleutel tellen "mr", "dr", "ir" en "ing" zonder punt alleen voor een naam van twee delen of meer, zoals "dr P. Bakker"; "dr Bakker" hangt alleen van de herkenner af.
• Wat wordt verborgen zonder een naam te zijn: een woord met een hoofdletter na een aanspreekvorm dat geen naam is, zoals een merk ("Dr. Pepper"). Gewone woorden waarmee een zin begint en functies blijven staan ("meneer Dank", "Mr. President", "Herr Direktor"). Af en toe ziet de herkenner een woord met een hoofdletter voor een naam aan, zoals "Hallo" aan het begin van een zin. Met Een valse treffer corrigeren zet je dat per gesprek recht.
• Wat de detectie niet vindt: een naam zonder hoofdletters, vaak een losse voornaam, en een naam die gespeld, gecodeerd of door andere tekens onderbroken is. Tekst in een andere taal dan de language van de sleutel wordt gelezen alsof hij in die taal geschreven is; reken erop dat namen daarin minder betrouwbaar worden gevonden. Zie de detectie als een filter dat de meeste persoonsgegevens weghaalt, nooit als bewijs dat er geen meer staan.

Wat het model te zien krijgt¶

Een plaatshouder is <TYPE_n>: het gevonden type en een nummer dat per type doortelt, zoals <PERSON_1>, <PERSON_2> en <EMAIL_ADDRESS_1>. Core vervangt vondsten in alles wat het model leest: je instructions, de berichten van het gesprek en de resultaten van tools.

Core voegt één vaste mededeling aan de context toe, die het model vertelt dat plaatshouders ondoorzichtig zijn, dat elke plaatshouder voor precies één ding staat, en dat ze letterlijk moeten worden herhaald. Die tekst komt van Core en bevat niets van jou.

Soms laat een model de punthaken weg waar ze niet passen, bijvoorbeeld in een bestandsnaam als offerte_PERSON_1.md. Core zet ook daar de waarde terug, maar alleen voor een plaatshouder die het gesprek echt heeft uitgedeeld, en alleen waar er geen letter of cijfer vóór vastzit: offerte_PERSON_1.md wordt offerte_Jan Bakker.md. Antwoordt het model met een plaatshouder die de vertaaltabel niet kent — het verzon er een zoals PERSON_11, of mangelde een bestaande — dan krijg je die letterlijk terug. Core raadt niet naar wat hij betekend zou kunnen hebben. Een woord in hoofdletters dat geen type is dat Core herkent, zoals MAX_RETRIES_3, blijft altijd staan.

Tekst van jezelf waarin al iets staat dat op een plaatshouder lijkt, zoals <PERSON_1> of PERSON_1 getypt in een bericht of in je instructions, is geen plaatshouder van het gesprek. Core markeert het vóór de modelaanroep zodat het model het niet als plaatshouder leest, zet er geen waarde voor in de plaats en geeft het je terug zoals het getypt was.

Streamen verandert hier niets aan. Core houdt een fragment dat op een halve plaatshouder eindigt vast tot het volgende fragment de zaak beslist, dus in response.output_text.delta staat nooit een half vervangen naam.

Wat een gesprek onthoudt¶

Binnen één gesprek krijgt dezelfde tekst altijd dezelfde plaatshouder, ook in een volgende beurt van dagen later. De koppeling gaat over de letterlijke tekst: Jan Jansen en Jan zijn twee waarden en dus twee plaatshouders. Een waarde die de detectie later als een ander type leest, houdt de plaatshouder die hij al had. De enige uitzondering is twee beurten die tegelijk in het gesprek lopen: zie renumbered.

Een waarde die het gesprek kent, wordt verborgen overal waar ze staat in wat het model krijgt, ook waar de detectie haar niet opnieuw vindt: in een eerder bericht, in een eerder antwoord van het model, in het resultaat van een tool. Binnen één beurt wordt een naam die in het derde bericht is gevonden ook in het eerste verborgen. Deze vergelijking is letterlijk en op hele woorden: staat Jan in de vertaaltabel, dan wordt Jan verborgen waar het als woord staat, en blijven Jans, Januari, jan en JAN staan, tenzij de detectie ze zelf vindt. Beginnen twee bekende waarden op dezelfde plek, dan geldt de langste: Jan Jansen wordt als één waarde vervangen.

Een beurt zonder opslag (store: false, of een sleutel zonder threads) heeft een vertaaltabel die alleen tijdens die beurt bestaat. De bescherming is dezelfde; er is daarna alleen niets meer terug te lezen en een volgende aanroep begint opnieuw bij <PERSON_1>.

De vertaaltabel teruglezen¶

GET /threads/{thread_id}/pseudonyms geeft terug wat dit gesprek heeft verborgen, oudste eerst, met cursorpaginering:

curl -s "$CORE_URL/threads/thr_4Np8.../pseudonyms?limit=50" \
    -H "Authorization: Bearer $CORE_KEY"

{
  "items": [
    {
      "id": "psn_2Ktq...",
      "object": "pseudonym",
      "entity": "EMAIL_ADDRESS",
      "placeholder": "<EMAIL_ADDRESS_1>",
      "value": "jan.jansen@example.nl",
      "suppressed": false,
      "created_at": "2026-09-14T09:12:03Z"
    }
  ],
  "next_cursor": null
}

De route hoort bij de sleutel van de organisatie die het gesprek bezit. Mist je sleutel threads of pseudonymisation, dan antwoordt Core 404, niet te onderscheiden van een pad dat niet bestaat.

De tabel bevat wat jij en je tools in het gesprek hebben gebracht. Draait een beurt een verzegelde kopie van een andere organisatie, zoals een agent waarvan je de instructies niet kunt lezen, dan worden de namen en nummers in die verzegelde tekst net als alle andere voor de modelleverancier verborgen, maar ze zijn van de uitgever: ze krijgen geen rij, ze staan niet in een export, en de gebeurtenis pseudonymisation.applied telt ze niet mee. Een waarde uit de verzegelde tekst die je ook zelf meestuurt, staat vanaf die beurt gewoon in de tabel.

De rijen verdwijnen met het gesprek: DELETE /threads/{thread_id} verwijdert ze mee, en ze hebben geen eigen bewaartermijn.

Een valse treffer corrigeren¶

Verbergt de detectie iets wat geen persoonsgegeven is — een productnaam die als persoon wordt gelezen, bijvoorbeeld — dan zet je dat per rij stop:

curl -s -X DELETE "$CORE_URL/threads/thr_4Np8.../pseudonyms/psn_2Ktq..." \
    -H "Authorization: Bearer $CORE_KEY"

Het antwoord is 204. De rij blijft bestaan en krijgt suppressed: true. Dat betekent twee dingen:

• vanaf de volgende beurt gaat die exacte tekst onveranderd naar het model;
• de plaatshouder wordt nooit aan een andere waarde uitgedeeld, dus elk eerder bericht dat het model onder die plaatshouder heeft gelezen, gaat nog steeds over hetzelfde.

Er is geen route om een waarde of plaatshouder te wijzigen. Met de rijen verbergen latere beurten van het gesprek dezelfde waarden; ze achteraf herschrijven zou de geschiedenis van het gesprek onjuist maken.

Een verborgen waarde wordt verborgen in elk bericht waar ze als woord staat. Een valse treffer kost dus meer dan de zin waarin hij gevonden is: een woord als Hallo dat als persoon is gelezen, wordt in het hele gesprek vervangen totdat je het stopzet. Een waarde die je niet langer verbergt blijft heel: is Jan Jansen stopgezet en staat Jan nog in de vertaaltabel, dan gaat Jan Jansen onveranderd naar het model.

Als pseudonimisering niet kan draaien¶

Kan Core de tekst niet analyseren, dan gaat de beurt niet door. Core stuurt de tekst dan niet alsnog onvervangen naar de leverancier. Het antwoord komt terug met:

{
  "status": "failed",
  "error": {
    "code": "pseudonymisation_failed",
    "message": "Personal data could not be pseudonymised."
  }
}

Bij streamen komt hetzelfde antwoord als response.failed; een achtergrondrun eindigt op dezelfde manier. De HTTP-status is de gewone status van een gelopen beurt, dus lees altijd status in het antwoord. De aanroep die niet doorging, kost geen modeltokens: er is geen model aangeroepen.

Je kunt de beurt opnieuw sturen: de aanroep die faalde is nooit bij de leverancier aangekomen. Blijft het gebeuren, meld het dan bij je beheerder — de oorzaak zit in de installatie, niet in je verzoek.

Web- en afbeeldingstools¶

builtin__web_search, builtin__web_fetch en de builtin__generate_image__<model>-tools sturen wat het model schreef — een zoekopdracht, het adres van een pagina, een prompt voor een afbeelding — naar een dienst buiten je organisatie (Webpagina's ophalen en zoeken, Afbeeldingen genereren). Core zet de echte waarden terug in de argumenten van een toolaanroep voordat een tool draait, en haalt ze er voor deze tools zonder regel dus weer uit voordat de aanroep naar de dienst gaat: elke waarde die in de vertaaltabel van de beurt staat, wordt in de zoekopdracht, het adres of de prompt vervangen door de bijbehorende plaatshouder.

Zoekt het model op <PERSON_1> adres, dan krijgt de zoekdienst precies dat, en niet de naam. De aanroep wordt hierom nooit geweigerd en de beurt gaat door, maar het resultaat verandert wel: een zoekopdracht op een plaatshouder levert weinig op, een pagina waarvan het adres een verborgen waarde bevat wordt meestal niet gevonden (Web page could not be fetched.), en een prompt voor een afbeelding komt met de plaatshouder bij het afbeeldingsmodel aan. Wat je zelf terugleest — de toolaanroep in het antwoord en de stream — bevat nog steeds je eigen tekst, en de bronvermelding van een pagina waarvan het adres is herschreven noemt het adres waar de beurt om vroeg.

Wat dit wel en niet dekt:

• Er wordt hier niets gedetecteerd, tenzij de tool op detect staat. Alleen waarden die al in de tabel staan, worden vervangen. Wat de detectie in je tekst miste, of van een soort is die je sleutel niet verbergt (entities), stond nooit in de tabel en gaat onveranderd weg. Dat geldt ook voor een naam die het model zelf bedacht; dat is opzet, zodat het model nog steeds een publiek figuur kan opzoeken.
• Alleen exacte overeenkomsten. Een waarde wordt vervangen waar ze precies zo staat als in de tabel, en in een adres ook waar ze procent-gecodeerd is (Jan%20Jansen, Jan+Jansen). Andere hoofdletters, een andere schrijfwijze, een deel van een naam of een slug als jan-jansen wordt niet herkend. Het model heeft alleen de plaatshouder gezien, dus dit komt weinig voor, maar het wordt niet gecontroleerd.
• Een korte waarde wordt ook binnen een langer woord vervangen. Staat Jan in de tabel, dan gaat Januari weg als <PERSON_1>uari. Anders dan in wat het model krijgt, hoeft de waarde hier geen heel woord te zijn.
• Een waarde die je niet langer verbergt gaat onveranderd weg, net als naar het model.
• Zelf de tool aanroepen valt hier niet onder, tenzij de tool op detect staat. POST /tools/{name}/call is geen beurt: er is niets voor een model verborgen, dus er is geen tabel, en de zoekopdracht, het adres of de prompt die je schrijft, komt onveranderd bij de dienst aan; onder detect leest de detectie wat je schrijft. Een tool die het model binnen een beurt via core__call_tool aanroept, valt er wel onder, zoals elke andere aanroep van die beurt.
• Referentieafbeeldingen blijven ongemoeid, tenzij media.images ze tegenhoudt. Alleen de tekst van de prompt wordt herschreven.
• Een afbeelding die op de achtergrond wordt gemaakt, valt er net zo onder. Start het model een afbeeldingstool als taak, dan bewaart Core de items van de tabel die de prompt bevat, versleuteld bij de taak, en vervangt ze als de taak draait; ze worden verwijderd als de taak eindigt. Ze liggen vast bij de start van de taak, dus een waarde die je daarna niet langer verbergt, wordt in de prompt van die taak toch vervangen.

Audio¶

Een opname gaat zoals ze is naar de leverancier van het audiomodel, ook op een sleutel met deze capability. De detectie leest tekst, en een opname heeft geen tekst totdat de leverancier haar heeft getranscribeerd. De stemmen en elke naam die in een opname wordt uitgesproken, bereiken de leverancier dus, of je de opname nu naar POST /audio/transcriptions stuurt, aan de transcriptietool geeft of in een input_audio-deel zet (Audio transcriberen). Welke leverancier dat is en in welke regio die draait, bepaalt het beleid van je sleutel voordat er iets wordt verstuurd; kies een audiomodel waarvan je de regio accepteert, of houd opnames tegen met media.audio (Per tool en per soort media).

Wat er daarna met de tekst gebeurt:

• In een gesprek wordt het transcript verborgen zoals alle andere tekst. Het transcript van een input_audio-deel is het eigen bericht van je gebruiker, en het resultaat van de transcriptietool is een toolresultaat; het chatmodel leest beide met persoonsgegevens vervangen door plaatshouders.
• De prompt van de transcriptietool wordt herschreven zoals een afbeeldingsprompt (Web- en afbeeldingstools): een waarde die de beurt verborg, wordt door haar plaatshouder vervangen voordat de prompt naar de leverancier gaat.
• POST /audio/transcriptions is geen beurt. Het geeft je het transcript terug zoals de leverancier het hoorde; er wordt niets voor je verborgen.

Wat in leesbare vorm blijft¶

Deze capability beperkt één ding: wat een modelleverancier over een beurt te zien krijgt. De rest blijft leesbaar, en dat is opzet:

• Tools krijgen de echte waarden, tenzij hun regel anders zegt. Een toolaanroep is een aanroep die Core namens jou op jouw eigen endpoint, MCP-server of index doet, dus Core zet de plaatshouders in de argumenten terug voordat de tool draait. Een function_call die je zelf moet uitvoeren, krijg je ook met echte waarden terug. De web- en afbeeldingstools zijn de uitzondering, omdat zij wat het model schreef naar een dienst buiten je organisatie sturen: zie Web- en afbeeldingstools hierboven.
• De opgeslagen geschiedenis staat in leesbare vorm. Berichten, samenvattingen, geheugenrecords en het antwoordobject bevatten je eigen tekst, en de arguments van een taak die het model startte ook. De vertaaltabel zelf is nog een plek waar die tekst staat; dat alles verdwijnt als je het gesprek verwijdert.
• Zoeken en indexeren zijn niet gedekt. Kennis en geheugen sturen hun teksten en zoekvragen onveranderd naar de leverancier die de embeddings maakt: een plaatshouder zou de vector veranderen, waardoor een index die anders is opgebouwd niet meer zou matchen. Het indexeren van een kennisbron draait buiten elke beurt, dus de modelstappen in zo'n pipeline lezen de tekst van de bron zoals die is. Hetzelfde geldt voor POST /knowledge/retrieval-tools/{id}/query en POST /knowledge/pipelines/{id}/test: ook die draaien buiten een beurt en krijgen je vraag en de gevonden tekst onveranderd. Dezelfde stappen die een beurt bereikt via een retrieval-tool, gaan wel door de vervanging heen.
• Afbeeldingen zijn niet gedekt. De detectie leest tekst; een afbeelding gaat naar de leverancier zoals hij binnenkwam, of helemaal niet als media.images haar tegenhoudt.
• Audio is niet gedekt. Een opname gaat naar de leverancier van het audiomodel zoals ze binnenkwam, of helemaal niet als media.audio haar tegenhoudt; zie Audio.

Elke beurt waarin de capability gold, levert een auditgebeurtenis pseudonymisation.applied op met alleen aantallen: hoeveel plaatshouders per type zijn verstuurd, hoeveel er zijn teruggezet, hoeveel er niet oplosbaar waren, en renumbered. Het stopzetten van een rij levert pseudonym.suppressed op met het id van die rij. In geen van beide gebeurtenissen staat tekst.

renumbered is alleen hoger dan nul als twee beurten tegelijk in hetzelfde gesprek liepen. Elke beurt nummert zijn nieuwe plaatshouders vanaf de vertaaltabel zoals die bij het begin van de beurt was, dus beide kunnen <PERSON_2> uitdelen, elk voor een andere waarde. De beurt die het eerst wordt opgeslagen, houdt zijn nummers. De waarden van de andere beurt worden opgeslagen onder het eerstvolgende vrije nummer, of onder de plaatshouder die de eerste beurt er al aan gaf, en renumbered telt bij hoeveel plaatshouders van die beurt dat gebeurde. Het antwoord dat je kreeg en de opgeslagen berichten veranderen daardoor niet: daarin staat je eigen tekst. De trace van die beurt wel: die toont de nummers die het model las, en die zijn niet op te zoeken in de vertaaltabel. Stuur de beurten van één gesprek na elkaar als elke trace herleidbaar moet zijn.