Civic Superagents

Commons di skill AI civici e data lake sugli open data pubblici italiani, comune-keyed, con uno strato agentico (MCP) che rende ogni comune leggibile in italiano naturale — ogni dato ancorato a una fonte citabile.

Sintesi pubblica → civic-superagents.md · mappa verificata delle fonti → notes/mappa-open-data-civici.md.

Stato

Data lake su Supabase (Postgres + Storage + PostGIS). 16 sistemi-fonte / 17 dataset, oltre 1,9 M righe, prevalentemente nazionali (l'aria copre i ~comuni con centralina, per natura del dato). Strato serving via MCP con 11 tool (eseguibile in locale o deployabile come server HTTP — vedi mcp/). Provenance per ogni dato (meta.fonti → file immutabile in Storage raw/).

Cosa c'è nel lake

Tema	Fonte	Tabella mart.*	Copertura
Rischio frane/alluvioni	ISPRA IdroGEO	idrogeo_comune	🇮🇹 7.896 comuni
Rifiuti / differenziata	ISPRA Catasto Rifiuti	rifiuti_comune_anno	🇮🇹 2020-24
Consumo di suolo	ISPRA	consumo_suolo_comune	🇮🇹 7.890
Qualità aria (PM10)	EEA (sintesi annuale) · ARPA Lombardia (pilota)	aria_comune_anno · aria_misure	comuni con centralina
Edilizia scolastica	MIUR	scuola_edificio	🇮🇹 39.331 edifici
Popolazione / demografia	ISTAT SDMX	geo.comuni.popolazione	🇮🇹 7.890
Spesa per missione	BDAP FET Rendiconto	bilancio_comune	🇮🇹 2024 (99%)
Appalti (chi vince)	ANAC	appalto	🇮🇹 2024, ~313k (≥ €40k)
Fondi di coesione	OpenCoesione	progetto_coesione (+_comune)	🇮🇹 2021-27, 171k progetti
PNRR	OpenPNRR	pnrr_progetto (+_comune)	🇮🇹 291k progetti
Chi governa	Min. Interno DAIT	amministratore_comune	🇮🇹 115k
Cultura — biblioteche	ICCU	biblioteca_comune	🇮🇹 19.598
Acque — balneazione	EEA/WISE (EMODnet)	balneazione_sito	🇮🇹 siti costieri/lacustri
Energia — CER	GSE	cer_comune	🇮🇹 751 comuni
Welfare — asili nido	ISTAT SDMX	welfare_comune	🇮🇹 7.898

Lo strato agentico

mcp/ espone il lake come 11 strumenti civici (vedi mcp/README.md) — la narrazione in italiano civico la fa l'agente, il data layer restituisce dati citati:

• cerca_comune / leggi_comune — risolve un comune e ne dà il profilo civico completo (ambiente · scuola · cultura · welfare · energia · bilancio per missione · appalti · fondi coesione+PNRR · gemelli finanziari · chi governa), ogni numero con la sua fonte.
• progetti_comune, confronta_comuni, classifica, appalti_comune — query mirate sui mart.
• helper_foia — bozza di accesso civico con i riferimenti normativi.
• domande_da_verificare/firma_risposta e fonti_da_verificare/verifica_licenza — revisione umana del test set e delle licenze.

npm run mcp          # server MCP (stdio, locale)
npm run start:http   # server MCP (Streamable HTTP) — proteggi /mcp con MCP_AUTH_TOKEN

Registrazione locale in Claude Code:

claude mcp add civic-superagents -- npx tsx /ABS/PATH/civic-superagents/mcp/stdio.ts

È attiva anche un'istanza HTTP (Streamable HTTP) su https://civic.playnew.com/mcp — accesso protetto da bearer token:

claude mcp add --transport http civic-superagents https://civic.playnew.com/mcp --header "Authorization: Bearer <token>"

Per Claude Desktop, claude.ai e Messages API → mcp/README.md.

Licenze delle fonti

Ogni fonte è stata verificata (con URL di prova). Riuso libero citando la fonte; due fonti sono share-alike.

Fonte	Licenza
ISPRA — IdroGEO, Catasto Rifiuti, Consumo di suolo	CC-BY-4.0
ISTAT — popolazione, servizi prima infanzia	CC-BY-4.0
ANAC — appalti	CC-BY-4.0
Min. Interno DAIT — amministratori	CC-BY-4.0
OpenCoesione — progetti coesione	CC-BY-4.0
EEA — aria PM10, balneazione (via EMODnet)	CC-BY-4.0
Openpolis geojson-italy — confini (da ISTAT)	CC-BY-4.0
MIUR — edilizia scolastica	IODL-2.0 (≈ CC-BY)
BDAP / MEF-RGS — rendiconti	CC-BY-3.0
dati.lombardia (ARPA) — aria · ICCU — biblioteche	CC0-1.0
OpenPNRR — progetti PNRR	ODbL-1.0 ⚠️ share-alike
GSE — comunità energetiche	CC-BY-SA-3.0-IT ⚠️ share-alike

⚠️ Il dataset combinato include due fonti share-alike (OpenPNRR ODbL-1.0, GSE CC-BY-SA-3.0-IT): le elaborazioni derivate vanno ricondivise con la stessa licenza e il lake non è ridistribuibile come CC0. Vanno sempre attribuite tutte le fonti usate (la leggi_comune espone fonti per ogni profilo).

Questo repo: codice EUPL-1.2, prompt e documentazione CC-BY-SA-4.0 (vedi LICENSE e LICENSES/). I dati restano sotto le licenze delle rispettive fonti, qui sopra.

Struttura

supabase/      progetto Supabase: config.toml + migrations/ (geo · meta · glossary · mart)
ingestors/     un modulo per fonte (fetch → land Storage → load → upsert mart → nota) + manifest.yaml
  _framework/  download · storage · provenance · util (parser IT, normName, bulkUpsert)
mcp/           server MCP (11 tool) — read-only via SUPABASE_DB_URL_READONLY (ruolo civic_serve)
glossary/      lookup JSON curati
notes/         mappa consolidata + una nota per fonte (quirk operativi)
tests/         questions.jsonl — 16 domande civiche con risposta verificata a mano
rfc/ · LICENSE · CONTRIBUTING.md · LICENSES/   governance RFC-style, EUPL-1.2 + CC-BY-SA-4.0

Principi non negoziabili

• Citation policy dura: ogni numero → riga meta.fonti → file immutabile in raw/. Senza fonte non si risponde.
• Il comune è la chiave: tutto fa join su geo.comuni (ISTAT / pro_com / catastale / PostGIS).
• Trappole dichiarate: liste d'attesa, acqua potabile, ritardi treni, criminalità comunale → "non pubblicato", mai promesse.
• Le API italiane cambiano in silenzio → riverificare la liveness delle fonti prima di ogni release.

Setup

.env da .env.example (Supabase: URL, service-role key, pooler SUPABASE_DB_URL). Poi supabase db push, npm run ingest:wedges / ingest:money, npm run verify, npm run mcp. Dettagli in ingestors/README.md.

⚠️ Le API pubbliche italiane cambiano spesso e in silenzio: riverificare la liveness delle fonti prima di qualsiasi ridistribuzione. I valori dell'aria sono operativi, non certificati.