# 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`