# Anonimizzatore Gare d'Appalto ### Presentazione del Progetto --- ## Cos'è Applicazione web per l'**anonimizzazione automatica di documenti italiani di gara d'appalto** (*capitolati, determine, bandi, contratti*). Identifica e oscura i dati personali e sensibili presenti nel testo — codici fiscali, partite IVA, nomi, indirizzi, importi, CIG, PEC, IBAN — preservando la struttura e la leggibilità del documento. Distribuita come **Hugging Face Space** (Gradio), eseguibile anche in locale. --- ## Problema affrontato I documenti di gara contengono informazioni sensibili che, prima della pubblicazione o condivisione, devono essere oscurate: - **Dati anagrafici**: nomi di RUP, commissari, direttori lavori - **Dati fiscali**: codici fiscali, partite IVA delle imprese - **Dati di contatto**: PEC, email, telefoni - **Dati finanziari**: importi base d'asta, IBAN, polizze - **Codici univoci**: CIG, CUP, CPV, REA, NUTS L'oscuramento manuale è **lento, soggetto a errori e non scalabile**. L'automazione richiede comprensione del dominio giuridico-amministrativo italiano — un contesto altamente specifico. --- ## Architettura: Pipeline Multi-Layer Il cuore del sistema è un **pipeline a 4 livelli di rilevamento** che operano in parallelo e si integrano tramite un resolver di priorità: ``` ┌──────────────────────────────────────────────────┐ │ Testo in ingresso │ └──────────────────────────────────────────────────┘ │ │ [Chunking 1500 char, overlap 200] │ │ │ ┌──────▼──────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │ Step0 │ │ L0 │ │ L1 │ │ L2 │ │ Presidio │ │ Regex │ │ NER │ │ GLiNER │ │ Built-in │ │Appalti │ │ Trans- │ │ Zero-shot│ │ (IT + EN) │ │ │ │ former │ │ │ │ prior. 3 │ │prior. 0│ │prior. 1│ │ prior. 2 │ └─────────────┘ └────────┘ └────────┘ └──────────┘ └──────────────┬───────────────────┘ │ ┌─────────▼─────────┐ │ Span Resolver │ │ priorità + score │ └─────────┬─────────┘ │ ┌─────────▼─────────┐ │ Confidence Boost │ │ agreement +0.15 │ │ post-regex +0.30 │ └─────────┬─────────┘ │ ┌─────────▼─────────┐ │ Offuscamento │ │ placeholder / *** │ └───────────────────┘ ``` --- ## Modelli e Tecnologie Utilizzate ### 1. Microsoft Presidio *(framework NER)* Framework open-source di Microsoft per il rilevamento e l'anonimizzazione di dati personali. Fornisce l'infrastruttura per orchestrare riconoscitori eterogenei (regex, ML, regole) e gestire gli span risultanti. ### 2. `DeepMount00/Italian_NER_XXL_v2` *(NER transformer)* Modello transformer fine-tunato su testi italiani per il Named Entity Recognition. Identifica entità anagrafiche, giuridiche, finanziarie e tecniche in italiano. Integrato in Presidio tramite `spacy-huggingface-pipelines`. | Caratteristica | Valore | |---|---| | Architettura | Transformer (BERT-like) | | Lingua | Italiano | | Entità coperte | ~60 tipi (PERSON, ORG, IBAN, CF, …) | | Deployment | Locale, CPU/GPU | ### 3. `DeepMount00/GLiNER_PII_ITA` *(NER zero-shot)* Modello GLiNER (*Generalist and Lightweight NER*) addestrato su testi italiani di PII. Non richiede fine-tuning per nuove categorie: opera tramite **label prompt** in linguaggio naturale, riconoscendo entità specifiche degli appalti che un NER classico non coprirebbe. | Caratteristica | Valore | |---|---| | Architettura | GLiNER (encoder bidirezionale + span classifier) | | Modalità | Zero-shot con label in italiano | | Entità target | RUP, stazione appaltante, importo base d'asta, … | | Vantaggi | Nessun training aggiuntivo per nuovi tipi | ### 4. Presidio Built-in Recognizers *(Step0 — regex puro)* 31 recognizer regex di Presidio per lingue IT e EN: codici fiscali italiani con validazione checksum, partite IVA, patenti, passaporti; più riconoscitori internazionali (IBAN, credit card, SSN US, NHS UK, Aadhaar India, ecc.). ### 5. Regex Procurement *(dominio appalti)* 20 `PatternRecognizer` custom per entità specifiche del codice degli appalti italiano: CIG, CUP, CPV, NUTS, ATECO, PEC, CODICE_ANAC, SIOGG, REA, polizze assicurative, atti amministrativi. --- ## Tecniche Chiave ### Chunking con Overlap Testi lunghi vengono suddivisi in **chunk da 1.500 caratteri con overlap di 200** per evitare il taglio di entità a cavallo di due blocchi. Gli offset vengono riportati al testo originale dopo l'analisi. ### Priority-based Span Resolution Quando più livelli rilevano lo stesso span, vince il livello con **priorità numerica più bassa** (Regex = 0, massima; Step0 = 3, minima). All'interno dello stesso livello vince lo span con score più alto, poi il più lungo. ### Cross-layer Agreement Boost Se **almeno 2 livelli** concordano sullo stesso span (similarità Jaccard ≥ 0.80), lo score viene aumentato di **+0.15**. Questo premia le entità rilevate in modo coerente da metodi diversi. ### Post-boost Regex Validation Dopo la risoluzione, ogni entità viene validata con un pattern di fullmatch specifico per il suo tipo. In caso di corrispondenza esatta (es. checksum IBAN, formato CIG), lo score viene aumentato di **+0.30**. ### Placeholder Numerati Coerenti (GLiNER) Le entità rilevate da GLiNER in modalità *placeholder* ricevono identificatori numerati e **coerenti all'interno del documento**: lo stesso soggetto (es. stessa stazione appaltante) riceve sempre lo stesso placeholder `[SA_001]`. ### Score Minimo Configurabile Tutte le entità con confidenza inferiore alla soglia configurabile (default **0.85**) vengono scartate, riducendo i falsi positivi. --- ## Modalità di Offuscamento L'utente sceglie come oscurare i dati rilevati: | Modalità | Risultato | Caso d'uso | |---|---|---| | **Placeholder** | `[PERSONA]`, `[IBAN]` | Revisione legale, audit | | **Asterischi** | `**********` | Pubblicazione anonima | | **Ultime 4 lettere** | `****ossi` | Pseudonimizzazione parziale | | **Prima lettera** | `R***` | Riconoscibilità ridotta | --- ## Filtro per Gravità Le entità sono classificate in 4 livelli di gravità. L'utente può **disabilitare selettivamente** uno o più livelli: le entità di quel livello non vengono oscurate ma rimangono visibili con stile "muted" nel documento evidenziato. | Livello | Entità tipiche | |---|---| | 🔴 Critica | CF, IBAN, carte di credito, password, CIG, CUP | | 🟠 Alta | Nomi, email, telefoni, IP, RUP | | 🟡 Media | Organizzazioni, importi, numeri protocollo | | 🔵 Bassa | Luoghi, URL, codici CPV/NUTS/ATECO | --- ## Stack Tecnologico | Componente | Tecnologia | |---|---| | UI | **Gradio 6** (Hugging Face) | | NLP framework | **Microsoft Presidio** | | NER transformer | **HuggingFace Transformers** | | Zero-shot NER | **GLiNER** | | PDF extraction | **pymupdf4llm** (MuPDF) | | SpaCy backend | `it_core_news_lg` | | Linguaggio | Python 3.12 | | Deployment | Hugging Face Spaces | --- ## Differenziatori del Progetto - **Dominio specializzato**: i pattern regex coprono il codice degli appalti italiano (CIG, CUP, CPV, NUTS, ATECO, ANAC, SIOGG) che nessun framework generico gestisce. - **Pipeline ibrido**: combina regex deterministici, NER supervisionato e zero-shot NER, sfruttando i punti di forza di ciascuno. - **Confidenza stratificata**: il sistema di boosting multi-livello riduce falsi positivi senza sacrificare il recall. - **Controllo utente**: l'utente può affinare il risultato via checkbox per singolo blocco e abilitare/disabilitare livelli di gravità. - **Formato Markdown nativo**: l'estrazione PDF produce direttamente Markdown strutturato (headers, tabelle, liste) preservando la gerarchia documentale. --- ## Glossario degli Acronimi ### AI / NLP / ML | Acronimo | Significato | Contesto nel progetto | |---|---|---| | **AI** | Artificial Intelligence | Contesto generale del progetto | | **NLP** | Natural Language Processing | Framework Presidio e pipeline di analisi | | **NER** | Named Entity Recognition | Tecnica usata dai layer 1 (transformer) e 2 (GLiNER) | | **GLiNER** | Generalist and Lightweight Named Entity Recognition | Modello zero-shot del layer 2 (`DeepMount00/GLiNER_PII_ITA`) | | **BERT** | Bidirectional Encoder Representations from Transformers | Architettura base del modello NER transformer (layer 1) | | **LLM** | Large Language Model | Riferimento generico ai modelli linguistici di grandi dimensioni | | **VLM** | Vision Language Model | Modelli multimodali (citati per contesto, non usati direttamente) | | **ML** | Machine Learning | Apprendimento automatico — categoria dei modelli usati | | **PII** | Personally Identifiable Information | Dati personali identificabili — target dell'anonimizzazione | | **OCR** | Optical Character Recognition | Riconoscimento ottico dei caratteri (alternativa a pdfplumber per l'estrazione da PDF) | | **GPU** / **CPU** | Graphics / Central Processing Unit | Dispositivi di esecuzione dei modelli transformer e GLiNER | | **XXL** | Extra Extra Large | Dimensione del modello `Italian_NER_XXL_v2` | ### Dominio Appalti (codice degli appalti italiano) | Acronimo | Significato | Contesto nel progetto | |---|---|---| | **CIG** | Codice Identificativo Gara | Identificatore univoco di ogni gara (ANAC); riconosciuto da regex custom | | **CUP** | Codice Unico di Progetto | Identifica i progetti di investimento pubblico; regex custom | | **CPV** | Common Procurement Vocabulary | Classificazione europea delle categorie merceologiche d'appalto | | **NUTS** | Nomenclature des Unités Territoriales Statistiques | Codifica eurostat delle unità territoriali (es. `ITC47`) | | **ATECO** | ATtività ECOnomiche | Codice ISTAT di classificazione delle attività economiche | | **ANAC** | Autorità Nazionale Anticorruzione | Ente vigilante sugli appalti pubblici; emette CIG e codici ANAC | | **BDNCP** | Banca Dati Nazionale dei Contratti Pubblici | Database ANAC di tutti i contratti pubblici; genera SIMOG/NUMGARA | | **SIMOG** | Sistema Informativo MOnitaggio Gare | Applicativo ANAC per la registrazione delle gare; produce il NUMGARA | | **NUMGARA** | NUMero GARA | Identificatore numerico assegnato da SIMOG ad ogni gara | | **SIOGG** | Sistema Informativo per l'OGGetto del contratto | Codice descrittivo dell'oggetto del contratto (Simog) | | **RUP** | Responsabile Unico del Procedimento | Funzionario responsabile della gara; dato anagrafico da anonimizzare | | **SA** | Stazione Appaltante | Ente che indice la gara; placeholder numerato `[SA_001]` in modalità GLiNER | | **CCIAA** | Camera di Commercio, Industria, Artigianato e Agricoltura | Ente camerale; fonte del numero REA | | **REA** | Repertorio Economico Amministrativo | Registro camerale delle imprese; numero identificativo dell'impresa | ### Dati Personali e Finanziari | Acronimo | Significato | Contesto nel progetto | |---|---|---| | **CF** | Codice Fiscale | Identificatore fiscale italiano delle persone fisiche; validato con checksum | | **IVA** | Imposta sul Valore Aggiunto | Partita IVA delle persone giuridiche; riconosciuta da Presidio built-in | | **PEC** | Posta Elettronica Certificata | Email certificata obbligatoria per le PA; regex custom | | **CAP** | Codice di Avviamento Postale | Codice postale italiano a 5 cifre | | **IBAN** | International Bank Account Number | Coordinate bancarie internazionali; validato con checksum | | **BIC** | Bank Identifier Code | Codice identificativo delle banche (detto anche codice SWIFT) | | **SWIFT** | Society for Worldwide Interbank Financial Telecommunication | Rete interbancaria internazionale; il suo codice coincide con il BIC | | **CVV** | Card Verification Value | Codice di sicurezza delle carte di credito | | **PIN** | Personal Identification Number | Codice segreto di accesso | | **IMEI** | International Mobile Equipment Identity | Identificatore univoco dei dispositivi mobili | | **MAC** | Media Access Control | Indirizzo hardware univoco delle interfacce di rete | | **INPS** | Istituto Nazionale della Previdenza Sociale | Ente previdenziale italiano; emette matricole e codici contributivi | ### Tecnologie e Strumenti | Acronimo | Significato | Contesto nel progetto | |---|---|---| | **UI** | User Interface | Interfaccia utente realizzata con Gradio | | **HTML** | HyperText Markup Language | Formato dei tab di output (Highlighted / Anonymized / Report) | | **JSON** | JavaScript Object Notation | Formato dei log strutturati e delle risposte intermedie | | **PDF** | Portable Document Format | Formato documenti supportato in input tramite pdfplumber/pymupdf4llm | | **URL** | Uniform Resource Locator | Indirizzi web riconosciuti come entità da anonimizzare | | **SDK** | Software Development Kit | Kit di sviluppo (es. Presidio SDK) |