From f1ff54bce0f8dcd27450782273ef506107f07f43 Mon Sep 17 00:00:00 2001 From: Zio Gabber <78922322+Gabrymi93@users.noreply.github.com> Date: Fri, 20 Mar 2026 10:45:02 +0000 Subject: [PATCH 1/2] docs: clarify inspect command contracts --- README.md | 58 +++++++++++++++++++++++++++++++++++++++ docs/notebook-contract.md | 42 ++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) diff --git a/README.md b/README.md index 7686b54..59d6417 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,58 @@ Per il percorso base: - `inspect schema-diff` confronta i principali segnali di schema RAW tra gli anni configurati - `--dry-run` valida config e SQL senza eseguire la pipeline +### `inspect paths` vs `inspect schema-diff` + +I due comandi sono entrambi read-only, ma hanno scopi diversi: + +- `inspect paths`: helper operativo per notebook, script locali e CI +- `inspect schema-diff`: helper diagnostico per capire drift e incoerenze del RAW tra anni + +Usa `inspect paths` quando ti serve sapere: + +- dove il toolkit scrive RAW, CLEAN, MART e run records per un dataset/anno +- qual e' il `root` effettivo risolto dalla config +- se esiste gia` un `latest_run` +- quali hint RAW sono disponibili (`encoding`, `delim`, `skip`, `suggested_read.yml`) + +Usa `inspect schema-diff` quando ti serve sapere: + +- se il RAW cambia tra anni in numero o nomi colonne +- se i profile hints cambiano tra anni +- se ci sono warning di sniffing o drift da esplicitare prima del `clean` + +Contratto operativo minimo: + +- input comune: `--config dataset.yml` +- `inspect paths` puo` essere scoped su un singolo anno con `--year` +- `inspect schema-diff` lavora sugli anni configurati nel dataset +- nessuno dei due modifica artefatti o lancia layer della pipeline + +`--json` e' il formato raccomandato quando il chiamante e': + +- CI +- notebook che vogliono evitare path logic duplicata +- script locali che leggono programmaticamente il payload + +Output garantito di `inspect paths`: + +- `dataset`, `year`, `config_path`, `root` +- blocco `paths.raw|clean|mart|run_dir` +- blocco `raw_hints` +- blocco `latest_run` se esiste, altrimenti `null` + +Output garantito di `inspect schema-diff`: + +- `dataset`, `config_path`, `years` +- `entries` con i principali segnali RAW per anno +- `comparisons` tra anni consecutivi + +Regola pratica: + +- CI e effective root: `inspect paths --json` +- onboarding notebook o script repo dataset: `inspect paths --json` +- debug schema drift su fonti multi-anno: `inspect schema-diff --json` + Esempi: ```bash @@ -257,6 +309,12 @@ Helper ufficiale per evitare path logic duplicata nei notebook: toolkit inspect paths --config dataset.yml --year 2024 --json ``` +`inspect schema-diff` non sostituisce `inspect paths`: + +- non nasce per trovare i path runtime +- nasce per confrontare hints e colonne RAW tra anni configurati +- ha senso quando stai definendo `clean.read`, validando una fonte instabile o spiegando un drift nella nota metodologica del dataset + Ruoli stabili degli output: - `metadata.json`: payload ricco del layer diff --git a/docs/notebook-contract.md b/docs/notebook-contract.md index 9b4f0ce..b7b455d 100644 --- a/docs/notebook-contract.md +++ b/docs/notebook-contract.md @@ -32,6 +32,48 @@ Nota pratica: - `inspect paths` restituisce path assoluti della macchina locale: e' pensato per notebook e script nello stesso ambiente, non come formato portabile tra macchine diverse. +## Contratto operativo di `inspect paths` + +`inspect paths` e' il comando da usare quando il problema e': + +- trovare i path runtime gia` risolti dal toolkit +- evitare di ricostruire a mano `root/data/...` +- leggere l'ultimo run disponibile per un anno +- recuperare i principali hint RAW senza aprire a mano i metadata + +Input minimo: + +- `--config dataset.yml` +- opzionale `--year` per restringere il payload a un solo anno + +Output garantito in `--json`: + +- `dataset`, `year`, `config_path`, `root` +- `paths.raw`, `paths.clean`, `paths.mart`, `paths.run_dir` +- `raw_hints` +- `latest_run` + +Regola pratica: + +- notebook e script locali: usa sempre `inspect paths --json` +- CI che deve validare `effective_root` o path contract: usa `inspect paths --json` +- se non passi `--year`, il payload puo` essere una lista multi-anno + +## Differenza rispetto a `inspect schema-diff` + +`inspect schema-diff` non e' un helper per notebook. + +Serve invece quando vuoi: + +- confrontare schema e hints RAW tra anni configurati +- capire se una fonte multi-anno ha drift di colonne o profile hints +- decidere se `clean.read` o una nota metodologica devono esplicitare un caveat + +In breve: + +- `inspect paths`: "dove sono gli artefatti e quale runtime path contract posso usare?" +- `inspect schema-diff`: "il RAW cambia tra anni e quanto cambia?" + Regola pratica: - il toolkit produce From 220e0445677160b024f9b68c249263e95cf4a070 Mon Sep 17 00:00:00 2001 From: Zio Gabber <78922322+Gabrymi93@users.noreply.github.com> Date: Fri, 20 Mar 2026 10:50:27 +0000 Subject: [PATCH 2/2] docs: align inspect contract with actual payload --- README.md | 18 +++++++++++++++--- docs/notebook-contract.md | 15 +++++++++++++-- 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 59d6417..0b8653b 100644 --- a/README.md +++ b/README.md @@ -233,7 +233,7 @@ Usa `inspect paths` quando ti serve sapere: - dove il toolkit scrive RAW, CLEAN, MART e run records per un dataset/anno - qual e' il `root` effettivo risolto dalla config - se esiste gia` un `latest_run` -- quali hint RAW sono disponibili (`encoding`, `delim`, `skip`, `suggested_read.yml`) +- quali hint RAW sono disponibili (`encoding`, `delim`, `decimal`, `skip`, `suggested_read_path`, `suggested_read_exists`) Usa `inspect schema-diff` quando ti serve sapere: @@ -257,8 +257,20 @@ Contratto operativo minimo: Output garantito di `inspect paths`: - `dataset`, `year`, `config_path`, `root` -- blocco `paths.raw|clean|mart|run_dir` -- blocco `raw_hints` +- blocco `paths` con: + - `raw.dir|manifest|metadata|validation` + - `clean.dir|output|manifest|metadata|validation` + - `mart.dir|outputs|manifest|metadata|validation` + - `run_dir` +- blocco `raw_hints` con: + - `primary_output_file` + - `suggested_read_path` + - `suggested_read_exists` + - `encoding` + - `delim` + - `decimal` + - `skip` + - `warnings` - blocco `latest_run` se esiste, altrimenti `null` Output garantito di `inspect schema-diff`: diff --git a/docs/notebook-contract.md b/docs/notebook-contract.md index b7b455d..9faa8ab 100644 --- a/docs/notebook-contract.md +++ b/docs/notebook-contract.md @@ -49,8 +49,19 @@ Input minimo: Output garantito in `--json`: - `dataset`, `year`, `config_path`, `root` -- `paths.raw`, `paths.clean`, `paths.mart`, `paths.run_dir` -- `raw_hints` +- `paths.raw` con `dir`, `manifest`, `metadata`, `validation` +- `paths.clean` con `dir`, `output`, `manifest`, `metadata`, `validation` +- `paths.mart` con `dir`, `outputs`, `manifest`, `metadata`, `validation` +- `paths.run_dir` +- `raw_hints` con: + - `primary_output_file` + - `suggested_read_path` + - `suggested_read_exists` + - `encoding` + - `delim` + - `decimal` + - `skip` + - `warnings` - `latest_run` Regola pratica: