feat: complete catalog-driven preprocessing
Publish documentation / publish (push) Successful in 2m12s
Publish documentation / publish (push) Successful in 2m12s
This commit is contained in:
Codex
@@ -1,12 +1,12 @@
|
||||
# Database management
|
||||
|
||||
Database Management is an administrative catalog for an external PostgreSQL schema. It is separate
|
||||
from workspace preprocessing and, today, does not change the DWH binding used by the NL→SQL
|
||||
session workflow.
|
||||
Database Management is the administrative PostgreSQL Metadata Catalog for an external PostgreSQL
|
||||
schema. Its binding and metadata are the sole database source used by workspace preprocessing and
|
||||
the NL→SQL session workflow.
|
||||
|
||||
## What the catalog owns
|
||||
|
||||
For each YAML workspace, an administrator may configure at most one Metadata Catalog binding. It holds
|
||||
For each workspace identity, an administrator may configure at most one Metadata Catalog binding. It holds
|
||||
the database name, schema, connection binding, write-only encrypted secrets, observed physical
|
||||
schema, optional curated descriptions, generated descriptions, and durable operation history.
|
||||
|
||||
@@ -170,11 +170,11 @@ starting generation. Changing a flag affects future generations only; existing g
|
||||
descriptions are not regenerated. Real and substituted samples remain transient and are not persisted
|
||||
or returned to the browser.
|
||||
|
||||
The database-level **Copy generated descriptions to all columns** action applies every non-empty
|
||||
AI-generated column description to the corresponding curated **Description** field in one atomic
|
||||
operation. It skips empty generated descriptions, reports copied and skipped counts, and retains the
|
||||
generated text. Because this can replace reviewed descriptions, the interface requires explicit
|
||||
confirmation before applying it.
|
||||
The database-level **Copy generated description to descriptions** action applies every non-empty
|
||||
AI-generated table and column description to the corresponding curated **Description** field in one
|
||||
atomic operation. It skips empty generated descriptions, reports aggregate copied and skipped
|
||||
counts, and retains the generated text. Because this can replace reviewed descriptions, the
|
||||
interface requires explicit confirmation before applying it.
|
||||
|
||||
The decisions behind this surface are [ADRs 0001–0011](../adr/0001-postgres-metadata-catalog.md)
|
||||
and the detailed acceptance record is
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
# Server handoff — preprocessing complete
|
||||
|
||||
Questo documento è un'istruzione operativa per il Codex eseguito sul server ThothII. Quando
|
||||
l'operatore chiede di applicarlo, eseguire i passi nell'ordine indicato e consegnare il report
|
||||
finale. La release autorizzata è il tag annotato `260906-preprocessing-complete`.
|
||||
|
||||
## Obiettivo verificabile
|
||||
|
||||
Al termine devono essere vere tutte queste condizioni:
|
||||
|
||||
- il checkout server è esattamente il commit puntato dal tag;
|
||||
- il binario host `tht` proviene dallo stesso checkout;
|
||||
- la migrazione PostgreSQL del catalogo `013_catalog_preprocessing_state` è terminata con exit 0
|
||||
prima dell'avvio del nuovo Core;
|
||||
- immagini `core` e `frontend` sono state ricostruite e i servizi sono healthy;
|
||||
- il workspace PSD ha completato il preprocessing catalog-driven;
|
||||
- Schema, relazioni ed Evidence sono in `<workspace>-reference`, mentre `memory` e
|
||||
`solved_question` restano in `<workspace>-memory`;
|
||||
- login e nuovo caricamento aprono la superficie Core.
|
||||
|
||||
## Confini operativi
|
||||
|
||||
- Conservare descriptor, env, secret, catalogo PostgreSQL, Qdrant, Memory, sessioni e repository
|
||||
workspace esistenti.
|
||||
- Non stampare descriptor completi, env, secret, connection string o log non sanitizzati.
|
||||
- Non usare `reset`, rebase, stash, prune, `down --volumes` o cancellazioni manuali.
|
||||
- Non eseguire `workspace preprocess clear`: l'upgrade richiede soltanto il normale `run`, che è
|
||||
idempotente, sostituisce i dati derivati e conserva la Memory.
|
||||
- Fermarsi davanti a worktree sporco, tag non verificabile, branch divergente, descriptor ambiguo,
|
||||
operazioni attive, migrazione fallita o servizi non healthy. Riportare l'evidenza redatta senza
|
||||
tentare correzioni distruttive.
|
||||
|
||||
## 1. Risolvere i target e fare l'inventario
|
||||
|
||||
Posizionarsi nel checkout server e valorizzare percorsi assoluti reali:
|
||||
|
||||
```bash
|
||||
THTII_REPO=$(git rev-parse --show-toplevel)
|
||||
THTII_INSTALLATION=/percorso/assoluto/thothii-installation.yaml
|
||||
THTII_RELEASE_TAG=260906-preprocessing-complete
|
||||
THTII_WORKSPACE_ID=psd-clinical
|
||||
cd "$THTII_REPO"
|
||||
```
|
||||
|
||||
Se il descriptor attivo non è identificabile univocamente dai comandi già usati sul server,
|
||||
chiederne il percorso all'operatore. Non cercare secret e non scegliere un file per somiglianza.
|
||||
|
||||
Eseguire l'inventario in sola lettura:
|
||||
|
||||
```bash
|
||||
git status --short --branch
|
||||
git branch --show-current
|
||||
git rev-parse HEAD
|
||||
git remote -v
|
||||
test -f "$THTII_INSTALLATION"
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
```
|
||||
|
||||
Registrare il vecchio hash. Il branch deve essere `main`, il worktree deve essere pulito e `origin`
|
||||
deve puntare al Gitea autorizzato `https://git.tylconsulting.it/mptyl/ThothII.git`. Verificare che
|
||||
non siano in corso sessioni Core o preprocessing; in caso contrario fermarsi.
|
||||
|
||||
**Completamento:** checkout, descriptor, installation Compose e workspace ID sono identificati
|
||||
senza ambiguità; il server è inattivo dal punto di vista applicativo e il worktree è pulito.
|
||||
|
||||
## 2. Integrare l'esatta release
|
||||
|
||||
```bash
|
||||
cd "$THTII_REPO"
|
||||
git fetch --prune origin main
|
||||
git fetch origin tag "$THTII_RELEASE_TAG"
|
||||
test "$(git cat-file -t "$THTII_RELEASE_TAG")" = tag
|
||||
THTII_RELEASE_COMMIT=$(git rev-parse "$THTII_RELEASE_TAG^{commit}")
|
||||
git switch main
|
||||
git merge --ff-only "$THTII_RELEASE_COMMIT"
|
||||
test "$(git rev-parse HEAD)" = "$THTII_RELEASE_COMMIT"
|
||||
git status --short --branch
|
||||
```
|
||||
|
||||
Il merge deve essere fast-forward e il worktree deve restare pulito. Se `origin/main` contiene
|
||||
commit successivi al tag, non integrarli in questa esecuzione: il tag è il confine della release.
|
||||
|
||||
**Completamento:** `HEAD` coincide byte per byte con il commit del tag annotato.
|
||||
|
||||
## 3. Installare il CLI della release e validare la configurazione
|
||||
|
||||
```bash
|
||||
cd "$THTII_REPO"
|
||||
./scripts/install-tht.sh
|
||||
tht version --json
|
||||
tht --installation "$THTII_INSTALLATION" update --check-only
|
||||
```
|
||||
|
||||
Leggere strutturalmente dal descriptor i valori `projectDirectory`, `envFile`, `profile` e la lista
|
||||
ordinata `overrides`, senza mostrare contenuti protetti. Devono descrivere il checkout corrente e il
|
||||
profilo `server`. Il descriptor e l'env esistenti sono configurazione autorevole: non rigenerarli e
|
||||
non sostituirli con gli esempi del repository.
|
||||
|
||||
Se esiste `.tht/<compose-project>/current-image.yaml`, fermarsi e segnalarlo: un pin immagine
|
||||
esplicito renderebbe ambiguo il deploy dal checkout.
|
||||
|
||||
**Completamento:** il nuovo `tht` è installato, il descriptor corrente è valido e nessun pin
|
||||
immagine impedisce la ricostruzione.
|
||||
|
||||
## 4. Preparare il comando Compose dell'installation
|
||||
|
||||
Costruire un array shell `THTII_COMPOSE` con lo stesso ordine usato da `tht`:
|
||||
|
||||
1. `docker compose`;
|
||||
2. `--project-name thothii-<prime 12 cifre sha256 del percorso canonico del descriptor>`;
|
||||
3. `--project-directory <projectDirectory>`;
|
||||
4. `--env-file <envFile>`;
|
||||
5. `-f <projectDirectory>/compose.yaml`;
|
||||
6. `-f <projectDirectory>/deploy/compose.server.yaml`;
|
||||
7. ogni override dichiarato, nello stesso ordine;
|
||||
8. `-f <directory descriptor>/generated/compose.models.yaml`;
|
||||
9. `-f <projectDirectory>/deploy/compose.auth-runtime-projection.yaml` quando il descriptor ha
|
||||
`authentication.runtimeProjection`.
|
||||
|
||||
Per una installation server con Git SSH e senza altri overlay, la forma è:
|
||||
|
||||
```bash
|
||||
THTII_INSTALLATION=$(realpath "$THTII_INSTALLATION")
|
||||
THTII_INSTALL_DIR=$(dirname "$THTII_INSTALLATION")
|
||||
THTII_ENV=/percorso/assoluto/letto-da-envFile
|
||||
THTII_COMPOSE_PROJECT="thothii-$(printf '%s' "$THTII_INSTALLATION" | sha256sum | cut -c1-12)"
|
||||
THTII_COMPOSE=(
|
||||
docker compose
|
||||
--project-name "$THTII_COMPOSE_PROJECT"
|
||||
--project-directory "$THTII_REPO"
|
||||
--env-file "$THTII_ENV"
|
||||
-f "$THTII_REPO/compose.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.server.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.git-ssh.yaml"
|
||||
-f "$THTII_INSTALL_DIR/generated/compose.models.yaml"
|
||||
-f "$THTII_REPO/deploy/compose.auth-runtime-projection.yaml"
|
||||
)
|
||||
"${THTII_COMPOSE[@]}" config --quiet
|
||||
```
|
||||
|
||||
Adattare l'array agli override realmente dichiarati. Non usare il blocco di esempio se il
|
||||
descriptor differisce.
|
||||
|
||||
**Completamento:** `config --quiet` termina con exit 0 usando esattamente l'identità e i file della
|
||||
installation già attiva.
|
||||
|
||||
## 5. Costruire, migrare e riavviare
|
||||
|
||||
La build può avvenire mentre i vecchi container sono ancora in esecuzione: i container mantengono
|
||||
il loro image ID. Fermare Core e frontend soltanto dopo una build riuscita.
|
||||
|
||||
```bash
|
||||
"${THTII_COMPOSE[@]}" build core frontend
|
||||
"${THTII_COMPOSE[@]}" stop frontend core
|
||||
"${THTII_COMPOSE[@]}" up --detach catalog-db qdrant embedding
|
||||
"${THTII_COMPOSE[@]}" run --rm catalog-migrate
|
||||
"${THTII_COMPOSE[@]}" run --rm embedding-model-init
|
||||
tht --installation "$THTII_INSTALLATION" start
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
tht --installation "$THTII_INSTALLATION" doctor --json
|
||||
```
|
||||
|
||||
`catalog-migrate` deve terminare con exit 0. `embedding-model-init` è one-shot: `exited (0)` è il
|
||||
suo stato corretto. Se un passo fallisce dopo lo stop, lasciare i container e i volumi disponibili
|
||||
per diagnosi e raccogliere soltanto:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" status
|
||||
tht --installation "$THTII_INSTALLATION" logs
|
||||
```
|
||||
|
||||
**Completamento:** migrazione completata, servizi persistenti healthy e job embedding terminato con
|
||||
exit 0.
|
||||
|
||||
## 6. Eseguire una volta il preprocessing completo
|
||||
|
||||
Ispezionare prima le precondizioni:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
||||
```
|
||||
|
||||
Lo stato atteso dopo l'upgrade è `required`. Se è `blocked`, correggere soltanto il prerequisito
|
||||
indicato. Se è `running`, fermarsi perché esiste un'operazione concorrente. Se è `failed`, leggere
|
||||
il solo ultimo diagnostico e i log sanitizzati del Core prima di ritentare.
|
||||
|
||||
Quando le precondizioni sono soddisfatte, eseguire:
|
||||
|
||||
```bash
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace preprocess run --workspace "$THTII_WORKSPACE_ID" --json
|
||||
|
||||
tht --installation "$THTII_INSTALLATION" \
|
||||
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
||||
```
|
||||
|
||||
Il secondo inspect deve riportare il workspace pronto e la revisione metadati processata uguale a
|
||||
quella corrente. Il run legge tabelle, colonne, descrizioni, sensibilità e foreign key dal Catalogo
|
||||
PostgreSQL; il workspace YAML fornisce soltanto identità ed eventuale Evidence. Un workspace senza
|
||||
Evidence è valido. Il run effettua anche il cutover dall'eventuale collezione Qdrant legacy,
|
||||
preservando `memory` e `solved_question`.
|
||||
|
||||
**Completamento:** preprocessing riuscito una volta, Core ammesso e Memory preservata.
|
||||
|
||||
## 7. Accettazione e report
|
||||
|
||||
Verificare, senza creare una sessione reale se non richiesto dall'operatore:
|
||||
|
||||
- `git rev-parse HEAD` uguale a `git rev-parse 260906-preprocessing-complete^{commit}`;
|
||||
- worktree pulito;
|
||||
- `tht doctor --json` con esito positivo;
|
||||
- `catalog-db`, Qdrant, embedding, Core e frontend healthy;
|
||||
- ultimo `workspace inspect` pronto;
|
||||
- login o hard refresh posizionati sulla pagina Core;
|
||||
- **Administration → Preprocessing** mostra `Status: Ready` e **Run again**;
|
||||
- **New session** è abilitato.
|
||||
|
||||
Consegnare un report breve con vecchio hash, nuovo hash, tag, versione `tht`, exit della migrazione,
|
||||
stato servizi e risultato preprocessing. Redigere URL interni, nomi utente e qualsiasi dato
|
||||
operativo sensibile.
|
||||
@@ -629,14 +629,15 @@ tht --installation "$THTII_NEW_INSTALLATION" workspace preprocess run \
|
||||
--workspace psd-clinical --json
|
||||
```
|
||||
|
||||
Se il preprocess restituisce un run ID interrotto, usare il suo `--resume RUN` soltanto dopo aver
|
||||
diagnosticato la causa. Non lanciare run paralleli. Il preprocess DWH materializza gli artifact
|
||||
runtime; il preprocess Evidence ricostruisce l'indice Qdrant con l'embedding fisso. Le nuove sessioni
|
||||
pinzano la revisione Git attiva del workspace.
|
||||
Se il preprocessing fallisce, correggere il Catalog o la configurazione e rilanciare lo stesso
|
||||
comando dall'inizio: non esistono resume o rollback. Il comando completo materializza LSH e vettori
|
||||
di schema dal Metadata Catalog e ricostruisce la slice Evidence. Le nuove sessioni pinzano la
|
||||
revisione Git attiva del workspace.
|
||||
|
||||
Non copiare nel nuovo descriptor i legacy `harness/workspaces/*.yaml` come catalogo authored e non
|
||||
trasferire vecchi indici vettoriali incompatibili. Il repository workspace schema v4 definisce
|
||||
database ed Evidence; binding, segreti e selezione attiva restano locali all'installation.
|
||||
identità ed Evidence; database, metadati, binding, segreti e selezione attiva restano locali
|
||||
all'installation.
|
||||
|
||||
**Esito richiesto:** `workspace inspect` mostra repository, branch e revisione PSD corretti; test
|
||||
DWH diretto, schema sync e preprocess completo terminano con successo; Qdrant contiene la nuova
|
||||
|
||||
@@ -7,7 +7,7 @@ boundary between what can be published and what can be used by an installation.
|
||||
|
||||
| Role | Owns | Does not own |
|
||||
| --- | --- | --- |
|
||||
| Curator | `thoth-workspaces.yaml`, `<id>/workspace.yaml`, Evidence, and curated schema annotations | installation secrets or active runtime bindings |
|
||||
| Curator | `thoth-workspaces.yaml`, `<id>/workspace.yaml`, and Evidence | database metadata, installation secrets, or active runtime bindings |
|
||||
| Installation operator | Git source, selected workspace, write-only runtime secrets, validation, connectivity, and preprocessing | commits or pushes to the workspace repository |
|
||||
| Reviewer | NL→SQL decisions in a pinned session | workspace publication or preprocessing |
|
||||
|
||||
@@ -20,14 +20,14 @@ Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 works
|
||||
are rejected before activation. Each catalog entry must have a matching descriptor at
|
||||
`<id>/workspace.yaml` in the same Git commit. The application validates a complete candidate
|
||||
revision and activates it atomically; invalid content leaves the preceding active revision in
|
||||
place.
|
||||
place. A v4 descriptor contains only workspace identity and optional Evidence configuration; it
|
||||
does not contain a database or database metadata.
|
||||
<!-- workspace-descriptor-contract:end -->
|
||||
|
||||
<!-- non-workspace-migration:start -->
|
||||
To convert a v3 descriptor before committing it, set `workspace.schema_version` to `4`, remove
|
||||
`llm_policy`, and remove `semantic_index`. Database, Evidence, diagnostics, and binding data remain
|
||||
unchanged. Validate the resulting v4 repository revision before activation; ThothII never rewrites
|
||||
the curator-owned repository during pull.
|
||||
Create a clean v4 descriptor with `workspace` and optional `evidence`. Do not import the old DWH,
|
||||
diagnostics, annotation, `llm_policy`, or `semantic_index` blocks. Configure the database in
|
||||
Database Management. ThothII never rewrites the curator-owned repository during pull.
|
||||
<!-- non-workspace-migration:end -->
|
||||
|
||||
## Operator sequence
|
||||
@@ -41,29 +41,36 @@ the curator-owned repository during pull.
|
||||
connections**. The workspace connection test uses that same current database configuration for
|
||||
DWH connectivity and also checks the workspace Evidence and installation semantic services.
|
||||
4. Select it as the installation workspace before creating sessions.
|
||||
5. Use the host CLI for preprocessing. It dispatches a profile-gated maintenance service and
|
||||
returns a single structured result; `--json` keeps stdout machine-readable.
|
||||
5. Expand **Administration** in the right sidebar and run **Preprocessing**. The button is available
|
||||
when all prerequisites are satisfied: it shows **Run** when preprocessing is required,
|
||||
**Run again** when the workspace is already current, and **Retry** after a failure. The same
|
||||
operation is available from the host CLI for unattended administration. **Clear**, immediately
|
||||
to the left, removes only replaceable Schema/Evidence vectors, LSH, corpus, and checkpoints after
|
||||
an inline confirmation; it preserves Memory and solved questions. `--json` keeps CLI stdout
|
||||
machine-readable.
|
||||
|
||||
```sh
|
||||
INSTALLATION=/absolute/path/thothii-installation.yaml
|
||||
WORKSPACE=example-workspace
|
||||
|
||||
tht --installation "$INSTALLATION" workspace inspect --workspace "$WORKSPACE" --json
|
||||
tht --installation "$INSTALLATION" workspace preprocess dwh --workspace "$WORKSPACE" --json
|
||||
tht --installation "$INSTALLATION" workspace preprocess evidence --workspace "$WORKSPACE" --json
|
||||
tht --installation "$INSTALLATION" workspace preprocess run --workspace "$WORKSPACE" --json
|
||||
tht --installation "$INSTALLATION" workspace preprocess clear --workspace "$WORKSPACE" --json
|
||||
```
|
||||
|
||||
For the full DWH → review → schema-index → Evidence chain, run
|
||||
`workspace preprocess run`. It may stop with `manual_review_required` when FK candidates need a
|
||||
curator decision. Publish the reviewed annotations, update the repository, then accept that exact
|
||||
run and resume it:
|
||||
The command snapshots tables, columns, descriptions, sensitivity, and active relationships from
|
||||
PostgreSQL, samples eligible DWH values for LSH, and replaces the schema/Evidence vector slices.
|
||||
It is rerunnable but not resumable and has no rollback. Catalog sync and description generation
|
||||
remain separate operations and must already be complete.
|
||||
|
||||
```sh
|
||||
tht --installation "$INSTALLATION" workspace schema accept \
|
||||
--workspace "$WORKSPACE" --run <run-id> --yes --json
|
||||
tht --installation "$INSTALLATION" workspace preprocess run \
|
||||
--workspace "$WORKSPACE" --resume <run-id> --json
|
||||
```
|
||||
After clear, the sidebar reports **Required** and the core rejects new sessions until a complete run
|
||||
succeeds. Clear can be repeated safely: an already absent reference collection or derived path is a
|
||||
no-op, and the separate Memory collection is never a cleanup target.
|
||||
|
||||
The sidebar retains no run history. If the current prerequisite blocks a start, it explains what
|
||||
must be completed and correctly reports that there is no run log. If the last run failed, it shows
|
||||
only that run's safe stage, error code, and finish time; use `docker compose logs core` for the
|
||||
corresponding service log.
|
||||
|
||||
The contract gives exact validation, exit code, and JSON rules in
|
||||
[Workspace preprocessing CLI](../contracts/workspace-preprocessing-cli.md). For Evidence source
|
||||
|
||||
Reference in New Issue
Block a user