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

12 KiB
Raw Blame History

ThothII — Guida utente

Per login, Remember me, ruoli, invalidazione delle sessioni, gruppi OIDC e ripristino, vedere la guida autenticazione locale e la guida OIDC generica.

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:

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:
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)

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:

# 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):

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

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):

# 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
Reference in New Issue View Git Blame Copy Permalink