mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: publish English public documentation
Publish documentation / publish (push) Successful in 43s
Details

Browse Source
This commit is contained in:
Codex
2026-08-26 10:54:44 +02:00
parent b5db0cd3c1
commit 7d32bb1e74
21 changed files with 1378 additions and 1326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guida-utente.md
+145 -152
View File
@@ -1,69 +1,69 @@
# ThothII — Guida utente
# ThothII user guide
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).
For login, **Remember me**, roles, session invalidation, OIDC groups, and recovery, see the
[local authentication guide](install/authentication-local.md) and the [generic OIDC guide](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.
This guide walks you through **preparing** the workspace repository, **using ThothII's tools** for
that repository, and **using the application** to ask natural-language questions and obtain
validated SQL. It uses plain language and examples. The contracts listed at the end contain the
technical details.
> **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.
> **What is ThothII?** It is a *datamart builder* with human review. You write a natural-language
> question, the model proposes each step in turn (clarifications, schema, CTEs, and SQL), and a
> **human reviewer decides** at every important step. The final result is validated SQL ready to
> run on the data warehouse.
---
## Parte 1 — Preparare il repository dei workspace su Git
## Part 1: prepare the workspace repository on Git
### 1.1 La struttura
### 1.1 Structure
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).
The workspace repository is a **Git repository** that describes *which data* is available and
*how to reach it*. It contains neither the data nor **secrets** such as passwords, tokens, or certificates.
Un repository valido contiene:
A valid repository contains:
```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)
thoth-workspaces.yaml # catalog: list of workspaces
<workspace-id>/workspace.yaml # workspace descriptor (schema v3)
<workspace-id>/evidence/ # optional context documents, such as *.md
<workspace-id>/schema/annotations.yaml # optional manually curated logical joins (P5)
```
- Il **catalogo** `thoth-workspaces.yaml` è un semplice elenco:
- The **catalog** `thoth-workspaces.yaml` is a simple list:
```yaml
schema_version: 1
workspaces:
- id: psd-clinical
name: Policlinico San Donato
description: DWH clinico del Policlinico San Donato
- id: acme-ebikes
name: ACME Limited
description: DWH for electric bicycle production
```
- 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.
- The **ID** must be lowercase, contain no spaces, and follow `acme-ebikes` (`[a-z][a-z0-9-]{2,62}`).
- The **descriptor** `<id>/workspace.yaml` uses schema v3. It is the only valid description.
### 1.2 Esempio di descrittore (Policlinico San Donato)
### 1.2 Descriptor example (ACME Limited)
```yaml
workspace:
schema_version: 3
id: psd-clinical
name: Policlinico San Donato
description: DWH clinico — aritmologia
language: it # le descrizioni/evidence sono in italiano
id: acme-ebikes
name: ACME Limited
description: Industrial DWH for electric bicycle production
language: en # descriptions and Evidence are in English
dwh:
engine: postgres
database: postgres
schema: datawarehouse
supported_transports: [rest_api] # accesso tramite API REST (PostgREST)
supported_transports: [rest_api] # access through the REST API (PostgREST)
semantic_index:
vector_store:
engine: qdrant
collection: psd-clinical
collection: acme-ebikes
dimensions: 1024
distance: cosine
embedding:
@@ -84,204 +84,197 @@ diagnostics:
evidence:
source:
type: filesystem
uri: psd-clinical/evidence # percorso dentro il repository
uri: acme-ebikes/evidence # path inside the repository
policy:
max_chunk_chars: 4000
retain_published_generations: 3
```
Cosa cambia rispetto ai vecchi workspace (se ne avevi uno):
Changes from older workspaces:
- 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.
- the database is reached only through **REST** or **direct Postgres** (`rest_api` /
`postgres_direct`); the SSH tunnel remains disabled;
- the semantic index is **internal** (Qdrant plus `qwen3-embedding:0.6b`, 1024 dimensions, cosine);
- **filesystem** Evidence lives in the repository (`<id>/evidence`) and is materialized from the
pinned Git commit (P6). HTTP Evidence is also supported.
### 1.3 Regole da rispettare
### 1.3 Rules
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.
1. **Git is the source of truth.** Change the descriptor, catalog, and Evidence only through a
*commit* and *push*, followed by an installation *pull*.
2. **No secrets in the repository.** Add passwords, tokens, private keys, and signed URLs at
runtime through Workspace management; the backend stores them encrypted.
3. **Schema v3 only.** Reject v1 and v2 descriptors before activation.
4. **The application does not push curated content.** The repository curator works in a separate
authoring clone.
---
## Parte 2 — Usare gli strumenti ThothII per il repository
## Part 2: use ThothII's repository tools
Ci sono **due** strumenti: l'**applicazione web** (gestione workspace) e la **CLI `tht`**
(preprocessing/operator). L'installazione completa è descritta nei manuali
There are **two** tools: the **web application** (workspace management) and the **`tht` CLI**
(preprocessing and operations). The complete installation is described in
`docs/install/local-workspace-registry.md` (macOS/Windows/Linux) e
`docs/install/server-workspace-registry.md`.
### 2.1 `tht` — comandi principali
### 2.1 `tht`: main commands
`tht` si invoca sempre con `--installation <percorso>/thothii-installation.yaml`. I comandi
utili, nell'ordine tipico:
Always invoke `tht` with `--installation <path>/thothii-installation.yaml`. The usual commands are:
```bash
# 1) vedere lo stato di un workspace (revisione e identità)
# 1) inspect workspace state (revision and identity)
tht --installation <install> workspace inspect --workspace <id> --json
# 2) introspezione del DWH (genera physical.yaml + LSH)
# 2) inspect the DWH (generates physical.yaml and LSH)
tht --installation <install> workspace preprocess dwh --workspace <id> --json
# 3) suggerire le join (FK) da SQL già approvato
# 3) suggest joins (FKs) from approved SQL
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
# 4) after review, publish curated FKs in Git and accept them
tht --installation <install> workspace schema accept --workspace <id> --run <run-id> --yes --json
# 5) indicizzare lo schema (Qdrant)
# 5) index the schema (Qdrant)
tht --installation <install> workspace index-schema --workspace <id> --json
# 6) preprocessing dell'Evidence
# 6) preprocess Evidence
tht --installation <install> workspace preprocess evidence --workspace <id> --json
# 7) catena completa (DWH → FK → schema → Evidence)
# 7) complete chain (DWH → FK → schema → Evidence)
tht --installation <install> workspace preprocess run --workspace <id> --json
# 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione)
# 8) inspect or rebuild the Qdrant collection (maintenance only)
tht --installation <install> workspace vector inspect --workspace <id> --json
tht --installation <install> workspace vector rebuild --workspace <id> --collection <nome> --confirm <nome> --destroy
```
Note importanti:
Important notes:
- **`--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
- **`--json` writes JSON only to stdout** (machine contract); use it in scripts.
- **`preprocess run` stops for human review** when it finds new proposed joins: it exits with
`manual_review_required`. After review, continue with `schema accept ... --yes` and
`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).
- **A filesystem Evidence file is materialized from the pinned Git commit** (there is no moving
checkout); symlinks, unsafe paths, and trees that are too large are rejected.
- **The CLI never writes to the repository** (it never pushes curated content).
### 2.2 Applicazione web — gestione workspace
### 2.2 Web application: workspace management
La gestione Workspace ha due livelli distinti.
Workspace management has two distinct levels.
**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.
**Level 1: repository.** The first section shows that the workspace source lives in a separate
directory, is published by the curator to a repository hosted on a Git server such as GitHub,
GitLab, or Gitea, and is read by ThothII in read-only mode. It shows the host, repository, branch,
active revision, and status of the last update.
- **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.
* **Update workspace repository** does not require a workspace to be selected. The backend fetches
or pulls the configured branch into ThothII's managed checkout, validates the entire candidate
revision, and activates it atomically. If validation fails, it keeps the previous revision. It
does not modify the remote source or save content from the GUI.
* To create a local workspace, prepare a source directory with the catalog, `workspace.yaml`, and
the expected subdirectories. Validate it, then commit and push from the authoring clone.
ThothII provides no commands to create, edit, or publish the source.
**Livello 2 — workspace selezionato.** Questi comandi sono isolati perché richiedono prima la
selezione del workspace.
**Level 2: selected workspace.** These commands are separate because they require a workspace to be selected first.
These commands are separate because they require a workspace to be selected first.
- **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.
- **Test workspace 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.
- **Validate workspace source** checks the catalog, descriptor, Evidence, and invariants of the
selected active revision again. It does not contact the DWH or modify files.
- **Save entered secrets** replaces the entered values without displaying them. The fields depend
on the declared DWH transport and Evidence authentication. The backend returns only configured
or missing status.
* **Forget stored value** removes the selected secret from the encrypted vault. Future sessions or
operations that need it remain blocked until it is entered again.
The remote Git repository and its credentials are installation settings. Runtime DWH and Evidence
secrets persist in the backend's encrypted vault, not in the GUI's local storage. The GUI is only
the interface: after submission it clears the field values and cannot read them back.
---
## Parte 3 — Usare l'applicazione ThothII di base
## Part 3: use the ThothII application
### 3.1 Nuova sessione
### 3.1 New session
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).
Open the application and use **New session**. Enter only the **natural-language question**;
workspace, model, and provider are already configured as global settings.
Esempio di domanda:
Example question:
> «Estrai i pazienti che hanno eseguito un'ablazione nell'ultimo anno, con nome, cognome e data
> dell'intervento.»
> "List the electric bicycles completed in the last year, with model, frame number, and completion
> date."
### 3.2 Il workflow a 8 fasi e i gate
### 3.2 The eight-phase workflow and gates
La domanda attraversa **8 fasi**. Tu vedi i documenti intermedi e decidi nei punti chiave:
The question passes through **eight phases**. You see the intermediate documents and decide at the important points:
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).
1. **F1 clarification**: the model removes ambiguity when needed;
2. **F2 Memory**: retrieves reusable Memory;
3. **F3 rewriting**: rewrites and approves the question;
4. **F4 schema linking**: proposes related tables and columns;
5. **F5 summary**: summarizes the selected schema;
6. **F6 CTE**: builds the CTEs;
7. **F7 final SQL**: produces `sql_final.sql`;
8. **F8 datamart**: execution or 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.
**Review gates** appear as widgets: choose one option, select several items, or confirm an
artifact or phase. The model *proposes* and the reviewer *decides*. The right side shows artifacts
(schema linking, CTEs, and SQL); the Model activity panel shows the question and reasoning.
### 3.3 Sessioni
### 3.3 Sessions
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.
Sessions appear in the sidebar with their ID, question, date, and author. A session
**resumes** from its last incomplete phase by rebuilding state from documents saved on disk
(`session_manifest.yaml`, phase artifacts, and `review_decisions.jsonl`). Saved state **is** the
truth: what is not recorded did not happen.
---
## Esempio pratico completo — Policlinico San Donato
## Complete example: ACME Limited
### Passo 0 — repository
### Step 0: repository
Crea il repository Git del workspace (es. `tht-workspace-psd`):
Create the workspace Git repository, for example `tht-workspace-acme`:
```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)
thoth-workspaces.yaml # catalog containing acme-ebikes
acme-ebikes/workspace.yaml # v3 descriptor (see §1.2)
acme-ebikes/evidence/ # curated context .md documents
acme-ebikes/schema/annotations.yaml # when curated joins exist
```
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).
Publish a new Git revision. In the installation, the application fetches and **activates** the
workspace, validates schema v3, materializes Evidence from the pinned revision, and prepares the
Qdrant collection (1024/cosine plus indexes).
### Passo 1 — preprocessing
### Step 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
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`):
If the run stops for joins (`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 <run-id> --yes --json
tht --installation ~/thothii-installation.yaml workspace preprocess run --workspace psd-clinical --resume <run-id> --json
# the curator reviews the candidates and publishes acme-ebikes/schema/annotations.yaml, then:
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
### Step 2: the question
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.
In the application, select the `acme-ebikes` workspace and create a session with the question.
Follow the phases and confirm the gates. The model will propose schema linking (tables and columns
from the `datawarehouse` DWH), CTEs, and finally the SQL, which you can view, copy, and run.
---
## Dove trovare i dettagli tecnici
## Where to find technical details
Per l'accesso DWH REST, la chiave è per installazione e vale solo per `rest_api`: il server PSD rimane `postgres_direct` e `ssh_tunnel` non usa questa chiave. Vedere [guida server DWH](install/dwh-auth-server.md), [enrollment client](install/dwh-auth-client-enrollment.md), [TLS](install/dwh-auth-tls.md) e [runbook PSD](operations/psd-dwh-auth-rollout.md).
For DWH REST access, the key is installation-specific and applies only to `rest_api`; `postgres_direct`
and `ssh_tunnel` do not use it. See the [DWH server guide](install/dwh-auth-server.md), [client
enrollment guide](install/dwh-auth-client-enrollment.md), and [TLS guide](install/dwh-auth-tls.md).
- Contratto CLI: `docs/contracts/workspace-preprocessing-cli.md`
- Contratto `.tht-dwh`: `docs/contracts/tht-dwh.md`
- CLI contract: `docs/contracts/workspace-preprocessing-cli.md`
- `.tht-dwh` contract: `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`