ThothII/docs/plans/2026-09-27-benchmark-examples.md

Tre esempi locali per l'installazione guidata

Stato: nota esplorativa conservata; requisiti definiti nel PRD e implementazione rinviata su richiesta dell'utente. Requisiti correnti e decisioni aperte sono ora raccolti nel PRD dei database di esempio, che prevale su questa nota esplorativa in caso di divergenza. Branch: codex/benchmark-examples, derivato da codex/guided-standalone-install al commit 67ee5262. Collegamento al progetto installazione: docs/plans/2026-09-27-guided-installation-resumption.md sul branch di origine.

Requisiti dell'utente

• Tre database pubblicamente scaricabili da BIRD o altro benchmark, con evidence.
• Tre livelli di complessità crescente; preferenza per dati in CSV.
• Esempi da implementare in locale.
• Caricamento opzionale tramite CLI dal repository dei workspace: selezione di uno, due o tutti e tre i database, dopo il setup; integrazione nel setup da valutare.
• Dati, schema PostgreSQL commentato ed Evidence disponibili per ogni esempio.
• Domande in un documento di accompagnamento per esercitarsi, senza SQL target.
• Collaudo in tre tappe: Windows, Linux Omarchy, macOS.

Criterio chiarito dall'utente

ThothII viene usato con human in the loop: questo progetto non serve a misurarlo contro un benchmark. I benchmark sono soltanto fonti di database e documentazione. Numero di domande, gold SQL, percentuali di correttezza e copertura delle annotazioni per domanda non sono criteri di selezione o di accettazione. Le domande sono invece utili come materiale didattico: il prodotto le include in un documento separato dalle Evidence, senza soluzioni SQL o valutazione automatica.

Si cercano complessità relazionale e semantica e documentazione sostanziale da curare come Source Evidence: significati, regole aziendali, formule, codifiche, granularità e relazioni. Documenti non collegati ai quesiti del benchmark contano quanto quelli collegati. DDL, righe di esempio e numero di file da soli non dimostrano una buona documentazione di dominio. Dopo il confronto delle alternative, il trio per cui l'utente richiede ora la procedura è Financial, European Football e F1.

Dataset proposti

California Schools è escluso per richiesta dell'utente. European Football è richiesto; l'utente ha inoltre chiesto di valutare Spider 2.0 e la disponibilità di evidence. La proposta corrente comprende Financial e European Football da BIRD e F1 da Spider 2.0-Lite. Shopify, QuickBooks e Workday restano alternative documentate. I livelli sono una progressione didattica proposta per ThothII.

Livello	Database	Motivo	Fonti per le Evidence
Primo percorso	BIRD financial	Conti, clienti, prestiti e movimenti	Codifiche di dominio e regole nelle annotazioni BIRD
Intermedio	BIRD european_football_2	Campionati, squadre, giocatori e partite	Stagioni, significato degli indicatori e aggregazioni nelle annotazioni BIRD
Avanzato	Spider 2.0-Lite f1	Stagioni, gare, piloti, giri, pit stop e cambi di posizione; 29 tabelle dichiarate	Documenti di dominio sui sorpassi e sui tipi di giro, da curare e integrare dove insufficienti

Revisione Hugging Face BIRD osservata: f65faf4ae3b638c1fa6df1d3370c8d92c8366301.

Le evidence BIRD comprendono spiegazioni di codici, significati di colonne e regole di calcolo. Sono annotazioni legate alle domande; richiedono adattamento e revisione per diventare Source Evidence di ThothII. Non sono già un archivio ThothII pronto.

Le definizioni dbt sono fonti da curare, non Evidence Unit già importate in ThothII. Non contare ogni descrizione di colonna come un'evidence distinta. I file tecnici delle librerie dbt non rientrano nel materiale semantico del database. Revisione Spider2 osservata: cafb867313aab4e674652054198f383cf4018943.

Le ricerche motivate e le alternative sono in docs/research/2026-09-27-spider2-lite-evidence-candidates.md e docs/research/2026-09-27-spider2-dbt-evidence-candidates.md.

Fonti e formati

• Dataset ufficiale e licenza dichiarata CC BY-SA 4.0.
• Domande PostgreSQL, evidence e SQL di riferimento.
• Istruzioni ufficiali e pacchetto database.
• Pacchetto completo indicato dalla dataset card.
• Archivio ZIP collegato dal repository ufficiale: risposta HEAD 200, 800943648 byte al controllo; contenuto non ancora scaricato né confrontato con il pacchetto aggiornato della dataset card.

I CSV database_description descrivono schema e valori, non contengono le righe delle tabelle. I dati sono forniti come database SQLite e materiale per PostgreSQL/ MySQL. Proposta: mantenere PostgreSQL come destinazione locale e, se utile, produrre CSV riproducibili insieme a DDL, tipi e vincoli. Non usare CSV senza schema come unica rappresentazione del database. Conservare provenienza, versione, attribuzione e licenza con gli artefatti derivati.

Fonti Spider 2.0-Lite per F1:

• Istruzioni per scaricare i database SQLite locali.
• Schema e metadati F1.
• Classificazione dei sorpassi.
• Tipi di giro.

I tre database sorgente sono SQLite. Esportazione CSV e caricamento PostgreSQL dovranno preservare tipi, relazioni, granularità e contenuto dei dati selezionati. I file sono stati individuati negli archivi; i dati completi non sono stati scaricati né convertiti durante la progettazione.

Proposta di download e caricamento PostgreSQL

Questa sezione risponde alla richiesta di fattibilità e non autorizza né attesta un'implementazione già eseguita.

Destinazione

Il Compose include catalog-db, PostgreSQL 17.6, con volume catalog-data e database thothii_catalog. Quest'ultimo ospita le informazioni applicative del Catalog e la persistenza Memory. Proposta per le installazioni dimostrative: riutilizzare lo stesso servizio PostgreSQL, creando tre database separati, con nomi da finalizzare: example_financial, example_football, example_f1. Ogni database avrà un solo schema applicativo, un workspace associato e un ruolo di interrogazione in sola lettura. L'importazione userà un ruolo distinto con permessi di scrittura.

La creazione degli esempi deve essere una manutenzione esplicita rieseguibile, non un'aggiunta affidata unicamente agli script di inizializzazione del volume PostgreSQL. Le migrazioni Catalog e i suoi ruoli runtime rimangono separati dal caricatore. La condivisione del servizio implica condivisione di risorse, volume e gestione backup; non equivale a isolamento fra istanze PostgreSQL indipendenti.

Sequenza prevista

1. Selezione esplicita di uno, due o tre esempi, anche dopo il primo setup.
2. Manifest versionato per ciascun esempio: URL ufficiali, revisione/checksum, file nell'archivio, fonti documentali, licenze e versione della conversione. Cache dei pacchetti comuni per evitare download duplicati.
3. Download ed estrazione dei SQLite e della documentazione. BIRD: descrizioni CSV e annotazioni evidence, conservando il contesto necessario a interpretarle. F1: metadati dello schema e documenti di dominio. Nessuna generazione automatica di nuove regole presentate come se fossero evidence originali.
4. Ispezione dello schema e dei dati effettivi; conversione SQLite verso DDL PostgreSQL e CSV, con mapping espliciti per tipi, date, booleani, valori null, identificatori e colonne prive di tipo. Rilevare PK/FK presenti e distinguere relazioni documentate o proposte da quelle effettivamente vincolate nella sorgente.
5. Caricamento in database di preparazione dedicati; creazione degli indici e vincoli verificati, confronto delle righe e dei valori e controlli relazionali. Un fallimento lascia l'esempio non pronto senza sostituire una versione funzionante.
6. Pubblicazione dei database validati e registrazione dei binding nel Catalog; creazione dei workspace e sincronizzazione degli schemi via servizi esistenti.
7. Importazione separata: descrizioni nel Catalog; documenti e regole nelle Source Evidence del workspace, con provenienza. Le Evidence restano artefatti del modulo Evidence; la proiezione ricercabile appartiene a Qdrant.
8. Revisione umana/consolidamento delle Evidence e delle relazioni proposte, preprocessing e controlli di utilizzabilità. La disponibilità dei file scaricati non equivale a un workspace pronto.

Il processo conserva stato e versioni per riprendere dopo errori, evita duplicazioni e non sovrascrive Evidence curate o dati esistenti durante una normale riesecuzione. Download ed elaborazione devono usare componenti containerizzati, mantenendo il percorso Windows/WSL2 senza richiedere Python o Node aggiuntivi sull'host.

Decisione architetturale aperta

Gli ADR 0001 e 0003 e il glossario corrente prevedono un database per workspace. La richiesta di un workspace con tre database richiede quindi una scelta esplicita. Proposta: un pacchetto/repository di esempi con tre workspace indipendenti, ognuno associato al proprio database. Nessuna modifica multi-database è approvata finora.

Lavoro previsto dopo la definizione

1. Fissare versione e checksum dei dati, ispezionare schema, tipi, chiavi e documentazione di dominio; definire percorsi dimostrativi di complessità crescente.
2. Preparare il caricamento locale selettivo dei tre dataset, con dati e ruoli distinti dal Catalog applicativo, ripresa e riesecuzione senza duplicazioni.
3. Preparare descriptor e Source Evidence con provenienza per ogni esempio; esplicitare ciò che è documentato e ciò che richiede una decisione del curatore.
4. Registrare binding nel Catalog, sincronizzare schema e predisporre il percorso di revisione/consolidamento e preprocessing dei workspace selezionati.
5. Integrare nel setup la scelta opzionale dei dataset e mostrare per ciascuno caricamento, configurazione, Evidence e stato di utilizzabilità.
6. Verificare tutte le sette selezioni non vuote dei tre esempi, la riesecuzione e gli errori di download/importazione. Collaudare una domanda reale per ciascun esempio installato, poi arresto e riavvio, prima su Windows.

La selezione opzionale comprende anche la possibilità di installare ThothII senza esempi. Nessun download massivo, caricamento database o implementazione del setup è stato eseguito durante questa proposta.