marcopanandClaude Opus 4.8
c4d130828f
Implementazione del piano di remediation progressiva sui difetti emersi dall'analisi dell'harness. Tutto verificato: 214 test Python (incl. L0 su Postgres reale), 14 test JS del gate, ruff pulito. Blocco 1 (CRITICA, integrazione gate↔CLI): - phase advance: gate usa --auto + exit 6; reviewer_confirm kind:phase fa advance esplicito che applica i prerequisiti (prima non avanzava per le fasi a conferma umana). - cte plan riceve i --name dal gate (param names); set-question con id posizionale; skill `tht search find`; nuovo comando `tht memory save-one` con dedup hash client-side in save_one_memory. Blocco 2 (D15, stato post-rollback): - campo `phase` su DecisionRecord + effective_decisions phase-aware per i subject "a nome" (cte_approved ecc.); _compute_promotions e finalize sulla vista effective; finalize confronta col piano CTE effettivo, non glob; `decision add --retracts` + comando `decision retract`. Blocco 3 (D7 read-only + D6 manifest): - assert_read_only su tutti e quattro i codepath (direct + REST); - manifest author/summary/updated_at/updated_by/schema_version popolati + helper touch_manifest sulle mutazioni. Blocco 4-5 (D14a/D14b): - decision_min_phase data-driven via `emits:` in workflow.yaml; - formula evidence: status auto, search_formulas, gruppo CLI `tht formula`, `search find --kind formula`, load_evidence_dir salta i .sql.md. Blocco 6 (robustezza): - taskdoc slice promoted_tables + bound enforced; report escaping/bound + rsplit note; filtro kind reader REST/direct; conteggio upserted robusto; guard REST run_query non-list; LSH disallineato -> LshIndexError. Blocco 7 (pulizia): - dead code gate e KIND_TO_TABLE morto rimossi; doc Postgres-only (README + connection.py). Blocco 0 (parziale): test di compatibilità firma gate↔CLI (tests/integration). Rinviati: fake-Pi runtime completo, artifact-gate da disco (#23), parità eligibility REST/direct (#28), unificazione reserved-labels (#30), memory_rejected da deselezione (#33). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
# ThothII harness — `tht`
|
|
|
|
The self-contained Pi layer of ThothII: a deterministic Python CLI (`tht`) + a Pi gate
|
|
extension (`.pi/extensions/tht-gate.js`) that runs the 8-phase NL→SQL workflow,
|
|
emitting and consuming widget-descriptor JSON. Derived from the reference implementation as a validated
|
|
starting point, **adapted** (not assumed reliable) to the ThothII contract.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
cd harness
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
The `tht` command is now on PATH. Node ≥ 20 is needed for the gate JS tests
|
|
(`npm test`).
|
|
|
|
## Configure
|
|
|
|
### `.env` (gitignored — secrets live ONLY here)
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# fill in: THT_PROFILE, THT_DB_*, THT_DWH_API_KEY, THT_VEC_API_KEY,
|
|
# THT_VEC_WRITE_API_KEY, THT_SSL_CA, THT_OLLAMA_URL, ...
|
|
```
|
|
|
|
Keys are never logged; URLs are fine. Rotate any key that appeared in chat.
|
|
|
|
### `workspaces/<name>.yaml`
|
|
|
|
A workspace wires the relational DWH + the pgvector (dual-key) + embeddings + evidence.
|
|
See `workspaces/tht.example.yaml`. `${THT_*}}` tokens expand from `.env`.
|
|
|
|
> **DB support (MVP):** the `direct` transport supports **PostgreSQL only** (psycopg2
|
|
> driver, `pg_*` catalog introspection, postgres-dialect sqlcheck/EXPLAIN). The central
|
|
> production DWH is reached via the `rest` transport. Multi-dialect `direct` support
|
|
> (sqlserver/mariadb/informix, cf. `Thoth/thoth_sqldb2`) is separate future work.
|
|
|
|
### Per-customer workspace repo (deployment shape)
|
|
|
|
ThothII is generic; **evidence content and LSH indexes are per-customer** and live in a
|
|
**separate repo**, not copied into `harness/`. The deployment is two checkouts + one `.env`:
|
|
|
|
```
|
|
ThothII/ generic harness (this repo)
|
|
└── harness/ tht CLI + .env (THT_* secrets, points at the customer repo)
|
|
|
|
tht-workspace-<customer>/ per-customer workspace repo (separate git repo)
|
|
├── <customer>.yaml workspace YAML (paths ABSOLUTE, anchored here)
|
|
├── evidence/ curated evidence markdown (frontmatter-structured, by domain)
|
|
├── artifacts/ derived artifacts (gitignored; regenerated by tht)
|
|
├── indexes/ LSH index (gitignored; regenerated by `tht lsh build`)
|
|
└── sessions/ per-session artifacts (gitignored)
|
|
```
|
|
|
|
`THT_DOCS_ROOT` in `.env` points at the **root** of the customer repo
|
|
(`evidence.source_root` + `evidence.evidence_dir` resolve the curated folder).
|
|
All `tht` commands take the customer workspace via `-c`:
|
|
|
|
```bash
|
|
tht schema introspect -c /path/to/tht-workspace-<customer>/<customer>.yaml
|
|
tht lsh build -c /path/to/tht-workspace-<customer>/<customer>.yaml
|
|
tht session new -c /path/to/tht-workspace-<customer>/<customer>.yaml
|
|
```
|
|
|
|
## The workflow
|
|
|
|
`workflow.yaml` is the **single source of workflow truth** (spec F2). Eight phases
|
|
(F1 chiarimento → F8 datamart). Edit it to change the workflow; `phase.py`, the gate,
|
|
and the skill all read from it — no mirrored constants to drift.
|
|
|
|
```bash
|
|
tht phase meta --json # the gate reads workflow facts from here
|
|
tht phase meta # human-readable
|
|
```
|
|
|
|
## Run
|
|
|
|
The harness runs inside Pi (`pi --mode rpc`, cwd = `harness/`):
|
|
|
|
```bash
|
|
pi --mode rpc
|
|
# in Pi: /nuova-domanda "<your question in natural language>"
|
|
```
|
|
|
|
The gate (`tht-gate.js`) presents reviewer widgets (widget-descriptor), the reviewer
|
|
decides, and `tht` persists decisions to the append-only ledger (`review_decisions.jsonl`).
|
|
See `docs/testing.md` for what each interaction level validates.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
pytest # L0 (testcontainers, real Postgres) + L1 (pure logic + gate builders)
|
|
npm test # gate widget-builder golden + fuzzy tests (JS)
|
|
pytest -m l2 # L2: real GLM 5.2 + remote DWH (pre-release; needs .env + VPN + CA bundle)
|
|
```
|
|
|
|
L0 needs Docker (present on the dev machine). L2 is manual, non-deterministic, and
|
|
skips cleanly without `.env`. See `docs/testing.md` for the honest split of what each
|
|
level covers and — crucially — does **not** cover.
|
|
|
|
## Layout
|
|
|
|
```
|
|
tht/ Python package (CLI + workflow + phase + decisions + db/rest/mschema/
|
|
vectorstore/evidence/search/session + memory)
|
|
.pi/ Pi project (settings, prompts, themes, extensions/tht-gate.js + gate/)
|
|
workflow.yaml single source of workflow truth (F2)
|
|
workspaces/ workspace YAML definitions (D3)
|
|
scripts/ reader/writer RPC SQL for pgvector (D11)
|
|
tests/ L0 (testcontainers), L1 (logic + builders), L2 (real model + DB)
|
|
docs/ testing guide + workflow editing
|
|
```
|
|
|
|
## Reference
|
|
|
|
- Architecture spec: `docs/superpowers/specs/2026-06-25-thothii-architecture-design.md`
|
|
- Implementation plan: `docs/superpowers/plans/2026-06-25-harness-implementation.md`
|