mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
a54d4769dde1cc70135983e41c6554a600e0029a
ThothII/docs/guida-utente.md
T

281 lines
12 KiB
Markdown
Raw Blame History

# 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
<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: acme-ebikes
name: ACME Limited
description: DWH della produzione di biciclette elettriche
```
- L'**id** deve essere minuscolo, senza spazi, es. `acme-ebikes` (`[a-z][a-z0-9-]{2,62}`).
- Il **descrittore** `<id>/workspace.yaml` è lo schema v3. È l'unica descrizione valida.
### 1.2 Esempio di descrittore (ACME Limited)
```yaml
workspace:
schema_version: 3
id: acme-ebikes
name: ACME Limited
description: DWH industriale — produzione di biciclette elettriche
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: acme-ebikes
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: acme-ebikes/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 `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 <percorso>/thothii-installation.yaml`. I comandi
utili, nell'ordine tipico:
```bash
# 1) vedere lo stato di un workspace (revisione e identità)
tht --installation <install> workspace inspect --workspace <id> --json
# 2) introspezione del DWH (genera physical.yaml + LSH)
tht --installation <install> workspace preprocess dwh --workspace <id> --json
# 3) suggerire le join (FK) da SQL già approvato
tht --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
tht --installation <install> workspace schema accept --workspace <id> --run <run-id> --yes --json
# 5) indicizzare lo schema (Qdrant)
tht --installation <install> workspace index-schema --workspace <id> --json
# 6) preprocessing dell'Evidence
tht --installation <install> workspace preprocess evidence --workspace <id> --json
# 7) catena completa (DWH → FK → schema → Evidence)
tht --installation <install> workspace preprocess run --workspace <id> --json
# 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione)
tht --installation <install> workspace vector inspect --workspace <id> --json
tht --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 source** verifica nuovamente catalogo, descrittore, Evidence e invarianti della
revisione attiva selezionata. Non contatta il DWH e non modifica file.
- **Save entered 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 stored value** elimina dal vault cifrato il singolo secret indicato. Le sessioni o operazioni future
che lo richiedono restano bloccate finché non viene inserito di nuovo.
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:
> «Elenca le biciclette elettriche completate nell'ultimo anno, con modello, numero di telaio e
> data di completamento.»
### 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 — ACME Limited
### Passo 0 — repository
Crea il repository Git del workspace (es. `tht-workspace-acme`):
```text
thoth-workspaces.yaml # catalogo con acme-ebikes
acme-ebikes/workspace.yaml # descrittore v3 (vedi §1.2)
acme-ebikes/evidence/ # i documenti .md di contesto curati
acme-ebikes/schema/annotations.yaml # (quando ci sono join curate)
```
Pubblica una nuova revisione Git. Nell'installazione, l'applicazione acquisisce e **attiva** il workspace:
valida lo schema v3, materializza l'Evidence dalla revisione fissata e prepara la collection Qdrant
(1024/cosine + indici).
### Passo 1 — preprocessing
```bash
tht --installation ~/thothii-installation.yaml workspace preprocess dwh --workspace acme-ebikes --json
tht --installation ~/thothii-installation.yaml workspace preprocess run --workspace acme-ebikes --json
```
Se il run si ferma per le join (`manual_review_required`):
```bash
# il curatore rivede i candidati e pubblica acme-ebikes/schema/annotations.yaml, poi:
tht --installation ~/thothii-installation.yaml workspace schema accept --workspace acme-ebikes --run RUN_ID --yes --json
tht --installation ~/thothii-installation.yaml workspace preprocess run --workspace acme-ebikes --resume RUN_ID --json
```
### Passo 2 — la domanda
Nell'applicazione seleziona il workspace `acme-ebikes` 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
Per l'accesso DWH REST, la chiave è per installazione e vale solo per `rest_api`; `postgres_direct` e `ssh_tunnel` non usano questa chiave. Vedere [guida server DWH](install/dwh-auth-server.md), [enrollment client](install/dwh-auth-client-enrollment.md) e [TLS](install/dwh-auth-tls.md).
- Contratto CLI: `docs/contracts/workspace-preprocessing-cli.md`
- Contratto `.tht-dwh`: `docs/contracts/tht-dwh.md`
- Evidence v3: `docs/contracts/workspace-evidence-v3.md`
Reference in New Issue View Git Blame Copy Permalink