Civic SuperAgents — data lake + mappa open data civici

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

Related MCP server: mcp-istat-it

Cosa c'è nel lake

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

Licenze delle fonti

Ogni fonte è stata verificata (con URL di prova). Riuso libero citando la fonte; due fonti sono 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.