Guida tecnica

Catalogo delle fonti

Ogni KPI esposto su ItalIntel proviene da una fonte ufficiale e mantiene la dichiarazione esplicita di granularità, frequenza e licenza. Il registry completo dei KPI numerici è versionato nel repository (file apps/api/registry/datasets.yaml). Anagrafica, zona climatica, link al sito ufficiale e alla voce Wikipedia e la foto del comune provengono invece da dataset statici (Wikidata + ENEA) allineati per codice ISTAT e gestiti lato front-end, non dal pipeline SDMX/DB. Tutti gli altri KPI numerici — comprese le fonti più recenti (AGCOM banda larga, ISTAT accessibilità ai trasporti) — sono nel registry come gli altri indicatori, con la stessa dichiarazione di granularità e licenza.

Aggiornamento dei dati

ItalIntel ri-scarica ciascuna fonte periodicamente con uno scheduler distribuito: ogni giorno della settimana è dedicato a una sola fonte, per evitare di sovraccaricare i portali ufficiali e rispettare i loro rate-limit (in particolare l'endpoint SDMX dell'ISTAT, che blocca gli IP che eccedono ~1 richiesta ogni 30 secondi).

Le fonti a pubblicazione annuale o sporadica (ISPRA consumo suolo e rifiuti, ISTAT imprese/turismo/istruzione/criminalità/incidenti/abitazioni, Eurostat PIL, AGCOM banda larga, ISTAT accessibilità ai trasporti) vengono invece ricontrollate il 1° di ogni mese: se la fonte ha pubblicato una nuova annualità o una revisione, il refresh la recepisce entro un mese.

Ogni job applica un jitter casuale fino a 30 minuti per non creare pattern di richieste fissi, un TTL per famiglia di KPI (es. la popolazione residente non viene riscaricata se l'ultimo successo è entro 7 giorni) e un backoff di 24 ore dopo tre fallimenti consecutivi. La scrittura sul database è idempotente (UPSERT su (comune, kpi, anno)), quindi una ri-esecuzione non duplica righe. L'upsert è inoltre change-aware: a ogni refresh ciascuna riga viene classificata come nuova annualità, recupero storico, revisione (la fonte ha corretto un valore già pubblicato) o invariata — e le righe invariate non vengono riscritte. Questo ci permette di misurare quanto spesso ciascuna fonte cambia davvero i propri dati.

Ogni esecuzione è loggata nella tabella dataset_runs con orario di inizio/fine, stato, righe ingerite (scomposte in nuove/riviste/invariate) e – se fallita – messaggio di errore. La colonna "Frequenza" della tabella sopra indica la cadenza di aggiornamento della fonte upstream: il dato che vedi in pagina è dunque al massimo vecchio quanto l'ultimo refresh schedulato successivo a una pubblicazione effettiva.

Metodologia degli indici sintetici

ItalIntel calcola 8 indici sintetici 0-100 per ciascun comune. Ogni indice è una media pesata dei percentili nazionali di alcune componenti. Per componenti dove "meno è meglio" il percentile è invertito prima della media.

Due note metodologiche. (1) I componenti di dotazione per 1.000 abitanti e le allocazioni «a blocchi» usano il percentile di cluster di taglia (micro/piccolo/medio/grande), non quello nazionale: così un comune è confrontato coi suoi pari di dimensione e le metriche pro-capite non premiano artificiosamente i micro-comuni (dove pochi abitanti gonfiano la densità). Riguarda la dotazione di servizi della Qualità della vita (scuole, biblioteche, musei, posti letto), entrambe le componenti della Salute (posti letto e farmacie) e il PNRR pro capite dell'Attrattività (un singolo progetto a denominatore piccolo gonfia il pro-capite del micro-comune). Le altre componenti dell'Attrattività — reddito, imposta, contribuenti, istruzione — restano nazionali: sono medie e percentuali che non soffrono il bias di taglia e il cui segnale economico reale va preservato. (2) Quando un indice è aggregato per area(provincia, regione), il punteggio è la media pesata per popolazione dei comuni — riflette dove vivono i residenti, non il numero di comuni. Questi indici misurano dotazione di servizi, attrattività e sicurezza secondo scelte di componenti e pesi dichiarate qui: sono una misura trasparente e confrontabile, non un giudizio assoluto di «qualità della vita».

Output per ciascun indice: punteggio 0-100, percentile nazionale (rispetto a tutti i ~7.900 comuni con dati sufficienti), percentile nel cluster di comuni di pari dimensione (micro <5k, piccolo 5-20k, medio 20-100k, grande >100k abitanti). Il cluster permette confronti più equi: confrontare una grande città metropolitana con un piccolo comune montano non è informativo.

Come si legge la formula

Per ogni componente di un indice ItalIntel calcola il percentile nazionale: un numero da 0 a 100 che indica dove si colloca il comune rispetto a tutti gli altri. Per esempio, se "reddito complessivo pro capite" del comune è 35.000 € e questo lo mette al 90° posto su 100 (cioè meglio del 90 % dei comuni), il suo percentile per quella componente vale 90. L'indice è la media pesata dei percentili delle sue componenti: si moltiplica ciascun percentile per il suo peso (i pesi sommano a 1), si sommano i risultati, si ottiene il punteggio finale 0-100.

Per le componenti dove "meno è meglio" (es. mortalità su natalità per l'indice di spopolamento) il percentile viene invertito: chi ha il valore più basso ottiene 100, chi ha il più alto ottiene 0.

Copertura e «non classificato». Se per un comune mancano i dati di alcune componenti, l'indice si calcola sulle sole componenti disponibili; la copertura (mostrata nella scheda quando è inferiore al 100%) indica la quota di peso effettivamente usata. Se invece mancano tutte le componenti — ad esempio un comune di fusione recente non ancora coperto dalle fonti, o un comune privo di qualsiasi struttura per l'indice «Salute» — il comune non riceve un punteggio 0 (che lo farebbe figurare erroneamente come «il peggiore»), ma è marcato «non classificato» ed escluso dalle classifiche e dalle mappe.

I pesi e le componenti elencati qui sono pubblici e versionati in packages/core/.../indices/weights.yaml. Una modifica richiede pull request e validazione su un campione di comuni.

Attivazione PNRR vs Efficacia PNRR. Misuriamo solo l'attivazione (importi e progetti registrati). L'efficacia esecutiva (% di completamento, ritardi, soldi davvero spesi) richiederebbe i dati ReGIS, che non sono ancora pubblicati in modo strutturato.

Indice personalizzato

Lo strumento Costruisci il tuo indice usa lo stesso motore degli otto indici ufficiali: ogni componente viene portato su una scala 0-100 con il percentile rispetto al riferimento scelto (tutta Italia oppure il cluster di comuni di pari taglia) e i componenti si combinano in una media pesata; i pesi inseriti sono relativi e vengono normalizzati a somma 100%. I comuni che non hanno il dato di un componente sono valutati sui soli componenti disponibili (ridistribuzione dei pesi, come per gli indici ufficiali).

La differenza è la forma di preferenza scelta per ciascun indicatore, che decide come il valore grezzo diventa punteggio:

• Più alto è meglio / più basso è meglio: percentile diretto o invertito.
• Valore ideale: il punteggio premia la vicinanza a un valore scelto (utile per «popolazione piccola» o «centro Italia»); a campana attorno all'ideale.
• Per categoria (regione, ripartizione): assegni tu un punteggio 0-100 a ciascuna categoria.

Partendo da un indice ufficiale, a parità di componenti, direzioni e pesi la classifica riproduce quella ufficiale. L'indice personalizzato è però una combinazione di preferenze soggettive: non è validato scientificamente e non sostituisce gli indici ufficiali del sito. Il calcolo è gratuito e non richiede registrazione.

Fallback di granularità

Quando un dato non è disponibile a livello comunale, ItalIntel mostra il valore alla granularità superiore disponibile (provincia → regione → nazione) marcandolo esplicitamente. Esempio: il tasso di occupazione RCFL è pubblicato da ISTAT solo a livello provinciale, quindi tutti i comuni di una stessa provincia mostrano lo stesso valore con granularity: provincia.

Assistente AI — come funziona

L'Assistente AI traduce la domanda in linguaggio naturale in chiamate a un insieme ristretto di strumenti (classifica, aggrega, serie storica, confronto) che eseguono query reali sul database. Il modello non genera numeri: ogni cifra mostrata proviene dal risultato di uno strumento sui dati ufficiali. Se un indicatore non è nel catalogo, l'assistente lo dichiara invece di inventare.

Gli aggregati territoriali rispettano la natura del KPI: i conteggi si sommano, le percentuali e i tassi si mediano pesando per la popolazione (o per la superficie), gli indicatori derivati (densità, reddito medio) si ricalcolano dai componenti aggregati. La granularità reale è rispettata: i KPI provinciali (es. tassi RCFL) vengono classificati per provincia, non per comune. Quando manca il numeratore di un indicatore derivato, l'assistente espone "dato non disponibile" anziché un valore pari a 0, coerentemente col principio di non inventare dati.

Classifiche e aggregati possono essere circoscritti a un ambito— una provincia o una regione specifica: una domanda come "i 10 comuni più popolosi della provincia di Viterbo" restituisce i soli comuni di quella provincia, non la classifica nazionale. Quando la domanda è ambigua o priva di un criterio (es. "i comuni più importanti"), l'assistente non tira a indovinare: chiede una precisazione proponendo riformulazioni già pronte da cliccare.

Ogni risposta cita le fonti dei dati usati ed è generata da un sistema di intelligenza artificiale (modello Claude di Anthropic), come richiesto dai principi di trasparenza dell'EU AI Act: può contenere imprecisioni di formulazione, verifica i dati alla fonte. Le funzioni AI sono riservate agli utenti registrati, con una quota di operazioni mensili che dipende dal piano.

Motore documenti & AI Composer

L'AI Composer poggia sullo stesso tool layer dell'Assistente. Un documento è una lista ordinata di blocchi (narrativa, grafico, tabella, punteggio, titolo di paragrafo); per i blocchi-dato il modello non produce prosa ma una spec strutturata e deterministica — lo strumento da invocare (classifica, aggrega, serie storica, confronto) con i suoi parametri. La spec risolta viene persistita: re-render, refresh ed export non richiamano l'LLM, che interviene solo alla prima risoluzione o quando l'utente modifica il prompt di un blocco. Questo rende i documenti riproducibili e contiene il costo AI. Titoli e testi di ogni blocco sono editabili dall'utente (anche la narrativa generata dall'AI e le card incluse dai modelli); i numeri dei blocchi-dato restano vincolati alla spec/fonte e non sono modificabili a mano.

La stessa spec viene resa in più formati: HTML (anteprima), PDF (Jinja2 → WeasyPrint, con grafici come SVG inline statici), Word (.docx via python-docx: tabelle e punteggi nativi, grafici come immagine) e PowerPoint (.pptx via python-pptx: grafici e tabelle come oggetti nativi modificabili). Il branding è un flag applicato in fase di export: filigrana italintel.it sui piani base, white-label (logo, colore, piè di pagina) sui piani alti.

I modelli predefiniti (Scheda completa, Benchmark, Dossier rischio, Due diligence di zona, Investitore immobiliare, Insediamento d'impresa, Dossier turismo, Sicurezza e qualità della vita, Dossier rischio per indirizzo) assemblano blocchi-dato deterministici (grafici, tabelle, punteggi: nessun numero inventato dall'LLM) a cui si aggiunge una breve guida alla lettura generata dall'AI; per questo consumano crediti. Il Dossier rischio per indirizzo consuma l'endpoint di catastima.it /v1/rischio/punto: geocodifica l'indirizzo e restituisce pericolosità da alluvione, frana e sismica del punto più la mappa. La mappa viene scaricata server-side e incorporata come data-URI, così la chiave API di catastima.it non transita mai dal browser né finisce nel PDF.

Endpoint di prodotto: POST /v1/composer/resolve_block (NL → spec + primi dati), POST /v1/composer/render_block (spec → dati, senza LLM) e /v1/composer/export.{pdf|docx|pptx}.

Tutela della privacy

Per dati fiscali MEF/BDAP, le classi di reddito con meno di 100 contribuenti sono soppresse (KPI = null) per evitare l'identificazione indiretta in comuni molto piccoli. Sui campi del breakdown per fonte (pensione, lavoro dipendente, lavoro autonomo, impresa, fabbricati) il MEF maschera le frequenze inferiori a 4: il fetcher converte le celle vuote in valori nulli e propaga il vuoto sui derivati.

Avvertenza metodologica sulla composizione del reddito. I KPI di breakdown per fonte (pensione media dichiarata, salario medio dichiarato, % dichiaranti per fonte) sono proxy fiscali, non anagrafiche. La frequenza «contribuenti che dichiarano reddito da pensione» non coincide con il numero di pensionati residenti: alcuni pensionati esenti dalla dichiarazione non compaiono, e una persona che continua a lavorare dopo i 65 anni può dichiarare contemporaneamente lavoro dipendente e pensione. Per gli usi narrativi del prodotto (distinguere territori a rendita pensionistica da territori a lavoro attivo) la proxy è eccellente e disponibile su tutti i 7.896 comuni; per usi attuariali rigorosi va citata come dato fiscale di fonte MEF dichiarazioni IRPEF, non come dato INPS.