ThothII/docs/guida-utente.md

# ThothII — Guida utente

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
<id-workspace>/workspace.yaml      ← descrittore del workspace (schema v3)
<id-workspace>/evidence/           ← (facoltativo) documenti di contesto, es. *.md
<id-workspace>/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** `<id>/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 (`<id>/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 `thothctl`**
(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 `thothctl` — comandi principali

`thothctl` si invoca sempre con `--installation <percorso>/thothii-installation.yaml`. I comandi
utili, nell'ordine tipico:

```bash
# 1) vedere lo stato di un workspace (revisione e identità)
thothctl --installation <install> workspace inspect --workspace <id> --json

# 2) introspezione del DWH (genera physical.yaml + LSH)
thothctl --installation <install> workspace preprocess dwh --workspace <id> --json

# 3) suggerire le join (FK) da SQL già approvato
thothctl --installation <install> workspace schema suggest-fks --workspace <id>   --from-sql <query>.sql --output <candidati>.yaml --json

# 4) dopo la revisione: pubblicare gli FK curati in Git e accettarli
thothctl --installation <install> workspace schema accept --workspace <id>   --run <run-id> --yes --json

# 5) indicizzare lo schema (Qdrant)
thothctl --installation <install> workspace index-schema --workspace <id> --json

# 6) preprocessing dell'Evidence
thothctl --installation <install> workspace preprocess evidence --workspace <id> --json

# 7) catena completa (DWH → FK → schema → Evidence)
thothctl --installation <install> workspace preprocess run --workspace <id> --json

# 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione)
thothctl --installation <install> workspace vector inspect --workspace <id> --json
thothctl --installation <install> workspace vector rebuild --workspace <id>   --collection <nome> --confirm <nome> --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 <run-id>`.
- **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
thothctl --installation ~/thothii-installation.yaml workspace preprocess dwh   --workspace psd-clinical --json
thothctl --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:
thothctl --installation ~/thothii-installation.yaml workspace schema accept   --workspace psd-clinical --run <run-id> --yes --json
thothctl --installation ~/thothii-installation.yaml workspace preprocess run   --workspace psd-clinical --resume <run-id> --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`