# ThothII — Guida utente Per login, **Remember me**, ruoli, invalidazione delle sessioni, gruppi OIDC e ripristino, vedere la [guida autenticazione locale](install/authentication-local.md) e la [guida OIDC generica](install/authentication-oidc.md). Questa guida accompagna passo-passo chi deve **preparare** il repository dei workspace, **usare gli strumenti** ThothII per quel repository e **usare l'applicazione** per fare domande in linguaggio naturale e ottenere SQL validato. Usa parole semplici ed esempi; i dettagli tecnici restano nei contratti citati in fondo. > **Che cos'è ThothII.** È un *datamart builder* con revisione umana: tu scrivi una domanda in > linguaggio naturale, un modello propone via via i passaggi (chiarimenti, schema, CTE, SQL) e un > **revisore umano decide** a ogni passaggio chiave. Il risultato finale è SQL validato pronto da > eseguire sul data warehouse. --- ## Parte 1 — Preparare il repository dei workspace su Git ### 1.1 La struttura Il repository dei workspace è un **repository Git** che descrive *quali dati* sono disponibili e *come raggiungerli*. Non contiene i dati e **non contiene segreti** (password, token, certificati). Un repository valido contiene: ```text thoth-workspaces.yaml ← catalogo: elenco dei workspace /workspace.yaml ← descrittore del workspace (schema v3) /evidence/ ← (facoltativo) documenti di contesto, es. *.md /schema/annotations.yaml ← (facoltativo) join logici curati a mano (P5) ``` - Il **catalogo** `thoth-workspaces.yaml` è un semplice elenco: ```yaml schema_version: 1 workspaces: - id: psd-clinical name: Policlinico San Donato description: DWH clinico del Policlinico San Donato ``` - L'**id** deve essere minuscolo, senza spazi, es. `psd-clinical` (`[a-z][a-z0-9-]{2,62}`). - Il **descrittore** `/workspace.yaml` è lo schema v3. È l'unica descrizione valida. ### 1.2 Esempio di descrittore (Policlinico San Donato) ```yaml workspace: schema_version: 3 id: psd-clinical name: Policlinico San Donato description: DWH clinico — aritmologia language: it # le descrizioni/evidence sono in italiano dwh: engine: postgres database: postgres schema: datawarehouse supported_transports: [rest_api] # accesso tramite API REST (PostgREST) semantic_index: vector_store: engine: qdrant collection: psd-clinical dimensions: 1024 distance: cosine embedding: provider: ollama_internal model: qwen3-embedding:0.6b dimensions: 1024 llm_policy: allowed: [zai/glm-5.2] diagnostics: dwh_rest: method: POST path: /rpc/ping auth: x-api-key response: { database: database, schema: schema } evidence: source: type: filesystem uri: psd-clinical/evidence # percorso dentro il repository policy: max_chunk_chars: 4000 retain_published_generations: 3 ``` Cosa cambia rispetto ai vecchi workspace (se ne avevi uno): - il database si raggiunge solo con **REST** o **Postgres diretto** (`rest_api` / `postgres_direct`); il tunnel SSH resta disabilitato; - l'indice semantico è **interno** (Qdrant + `qwen3-embedding:0.6b`, 1024 dimensioni, cosine); - l'Evidence **filesystem** sta dentro il repository (`/evidence`) e viene materializzata dal commit Git fissato (P6); è supportata anche l'Evidence HTTP. ### 1.3 Regole da rispettare 1. **Git è la fonte di verità.** Descriptor, catalogo ed Evidence si modificano solo con un *commit* + *push* e poi un *pull* dell'installazione. 2. **Niente segreti nel repository.** Password, token, chiavi private e URL firmati vengono inseriti a runtime nella gestione Workspace e conservati cifrati dal backend. 3. **Solo schema v3.** I descrittori v1/v2 vengono rifiutati prima dell'attivazione. 4. **L'applicazione non fa push di contenuti curati.** L'operatore che cura il repository lavora in un clone autore separato. --- ## Parte 2 — Usare gli strumenti ThothII per il repository Ci sono **due** strumenti: l'**applicazione web** (gestione workspace) e la **CLI `tht`** (preprocessing/operator). L'installazione completa è descritta nei manuali `docs/install/local-workspace-registry.md` (macOS/Windows/Linux) e `docs/install/server-workspace-registry.md`. ### 2.1 `tht` — comandi principali `tht` si invoca sempre con `--installation /thothii-installation.yaml`. I comandi utili, nell'ordine tipico: ```bash # 1) vedere lo stato di un workspace (revisione e identità) tht --installation workspace inspect --workspace --json # 2) introspezione del DWH (genera physical.yaml + LSH) tht --installation workspace preprocess dwh --workspace --json # 3) suggerire le join (FK) da SQL già approvato tht --installation workspace schema suggest-fks --workspace --from-sql .sql --output .yaml --json # 4) dopo la revisione: pubblicare gli FK curati in Git e accettarli tht --installation workspace schema accept --workspace --run --yes --json # 5) indicizzare lo schema (Qdrant) tht --installation workspace index-schema --workspace --json # 6) preprocessing dell'Evidence tht --installation workspace preprocess evidence --workspace --json # 7) catena completa (DWH → FK → schema → Evidence) tht --installation workspace preprocess run --workspace --json # 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione) tht --installation workspace vector inspect --workspace --json tht --installation workspace vector rebuild --workspace --collection --confirm --destroy ``` Note importanti: - **`--json` produce solo JSON su stdout** (contratto macchina): usalo negli script. - **`preprocess run` si ferma per la revisione umana** quando ci sono nuove join proposte: esce con `manual_review_required`. Dopo la revisione si riparte con `schema accept ... --yes` e `preprocess run --resume `. - **Un file Evidence filesystem viene materializzato dal commit Git fissato** (niente checkout mobile); symlink, percorsi pericolosi e alberi troppo grandi vengono rifiutati. - **Il CLI non scrive mai nel repository** (nessun push di contenuti curati). ### 2.2 Applicazione web — gestione workspace La gestione Workspace ha due livelli distinti. **Livello 1 — repository.** La parte iniziale spiega che il sorgente del workspace vive in una directory separata, viene pubblicato dal curatore su un repository ospitato da un server Git come GitHub, GitLab o Gitea, e viene letto da ThothII in sola lettura. Mostra host, repository, branch, revisione attiva e stato dell'ultimo aggiornamento. - **Update workspace repository** non richiede la selezione di un workspace. Il backend esegue il fetch/pull del branch configurato direttamente nel checkout gestito da ThothII, valida l'intera revisione candidata e la attiva in modo atomico. Se la validazione fallisce, conserva la revisione precedente. Non modifica il sorgente remoto e non salva contenuti nella GUI. - Per creare un workspace locale, prepara una directory sorgente con catalogo, `workspace.yaml` e le sottodirectory previste; quindi validala, esegui commit e push dal clone autore. ThothII non offre comandi di creazione, modifica o pubblicazione del sorgente. **Livello 2 — workspace selezionato.** Questi comandi sono isolati perché richiedono prima la selezione del workspace. - **Validate workspace** verifica nuovamente catalogo, descrittore, Evidence e invarianti della revisione attiva selezionata. Non contatta il DWH e non modifica file. - **Save runtime secrets** sostituisce alla cieca i valori compilati. I campi dipendono dal trasporto DWH e dall'autenticazione Evidence dichiarati; il backend restituisce solo lo stato configurato/mancante. - **Forget** elimina dal vault cifrato il singolo secret indicato. Le sessioni o operazioni future che lo richiedono restano bloccate finché non viene inserito di nuovo. - **Test connections** materializza temporaneamente i secret necessari, contatta i servizi dati configurati per quel workspace e rimuove i file temporanei alla fine. Non esporta né pubblica nulla. Il repository Git remoto e le relative credenziali sono impostazioni di installazione. I secret runtime DWH/Evidence sono invece persistenti nel vault cifrato del backend e non nel local storage della GUI. La GUI è soltanto l'interfaccia: dopo l'invio cancella i valori dai campi e non può rileggerli. --- ## Parte 3 — Usare l'applicazione ThothII di base ### 3.1 Nuova sessione Apri l'applicazione e usa il modulo **New session**: inserisci solo la **domanda** in linguaggio naturale (workspace, modello e provider sono impostazioni globali già configurate). Esempio di domanda: > «Estrai i pazienti che hanno eseguito un'ablazione nell'ultimo anno, con nome, cognome e data > dell'intervento.» ### 3.2 Il workflow a 8 fasi e i gate La domanda attraversa **8 fasi**. Tu vedi i documenti intermedi e decidi nei punti chiave: 1. **F1 chiarimento** — se serve, il modello chiede di togliere ambiguità; 2. **F2 memoria** — recupera le memory riutilizzabili; 3. **F3 riscrittura** — riscrive e approva la domanda; 4. **F4 schema-linking** — propone tabelle e colonne collegate; 5. **F5 sintesi** — riassume lo schema scelto; 6. **F6 CTE** — costruisce i CTE; 7. **F7 SQL finale** — produce `sql_final.sql`; 8. **F8 datamart** — esecuzione/export (dbt, CSV, Excel). I **gate di revisione** appaiono come widget: scegli un'opzione singola, seleziona più voci, o conferma un artefatto/fase. Il modello *propone*, il revisore *decide*. Il lato destro mostra gli artefatti (schema-linking, CTE, SQL); il pannello Model activity mostra domanda/ragionamento. ### 3.3 Sessioni Le sessioni sono elencate nella barra laterale con id, domanda, data e autore. Una sessione **riprende** dall'ultima fase incompleta ricostruendo lo stato dai documenti salvati su disco (`session_manifest.yaml` + artefatti di fase + `review_decisions.jsonl`). Lo stato salvato **è** la verità: ciò che non è registrato non è avvenuto. --- ## Esempio pratico completo — Policlinico San Donato ### Passo 0 — repository Crea il repository Git del workspace (es. `tht-workspace-psd`): ```text thoth-workspaces.yaml # catalogo con psd-clinical psd-clinical/workspace.yaml # descrittore v3 (vedi §1.2) psd-clinical/evidence/ # i documenti .md di contesto curati psd-clinical/schema/annotations.yaml # (quando ci sono join curate) ``` Fai `commit` e `push`. Nell'installazione, l'applicazione fa `Pull` e **attiva** il workspace: valida lo schema v3, materializza l'Evidence dal commit fissato e prepara la collection Qdrant (1024/cosine + indici). ### Passo 1 — preprocessing ```bash tht --installation ~/thothii-installation.yaml workspace preprocess dwh --workspace psd-clinical --json tht --installation ~/thothii-installation.yaml workspace preprocess run --workspace psd-clinical --json ``` Se il run si ferma per le join (`manual_review_required`): ```bash # il curatore rivede i candidati e pubblica psd-clinical/schema/annotations.yaml, poi: tht --installation ~/thothii-installation.yaml workspace schema accept --workspace psd-clinical --run --yes --json tht --installation ~/thothii-installation.yaml workspace preprocess run --workspace psd-clinical --resume --json ``` ### Passo 2 — la domanda Nell'applicazione seleziona il workspace `psd-clinical` e crea una sessione con la domanda. Segui le fasi e conferma ai gate: il modello proporrà lo schema-linking (tabelle/colonne del DWH `datawarehouse`), i CTE e infine l'SQL finale, che potrai copiare/visualizzare ed eseguire. --- ## Dove trovare i dettagli tecnici - Contratto CLI: `docs/contracts/workspace-preprocessing-cli.md` - Contratto `.tht-dwh`: `docs/contracts/tht-dwh.md` - Evidence v3: `docs/contracts/workspace-evidence-v3.md` - Installazione locale: `docs/install/local-workspace-registry.md` - Installazione server: `docs/install/server-workspace-registry.md` - Verifica manuale P2–P6: `docs/testing/p2-p6-manual-verification.md`