ThothII/docs/install/psd-workspace-setup.md

Policlinico San Donato — setup workspace (nuova gestione)

Guida operativa per collegare ThothII al DWH di PSD con il nuovo sistema (registry Git + descriptor v3 + thothctl). Lo stato attuale:

• il repository PSD è già stato ristrutturato e committato localmente in /Users/mp/projects/tht-workspace-psd (layout P1.1: thoth-workspaces.yaml + psd-clinical/workspace.yaml + psd-clinical/evidence/ + psd-clinical/schema/annotations.yaml);
• la validazione locale del registry è già passata (descriptor v3 valido, 36 Evidence materializzate, 42 KB di annotations sincronizzate, docs generate).

Rimangono i passi che richiedono segreti/accesso. I template pronti sono in deploy/psd/ (*.example).

1. Pubblica il repository PSD su GitHub

Crea un repository Git privato su GitHub e pubblicalo:

git -C /Users/mp/projects/tht-workspace-psd remote add origin <URL-repo>
git -C /Users/mp/projects/tht-workspace-psd push -u origin main

Oppure fornisci URL + credenziali e lo pusho io.

2. Prepara i segreti (in deploy/psd/secrets/, non tracciati)

File	Contenuto	Riuso
psd-clinical-dwh-api-key	la X-API-Key del DWH REST	THT_DWH_API_KEY esistente
psd-clinical-dwh-ca.pem	CA interna (solo se il REST la presenta)	THT_SSL_CA esistente
pi-auth.json	profilo Pi con le credenziali LLM (zai/deepseek/qwen)	esistente
thothii.secrets	bundle secret dell'app	esistente
git-credentials	credenziali HTTPS del remote Git privato	nuova

Nota CA: il preprocessing DWH via REST supporta la CA (TLS_CA_FILE). Il diagnostic di readiness REST, invece, rifiuta una CA per-request privata: se il ping fallisce per la CA, va reso trusted a runtime oppure si adatta diagnostics.dwh_rest nel descriptor Git.

3. Compila i file operatore (dai template)

cd deploy/psd
cp workspace-bindings.env.example workspace-bindings.env
cp operator.env.example operator.env
cp thothii-installation.yaml.example thothii-installation.yaml

Compila i placeholder con i valori reali (remote GitHub, path assoluti). Il bindings file per PSD è:

THT_WS_PSD_CLINICAL_DWH_TRANSPORT=rest_api
THT_WS_PSD_CLINICAL_DWH_BASE_URL=https://supabase-aritmolab.policlinicosandonato.it/dwh/
THT_WS_PSD_CLINICAL_DWH_API_KEY_FILE=/run/secrets/psd-clinical-dwh-api-key

4. Genera il connector override

scripts/generate-connector-secrets-override.sh   --bindings-env deploy/psd/workspace-bindings.env   --operator-env deploy/psd/operator.env   --output deploy/psd/connector-secrets.yaml   --service workspace-maintenance --role all

5. Avvia lo stack (VPN attiva; internet per scaricare il modello)

scripts/compose-with-preflight.sh --env-file deploy/psd/operator.env   -f compose.yaml -f deploy/compose.local.yaml   -f deploy/compose.git-https.yaml -f deploy/psd/connector-secrets.yaml   up --build -d

Il primo avvio esegue embedding-model-init, che scarica qwen3-embedding:0.6b nel volume embedding-models e poi sblocca core.

6. Attiva e valida il workspace

curl --fail --silent http://127.0.0.1:8787/health
thothctl --installation deploy/psd/thothii-installation.yaml workspace inspect --workspace psd-clinical --json

7. Preprocessing (DWH → FK → schema → Evidence)

thothctl --installation deploy/psd/thothii-installation.yaml workspace preprocess run   --workspace psd-clinical --json

Se il run si ferma per la revisione delle join (manual_review_required):

# il curatore rivede i candidati e pubblica psd-clinical/schema/annotations.yaml (commit+push),
# poi l'installazione fa pull, e si esegue:
thothctl --installation deploy/psd/thothii-installation.yaml workspace schema accept   --workspace psd-clinical --run <run-id> --yes --json
thothctl --installation deploy/psd/thothii-installation.yaml workspace preprocess run   --workspace psd-clinical --resume <run-id> --json

8. Testa una domanda reale

Apri l'app (http://localhost:5173), seleziona psd-clinical e crea una sessione con una domanda in linguaggio naturale. Segui le 8 fasi e conferma ai gate fino all'SQL finale.

Cosa serve ancora da te

1. URL + credenziali del repo GitHub del workspace PSD (passo 1).
2. X-API-Key DWH (+ CA, se serve) riusabili dall'ambiente attuale (passo 2).
3. Conferma del provider/modello LLM di default (zai/glm-5.2 è già impostato nel descriptor).
4. Conferma dell'endpoint ping REST del DWH (POST /rpc/ping con X-API-Key) per il diagnostics.dwh_rest del descriptor.

Con questi quattro elementi completiamo i passi 2–4 insieme e lanciamo lo smoke live.