Skip to content

fix(profile): profila la stessa relazione del clean — pipeline, file e stato - #551

Merged
Gabrymi93 merged 4 commits into
mainfrom
fix/profile-clean-parity
Nov 18, 2026
Merged

Gabrymi93 merged 4 commits into
mainfrom
fix/profile-clean-parity

Conversation

@Gabrymi93

@Gabrymi93 Gabrymi93 commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Sintesi

Il profilo RAW aveva un parser proprio: costruiva una read_csv a mano mentre il clean usa read_raw_to_relation. Le due copie sono divergite e il profilo falliva in silenzio — zero colonne, warning solo dentro _profile/raw_profile.json — lasciando il run verde.

Misurato sul workspace (219 run con profilo vuoto): 188 erano ancora riproducibili con il codice precedente. Dopo il fix: 190 tornano pieni, 0 falliscono. La stessa PR chiude le due metà della parità (parametri di lettura e selezione dei file) e rende lo stato del profilo visibile nel gate.

Contesto collegato

Nessuna issue collegata: emerso da un'analisi della fase raw/profile su 631 dataset.yml e 1.480 artefatti raw_profile.json del workspace. La verifica prima/dopo è nei numeri qui sotto.

Cosa cambia

  • Bug fix
  • Nuova funzionalità del motore
  • Nuovo plugin sorgente
  • Modifica contratto pubblico (dataset.yml, path output, schema parquet)
  • Refactor / performance
  • Documentazione
  • Dipendenze o CI

Tre blocchi, un solo tema: il profilo deve descrivere la relazione che il clean legge.

1. Lettura. profile_with_read_cfg costruisce RAW_INPUT_VIEW con core.duckdb_read.read_raw_to_relation, la funzione esatta del clean. Sparisce il parser del profilo, che non gestiva il formato compatto columns: {column00: "nome:VARCHAR"} (DuckDB riceveva nome:VARCHAR come tipo), normalize_rows_to_columns per nome e align_by_header. Passa anche read_mode (strict/fallback/robust) del dataset, quindi il profilo non può più dichiarare leggibile un file che il clean rifiuterebbe. .ods era trattato come "zip non supportato" mentre il clean lo legge: ora è profilato. profile_excel diventa un wrapper di 3 righe invece di un secondo parser pandas.

2. Selezione file. Il profilo prendeva sempre il primary_output_file; con mode: all|explicit|largest il clean legge N file (o il sottoinsieme di include), quindi hint, row_count, col_count e null_counts descrivevano un'altra relazione. Ora la selezione è quella del clean, riusando select_raw_input, con una precisazione sul chi la decide:

  • dentro run_raw contano i file scritti da questo run (source_files): il metadata.json sul disco è ancora quello del run precedente, quindi leggerlo darebbe la relazione vecchia;
  • per i chiamanti diretti (nessun source_files) contano le entry del manifest, con la stessa soglia del clean (ultimo run RAW SUCCESS);
  • mai la lista della directory, che include copie sciolte non elencate nel manifest.

Per questo clean/input_selection.py → core/input_selection.py: è un contratto condiviso, non un dettaglio del clean.

3. Stato visibile. metadata.json espone profile: {status, file, row_count, columns, warnings}; run_raw_validation emette raw_profile_empty; readiness, inspect schema e review-readiness riportano profile_status e i warning.

Codice morto rimosso: build_suggested_read_cfg non emette più ignore_errors/null_padding/auto_detect/strict_mode — clean.read li filtrava sempre (filter_suggested_format_keys), quindi suggeriva un comportamento che non arrivava mai.

Impatto su contratti pubblici

  • Struttura dataset.yml (nuovo campo, cambio obbligatorietà)
  • Path output (nuovo layer, cambio percorso artifact)
  • Schema parquet (nuova colonna, rename, cambio tipo)
  • CLI o MCP tool (nuovo comando, cambio parametro)
  • API pubblica del toolkit (firma funzione, classe, eccezione)

Dettaglio:

  • clean.input_selection → core.input_selection: verificata l'assenza di import in tutta l'org (rg su workspace, esclusi _local/ e note storiche). Nessuno shim: il modulo non era esportato da clean/__init__.
  • profile_with_read_cfg(file0, ...) → (files: Path | Sequence[Path], ...): compatibile in posizione, accetta una lista per il multi-file. Nessun chiamante usa file0= come keyword.
  • profile_excel(file0, ...) → (files: Path | Sequence[Path], ...): stessa forma di ritorno, ora wrapper.
  • metadata.json raw: nuova chiave root profile (additiva; nessun consumer fuori dal toolkit la legge).
  • build_suggested_read_cfg: rimossi 4 campi dall'output. Verificato che l'unico consumer (clean/read_config.load_suggested_read) li filtrava già.

Se segnato, hai aggiornato downstream? [ ] dataset-incubator — [x] docs/

docs/: CHANGELOG.md aggiornato. Nessun doc descrive le funzioni interne cambiate; docs/advanced-workflows.md continua a valere (suggested_read.yml non più prodotto, leggibile come fallback).

Verifica

Suite completa e strumenti statici:

pytest tests/ -q --ignore=tests/test_s3_parquet_smoke.py   # 1405 passed
ruff check toolkit/ tests/                                  # All checks passed
mypy toolkit/                                               # Success: 127 source files

Verifica sul campo, non solo unit test — rieseguendo il profilo sui dati reali del workspace con il codice nuovo:

  • 219 run con profilo vuoto: 188 FAIL con il codice precedente → 190 ok, 0 FAIL.
  • 80 dataset con selezione multi-file (mode: all|explicit|largest): 54 cambiano, 26 restano identici (quelli con un solo file). Scarti: ga_sentenze 65.768 → 501.531 righe (31 file), openga_ricorsi_appalto 8.446 → 35.116 (31 file a manifest), senato_ddl 16 → 27 colonne, mur_esoneri 9 → 15, bdap_ni_indicatori vuoto → 35 colonne / 8.801 righe. Costo: caso peggiore 1,6 s.
  • Manifest vs directory: 5 dataset hanno un manifest valido e file extra nella directory. Sui due con impatto reale il profilo ora coincide con la selezione del clean: anac_stati_avanzamento 3.459.926 → 2.185.125 righe (9 file a manifest, non 10), openga_ricorsi_appalto 70.232 → 35.116 (31 file, non 32: raw_input.csv è la concatenazione degli altri 31). Numeri verificati con lo stesso read_raw_to_relation che usa il clean.
  • 434 dataset mode: latest: percorso invariato (manifest primary), nessuna modifica attesa né osservata.
  • 4 dataset open-aci con include diverso dal primary: ora profilano il file che il clean legge (Parco_veicolare_2025.xlsx, non Circolante_Copert_2025.xlsx).
  • Controllo nella direzione opposta su 60 profili già sani: 38 identici; i 17 diversi sono tutti spiegati (row_count prima None, oppure artefatti prodotti con un config precedente — es. skip: 1 vs skip: 9 attuale; un caso, inps_retribuzioni, ha il raw riscaricato l'11/11 contro un profilo del 28/10).

Test aggiunti:

  • tests/test_profile_read_parity.py (11, marker regression/policy): formato compatto column00: "nome:VARCHAR", parità colonne profilo↔clean, align_by_header, read_mode: strict, row_count, union multi-file, include, latest invariato, due casi con layout reale <root>/data/raw/<ds>/<year> dove un file sciolto nella directory non deve entrare (source_files e fallback al manifest), e inspect profile che rispetta read_mode.

  • tests/test_raw_profile_visibility.py (5): profile.status nel metadata, warning raw_profile_empty nel gate, load_raw_profile_status per artefatto assente/pieno/vuoto.

  • 2 test riscritti in test_profile_sniff.py: pattavano _profile_view (implementazione rimossa) con un monkeypatch; ora usano un CSV realmente irregolare e testano il comportamento.

  • pytest -m core passa (suite intera eseguita)

  • ruff check . passa

  • mypy toolkit/ passa

  • Modificato o aggiunto test con marker appropriato (contract / policy / regression / adapter / pure_unit / smoke) — verificato con audit-test-markers tests --diff --files ...: 60/60 marcati

Checklist PR

  • Perimetro stretto: una PR = un layer o un fix mirato (fase raw/profile)
  • Se nuovo plugin: test + docs inclusi (n/a)
  • Issue collegata o motivazione dell'assenza (motivata sopra)
  • Se rimuovo un modulo/funzione pubblica: verificato con rg su tutta l'org, nessun importer del modulo spostato. Nessuna funzione pubblica rimossa.

Note per chi revisiona

Punti da guardare con attenzione:

  1. _select_profile_files: con latest/fallback resta il primary_output_file ricevuto da run_raw (nessuna lettura extra del manifest). Con all/explicit/largest la selezione è delegata a select_raw_input. Se la selezione solleva, si ricade sul primary con un warning — meglio un profilo parziale e dichiarato che nessuno.
  2. metadata.profile è una chiave nuova ma additiva. Non l'ho usata come fonte nei consumer: path_resolver e readiness rileggono l'artefatto con load_raw_profile_status, così un metadata vecchio resta leggibile.
  3. robust_preset e None: il preset usava setdefault, che non sovrascrive una chiave presente con valore None — e la config tipizzata le emette tutte. Il fallback strict→robust restava quindi disattivato per il profilo (il clean riceve un dict già filtrato da merge_read_cfg). Corretto: None vale "non impostato". Lo ha fatto emergere il test su inspect profile, che a sua volta non passava read_mode.
  4. source_files vs manifest: sono due percorsi per lo stesso risultato. Dentro run_raw serve il primo (manifest sul disco = run precedente); per un chiamante diretto serve il secondo. Il test copre entrambi con lo stesso fixture, così una futura semplificazione non può romperne uno in silenzio.
  5. Warning, non errore: con 574 dataset su fail_on_error: true, trasformare un profilo vuoto in errore avrebbe reso rossi dataset oggi verdi. Il gate resta warn_only; l'escalation a errore è una decisione separata.
  6. Costo: il profilo ora paga quello che paga il clean. Con ignore_errors: true questo include il health probe di read_csv (uno scan in più). Sui dataset del workspace il caso peggiore misurato è 1,6 s.
  7. Limite noto, non toccato: raw.sources[].name non subisce la sostituzione di {year} (solo args la subisce). In appalti-pubblici/anac_bandi_gara il sorgente si chiama cig_{year} senza args.filename, quindi il file viene scritto letteralmente cig_{year}.csv e il manifest contiene un primary_output_file inesistente (il clean recupera con fallback "legacy selection"). Il fix cambia i nomi dei file raw: con mode: all un rilancio leggerebbe vecchio e nuovo insieme. Serve una migrazione concordata, non un cambio silenzioso: fuori da questa PR.
  8. suggested_read.yml: resta il fallback legacy in clean/read_config.py (0 file presenti su 640 dataset, nessun writer nel codice). Tocca il payload MCP (suggested_read_path/exists): candidato a una PR di pulizia separata.

…e stato

Il profilo RAW aveva un parser proprio: costruiva una `read_csv` a mano mentre
il clean usa `read_raw_to_relation`. Le due copie sono divergite e il profilo
falliva in silenzio (zero colonne, warning solo dentro l'artefatto) su ogni
dataset con `columns` compatto `column00: "nome:VARCHAR"`, con
`normalize_rows_to_columns` per nome o con `align_by_header`. Misurato: dei 219
run con profilo vuoto, 188 erano ancora riproducibili con il codice precedente;
dopo il fix 190 tornano pieni e 0 falliscono. I 434 dataset `latest` restano
sul percorso invariato.

Lettura. `profile_with_read_cfg` costruisce `RAW_INPUT_VIEW` con
`core.duckdb_read.read_raw_to_relation`, la stessa funzione del clean: formato
compatto, normalize, align_by_header, Excel e `.ods` non hanno piu' un parser
separato (`profile_excel` diventa un wrapper di 3 righe; `.ods` era trattato
come "zip non supportato" mentre il clean lo legge). Passa anche `read_mode`
del dataset (`strict`/`fallback`/`robust`), cosi' il profilo non puo'
dichiarare leggibile un file che il clean rifiuterebbe, e restituisce
`row_count` senza la seconda connessione che rileggeva il file da capo.

Selezione. Il profilo prendeva sempre il `primary_output_file`; con
`mode: all|explicit|largest` il clean legge N file (o il sottoinsieme di
`include`), quindi hint, `row_count`, `col_count` e `null_counts` descrivevano
un'altra relazione. Ora la selezione e' quella del clean, riusando
`select_raw_input`. Misurato: 54 dataset su 80 con selezione multi-file
cambiano, con scarti fino a 10x sulle righe (`ga_sentenze` 65.768 -> 501.531 su
31 file, `openga_ricorsi_appalto` 8.446 -> 70.232 su 32) e colonne in piu'
dalla union per nome (`senato_ddl` 16 -> 27). Per questo
`clean/input_selection.py` -> `core/input_selection.py`: la selezione dei file
RAW e' un contratto condiviso, non un dettaglio del clean.

Stato. Un profilo vuoto non e' piu' un successo silenzioso: `metadata.json`
espone `profile: {status, file, row_count, columns, warnings}`,
`run_raw_validation` emette `raw_profile_empty`, e readiness / `inspect schema`
/ `review-readiness` riportano `profile_status` e i warning del profilo. A
valle il clean leggeva con i soli hint dello sniff leggero e si spegnevano
scaffold check, inferenza NOT NULL e suggerimento `dateformat`.

Codice morto rimosso: `build_suggested_read_cfg` non emette piu'
`ignore_errors`/`null_padding`/`auto_detect`/`strict_mode` — `clean.read` li
filtrava sempre, quindi suggeriva un comportamento inesistente.

Test: test_profile_read_parity.py (8: compact columns, union multi-file,
include, read_mode strict, row_count), test_raw_profile_visibility.py (5:
metadata + warning del gate). Due test riscritti dove pattavano
implementazione rimossa (`_profile_view`) con CSV realmente irregolari.
Suite: 1405 passed, ruff e mypy puliti.
L'audit dei marker (job audit-markers) richiede un marker per ogni test: i
quattro test di test_raw_profile_visibility.py proteggevano il formato
dell'artefatto (metadata.profile + warning del gate), quindi `contract`.
…rectory

`_select_profile_files` chiamava `select_raw_input(raw_dir, ...)` senza
`root/dataset/year`: con `dataset=None` la funzione ricade su
`list_input_files(raw_dir)` (la directory), mentre il clean usa
`list_raw_candidates` -> `_metadata_candidates` (le entry del manifest). Con un
file presente su disco ma non elencato nel manifest il profilo descriveva
un'altra relazione — la stessa classe che questa PR vuole chiudere.

Casi reali nel workspace (5 dataset in mode all/explicit/largest con manifest
valido e file extra):

- `anac_stati_avanzamento`: 9 file a manifest, 10 su disco (copia del full).
  Profilo 3.459.926 righe contro le 2.185.125 del clean.
- `openga_ricorsi_appalto`: 31 file a manifest, 32 su disco (`raw_input.csv`,
  concatenazione dei 31 da 35.116 righe). Profilo 70.232 contro 35.116.

Il numero di 70.232 citato nella descrizione iniziale della PR era proprio
quello gonfiato: corretto.

Fix a due livelli, con la regola in un solo posto:

- `run_raw` passa `source_files` = i file scritti da questo run. E' la verita'
  quando il profilo gira dentro il run: il `metadata.json` sul disco e' ancora
  quello del run precedente, quindi leggerlo darebbe la relazione vecchia.
- senza `source_files` (chiamante diretto) la selezione usa il manifest via
  `select_raw_input(root=..., dataset=..., year=...)`, con la stessa soglia
  del clean (ultimo run RAW SUCCESS).

`_is_usable_input_file` diventa pubblico (`is_usable_input_file`) perche' il
filtro dei candidati e' la stessa regola, non una seconda copia.

Test: due casi nuovi in test_profile_read_parity.py con layout reale
(`<root>/data/raw/<ds>/<year>`), manifest a 2 file e un terzo file sciolto da
3 righe: `row_count` resta 2 sia passando `source_files` sia lasciando che la
selezione legga il manifest. Suite 1407 passed, marker audit 60/60.
…ust con None

Tre note dal review, più una regressione che è emersa scrivendone il test.

1. `inspect profile` non passava `read_mode`: `run_profile` profilava in
   `fallback` anche su dataset `strict`/`robust`, quindi la garanzia "il
   profilo non dichiara leggibile un file che il clean rifiuterebbe" valeva
   solo per `run_raw`. Ora legge `clean.read_mode`.

2. `_raw_root` è un'euristica sul layout `<root>/data/raw/<ds>/<year>`:
   `profile_raw` accetta `root` esplicito (lo usa `run_profile` con `cfg.root`)
   e l'inferenza resta solo come fallback per i chiamanti che non lo passano.

3. Regressione trovata dal test di (1): `robust_preset` usava `setdefault`, che
   non sovrascrive una chiave presente con valore `None` — e la config
   tipizzata emette tutte le chiavi. Il preset robusto restava quindi
   disattivato (`ignore_errors=None`, `null_padding=None`) e il fallback
   strict->robust falliva come lo strict. Il clean non lo vedeva perché riceve
   un dict già filtrato da `merge_read_cfg`; il profilo riceve quello grezzo,
   quindi ogni CSV irregolare profilato con `source: auto` finiva in
   `profile_failed`. Ora `None` vale "non impostato", anche in
   `create_profile_relation` (la parità con il clean passa da qui).

Test: `test_inspect_profile_passes_read_mode` (fallback -> colonne, strict ->
profilo vuoto) e `test_robust_preset_treats_none_as_unset`. Suite 1409 passed,
marker audit 74/74.
@Gabrymi93
Gabrymi93 merged commit 84e1380 into main Nov 18, 2026
3 checks passed
@Gabrymi93
Gabrymi93 deleted the fix/profile-clean-parity branch November 18, 2026 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant