ThothII/harness

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

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)

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.

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.

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/):

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

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