Documentation

# Toolchain Service Infrastructure This directory implements the adopted infrastructure experiment in `../research/toolchain-service-infrastructure/PLAN.md`. It keeps the installed research tools resident behind local capability services, routes them through a Go hub, and exposes their verification evidence through the Toolchain Debug UI. It does not implement radiology interpretation semantics. ## Operator interface ```sh make -C infrastructure doctor make -C infrastructure start make -C infrastructure status make -C infrastructure smoke-services make -C infrastructure smoke-hub make -C infrastructure smoke-assembly make -C infrastructure test-ui make -C infrastructure test-interpreter-ui make -C infrastructure verify make -C infrastructure stop ``` `start` links the three checked-in user units and starts them, but does not enable them at login. All services bind only to loopback: | Process boundary | Address | Responsibility | |---|---|---| | Go Toolchain hub | `http://127.0.0.1:8170` | caller API, evaluation records, and web UI | | Python linguistics service | `http://127.0.0.1:8171` | Stanza, Grew/UCxn, MoCCA, and FrameNet | | SWI-Prolog service | `http://127.0.0.1:8172` | CoNLL-U inspection and the resident RadLex bundle | The public research host uses the same user units with lingering and login enablement so they return after reboot. Its accepted installation and recovery details are recorded in `FULL-TOOLCHAIN-DEPLOYMENT-REPORT.md`. The retired artifact-only deployment remains available as an explicit rollback service. The primary interpreter UI and supporting Toolchain UI are: ```text http://127.0.0.1:8170/interpretations/new http://127.0.0.1:8170/toolchains/rad-nlp-research ``` The interpreter UI is the UI-only first slice: it loads and resolves the reviewed POC transcription to its immutable checked-in R0–R5 artifact. It does not yet run edited or arbitrary text through a durable interpretation operation. The interface states that boundary explicitly instead of presenting an edited Draft as a completed interpretation. A dependency-free vanilla-JS SPA layer performs Run, depth, focus, and history transitions in place; the same server-rendered GET URLs bootstrap refreshes and deep links. The interactive workflow intentionally has no parallel non-JavaScript fallback. After Run, the Draft textarea is replaced by depth-specific visual representations: source text, linguistic tokens, constructions, semantic frames, ontology groundings, and validated structured findings. Object indexes and raw JSON remain secondary inspection details. ## Configuration and evidence `config/services.json` is the operational inventory. It fixes service IDs, loopback addresses, user-unit names, limits, and the component/resource identities required for hub readiness. `config/environment` is an optional, untracked operator override; `config/environment.example` documents supported non-secret values. Runtime evidence is written beneath `infrastructure/var/evaluations/`, which is not version controlled. Each completed evaluation has a read-only JSON record and content-addressed artifacts. The UI and `/api/v1/evaluations/{id}` expose the same durable truth; browser connection state is not authoritative. ## Operation and troubleshooting Use `make -C infrastructure status` for unit and readiness state. Logs remain in the user journal: ```sh infrastructure/scripts/manage-services.sh logs journalctl --user -u radnlp-linguistics.service -f journalctl --user -u radnlp-prolog.service -f journalctl --user -u radnlp-toolchain-hub.service -f ``` If the hub reports `not_ready`, inspect `/readyz` and `/v1/manifest` on the two bare services. A component identity that differs from the checked-in inventory is intentionally treated as stale rather than silently accepted. Rebuild and restart only the Go boundary with: ```sh make -C infrastructure build systemctl --user restart radnlp-toolchain-hub.service ``` `make -C infrastructure stop` cleanly stops all three project units and the Python-owned Grew child. The direct heavy smokes use separate ports 18171 and 18172, so they can validate clean resident instances independently.