Documentazione di Anonimal

Anonimal rileva le PII nel testo e le sostituisce secondo una modalità scelta. Un rilevatore si limita a trovare gli intervalli; la sostituzione è decisa separatamente. Tutto gira in locale — i dati originali non lasciano mai la macchina.

Quali PII rileva

Il rilevamento dipende dal motore attivo.

Dati strutturati (entrambi i motori)

Email, numeri di telefono, carte di credito (validate con il controllo di Luhn), URL, indirizzi IPv4 e segreti comuni.

Identificatori LATAM (entrambi i motori)

DNI argentino, CUIT / CUIL (con cifra di controllo) e numeri bancari CBU.

PII in forma libera (solo motore ML)

Nomi di persone e indirizzi in prosa corrente, tramite NER — la parte che la regex non può vedere.

Regole personalizzate

Regole fornite dall’utente: whitelist di sempre-nascondi / mai-nascondi e i tuoi pattern {regex, placeholder}.

Motore: regex (lite) vs ML

Un rilevatore espone detect(text) → [Span]; le sovrapposizioni sono risolte con lo span più lungo (i pareggi sono risolti dalla priorità dell’etichetta).

• lite — solo regex. Leggero, offline, senza modello. Copre i dati strutturati e gli identificatori LATAM sopra. Non vede nomi o indirizzi in forma libera. Sempre presente, anche nell’immagine lite e nella libreria anonimal_lite.
• ml — incapsula l’OpenAI Privacy Filter (OPF, Apache-2.0). Accurato per le PII in forma libera. Pesante (~2.8 GB di checkpoint, ~3 GB di RAM), vincolato alla CPU, caricato in modo lazy in background con inferenza serializzata. Opzionale.

Seleziona con ANONIMAL_ENGINE: auto (ML se pronto, altrimenti lite) · lite · ml. Le richieste possono sovrascrivere il valore predefinito per ogni chiamata con un campo engine.

Modalità di sostituzione

Due modalità sono opache (a senso unico) e una è reversibile. Un singolo anonimizzatore è usato per documento, così lo stesso valore ottiene sempre la stessa sostituzione (coerenza).

Modalità	Risultato	Reversibile
typed	[EMAIL] (placeholder per categoria)	no
anon	«REDACTADO» (singolo token opaco)	no
pseudo	EMAIL_1 (pseudonimo numerato stabile)	sì (restituisce una mappa)
mask	j***@***.com / ****-****-****-1234 (consapevole del tipo)	no
hash	EMAIL_a1b2c3d4e5 (HMAC deterministico)	no

Marcatori opachi

typed, anon, mask e hash producono un output non reversibile. Usali quando hai solo bisogno di condividere o archiviare il testo in modo sicuro. La modalità hash è deterministica: imposta ANON_HASH_KEY così lo stesso valore produce lo stesso hash tra i riavvii (collegamento stabile senza archiviare una mappa).

Modalità reversibile (re-idratazione)

pseudo è la modalità reversibile. Sostituisce ogni valore con un token stabile (EMAIL_1, PERSON_2, …) e restituisce una mappa token → originale. Il flusso di lavoro:

1. POST /anonymize con mode: "pseudo" → ottieni l’output anonimizzato più la map.
2. Invia l’output all’LLM (le PII originali non lo raggiungono mai).
3. POST /deanonymize con la risposta dell’LLM e la stessa map → i valori originali vengono re-idratati nel testo.

Attenzione

La map è l’unico modo per invertire l’output pseudo. Tienila privata — contiene le PII originali. Le altre quattro modalità restituiscono una mappa vuota e non possono essere invertite.

Formati

Anonimal preserva il formato dei file che sono già testo: txt, md, log, srt, html, CSV (celle anonimizzate, colonne intatte) e JSON (valori stringa anonimizzati, chiavi mai toccate; l’output rimane JSON valido). Un singolo anonimizzatore per file significa una mappa coerente per l’intero documento.

Convertire Word / Excel / immagini / audio / URL non è compito di Anonimal — quello spetta a Escriba, Extracta e Fisherboy, che gli forniscono testo già convertito. Anonimal offre però un vero oscuramento dei PDF (/redact_pdf): un autentico annerimento degli intervalli rilevati più la rimozione dei metadati.

REST API

Tutti gli endpoint tranne /health sono protetti da require_auth (vedi autenticazione). L’URL base è il tuo deployment, ad es. http://localhost:8920.

Metodo	Percorso	Cosa fa
GET	/health	Stato + disponibilità del motore ML. Sempre aperto.
POST	/detect	{text} → intervalli rilevati.
POST	/anonymize	{text, mode, engine?} → {output, map, summary}.
POST	/deanonymize	{text, map} → testo originale.
POST	/anonymize_file	Caricamento file + mode → contenuto anonimizzato (stesso formato).
POST	/redact_pdf	PDF → PDF oscurato (annerimento + metadati cancellati).

POST /anonymize

Richiesta:

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

Risposta:

{
  "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 map è popolata solo per pseudo; reversible lo riflette.

POST /deanonymize

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

→ { "output": "reply to juan@acme.com" }. Una map mancante o vuota restituisce 422.

Legacy (drop-in) /anonymize

Chiamare POST /anonymize senza una mode restituisce il contratto legacy usato dall’Anonimal incorporato — {text, detected_spans, redacted_text, summary} con un placeholder per intervallo. Questo permette a Escriba e Fisherboy di puntare il loro ANONIMAL_URL al nuovo servizio senza cambiare una riga di codice.

GET /health

Restituisce status, il motore e la modalità predefiniti, e un blocco ml con available, ready ed error. Usato dall’healthcheck del container.

Errori

401 (token o sessione mancante/non valido), 413 (testo o PDF oltre il limite di dimensione), 422 (modalità non valida / mappa mancante / rules_json non valido), 503 (motore ML o supporto PDF non disponibile).

Autenticazione

Anonimal accetta due credenziali indipendenti sull’API:

• Token di servizio — imposta ANONIMAL_TOKEN. Ogni richiesta deve quindi includerlo, o come Authorization: Bearer <token> o come header X-Anonimal-Token. È così che Escriba e Fisherboy si autenticano sulla rete interna.
• Sessione del browser — quando ANONIMAL_AUTH_ENABLED=true, un cookie firmato dalla pagina /login soddisfa anch’esso il controllo dell’API (per la UI web).

Se nessuno dei due è configurato, l’API è aperta (assume localhost). /health è sempre raggiungibile per gli healthcheck.

Integrazione nell’ecosistema

Anonimal è l’unico titolare dell’anonimizzazione nella Escriba Suite; i satelliti gli delegano.

• Modalità servizio — un prodotto con ANONIMAL_URL impostato chiama Anonimal via HTTP (copertura ML completa), autenticandosi con X-Anonimal-Token.
• Fallback libreria — senza ANONIMAL_URL, un prodotto ricade sulla libreria anonimal_lite inclusa (solo regex, pura stdlib), così può comunque anonimizzare in modalità standalone.

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))

Ci sono due flussi verso Anonimal: un percorso umano (Extracta/Fisherboy passano il testimone a Escriba via sessionStorage['escriba.handoff'], e il pulsante “Anonymize” di Escriba chiama l’API) e un percorso automatico (un worker non presidiato chiama l’API direttamente). In entrambi i casi, Anonimal rimane l’unico posto in cui avviene l’anonimizzazione.

Regole personalizzate

/detect, /anonymize (campo rules) e /anonymize_file (rules_json) accettano un oggetto di regole: always (nascondi sempre), never (non nascondere mai) e patterns ({regex, placeholder}). I pattern sono un sovrainsieme delle regole di Escriba, con RE2 opzionale per proteggere dal ReDoS.