marcopanandClaude Sonnet 5
7c417d4cf1
Add mkdocs.yml (windmill theme, mermaid2, matching ~/Chirone/chirone/etl setup) with nav split into "ThothII (Documentazione Tecnica)" — architecture overview, existing design specs/plans, reports — and "Considerazioni Generali" for cross-project notes. Add docs/general/pi-configuration.md explaining Pi's three model-resolution tiers (built-in, user models.json, project extension) and where GLM/DeepSeek/ Qwen each sit. Add docs/architecture/overview.md synthesizing the ThothII architecture for the doc site. Relocate the L2 run report into docs/reports/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
60 lines
4.7 KiB
Markdown
60 lines
4.7 KiB
Markdown
# Panoramica dell'architettura
|
|
|
|
> Sintesi ad uso documentazione. Per il dettaglio storico delle decisioni di design vedi le [Specifiche di Design](../superpowers/specs/2026-06-25-thothii-architecture-design.md) e i [Piani di Implementazione](../superpowers/plans/2026-06-25-harness-implementation.md). Per lo stato corrente del progetto (gate manuali pendenti, layout workspace/secret) vedi `PROJECT_STATE.md` nella radice del repo.
|
|
|
|
ThothII è un **datamart builder human-in-the-loop**: trasforma una domanda in linguaggio naturale in SQL validato (ed eventualmente un datamart dbt) attraverso un **workflow deterministico a 8 fasi NL→SQL**, in cui il modello *propone* e un revisore umano *decide* ai gate.
|
|
|
|
## I tre progetti indipendenti
|
|
|
|
```
|
|
frontend (React/SSE) → backend (Fastify) → pi --mode rpc → tht/harness → DWH (sola lettura)
|
|
```
|
|
|
|
| Layer | Stack | Ruolo |
|
|
|---|---|---|
|
|
| **harness/** | Python (`tht` CLI) + Pi gate extension (JS) | Possiede il workflow e **tutta** la persistenza |
|
|
| **backend/** | Fastify + TypeScript | Ponte sottile senza database proprio |
|
|
| **frontend/** | React 18 + Vite | UI che renderizza i widget di gate e ricostruisce il transcript live dallo stream SSE |
|
|
|
|
## L'harness possiede il workflow
|
|
|
|
`tht` (Python) è una CLI deterministica; `harness/.pi/extensions/tht-gate.js` è un'estensione Pi che guida il workflow a 8 fasi. La fonte di verità unica del workflow è `harness/workflow.yaml`; le regole di orchestrazione che il modello deve seguire sono in `harness/.pi/skills/tht-sessione/SKILL.md`. La "fase corrente" **non è memorizzata**: viene calcolata piegando il decision ledger (`harness/tht/phase.py`) — va letta prima di ragionare sulla logica di fase.
|
|
|
|
## Persistenza = documenti di fase, non chat
|
|
|
|
Una sessione è una directory sotto `sessions/` (path definito dal workspace): `session_manifest.yaml` + artefatti per fase (`question.md`, `schema_linking.json`, `sql_final.sql`, …) + `review_decisions.jsonl`. Il contratto (SKILL.md): *"lo stato persistito è la verità — ciò che non è registrato non è accaduto"*. Non esiste uno store di transcript verbatim. Un processo Pi ripreso ricostruisce il contesto da `tht session show <id>` + gli artefatti su disco.
|
|
|
|
## Il backend è un ponte sottile senza database
|
|
|
|
- `ThtRunner` esegue subcommand `tht` in shell
|
|
- `PiProcessManager` esegue un processo Pi figlio per sessione e fa da bridge al suo stream RPC
|
|
- `SessionBridge` mappa eventi RPC di Pi → eventi client (`ui_request` / `text_delta` / `info`)
|
|
- `SseHub` distribuisce questi eventi via SSE al browser
|
|
|
|
Le impostazioni applicative vivono in un file JSON (`backend/data/settings.json`), non in un database.
|
|
|
|
## Contratto del gate human-in-the-loop
|
|
|
|
Il modello propone; un revisore umano decide ai gate tramite widget:
|
|
|
|
- **`reviewer_select`** — scelta singola: un'opzione con `decision` payload auto-conferma/persiste direttamente; un'opzione senza payload chiede soltanto
|
|
- **`reviewer_decide`** — multiselect: ogni scelta È una decisione
|
|
- **`reviewer_confirm`** — gate su artefatto/fase
|
|
|
|
Il frontend renderizza questi widget-descriptor (registro in `src/widgets/`); il transcript live viene ricostruito in memoria dallo stream SSE (`src/store/sessionStore.ts`) — **non è persistito**.
|
|
|
|
## Punti di attenzione ricorrenti
|
|
|
|
- `tht -c`/`--config` è un'opzione **per-comando**: deve seguire il subcommand, mai precederlo (`ThtRunner.buildArgv` lo impone).
|
|
- L'output `--json` deve essere JSON puro su stdout — è un contratto machine-readable.
|
|
- Le stringhe UI sono in inglese; il *contenuto* dei documenti resta nella lingua del workspace (italiano per `psd`), perché è il dato reale — solo chrome/label sono in inglese.
|
|
- I workspace (`harness/workspaces/*.yaml`) impostano il target DB e i path **assoluti** `paths.sessions/artifacts/indexes` — per `psd` puntano a un repo separato e non versionato (`tht-workspace-psd/`). I segreti vivono solo in `harness/.env` (gitignored).
|
|
- Le impostazioni sono globali (`backend/data/settings.json`: workspace/provider/modello/thinking); il form di nuova sessione richiede solo la domanda.
|
|
- **Resume**: una sessione riprendibile rientra all'ultima fase incompleta. Il backend rifiuta il resume con 409 se `finalized` o `archived`; `PiProcessManager.spawnFor` deve inviare `/riprendi-sessione <id>` (resume) vs `/nuova-domanda` (nuova) — il prompt sbagliato trasforma silenziosamente un resume in una nuova domanda.
|
|
|
|
## Come si lancia lo stack
|
|
|
|
Lo **stack completo** (Pi reale + DWH reale, serve VPN + `harness/.env` + `pi` sul PATH) si avvia con `./scripts/run-stack.sh` (frontend `:5173` → backend `:8787`).
|
|
|
|
Comandi per singolo layer, test, lint: vedi il file `CLAUDE.md` nella radice del repo (guida operativa per Claude Code, tenuta sincronizzata con questa pagina).
|