marcopan
50d5f9c9cf
README: install, configure (.env + workspaces/), the workflow, run inside Pi, the three-level test commands, layout, references. docs/workflow-editing.md: how to edit workflow.yaml (add/reorder/merge/skip phases, advance kinds, prerequisite predicates, decision_min_phase derivation, artifacts_out + teardown) -- referencing spec §5.3. Emphasizes no mirrored constants (the F2 point). docs/testing.md: the honest L0/L1/L2 split in plain language -- what each covers and does NOT. States the headline plainly: the skill->LLM->gate loop has NO automated regression coverage (L2 only, pre-release). Documents the fake-Pi follow-up as the gap-closer. Security note on keys (.env gitignored, never logged, rotate leaked keys).
89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
# ThothII harness — `nsp`
|
|
|
|
The self-contained Pi layer of ThothII: a deterministic Python CLI (`nsp`) + a Pi gate
|
|
extension (`.pi/extensions/nsp-gate.js`) that runs the 8-phase NL→SQL workflow,
|
|
emitting and consuming widget-descriptor JSON. Derived from ChironeWp3 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 `nsp` 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: THOTH_PROFILE, THOTH_DB_*, THOTH_DWH_API_KEY, THOTH_VEC_API_KEY,
|
|
# THOTH_VEC_WRITE_API_KEY, THOTH_SSL_CA, THOTH_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/chirone.example.yaml`. `${THOTH_*}` 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.
|
|
|
|
```bash
|
|
nsp phase meta --json # the gate reads workflow facts from here
|
|
nsp 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 (`nsp-gate.js`) presents reviewer widgets (widget-descriptor), the reviewer
|
|
decides, and `nsp` 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
|
|
|
|
```
|
|
nsp/ Python package (CLI + workflow + phase + decisions + db/rest/mschema/
|
|
vectorstore/evidence/search/session + memory)
|
|
.pi/ Pi project (settings, prompts, themes, extensions/nsp-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`
|