DataCivicLab Toolkit

Motore di pipeline dati del DataCivicLab — da fonti pubbliche a dataset pronti per l'analisi.

Prende dati grezzi da fonti eterogenee (HTTP, CKAN, SDMX, SPARQL, file locali), li normalizza e li produce in parquet pronti per l'analisi, con un contratto chiaro tra ogni layer.

Per chi è

Se sei...	toolkit fa per te perché...
Autore di dataset del Lab	scrivi dataset.yml + SQL, toolkit esegue e produce parquet RAW → CLEAN → MART
Analista	consumi i parquet già prodotti via data-explorer o notebook — qui trovi come sono stati generati
Sviluppatore del motore	contribuisci a raw/, clean/, mart/, plugins/ — questo è il repo

Primi passi in 3 comandi

pip install -e .[dev]
toolkit run -c dataset.yml
toolkit inspect -c dataset.yml

Se toolkit non è nel PATH: python -m toolkit.cli.app run -c dataset.yml

Pipeline: tre livelli

RAW ──→ CLEAN ──→ MART

Layer	Contenuto	Destinazione
RAW	File originale dalla fonte, senza modifiche	Audit, verifica, debug
CLEAN	Dato normalizzato: nomi colonna coerenti, tipi fissi, schema stabile	Notebook, analisi, data-explorer
MART	Dato aggregato per report e dashboard	Report, insight rapidi

Ogni run produce metadata.json e validation.json per audit trail.

Ecosistema

source-observatory → dataset-incubator → [toolkit] → GCS → data-explorer
↑
MCP server

Il toolkit non gestisce il deployment: scrive nella directory configurata. La CI di dataset-incubator carica su GCS dopo ogni run validato.

CLI — comandi essenziali

Comando	Cosa fa
toolkit run	Esecuzione completa RAW→CLEAN→MART (default)
toolkit run --batch <file>	Esegue piú dataset in sequenza
toolkit run --refresh-support	Forza la rigenerazione dei support (di default i support con output già presenti vengono riusati)
toolkit run raw	Solo layer RAW
toolkit run clean	Solo layer CLEAN
toolkit run mart	Solo layer MART
toolkit inspect	Stato ultimo run (riassunto)
toolkit inspect config --diff	Schema-diff RAW tra anni
toolkit inspect runs --resume	Riprendi run interrotto
toolkit scout <URL>	Esplora fonte esterna (HTTP/CKAN/SDMX)

--config è opzionale: se omesso, toolkit cerca dataset.yml nella directory corrente. Se passi uno slug (es. terna-electricity-by-source), lo risolve nel workspace.

📖 Reference completo: toolkit --help

Configurazione (dataset.yml)

dataset:
name: mio_datasetyears: [2023]raw:
sources:
- type: http_fileurl: https://example.com/dati.csvclean:
sql: sql/clean.sqlmart:
tables:
- name: basicsql: sql/mart/basic.sql

Il toolkit risolve i path relativi, esegue SQL su DuckDB e produce output in root/data/.

Plugin sorgente supportati: http_file, http_post_file, local_file, ckan, sdmx, sparql.

📖 Documenti di riferimento:

Documento	Contenuto
config-schema.md	Specifica completa YAML
standard-macros.md	Macro SQL predefinite per clean.sql
conventions.md	Path, metadata, manifest
advanced-workflows.md	Resume, run parziali, debug
notebook-contract.md	Come leggere output nei notebook
feature-stability.md	Cosa è stabile, sperimentale, deprecated

Integrazione AI (MCP)

Il toolkit espone 5 tool MCP aggregati per agenti AI e IDE:

Tool	Azioni	Cosa fa
toolkit_dataset	find, overview, status, preflight, schema-diff	Cerca, ispeziona, diagnostica dataset
toolkit_query	run, preview	SQL su raw/clean/mart, preview URL CSV/TSV
toolkit_pipeline	contract, runs, registry_list, registry_show, graph	Contratti, run history, registry, grafo relazioni
toolkit_source	probe, ckan, links, sparql	Probe HTTP, CKAN, HTML links, SPARQL
toolkit_contract	(unico)	Contratti pipeline (backward compat)

Config IDE (.mcp.json):

{
"toolkit": {
"command": "/path/to/python",
"args": ["-m", "toolkit.mcp.server"]
}
}

📖 Dettaglio: toolkit/mcp/README.md

FAQ — problemi comuni

| Problema | Soluzione | |---|---|---| | toolkit: command not found | Usa python -m toolkit.cli.app | | Run interrotto | toolkit inspect runs --resume -c dataset.yml | | Schema diverso tra anni | toolkit inspect config -c dataset.yml --diff | | Dove sono i parquet? | toolkit inspect -c dataset.yml (mostra path nel riassunto) |

Sviluppo

pip install -e .[dev]
pytest -m core # contratto pubblico
ruff check .# lint

Test: 85+ file, marker core (deve sempre passare), advanced, compat. CI: .github/workflows/ci.yml — Python 3.10–3.12, ruff, coverage ≥70%.

Struttura del repo

toolkit/
toolkit/ # package Python
cli/ # comandi CLI (typer, re-export)
core/ # engine condiviso (infrastruttura)
domain/ # logica di dominio (orchestrazione)
raw/ clean/ mart/ # layer pipeline
plugins/ # plugin sorgente
mcp/ # server MCP
profile/ # profiling RAW
tests/ # pytest (85+ file)
docs/ # documentazione tecnica
project-example/ # esempio funzionante

Licenza

MIT — CONTRIBUTING.md · CHANGELOG.md