From 2e34ba33e0e0aef0b0b0a2d1bcbcfe81358523d8 Mon Sep 17 00:00:00 2001 From: mptyl Date: Fri, 26 Jun 2026 22:27:05 +0200 Subject: [PATCH] =?UTF-8?q?docs(spec):=20allinea=20=C2=A75.1=20workspace?= =?UTF-8?q?=20YAML=20al=20Config=20reale=20(decisione=20B,=20post=20Task?= =?UTF-8?q?=20A2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit La prima stesura usava una struttura 'ideale' (relational/vector_db.collection/ embeddings.provider) che non combaciava col modello Config portato da ChironeWp3. Allineato alla struttura reale (database/rest/vector_rest/vector_write_rest/ vector_db top-level). Aggiunta nota di allineamento + modello delle key D11. --- .../2026-06-25-thothii-architecture-design.md | 81 ++++++------------- 1 file changed, 24 insertions(+), 57 deletions(-) diff --git a/docs/superpowers/specs/2026-06-25-thothii-architecture-design.md b/docs/superpowers/specs/2026-06-25-thothii-architecture-design.md index f3a36937..95e9f2ca 100644 --- a/docs/superpowers/specs/2026-06-25-thothii-architecture-design.md +++ b/docs/superpowers/specs/2026-06-25-thothii-architecture-design.md @@ -463,68 +463,35 @@ Questa sezione specifica D16. Il requisito: ogni passaggio deve dare al modello ### 5.1 Workspace — `harness/workspaces/.yaml` +> **Nota di allineamento (post-brainstorming):** la prima stesura di questa sezione usava una struttura "ideale" (`relational:`, `vector_db.collection`, `embeddings.provider`) che non corrispondeva al modello `Config` reale portato da ChironeWp3. Durante il Task A2 del piano harness si è scelto (decisione B) di **allineare spec e codice alla struttura reale di `Config`**, perché è uno dei pochi pezzi riusati quasi tal quali e ristrutturarlo avrebbe propagato il cambio a tutti i moduli che lo leggono. La struttura canonica verificata è `harness/workspaces/chirone.example.yaml`; il blocco YAML sotto è un estratto che riflette `nsp/config.py` fedelmente (sezioni `database`/`rest`/`vector_db`/`vector_rest`/`vector_write_rest`/`embeddings`/`evidence`/`execution`, tutte top-level; nessun `relational:` o `vector_db.collection`). Per l'esempio completo fare riferimento al file `chirone.example.yaml`. + ```yaml -name: chirone -description: "Datawarehouse Policlinico San Donato" - -relational: - db_type: postgres # postgres|mariadb|sqlserver|informix|sqlite - transport: rest # direct|rest (rest=PostgREST, direct=nativo) - # --- per transport: direct --- - host: ${CHIRONE_DB_HOST} - port: 5432 - database: datawarehouse - schema: datawarehouse - user: ${CHIRONE_DB_USER} - password: ${CHIRONE_DB_PASSWORD} - # --- per transport: rest (PostgREST) --- - # rest: { base_url: ${CHIRONE_REST_URL}, api_key: ${CHIRONE_REST_KEY}, ssl_ca: ... } - # --- eventuale tunnel ssh (pattern thoth_sqldb2) --- - # ssh: { enabled: true, host: ..., username: ..., auth: private_key, key_path: ... } - -vector_db: - collection: chirone_docs # tabella pgvector target (schema_records|evidence|memory) - dim: 768 - # --- LOADING diretto (server-only, come ChironeWp3 vector_db): ricostruzione distruttiva --- - # local: - # host: localhost - # port: 5438 - # database: postgres - # schema: vectors - # --- LETTURA via REST remota (rpc search_similar, key reader) --- - rest: - base_url: ${THOTH_VEC_REST_URL} # es. https://host/vector/v1/ - api_key: ${THOTH_VEC_API_KEY} # header X-API-Key, read-only - ssl_ca: ${THOTH_SSL_CA} # opzionale, CA interna - # --- SCRITTURA via REST remota (upsert/hash via RPC allowlist, key writer) --- - # OPZIONALE: assente o key vuota = scrittura non abilitata (solo lettura). - # Abilita nsp memory save-one / vector index-schema su postazione remota. - write_rest: - base_url: ${THOTH_VEC_REST_URL} # stessa URL del reader - api_key: ${THOTH_VEC_WRITE_API_KEY} # key SEPARATA, ruolo vector_writer - ssl_ca: ${THOTH_SSL_CA} - -evidence: - source_root: ${EVIDENCE_ROOT} - evidence_dir: evidence/chirone - +# Estratto — struttura reale del Config (vedi chirone.example.yaml per il completo). +database: # DWH relazionale + host: ${THOTH_DB_HOST} + transport: rest # direct | rest +rest: # richiesto se transport=rest + base_url: ${THOTH_DWH_REST_URL} + api_key: ${THOTH_DWH_API_KEY} # ruolo dwh_reader +vector_rest: # LETTURA pgvector (rpc search_similar), key reader + base_url: ${THOTH_VEC_REST_URL} + api_key: ${THOTH_VEC_API_KEY} +vector_write_rest: # SCRITTURA pgvector (upsert/hash), key writer SEPARATA, opzionale + base_url: ${THOTH_VEC_REST_URL} + api_key: ${THOTH_VEC_WRITE_API_KEY} +vector_db: # LOADING diretto pgvector, server-only + host: ${THOTH_VEC_HOST} embeddings: - provider: ollama # interfaccia embed(texts)→vectors; 1 impl nell'MVP - base_url: ${OLLAMA_URL} # http://localhost:11434 - model: nomic-embed-text-v2-moe - dim: 768 - batch_size: 64 - -execution: # fonte di verità read-only (D7 rischio) + base_url: ${THOTH_OLLAMA_URL} +evidence: + source_root: ${THOTH_DOCS_ROOT} +execution: # fonte verità read-only (D7) allow: [cte_test, explain, preview, aggregate, export] - max_preview_rows: 10 - max_export_rows: 10000 - statement_timeout_ms: 5000 - # esempio: funzioni che permettono side-effect o escalation privilegi - forbidden_functions: [set_config, dblink, dblink_exec, lo_import] ``` -Il modulo `workspace.py` carica + valida + espande `${VAR}` dal `.env`. Una sola fonte di verità per `execution.allow`, condivisa tra `nsp` (validazione durante il workflow) e backend (SQL finale read-only). +Il modulo `workspace.py` (confine D3) carica + valida + espande `${VAR}` dal `.env`, delegando a `load_config` (portato da ChironeWp3). Una sola fonte di verità per `execution.allow`, condivisa tra `nsp` (validazione durante il workflow) e backend (SQL finale read-only). + +**Modello delle key (D11, vedi §5.4):** il `Config` ha tre sezioni `RestConfig` indipendenti con key distinte — `rest.api_key` (DWH reader), `vector_rest.api_key` (pgvector reader), `vector_write_rest.api_key` (pgvector writer). Nel deployment Chirone reale la key del DWH reader e quella del pgvector reader **condividono lo stesso valore** (key unica validata da Nginx), ma restano campi separati nella config per chiarezza e flessibilità. ### 5.2 Session — `harness/sessions//`