751 lines
29 KiB
Markdown
751 lines
29 KiB
Markdown
# Ollama Ensure (embeddings preflight) Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Guarantee Ollama embeddings are available before a session starts — a hard-fail preflight that starts Ollama if down, warms the configured model, and refuses session create/restart when embeddings can't be made available.
|
|
|
|
**Architecture:** A deterministic `tht ollama ensure` command in the harness (which owns the embeddings config + the `OllamaEmbeddings` client) does probe → start (configurable command, detached) → poll → verify model installed → warm. The Fastify backend calls it as a preflight before spawning Pi; a non-zero exit becomes a 503 and no session is created.
|
|
|
|
**Tech Stack:** Python (typer, requests, subprocess, pydantic, pytest) · Node/Fastify + TypeScript (vitest).
|
|
|
|
## Global Constraints
|
|
|
|
- **Embeddings are mandatory.** Any condition that makes embeddings unavailable (no `embeddings`
|
|
config, Ollama unreachable after timeout, model not installed, warm fails) is a **hard error**:
|
|
the command exits non-zero and the backend refuses the session (HTTP 503, no Pi spawned). No
|
|
"degraded" session.
|
|
- **No automatic `ollama pull`** — a missing model is a hard error with guidance (`ollama pull <model>`).
|
|
- **"Load" = warm-only** — load the already-installed model into memory via one embed ping.
|
|
- **Parameterized invocation** — the ollama binary (`embeddings.bin`, default `"ollama"`) and the
|
|
start command (`embeddings.start_cmd`, default `[bin, "serve"]`, `[]` disables auto-start) are
|
|
config-driven; the base URL is `embeddings.base_url`.
|
|
- **`tht`'s `-c`/`--config` is PER-COMMAND** — it follows the subcommand (`ThtRunner` appends it).
|
|
- **`--json` output must be pristine** (only valid JSON on stdout). On error with `--json`, the
|
|
error JSON is on stdout AND the exit code is non-zero (the exit code is authoritative).
|
|
- **Blocking with timeout** (default 60s, backend env `OLLAMA_ENSURE_TIMEOUT_MS`): the timeout
|
|
only bounds waiting for the server to come up; on expiry → error, not degrade.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
**Harness (`tht`)**
|
|
- Modify `harness/tht/config.py` — add `bin` + `start_cmd` to `EmbeddingsConfig`.
|
|
- Create `harness/tht/cli/ollama_cmd.py` — ops (`_probe`/`_installed_models`/`_start`/`_warm`),
|
|
the pure `ensure_ollama(...)` orchestration, and the `ollama ensure` CLI command.
|
|
- Modify `harness/tht/cli/__init__.py` — register the `ollama` sub-app.
|
|
- Create `harness/tests/test_ollama_ensure.py`.
|
|
|
|
**Backend (Fastify)**
|
|
- Modify `backend/src/tht/tht-runner.ts` — `ollamaEnsure(workspace, timeoutSec)`.
|
|
- Modify `backend/src/config.ts` — `ollamaEnsureTimeoutMs`.
|
|
- Modify `backend/src/app.ts` — pass the timeout (seconds) into `sessionRoutes` deps.
|
|
- Modify `backend/src/routes/sessions.ts` — preflight in `POST /sessions` and `POST /sessions/:id/resume`.
|
|
- Modify `backend/test/tht-runner.test.ts`, `backend/test/routes-sessions.test.ts`.
|
|
|
|
---
|
|
|
|
## Phase A — Harness
|
|
|
|
### Task 1: EmbeddingsConfig fields + `ensure_ollama` orchestration
|
|
|
|
**Files:**
|
|
- Modify: `harness/tht/config.py` (`EmbeddingsConfig`)
|
|
- Create: `harness/tht/cli/ollama_cmd.py`
|
|
- Test: `harness/tests/test_ollama_ensure.py` (create)
|
|
|
|
**Interfaces:**
|
|
- Consumes: `EmbeddingsConfig`, `OllamaEmbeddings` (`tht/vectorstore/embeddings.py`, `.embed_query`).
|
|
- Produces:
|
|
- `EmbeddingsConfig.bin: str = "ollama"`, `EmbeddingsConfig.start_cmd: list[str] | None = None`
|
|
- `ensure_ollama(cfg, *, timeout: int, no_start: bool, probe=_probe, installed_models=_installed_models, start=_start, warm=_warm, sleep=time.sleep, clock=time.monotonic) -> dict`
|
|
returning `{"ok": True, "server": "up"|"started", "model": "warmed", "model_name": str}` on
|
|
success or `{"ok": False, "stage": "config"|"server"|"model"|"warm", "error": str}` on failure.
|
|
- Module ops `_probe(base_url)->bool`, `_installed_models(base_url)->set[str]`, `_start(cmd)->None`,
|
|
`_warm(cfg)->None`, and `_model_present(installed, model)->bool`.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `harness/tests/test_ollama_ensure.py`:
|
|
|
|
```python
|
|
"""Tests for the ensure_ollama orchestration (Ollama mocked via injected ops)."""
|
|
from types import SimpleNamespace
|
|
|
|
from tht.config import EmbeddingsConfig
|
|
from tht.cli.ollama_cmd import ensure_ollama
|
|
|
|
|
|
def _cfg(**kw):
|
|
emb = EmbeddingsConfig(base_url="http://localhost:11434", **kw)
|
|
return SimpleNamespace(embeddings=emb)
|
|
|
|
|
|
def test_no_embeddings_config_is_hard_error():
|
|
r = ensure_ollama(SimpleNamespace(embeddings=None), timeout=5, no_start=False)
|
|
assert r["ok"] is False and r["stage"] == "config"
|
|
|
|
|
|
def test_server_up_model_present_warms_ok():
|
|
warmed = []
|
|
r = ensure_ollama(
|
|
_cfg(model="nomic-embed-text-v2-moe"), timeout=5, no_start=False,
|
|
probe=lambda url: True,
|
|
installed_models=lambda url: {"nomic-embed-text-v2-moe:latest"},
|
|
start=lambda cmd: (_ for _ in ()).throw(AssertionError("must not start")),
|
|
warm=lambda cfg: warmed.append(True),
|
|
)
|
|
assert r == {"ok": True, "server": "up", "model": "warmed", "model_name": "nomic-embed-text-v2-moe"}
|
|
assert warmed == [True]
|
|
|
|
|
|
def test_server_down_then_started_after_poll():
|
|
started = []
|
|
probes = iter([False, True]) # down, then up after start
|
|
r = ensure_ollama(
|
|
_cfg(), timeout=5, no_start=False,
|
|
probe=lambda url: next(probes),
|
|
installed_models=lambda url: {"nomic-embed-text-v2-moe"},
|
|
start=lambda cmd: started.append(cmd),
|
|
warm=lambda cfg: None,
|
|
sleep=lambda s: None,
|
|
)
|
|
assert r["ok"] is True and r["server"] == "started"
|
|
assert started and started[0] == ["ollama", "serve"]
|
|
|
|
|
|
def test_server_unreachable_after_timeout_is_error():
|
|
clk = iter([0.0, 1.0, 2.0, 99.0]) # monotonic crosses the deadline
|
|
r = ensure_ollama(
|
|
_cfg(), timeout=5, no_start=False,
|
|
probe=lambda url: False, # never comes up
|
|
installed_models=lambda url: set(),
|
|
start=lambda cmd: None,
|
|
warm=lambda cfg: None,
|
|
sleep=lambda s: None,
|
|
clock=lambda: next(clk),
|
|
)
|
|
assert r["ok"] is False and r["stage"] == "server"
|
|
|
|
|
|
def test_no_start_and_down_is_error_without_starting():
|
|
r = ensure_ollama(
|
|
_cfg(), timeout=5, no_start=True,
|
|
probe=lambda url: False,
|
|
installed_models=lambda url: set(),
|
|
start=lambda cmd: (_ for _ in ()).throw(AssertionError("must not start")),
|
|
warm=lambda cfg: None,
|
|
)
|
|
assert r["ok"] is False and r["stage"] == "server"
|
|
|
|
|
|
def test_empty_start_cmd_disables_autostart():
|
|
r = ensure_ollama(
|
|
_cfg(start_cmd=[]), timeout=5, no_start=False,
|
|
probe=lambda url: False,
|
|
installed_models=lambda url: set(),
|
|
start=lambda cmd: (_ for _ in ()).throw(AssertionError("must not start")),
|
|
warm=lambda cfg: None,
|
|
)
|
|
assert r["ok"] is False and r["stage"] == "server"
|
|
|
|
|
|
def test_model_absent_is_error_with_pull_guidance():
|
|
r = ensure_ollama(
|
|
_cfg(model="missing-model"), timeout=5, no_start=False,
|
|
probe=lambda url: True,
|
|
installed_models=lambda url: {"nomic-embed-text-v2-moe"},
|
|
start=lambda cmd: None,
|
|
warm=lambda cfg: None,
|
|
)
|
|
assert r["ok"] is False and r["stage"] == "model"
|
|
assert "ollama pull missing-model" in r["error"]
|
|
|
|
|
|
def test_warm_failure_is_error():
|
|
r = ensure_ollama(
|
|
_cfg(), timeout=5, no_start=False,
|
|
probe=lambda url: True,
|
|
installed_models=lambda url: {"nomic-embed-text-v2-moe"},
|
|
start=lambda cmd: None,
|
|
warm=lambda cfg: (_ for _ in ()).throw(RuntimeError("boom")),
|
|
)
|
|
assert r["ok"] is False and r["stage"] == "warm"
|
|
|
|
|
|
def test_custom_start_cmd_used():
|
|
started = []
|
|
probes = iter([False, True])
|
|
ensure_ollama(
|
|
_cfg(bin="ollama", start_cmd=["docker", "start", "ollama"]), timeout=5, no_start=False,
|
|
probe=lambda url: next(probes),
|
|
installed_models=lambda url: {"nomic-embed-text-v2-moe"},
|
|
start=lambda cmd: started.append(cmd),
|
|
warm=lambda cfg: None,
|
|
sleep=lambda s: None,
|
|
)
|
|
assert started[0] == ["docker", "start", "ollama"]
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `cd harness && .venv/bin/pytest tests/test_ollama_ensure.py -q`
|
|
Expected: FAIL — `ModuleNotFoundError: No module named 'tht.cli.ollama_cmd'`.
|
|
|
|
- [ ] **Step 3: Add the config fields**
|
|
|
|
In `harness/tht/config.py`, in `EmbeddingsConfig`, after `timeout: int = 120` add:
|
|
|
|
```python
|
|
bin: str = "ollama"
|
|
start_cmd: list[str] | None = None
|
|
```
|
|
|
|
- [ ] **Step 4: Create `ollama_cmd.py`**
|
|
|
|
Create `harness/tht/cli/ollama_cmd.py`:
|
|
|
|
```python
|
|
"""`tht ollama` -- embeddings preflight (ensure Ollama up + model warm).
|
|
|
|
The system REQUIRES embeddings: any condition that makes them unavailable is a hard
|
|
error (the caller refuses the session). "Load" = warm the already-installed model.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import subprocess
|
|
import time
|
|
from pathlib import Path
|
|
|
|
import typer
|
|
|
|
from tht.cli.config_cmd import CONFIG_OPT
|
|
from tht.cli.schema_cmd import _load_config_or_exit
|
|
|
|
ollama_app = typer.Typer(help="Ollama (embeddings) -- preflight.")
|
|
|
|
|
|
# --- low-level ops (real implementations; injected as fakes in tests) ----------
|
|
|
|
def _probe(base_url: str, timeout: float = 2.0) -> bool:
|
|
import requests
|
|
|
|
try:
|
|
return requests.get(f"{base_url.rstrip('/')}/api/tags", timeout=timeout).status_code == 200
|
|
except requests.RequestException:
|
|
return False
|
|
|
|
|
|
def _installed_models(base_url: str, timeout: float = 5.0) -> set[str]:
|
|
import requests
|
|
|
|
resp = requests.get(f"{base_url.rstrip('/')}/api/tags", timeout=timeout)
|
|
resp.raise_for_status()
|
|
return {m.get("name", "") for m in resp.json().get("models", [])}
|
|
|
|
|
|
def _start(start_cmd: list[str]) -> None:
|
|
# Detached so the server outlives this short-lived CLI process.
|
|
subprocess.Popen( # noqa: S603
|
|
start_cmd, start_new_session=True,
|
|
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
|
|
)
|
|
|
|
|
|
def _warm(cfg) -> None:
|
|
from tht.vectorstore.embeddings import OllamaEmbeddings
|
|
|
|
OllamaEmbeddings(cfg.embeddings).embed_query("ping")
|
|
|
|
|
|
def _model_present(installed: set[str], model: str) -> bool:
|
|
"""Match the configured model against installed names, allowing the implicit ':latest'."""
|
|
if model in installed:
|
|
return True
|
|
base = model.split(":")[0]
|
|
return any(name == base or name.split(":")[0] == base for name in installed)
|
|
|
|
|
|
# --- orchestration (pure: returns a result dict, never raises for control flow) ----
|
|
|
|
def ensure_ollama(
|
|
cfg,
|
|
*,
|
|
timeout: int,
|
|
no_start: bool,
|
|
probe=_probe,
|
|
installed_models=_installed_models,
|
|
start=_start,
|
|
warm=_warm,
|
|
sleep=time.sleep,
|
|
clock=time.monotonic,
|
|
) -> dict:
|
|
if cfg.embeddings is None:
|
|
return {"ok": False, "stage": "config",
|
|
"error": "il sistema richiede embeddings ma il workspace non li configura"}
|
|
emb = cfg.embeddings
|
|
base_url = emb.base_url
|
|
start_cmd = emb.start_cmd if emb.start_cmd is not None else [emb.bin, "serve"]
|
|
|
|
server_state = "up"
|
|
if not probe(base_url):
|
|
if no_start or start_cmd == []:
|
|
return {"ok": False, "stage": "server",
|
|
"error": f"Ollama non raggiungibile su {base_url} e avvio disabilitato"}
|
|
start(start_cmd)
|
|
server_state = "started"
|
|
deadline = clock() + timeout
|
|
up = False
|
|
while clock() < deadline:
|
|
sleep(1.0)
|
|
if probe(base_url):
|
|
up = True
|
|
break
|
|
if not up:
|
|
return {"ok": False, "stage": "server",
|
|
"error": f"Ollama non raggiungibile su {base_url} entro {timeout}s"}
|
|
|
|
try:
|
|
installed = installed_models(base_url)
|
|
except Exception as e: # noqa: BLE001 - any read failure is a hard error
|
|
return {"ok": False, "stage": "server",
|
|
"error": f"impossibile leggere i modelli da {base_url}: {e}"}
|
|
if not _model_present(installed, emb.model):
|
|
return {"ok": False, "stage": "model",
|
|
"error": f"modello '{emb.model}' non installato in Ollama: "
|
|
f"esegui `ollama pull {emb.model}` o importalo"}
|
|
|
|
try:
|
|
warm(cfg)
|
|
except Exception as e: # noqa: BLE001 - warm failure is a hard error
|
|
return {"ok": False, "stage": "warm",
|
|
"error": f"warm del modello '{emb.model}' fallito: {e}"}
|
|
|
|
return {"ok": True, "server": server_state, "model": "warmed", "model_name": emb.model}
|
|
```
|
|
|
|
- [ ] **Step 5: Run test to verify it passes**
|
|
|
|
Run: `cd harness && .venv/bin/pytest tests/test_ollama_ensure.py -q`
|
|
Expected: PASS (9 passed). Then `cd harness && .venv/bin/ruff check tht/cli/ollama_cmd.py tht/config.py tests/test_ollama_ensure.py` → clean.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add harness/tht/config.py harness/tht/cli/ollama_cmd.py harness/tests/test_ollama_ensure.py
|
|
git commit -m "feat(harness): EmbeddingsConfig bin/start_cmd + ensure_ollama preflight orchestration"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: `tht ollama ensure` CLI command + registration
|
|
|
|
**Files:**
|
|
- Modify: `harness/tht/cli/ollama_cmd.py` (add the command)
|
|
- Modify: `harness/tht/cli/__init__.py` (register `ollama_app`)
|
|
- Test: `harness/tests/test_ollama_ensure.py` (append CLI tests)
|
|
|
|
**Interfaces:**
|
|
- Consumes: `ensure_ollama` (Task 1), `_load_config_or_exit`, `CONFIG_OPT`, `ollama_app`.
|
|
- Produces: CLI `tht ollama ensure [--timeout N] [--no-start] [--json] -c <ws>` — exit 0 on ok,
|
|
exit 1 on any failure; with `--json`, only the result JSON on stdout (pristine) on both paths.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Append to `harness/tests/test_ollama_ensure.py`:
|
|
|
|
```python
|
|
import json as _json
|
|
|
|
from typer.testing import CliRunner
|
|
|
|
from tht.cli.ollama_cmd import ollama_app
|
|
from tht.cli import ollama_cmd
|
|
|
|
|
|
def _patch(monkeypatch, result):
|
|
monkeypatch.setattr(ollama_cmd, "_load_config_or_exit", lambda _c: SimpleNamespace(embeddings=object()))
|
|
monkeypatch.setattr(ollama_cmd, "ensure_ollama", lambda cfg, **kw: result)
|
|
|
|
|
|
def test_cli_ok_exit_zero_and_json_pristine(monkeypatch):
|
|
_patch(monkeypatch, {"ok": True, "server": "up", "model": "warmed", "model_name": "m"})
|
|
res = CliRunner().invoke(ollama_app, ["ensure", "--json"])
|
|
assert res.exit_code == 0, res.output
|
|
assert _json.loads(res.output) == {"ok": True, "server": "up", "model": "warmed", "model_name": "m"}
|
|
|
|
|
|
def test_cli_error_exit_one_and_json_on_stdout(monkeypatch):
|
|
_patch(monkeypatch, {"ok": False, "stage": "model", "error": "missing"})
|
|
res = CliRunner().invoke(ollama_app, ["ensure", "--json"])
|
|
assert res.exit_code == 1
|
|
assert _json.loads(res.output) == {"ok": False, "stage": "model", "error": "missing"}
|
|
|
|
|
|
def test_cli_error_human_mode_exit_one(monkeypatch):
|
|
_patch(monkeypatch, {"ok": False, "stage": "server", "error": "down"})
|
|
res = CliRunner().invoke(ollama_app, ["ensure"])
|
|
assert res.exit_code == 1
|
|
|
|
|
|
def test_cli_registered_on_root_app():
|
|
from tht.cli import app # the root Typer app
|
|
runner = CliRunner()
|
|
res = runner.invoke(app, ["ollama", "--help"])
|
|
assert res.exit_code == 0
|
|
assert "ensure" in res.output
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `cd harness && .venv/bin/pytest tests/test_ollama_ensure.py -k cli -q`
|
|
Expected: FAIL — `No such command 'ensure'` / the root app has no `ollama` command.
|
|
|
|
- [ ] **Step 3: Add the CLI command**
|
|
|
|
In `harness/tht/cli/ollama_cmd.py`, append:
|
|
|
|
```python
|
|
@ollama_app.command("ensure")
|
|
def ensure_cmd(
|
|
timeout: int = typer.Option(60, "--timeout", help="Secondi di attesa per l'avvio di Ollama."),
|
|
no_start: bool = typer.Option(False, "--no-start", help="Non avviare Ollama (solo verifica)."),
|
|
json_out: bool = typer.Option(False, "--json", help="Emetti JSON puro su stdout."),
|
|
config: Path = CONFIG_OPT,
|
|
) -> None:
|
|
"""Assicura Ollama attivo + modello di embedding caricato; errore se non possibile."""
|
|
cfg = _load_config_or_exit(config)
|
|
result = ensure_ollama(cfg, timeout=timeout, no_start=no_start)
|
|
if json_out:
|
|
typer.echo(json.dumps(result, ensure_ascii=False))
|
|
elif result["ok"]:
|
|
typer.secho(
|
|
f"OK: Ollama {result['server']}, modello {result['model_name']} {result['model']}.",
|
|
fg=typer.colors.GREEN,
|
|
)
|
|
else:
|
|
typer.secho(f"ERRORE [{result['stage']}]: {result['error']}", fg=typer.colors.RED, err=True)
|
|
if not result["ok"]:
|
|
raise typer.Exit(code=1)
|
|
```
|
|
|
|
- [ ] **Step 4: Register the sub-app**
|
|
|
|
In `harness/tht/cli/__init__.py`, add the import alongside the others:
|
|
|
|
```python
|
|
from tht.cli.ollama_cmd import ollama_app # noqa: E402
|
|
```
|
|
|
|
and the registration alongside the other `add_typer` calls:
|
|
|
|
```python
|
|
app.add_typer(ollama_app, name="ollama")
|
|
```
|
|
|
|
- [ ] **Step 5: Run test to verify it passes**
|
|
|
|
Run: `cd harness && .venv/bin/pytest tests/test_ollama_ensure.py -q`
|
|
Expected: PASS (all). Then `cd harness && .venv/bin/ruff check tht/cli/ollama_cmd.py tht/cli/__init__.py` → clean.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add harness/tht/cli/ollama_cmd.py harness/tht/cli/__init__.py harness/tests/test_ollama_ensure.py
|
|
git commit -m "feat(harness): tht ollama ensure CLI command (hard-fail preflight)"
|
|
```
|
|
|
|
---
|
|
|
|
## Phase B — Backend
|
|
|
|
### Task 3: `ThtRunner.ollamaEnsure`
|
|
|
|
**Files:**
|
|
- Modify: `backend/src/tht/tht-runner.ts`
|
|
- Test: `backend/test/tht-runner.test.ts` (append)
|
|
|
|
**Interfaces:**
|
|
- Consumes: `ThtRunner.run(args, workspace)`.
|
|
- Produces: `ollamaEnsure(workspace: string, timeoutSec: number): Promise<{ ok: boolean; stage?: string; error?: string; server?: string; model?: string; model_name?: string }>`
|
|
— shells `tht ollama ensure --json --timeout <sec>` (workspace via the per-command `-c`); exit 0
|
|
→ `{ ok: true, ...parsedJson }`, non-zero → `{ ok: false, stage, error }`.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Append to `backend/test/tht-runner.test.ts`:
|
|
|
|
```typescript
|
|
test("ollamaEnsure builds argv with --json --timeout and the workspace -c", async () => {
|
|
let calledArgs: string[] = [];
|
|
let calledWs: string | undefined;
|
|
const r = new ThtRunner({ thtBin: "tht", harnessDir: "/nope", configPath: "config/tht.yaml" });
|
|
r.run = async (args, ws) => { calledArgs = args; calledWs = ws; return { code: 0, stdout: '{"ok":true,"server":"up","model":"warmed","model_name":"m"}', stderr: "" }; };
|
|
const res = await r.ollamaEnsure("psd", 60);
|
|
expect(calledArgs).toEqual(["ollama", "ensure", "--json", "--timeout", "60"]);
|
|
expect(calledWs).toBe("psd");
|
|
expect(res).toEqual({ ok: true, server: "up", model: "warmed", model_name: "m" });
|
|
});
|
|
|
|
test("ollamaEnsure maps a non-zero exit to ok:false with stage/error from stdout JSON", async () => {
|
|
const r = new ThtRunner({ thtBin: "tht", harnessDir: "/nope", configPath: "config/tht.yaml" });
|
|
r.run = async () => ({ code: 1, stdout: '{"ok":false,"stage":"model","error":"missing"}', stderr: "" });
|
|
expect(await r.ollamaEnsure("psd", 60)).toEqual({ ok: false, stage: "model", error: "missing" });
|
|
});
|
|
|
|
test("ollamaEnsure falls back to stderr when stdout is not JSON on failure", async () => {
|
|
const r = new ThtRunner({ thtBin: "tht", harnessDir: "/nope", configPath: "config/tht.yaml" });
|
|
r.run = async () => ({ code: 1, stdout: "", stderr: "boom" });
|
|
const res = await r.ollamaEnsure("psd", 60);
|
|
expect(res.ok).toBe(false);
|
|
expect(res.error).toContain("boom");
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `cd backend && npx vitest run test/tht-runner.test.ts`
|
|
Expected: FAIL — `r.ollamaEnsure is not a function`.
|
|
|
|
- [ ] **Step 3: Implement the method**
|
|
|
|
In `backend/src/tht/tht-runner.ts`, add a result interface near `SessionDocument`:
|
|
|
|
```typescript
|
|
export interface OllamaEnsureResult {
|
|
ok: boolean;
|
|
stage?: string;
|
|
error?: string;
|
|
server?: string;
|
|
model?: string;
|
|
model_name?: string;
|
|
}
|
|
```
|
|
|
|
and the method (after `documents`):
|
|
|
|
```typescript
|
|
async ollamaEnsure(workspace: string, timeoutSec: number): Promise<OllamaEnsureResult> {
|
|
const { code, stdout, stderr } = await this.run(
|
|
["ollama", "ensure", "--json", "--timeout", String(timeoutSec)],
|
|
workspace,
|
|
);
|
|
let parsed: Partial<OllamaEnsureResult> = {};
|
|
try { parsed = JSON.parse(stdout.trim() || "{}"); } catch { /* leave {} */ }
|
|
if (code === 0) return { ok: true, ...parsed };
|
|
return {
|
|
ok: false,
|
|
stage: parsed.stage,
|
|
error: parsed.error ?? (stderr.trim() || `tht ollama ensure exit ${code}`),
|
|
};
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `cd backend && npx vitest run test/tht-runner.test.ts` then `npx tsc --noEmit -p .`
|
|
Expected: PASS, typecheck clean.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add backend/src/tht/tht-runner.ts backend/test/tht-runner.test.ts
|
|
git commit -m "feat(backend): ThtRunner.ollamaEnsure (parses tht ollama ensure --json)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Backend preflight in session routes + timeout config
|
|
|
|
**Files:**
|
|
- Modify: `backend/src/config.ts` (`ollamaEnsureTimeoutMs`)
|
|
- Modify: `backend/src/app.ts` (pass `ollamaEnsureTimeoutSec` to `sessionRoutes`)
|
|
- Modify: `backend/src/routes/sessions.ts` (preflight in create + resume)
|
|
- Test: `backend/test/routes-sessions.test.ts` (append)
|
|
|
|
**Interfaces:**
|
|
- Consumes: `ThtRunner.ollamaEnsure` (Task 3), `getSettings().workspace`.
|
|
- Produces: `POST /sessions` and `POST /sessions/:id/resume` run `ollamaEnsure` first; on `!ok`
|
|
reply **503** `{ error }` and do NOT create/resume; the `sessionRoutes` deps object gains
|
|
`ollamaEnsureTimeoutSec: number`.
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Append to `backend/test/routes-sessions.test.ts`:
|
|
|
|
```typescript
|
|
test("POST /sessions refuses with 503 when ollamaEnsure fails (no session created)", async () => {
|
|
let createdCalled = false;
|
|
const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
|
|
thtRunner: {
|
|
ollamaEnsure: async () => ({ ok: false, stage: "model", error: "modello non installato" }),
|
|
sessionNew: async () => { createdCalled = true; return { id: "s1" }; },
|
|
} as any,
|
|
getSettings: () => ({ workspace: "psd" }) as any,
|
|
spawnFn: () => nodeSpawn("node", [FAKE, SCRIPT]) as any,
|
|
});
|
|
const res = await app.inject({ method: "POST", url: "/sessions", payload: { question: "q" } });
|
|
expect(res.statusCode).toBe(503);
|
|
expect(res.json().error).toContain("non installato");
|
|
expect(createdCalled).toBe(false);
|
|
});
|
|
|
|
test("POST /sessions proceeds when ollamaEnsure succeeds", async () => {
|
|
let ensureWs: string | undefined;
|
|
const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
|
|
thtRunner: {
|
|
ollamaEnsure: async (ws: string) => { ensureWs = ws; return { ok: true }; },
|
|
sessionNew: async () => ({ id: "s1" }),
|
|
} as any,
|
|
getSettings: () => ({ workspace: "psd" }) as any,
|
|
spawnFn: () => nodeSpawn("node", [FAKE, SCRIPT]) as any,
|
|
});
|
|
const res = await app.inject({ method: "POST", url: "/sessions", payload: { question: "q" } });
|
|
expect(res.json()).toEqual({ id: "s1" });
|
|
expect(ensureWs).toBe("psd");
|
|
});
|
|
|
|
test("POST /sessions/:id/resume refuses with 503 when ollamaEnsure fails", async () => {
|
|
const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
|
|
thtRunner: {
|
|
ollamaEnsure: async () => ({ ok: false, error: "Ollama down" }),
|
|
sessionShow: async () => ({ status: "open", archived: false }),
|
|
} as any,
|
|
getSettings: () => ({ workspace: "psd" }) as any,
|
|
spawnFn: () => nodeSpawn("node", [FAKE, SCRIPT]) as any,
|
|
});
|
|
const res = await app.inject({ method: "POST", url: "/sessions/s1/resume" });
|
|
expect(res.statusCode).toBe(503);
|
|
});
|
|
```
|
|
|
|
(Note: the existing `mutApp` tests in this file do not pass `ollamaEnsure`; keep those tests
|
|
unaffected — the routes that call `ollamaEnsure` are only create and resume, and `mutApp` is used
|
|
for rename/group/archive/delete/documents. The two pre-existing create/resume tests at the top of
|
|
the file DO call create/resume, so update them per Step 4's note.)
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `cd backend && npx vitest run test/routes-sessions.test.ts`
|
|
Expected: FAIL — create/resume don't call `ollamaEnsure` (503 tests fail; and the new success test fails because `ollamaEnsure` isn't invoked).
|
|
|
|
- [ ] **Step 3: Add the timeout config**
|
|
|
|
In `backend/src/config.ts`, add to the `AppConfig` interface:
|
|
|
|
```typescript
|
|
ollamaEnsureTimeoutMs: number;
|
|
```
|
|
|
|
and in `loadConfig`'s returned object:
|
|
|
|
```typescript
|
|
ollamaEnsureTimeoutMs: Number(env.OLLAMA_ENSURE_TIMEOUT_MS ?? 60000),
|
|
```
|
|
|
|
- [ ] **Step 4: Wire the preflight into the routes**
|
|
|
|
In `backend/src/app.ts`, pass the timeout (seconds) into `sessionRoutes`. Change the call:
|
|
|
|
```typescript
|
|
sessionRoutes(app, { mgr, tht: tht as ThtRunner, hub, getSettings });
|
|
```
|
|
|
|
to:
|
|
|
|
```typescript
|
|
sessionRoutes(app, {
|
|
mgr, tht: tht as ThtRunner, hub, getSettings,
|
|
ollamaEnsureTimeoutSec: Math.round(config.ollamaEnsureTimeoutMs / 1000),
|
|
});
|
|
```
|
|
|
|
In `backend/src/routes/sessions.ts`, extend the deps type and add the preflight. Change the
|
|
function signature's deps to include the timeout:
|
|
|
|
```typescript
|
|
export function sessionRoutes(
|
|
app: FastifyInstance,
|
|
d: { mgr: PiProcessManager; tht: ThtRunner; hub: SseHub; getSettings: () => Settings; ollamaEnsureTimeoutSec: number },
|
|
) {
|
|
```
|
|
|
|
At the **start** of the `POST /sessions` handler (before `d.tht.sessionNew`):
|
|
|
|
```typescript
|
|
app.post("/sessions", async (req, reply) => {
|
|
const b = req.body as { question: string; name?: string };
|
|
const s = d.getSettings();
|
|
const ensure = await d.tht.ollamaEnsure(s.workspace, d.ollamaEnsureTimeoutSec);
|
|
if (!ensure.ok) return reply.code(503).send({ error: ensure.error ?? "Ollama/embeddings non disponibili" });
|
|
// ... existing sessionNew + spawnFor unchanged ...
|
|
```
|
|
|
|
At the **start** of the `POST /sessions/:id/resume` handler (before the manifest read / guard):
|
|
|
|
```typescript
|
|
app.post("/sessions/:id/resume", async (req, reply) => {
|
|
const id = (req.params as any).id;
|
|
const ensure = await d.tht.ollamaEnsure(d.getSettings().workspace, d.ollamaEnsureTimeoutSec);
|
|
if (!ensure.ok) return reply.code(503).send({ error: ensure.error ?? "Ollama/embeddings non disponibili" });
|
|
// ... existing manifest read + finalized/archived guard + mgr.resume unchanged ...
|
|
```
|
|
|
|
**Note — keep the pre-existing tests green.** The preflight now runs before any create/resume
|
|
logic, so every injected `thtRunner` double that hits `POST /sessions` or `/resume` needs an
|
|
`ollamaEnsure`, else it throws `d.tht.ollamaEnsure is not a function`. Two edits cover all cases:
|
|
|
|
1. **Give `mutApp` a default `ollamaEnsure`** so its tests (including the resume-guard 409 tests
|
|
from the session-management feature) pass the preflight and still reach their logic. Change the
|
|
helper so the injected runner is `{ ollamaEnsure: async () => ({ ok: true }), ...thtRunner }`:
|
|
```typescript
|
|
function mutApp(thtRunner: any) {
|
|
return buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
|
|
thtRunner: { ollamaEnsure: async () => ({ ok: true }), ...thtRunner },
|
|
getSettings: () => ({ workspace: "w" }) as any,
|
|
spawnFn: () => nodeSpawn("node", [FAKE, SCRIPT]) as any,
|
|
});
|
|
}
|
|
```
|
|
2. **Add `ollamaEnsure: async () => ({ ok: true })`** to the two top-of-file inline doubles that
|
|
POST `/sessions`: the "POST /sessions usa i settings…" test and the
|
|
"POST /sessions/:id/response inoltra al bridge…" test.
|
|
|
|
- [ ] **Step 5: Run test to verify it passes**
|
|
|
|
Run: `cd backend && npx vitest run test/routes-sessions.test.ts` then `npx tsc --noEmit -p .`
|
|
Expected: PASS (new 503/success tests + the updated pre-existing tests), typecheck clean.
|
|
|
|
- [ ] **Step 6: Run the full backend suite (catch regressions)**
|
|
|
|
Run: `cd backend && npx vitest run`
|
|
Expected: PASS. The resume-guard 409 tests from the session-management feature use `mutApp`, so the
|
|
default `ollamaEnsure` added in Step 4 lets the preflight pass and the 409 guard is still reached.
|
|
If any other test that POSTs create/resume was missed, give its `thtRunner` double an
|
|
`ollamaEnsure: async () => ({ ok: true })`.
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add backend/src/config.ts backend/src/app.ts backend/src/routes/sessions.ts backend/test/routes-sessions.test.ts
|
|
git commit -m "feat(backend): Ollama embeddings preflight on session create/resume (503 hard-fail)"
|
|
```
|
|
|
|
---
|
|
|
|
## Final verification
|
|
|
|
- [ ] **Harness:** `cd harness && .venv/bin/pytest tests/test_ollama_ensure.py -q` → all pass; `.venv/bin/ruff check tht/cli/ollama_cmd.py` → clean.
|
|
- [ ] **Backend:** `cd backend && npx vitest run` → all pass; `npx tsc --noEmit -p .` → clean.
|
|
- [ ] **Manual smoke (optional, needs the stack):** with Ollama stopped, `tht ollama ensure --json -c workspaces/psd.yaml` starts it and warms the model (exit 0); with the model uninstalled it exits 1 with `ollama pull` guidance; creating a session via the UI while Ollama is down returns a 503 with the diagnostic.
|
|
|
|
## Spec coverage check
|
|
- `bin`/`start_cmd` parameterization → Task 1.
|
|
- Hard-fail matrix (config/server/model/warm) → Task 1 (`ensure_ollama`) + Task 2 (exit codes).
|
|
- `tht ollama ensure` command, pristine `--json`, `--no-start` → Task 2.
|
|
- `ThtRunner.ollamaEnsure` parsing + non-zero mapping → Task 3.
|
|
- Preflight-before-spawn, 503, no degraded session, timeout env → Task 4.
|
|
- Warm-only / no auto-pull → enforced by `ensure_ollama` (model-absent = error) — Task 1.
|
|
- Frontend: none (the 503 reaches the existing error path) — no task, by design.
|