From ecd986f208a9d840c05b80ac0fdc3df25232439d Mon Sep 17 00:00:00 2001 From: mptyl Date: Thu, 13 Aug 2026 13:00:08 +0200 Subject: [PATCH] docs: aggregate P2-P6 acceptance, full-suite results, and user guide --- PROJECT_STATE.md | 30 ++- docs/guida-utente.md | 255 ++++++++++++++++++++++ docs/testing/p2-p6-manual-verification.md | 7 +- mkdocs.yml | 1 + 4 files changed, 291 insertions(+), 2 deletions(-) create mode 100644 docs/guida-utente.md diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 40b43024..24bd1d8a 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -7,7 +7,7 @@ > ThothII per il repository (app + CLI `thothctl`), (3) come usare l'applicazione ThothII di base > (sessioni, domande, gate). Il documento userà parole semplici ed esempi; i dettagli tecnici > resteranno nei contratti esistenti. Esempio pratico completo: Policlinico San Donato. - Last updated: 2026-08-13 (P2–P6 all accepted). + Last updated: 2026-08-13 (P2–P6 accepted; aggregate PASS; user guide written). > Point a fresh session here ("read PROJECT_STATE.md") before substantial work. ### P3 effective configuration and `.tht-dwh` — implementation complete, automated PASS, manual PASS (2026-08-13) @@ -134,6 +134,34 @@ - **Manual acceptance:** PASS (owner approval 2026-08-13) — walkthrough section P6 in `docs/testing/p2-p6-manual-verification.md`. +### Final aggregate P2–P6 verification — automated PASS, manual PENDING (2026-08-13) + +- **Aggregate process goal:** one clean-state run exercises the complete DWH → FK → schema → + filesystem Evidence chain through `thothctl`/the operator surface, proves idempotency and + revision isolation, proves a second installation consumes the same Git workspace with its own + state, exercises unsafe-tree and bound negatives, and cleans only owned resources. +- **Automated acceptance:** PASS 12/12 (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report + `.artifacts/p2p6-integration/p2p6-ee542112c526ef0d4c25ddf6c8bc164b/` retained via `--keep`, bound + to clean source commit `1dcf4051b0d9db8ae163e4d7c53871564ca3c564`): preflight, clean_state, + ownership, activation_materialization, dwh_chain, fk_schema_evidence_chain, revision_isolation, + second_installation, unsafe_tree_refused, bound_refused, secret_scan, cleanup_confinement. Runner: + `scripts/p2p6-acceptance.sh` / `backend/scripts/p2p6-acceptance.mjs` (+unit test). +- **Full suites + builds (design §10):** harness **873 passed / 4 deselected** (with color disabled; + the forced-color environment splits `--help` flags and trips the gate-CLI consistency test only); + backend **698/698** + tsc + build; frontend **364/364** + `tsc -b` + build; `thothctl` Go + build+test **9/9**; `git diff --check` clean. +- **Manual acceptance:** PENDING — "Final aggregate P2–P6 verification" in + `docs/testing/p2-p6-manual-verification.md`. + +### User-guide deliverable (owner requirement) — written, review PENDING (2026-08-13) + +- **`docs/guida-utente.md`** (Italian, simple words + examples) covers: (1) preparing the workspace + Git repository (catalog + schema-v3 descriptor + Evidence + curated annotations), (2) using the + ThothII tools for the repository (`thothctl` commands + read-only workspace management), and (3) + using the base ThothII application (sessions, questions, gates). It ends with a complete + Policlinico San Donato walkthrough and links to the technical contracts. +- Registered in the MkDocs nav (`mkdocs.yml`). Owner review PENDING. + ### P2 host preprocessing CLI — implementation complete, automated PASS, manual PENDING (2026-08-11) - **Scope:** P2 (PRD D2, based on the P1.1 registry contract): the installed native `thothctl` diff --git a/docs/guida-utente.md b/docs/guida-utente.md new file mode 100644 index 00000000..4950ab06 --- /dev/null +++ b/docs/guida-utente.md @@ -0,0 +1,255 @@ +# 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 +/workspace.yaml ← descrittore del workspace (schema v3) +/evidence/ ← (facoltativo) documenti di contesto, es. *.md +/schema/annotations.yaml ← (facoltativo) join logici curati a mano (P5) +workspace-docs// ← generato dall'applicazione, non va editato +``` + +- 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.** Endpoint, token, certificati e password vivono solo nei file + di installazione protetti (fuori da Git). +3. **I file `workspace-docs/` sono generati** dall'applicazione: non modificarli a mano. +4. **Solo schema v3.** I descrittori v1/v2 vengono rifiutati prima dell'attivazione. +5. **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 /thothii-installation.yaml`. I comandi +utili, nell'ordine tipico: + +```bash +# 1) vedere lo stato di un workspace (revisione e identità) +thothctl --installation workspace inspect --workspace --json + +# 2) introspezione del DWH (genera physical.yaml + LSH) +thothctl --installation workspace preprocess dwh --workspace --json + +# 3) suggerire le join (FK) da SQL già approvato +thothctl --installation workspace schema suggest-fks --workspace --from-sql .sql --output .yaml --json + +# 4) dopo la revisione: pubblicare gli FK curati in Git e accettarli +thothctl --installation workspace schema accept --workspace --run --yes --json + +# 5) indicizzare lo schema (Qdrant) +thothctl --installation workspace index-schema --workspace --json + +# 6) preprocessing dell'Evidence +thothctl --installation workspace preprocess evidence --workspace --json + +# 7) catena completa (DWH → FK → schema → Evidence) +thothctl --installation workspace preprocess run --workspace --json + +# 8) ispezione/ricostruzione della collection Qdrant (solo manutenzione) +thothctl --installation workspace vector inspect --workspace --json +thothctl --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 + +Per i workspace **già pronti** (`ready`) la pagina workspace è **in sola lettura**: +*Pull/Sync*, *Validate*, *Test* dell'installazione, *Export*, riepilogo Evidence e la guida Git per +il curatore. Il modulo di bootstrap modificabile compare solo per gli slot del catalogo in stato +`configuration_required`. + +--- + +## 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 --yes --json +thothctl --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` diff --git a/docs/testing/p2-p6-manual-verification.md b/docs/testing/p2-p6-manual-verification.md index df422a91..f60bf76b 100644 --- a/docs/testing/p2-p6-manual-verification.md +++ b/docs/testing/p2-p6-manual-verification.md @@ -203,7 +203,12 @@ Checks: Decision: **PASS** (owner approval 2026-08-13). ## Final aggregate P2–P6 verification -**Status:** runnable only after P6. +**Status:** runnable; automated integration PASS; manual acceptance PENDING. + +The automated aggregate (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report +`.artifacts/p2p6-integration/...`) already executed the complete DWH → FK → schema → filesystem +Evidence chain, idempotency, revision isolation, a second installation, unsafe-tree/bound negatives, +secret scan, and exact cleanup. The final manual pass will start with a new registry and two independent installations. It will run the complete DWH → FK → schema → filesystem Evidence chain, prove idempotency and revision diff --git a/mkdocs.yml b/mkdocs.yml index 07713d3c..bbc64d70 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,7 @@ markdown_extensions: alternate_style: true nav: - Home: index.md +- Guida utente: guida-utente.md - ThothII (Documentazione Tecnica): - Panoramica Architettura: architecture/overview.md - Installazione Docker (4 contesti): installazione-docker-4-contesti.md