Documentation d'Anonimal

Anonimal détecte les PII dans le texte et les remplace selon un mode choisi. Un détecteur ne fait que trouver des plages ; le remplacement est décidé séparément. Tout s’exécute en local — les données d’origine ne quittent jamais la machine.

Quelles PII il détecte

La détection dépend du moteur actif.

Données structurées (les deux moteurs)

E-mails, numéros de téléphone, cartes de crédit (validées avec le contrôle de Luhn), URL, adresses IPv4 et secrets courants.

Identifiants LATAM (les deux moteurs)

Les numéros bancaires argentins DNI, CUIT / CUIL (avec chiffre de contrôle) et CBU.

PII en texte libre (moteur ML uniquement)

Les noms de personnes et les adresses dans une prose continue, via NER — la partie que la regex ne peut pas voir.

Règles personnalisées

Règles fournies par l’utilisateur : listes blanches toujours-masquer / jamais-masquer et vos propres motifs {regex, placeholder}.

Moteur : regex (lite) vs ML

Un détecteur expose detect(text) → [Span] ; les chevauchements sont résolus par la plage la plus longue (les égalités sont départagées par la priorité de l’étiquette).

• lite — regex uniquement. Léger, hors ligne, sans modèle. Couvre les données structurées et les identifiants LATAM ci-dessus. Il ne voit pas les noms ou adresses en texte libre. Toujours présent, même dans l’image lite et la bibliothèque anonimal_lite.
• ml — encapsule le OpenAI Privacy Filter (OPF, Apache-2.0). Précis pour les PII en texte libre. Lourd (~2,8 Go de checkpoint, ~3 Go de RAM), lié au CPU, chargé paresseusement en arrière-plan avec une inférence sérialisée. Optionnel.

Sélectionnez avec ANONIMAL_ENGINE : auto (ML si prêt, sinon lite) · lite · ml. Les requêtes peuvent remplacer la valeur par défaut au cas par cas avec un champ engine.

Modes de remplacement

Deux modes sont opaques (à sens unique) et un est réversible. Un seul anonymiseur est utilisé par document, de sorte que la même valeur reçoit toujours le même remplacement (cohérence).

Mode	Résultat	Réversible
typed	[EMAIL] (placeholder par catégorie)	non
anon	«REDACTADO» (jeton opaque unique)	non
pseudo	EMAIL_1 (pseudonyme numéroté stable)	oui (renvoie une table)
mask	j***@***.com / ****-****-****-1234 (selon le type)	non
hash	EMAIL_a1b2c3d4e5 (HMAC déterministe)	non

Marqueurs opaques

typed, anon, mask et hash produisent une sortie non réversible. Utilisez-les lorsque vous avez seulement besoin de partager ou stocker du texte en toute sécurité. Le mode hash est déterministe : définissez ANON_HASH_KEY pour que la même valeur soit hachée à l’identique entre les redémarrages (liaison stable sans stockage d’une table).

Mode réversible (réhydratation)

pseudo est le mode réversible. Il remplace chaque valeur par un jeton stable (EMAIL_1, PERSON_2, …) et renvoie une table token → original. Le flux de travail :

1. POST /anonymize avec mode: "pseudo" → obtenez la sortie anonymisée output plus la table map.
2. Envoyez output au LLM (les PII d’origine ne l’atteignent jamais).
3. POST /deanonymize avec la réponse du LLM et la même table map → les valeurs d’origine sont réhydratées dans le texte.

Attention

La table map est le seul moyen d’inverser la sortie pseudo. Gardez-la privée — elle contient les PII d’origine. Les quatre autres modes renvoient une table vide et ne peuvent pas être inversés.

Formats

Anonimal préserve le format des fichiers qui sont déjà du texte : txt, md, log, srt, html, CSV (cellules anonymisées, colonnes intactes) et JSON (valeurs de chaîne anonymisées, clés jamais touchées ; la sortie reste un JSON valide). Un seul anonymiseur par fichier signifie une table cohérente pour tout le document.

La conversion de Word / Excel / images / audio / URL n’est pas le travail d’Anonimal — cela revient à Escriba, Extracta et Fisherboy, qui fournissent en entrée du texte déjà converti. Anonimal offre toutefois une véritable rédaction de PDF (/redact_pdf) : un masquage authentique des plages détectées plus la suppression des métadonnées.

REST API

Tous les points de terminaison sauf /health sont protégés par require_auth (voir authentification). L’URL de base est votre déploiement, par ex. http://localhost:8920.

Méthode	Chemin	Ce qu’il fait
GET	/health	État + disponibilité du moteur ML. Toujours ouvert.
POST	/detect	{text} → plages détectées.
POST	/anonymize	{text, mode, engine?} → {output, map, summary}.
POST	/deanonymize	{text, map} → texte original.
POST	/anonymize_file	Téléversement de fichier + mode → contenu anonymisé (même format).
POST	/redact_pdf	PDF → PDF rédigé (masquage + métadonnées effacées).

POST /anonymize

Requête :

{
  "text": "email juan@acme.com, CUIT 20-12345678-6",
  "mode": "pseudo",
  "engine": "auto",
  "rules": null
}

Réponse :

{
  "engine": "lite",
  "mode": "pseudo",
  "output": "email EMAIL_1, CUIT ID_1",
  "spans": [
    { "label": "EMAIL", "start": 6, "end": 19, "text": "juan@acme.com" }
  ],
  "map": { "EMAIL_1": "juan@acme.com", "ID_1": "20-12345678-6" },
  "reversible": true,
  "summary": { "EMAIL": 1, "ID": 1 }
}

La table map n’est renseignée que pour pseudo ; reversible le reflète.

POST /deanonymize

{ "text": "reply to EMAIL_1", "map": { "EMAIL_1": "juan@acme.com" } }

→ { "output": "reply to juan@acme.com" }. Une table map manquante ou vide renvoie 422.

/anonymize hérité (compatible)

Appeler POST /anonymize sans mode renvoie le contrat hérité utilisé par l’Anonimal intégré — {text, detected_spans, redacted_text, summary} avec un placeholder par plage. Cela permet à Escriba et Fisherboy de pointer leur ANONIMAL_URL vers le nouveau service sans changer une seule ligne de code.

GET /health

Renvoie status, le moteur et le mode par défaut, et un bloc ml avec available, ready et error. Utilisé par le healthcheck du conteneur.

Erreurs

401 (jeton ou session manquant/invalide), 413 (texte ou PDF au-delà du plafond de taille), 422 (mode invalide / table manquante / rules_json invalide), 503 (moteur ML ou prise en charge des PDF indisponible).

Authentification

Anonimal accepte deux identifiants indépendants sur l’API :

• Jeton de service — définissez ANONIMAL_TOKEN. Chaque requête doit alors le porter, soit comme Authorization: Bearer <token>, soit comme l’en-tête X-Anonimal-Token. C’est ainsi qu’Escriba et Fisherboy s’authentifient sur le réseau interne.
• Session de navigateur — lorsque ANONIMAL_AUTH_ENABLED=true, un cookie signé depuis la page /login satisfait également le contrôle d’accès de l’API (pour l’interface web).

Si aucun n’est configuré, l’API est ouverte (elle suppose localhost). /health est toujours accessible pour les healthchecks.

Intégration à l’écosystème

Anonimal est l’unique responsable de l’anonymisation dans l’Escriba Suite ; les satellites lui délèguent cette tâche.

• Mode service — un produit avec ANONIMAL_URL défini appelle Anonimal via HTTP (couverture ML complète), en s’authentifiant avec X-Anonimal-Token.
• Solution de repli en bibliothèque — sans ANONIMAL_URL, un produit se rabat sur la bibliothèque anonimal_lite fournie (regex uniquement, stdlib pure), de sorte qu’il peut tout de même anonymiser de manière autonome.

pip install "anonimal-lite @ git+https://github.com/diegoparras/anonimal.git@v0.4.0"

from anonimal_lite import LiteEngine, Anonymizer, deanonymize

eng = LiteEngine()
out = Anonymizer("pseudo").process(text, eng.detect(text))

Il existe deux flux vers Anonimal : un parcours humain (Extracta/Fisherboy transmettent à Escriba via sessionStorage['escriba.handoff'], et le bouton « Anonymiser » d’Escriba appelle l’API) et un parcours automatique (un worker sans surveillance appelle l’API directement). Dans les deux cas, Anonimal reste le seul endroit où l’anonymisation se produit.

Règles personnalisées

/detect, /anonymize (champ rules) et /anonymize_file (rules_json) acceptent un objet de règles : always (toujours masquer), never (jamais masquer) et patterns ({regex, placeholder}). Les motifs sont un sur-ensemble des règles d’Escriba, avec RE2 optionnel pour se prémunir contre les ReDoS.