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](2026-09-27-example-databases-prd.md), 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](https://huggingface.co/datasets/birdsql/bird_mini_dev).
- [Domande PostgreSQL, evidence e SQL di riferimento](https://huggingface.co/datasets/birdsql/bird_mini_dev/blob/f65faf4ae3b638c1fa6df1d3370c8d92c8366301/data/mini_dev_pg-00000-of-00001.json).
- [Istruzioni ufficiali e pacchetto database](https://github.com/bird-bench/mini_dev).
- [Pacchetto completo indicato dalla dataset card](https://drive.google.com/file/d/13VLWIwpw5E3d5DUkMvzw7hvHE67a4XkG/view?usp=sharing).
- [Archivio ZIP collegato dal repository ufficiale](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip):
  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](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
- [Schema e metadati F1](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/f1).
- [Classificazione dei sorpassi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/f1_overtake.md).
- [Tipi di giro](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/lap_type.md).

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.