Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(local-models): one overview payload, painted from the disk snapshot first
rubenluetke10-beepc2d24efbb2ac
diff --git a/jarvis/brain/ollama_overview.py b/jarvis/brain/ollama_overview.pynew file mode 100644index 0000000000..738d129624--- /dev/null+++ b/jarvis/brain/ollama_overview.py@@ -0,0 +1,428 @@+"""The "Local models" overview: one payload, painted from disk first.++Opening the section used to mean four cold requests (server, roles,+inventory, shortlist) that each ran their own probes, and two to three+seconds of nothing on screen. This module gives the section ONE payload —+:func:`build_overview` composes the four from the shared inventory snapshot+(:mod:`jarvis.brain.ollama_inventory`) — and keeps the last good one on disk+so the next open paints at once:++* :func:`get_overview` answers ``(payload, source)``. A fresh in-memory memo+ is ``"live"``. Otherwise the disk snapshot is returned immediately as+ ``"cache"`` and ONE background refresh is scheduled (its task reference is+ kept, never created at import — AP-26); a snapshot older than a day is+ skipped in favour of a live build, and ``fresh=True`` forces one.+* :func:`load_snapshot` / :func:`save_snapshot` keep+ ``DATA_DIR/local_models_snapshot.json`` (atomic ``.part`` + ``os.replace``).++The dict builders here (:func:`model_row`, :func:`role_row`, ...) are the+ONE place the wire shape of the section's rows is spelled out; the routes+wrap them in their Pydantic models (AP-4), so the single endpoints and the+overview cannot drift apart.+"""++from __future__ import annotations++import asyncio+import functools+import json+import logging+import os+import time+from dataclasses import asdict+from pathlib import Path+from typing import Any++from jarvis.brain import ollama_inventory as inventory+from jarvis.brain import ollama_pull, ollama_roles, ollama_runtime+from jarvis.brain.ollama_inventory import (+ OllamaModelInfo,+ OllamaRunningModel,+ OllamaServerError,+ same_model,+)+from jarvis.plugins.brain.ollama import normalize_server_root++log = logging.getLogger(__name__)++__all__ = [+ "SNAPSHOT_FILE_NAME",+ "DEFAULT_MAX_AGE_S",+ "STALE_AFTER_S",+ "build_overview",+ "get_overview",+ "inventory_payload",+ "load_snapshot",+ "model_row",+ "role_row",+ "roles_payload",+ "running_row",+ "save_snapshot",+ "server_payload",+ "snapshot_path",+]++SNAPSHOT_FILE_NAME = "local_models_snapshot.json"++#: How long an in-memory overview counts as live. The section refetches on+#: this cadence too, so two opens within it cost nothing.+DEFAULT_MAX_AGE_S = 15.0++#: A disk snapshot older than this is not worth painting: a day is long+#: enough for a server to have been reinstalled or its downloads pruned.+STALE_AFTER_S = 24 * 3600.0++# ── Row builders (the wire shape, spelled out once) ──────────────────────+++def model_row(+ info: OllamaModelInfo, running: dict[str, OllamaRunningModel], used_by: list[str]+) -> dict[str, Any]:+ """One inventory row: the download's facts plus what ``/api/ps`` says."""+ live = next((r for key, r in running.items() if same_model(key, info.name)), None)+ return {+ "name": info.name,+ "size_bytes": info.size_bytes,+ "digest": info.digest,+ "modified_at": info.modified_at,+ "family": info.family,+ "parameter_size": info.parameter_size,+ "quantization_level": info.quantization_level,+ "context_length": info.context_length,+ "capabilities": list(info.capabilities),+ "license": info.license,+ "probed": info.probed,+ "used_by": used_by,+ "loaded": live is not None,+ "size_vram_bytes": live.size_vram_bytes if live else 0,+ "expires_at": live.expires_at if live else "",+ "running_context_length": live.context_length if live else None,+ }+++def running_row(model: OllamaRunningModel) -> dict[str, Any]:+ return asdict(model)+++def role_row(state: ollama_roles.RoleState) -> dict[str, Any]:+ spec = state.spec+ return {+ "id": spec.id,+ "label_key": spec.label_key,+ "config_key": spec.config_key,+ "current": state.current,+ "installed": state.installed,+ "required": list(spec.required),+ "recommended_capabilities": list(spec.recommended),+ "qualifying": list(state.qualifying),+ "recommended": state.recommended,+ "writable": spec.writable,+ "advanced": spec.advanced,+ "note": state.note,+ "context_tokens": state.context_tokens,+ "context_source": state.context_source,+ }+++# ── Payloads (what the single endpoints answer) ──────────────────────────+++async def _snapshot(root: str) -> tuple[inventory.InventorySnapshot | None, str | None]:+ """The shared snapshot, or ``(None, sentence)`` when the server is down."""+ try:+ return await inventory.cached_snapshot(root), None+ except OllamaServerError as exc:+ return None, str(exc)+++def _inventory_from(+ provider_id: str,+ root: str,+ cfg: Any,+ snapshot: inventory.InventorySnapshot | None,+ error: str | None,+) -> dict[str, Any]:+ if snapshot is None:+ return {+ "provider": provider_id,+ "server": root,+ "models": [],+ "running": [],+ "disk_bytes": 0,+ "loaded_vram_bytes": 0,+ "error": error,+ }+ running = {r.name: r for r in snapshot.running}+ return {+ "provider": provider_id,+ "server": root,+ "models": [+ model_row(m, running, ollama_roles.roles_using(cfg, m.name) if cfg else [])+ for m in snapshot.models+ ],+ "running": [running_row(r) for r in snapshot.running],+ "disk_bytes": sum(m.size_bytes for m in snapshot.models),+ "loaded_vram_bytes": sum(r.size_vram_bytes for r in snapshot.running),+ "error": None,+ }+++async def inventory_payload(provider_id: str, root: str, cfg: Any) -> dict[str, Any]:+ """Every download with its facts, what is loaded, and the disk total —+ the body of ``GET .../inventory``."""+ snapshot, error = await _snapshot(root)+ return _inventory_from(provider_id, root, cfg, snapshot, error)+++async def _roles_from(+ provider_id: str,+ root: str,+ cfg: Any,+ snapshot: inventory.InventorySnapshot | None,+ error: str | None,+ shortlist: list[dict[str, Any]] | None,+) -> dict[str, Any]:+ models = list(snapshot.models) if snapshot is not None else []+ states, _unused = await ollama_roles.list_roles(root, cfg, models=models, shortlist=shortlist)+ return {+ "provider": provider_id,+ "server": root,+ "roles": [role_row(s) for s in states],+ "error": error,+ }+++async def roles_payload(provider_id: str, root: str, cfg: Any) -> dict[str, Any]:+ """Every role with its pick, what qualifies, and the recommendation —+ the body of ``GET .../roles``."""+ snapshot, error = await _snapshot(root)+ return await _roles_from(provider_id, root, cfg, snapshot, error, None)+++async def _server_from(status: dict[str, object], fallback_root: str) -> dict[str, Any]:+ root = str(status.get("base_url") or fallback_root)+ running: list[dict[str, Any]] = []+ disk = 0+ error: str | None = None+ if status.get("running"):+ snapshot, error = await _snapshot(root)+ if snapshot is not None:+ disk = sum(m.size_bytes for m in snapshot.models)+ running = [running_row(r) for r in snapshot.running]+ else:+ log.info("local-models: inventory unavailable at %s: %s", root, error)+ return {+ "installed": bool(status.get("installed")),+ "binary": str(status.get("binary") or ""),+ "running": bool(status.get("running")),+ "version": str(status.get("version") or ""),+ "detail": str(status.get("detail") or ""),+ "base_url": root,+ "host_kind": str(status.get("host_kind") or "local"),+ "models_dir": str(status.get("models_dir") or ""),+ "running_models": running,+ "disk_bytes": disk,+ "loaded_vram_bytes": sum(int(r.get("size_vram_bytes") or 0) for r in running),+ "error": error,+ }+++async def server_payload(root: str) -> dict[str, Any]:+ """Runtime picture plus what is loaded and the disk total — the body of+ ``GET .../server``. The runtime probe is synchronous and runs off-loop."""+ status = await asyncio.to_thread(ollama_runtime.runtime_status)+ return await _server_from(status, root)+++async def _recommendations() -> dict[str, Any]:+ try:+ return await ollama_pull.recommendations()+ except Exception as exc: # noqa: BLE001 — the shortlist is advisory, the overview is not+ log.warning("local-models: shortlist unavailable: %s", exc)+ return {"models": [], "error": str(exc)}+++async def build_overview(root: str, cfg: Any, *, provider_id: str = "ollama") -> dict[str, Any]:+ """Compose server, roles, inventory and the shortlist from ONE sweep.++ The runtime probe, the shortlist (registry + hardware) and the inventory+ snapshot run concurrently; the payload carries ``fetched_at`` (epoch+ seconds) so a reader can say how old it is.+ """+ root = normalize_server_root(root)+ status, recommended, (snapshot, error) = await asyncio.gather(+ asyncio.to_thread(ollama_runtime.runtime_status),+ _recommendations(),+ _snapshot(root),+ )+ shortlist = recommended.get("models") if isinstance(recommended, dict) else None+ roles = await _roles_from(+ provider_id, root, cfg, snapshot, error, shortlist if isinstance(shortlist, list) else []+ )+ server = await _server_from(status, root)+ return {+ "server": server,+ "roles": roles,+ "inventory": _inventory_from(provider_id, root, cfg, snapshot, error),+ "recommended": recommended,+ "fetched_at": time.time(),+ }+++# ── Disk snapshot ────────────────────────────────────────────────────────+++def _data_dir() -> Path:+ env_dir = os.environ.get("JARVIS_DATA_DIR")+ if env_dir and env_dir.strip():+ return Path(env_dir.strip())+ from jarvis.core.config import DATA_DIR # lazy (AP-26)++ return DATA_DIR+++def snapshot_path() -> Path:+ return _data_dir() / SNAPSHOT_FILE_NAME+++def load_snapshot(path: Path | None = None) -> dict[str, Any] | None:+ """The saved overview ``{"root", "fetched_at", "payload"}`` or ``None``.++ A missing file is the normal first-run state; an unreadable or malformed+ one is logged and treated the same — the next live build overwrites it.+ """+ target = path or snapshot_path()+ try:+ raw = target.read_text(encoding="utf-8")+ except FileNotFoundError:+ return None+ except OSError:+ log.warning("local-models: snapshot %s unreadable", target, exc_info=True)+ return None+ try:+ data = json.loads(raw)+ except ValueError:+ log.warning("local-models: snapshot %s is not JSON; ignoring it", target)+ return None+ if (+ not isinstance(data, dict)+ or not isinstance(data.get("payload"), dict)+ or not isinstance(data.get("fetched_at"), (int, float))+ ):+ log.warning("local-models: snapshot %s has an unexpected shape; ignoring it", target)+ return None+ return data+++def save_snapshot(root: str, payload: dict[str, Any], path: Path | None = None) -> None:+ """Persist ``payload`` atomically (``.part`` + ``os.replace``).++ A crash mid-write leaves the previous snapshot intact; a write failure+ is logged and swallowed on purpose — the overview was already answered+ live, the cache is only the next open's head start.+ """+ target = path or snapshot_path()+ part = target.with_suffix(target.suffix + ".part")+ data = {"root": root, "fetched_at": float(payload.get("fetched_at") or time.time())}+ data["payload"] = payload+ try:+ target.parent.mkdir(parents=True, exist_ok=True)+ part.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")+ os.replace(part, target)+ except OSError:+ log.warning("local-models: could not save the snapshot to %s", target, exc_info=True)+ try:+ part.unlink(missing_ok=True)+ except OSError:+ log.debug("local-models: stale .part left at %s", part, exc_info=True)+++# ── Stale-while-revalidate ───────────────────────────────────────────────++_memo: dict[str, tuple[float, dict[str, Any]]] = {} # root -> (monotonic, payload)+#: The one background refresh per root; the reference is kept so the task+#: cannot be garbage-collected mid-flight, and a second open joins it.+_refresh_tasks: dict[str, asyncio.Task[dict[str, Any]]] = {}+++def _reset_for_tests() -> None:+ """Drop the in-memory overview memo and refresh bookkeeping (tests only)."""+ _memo.clear()+ _refresh_tasks.clear()+++def _fresh(root: str, max_age_s: float) -> dict[str, Any] | None:+ hit = _memo.get(root)+ if hit is not None and time.monotonic() - hit[0] < max_age_s:+ return hit[1]+ return None+++async def _refresh(root: str, cfg: Any, provider_id: str) -> dict[str, Any]:+ """Build live, memoise, save to disk (off-loop); returns the payload."""+ payload = await build_overview(root, cfg, provider_id=provider_id)+ _memo[root] = (time.monotonic(), payload)+ await asyncio.to_thread(save_snapshot, root, payload)+ return payload+++def _refresh_done(root: str, task: asyncio.Task[dict[str, Any]]) -> None:+ _refresh_tasks.pop(root, None)+ if task.cancelled():+ log.info("local-models: background refresh for %s was cancelled", root)+ return+ exc = task.exception()+ if exc is not None:+ log.warning("local-models: background refresh for %s failed: %s", root, exc)+++def _schedule_refresh(root: str, cfg: Any, provider_id: str) -> asyncio.Task[dict[str, Any]]:+ """ONE refresh per root: a second open while one runs joins it."""+ running = _refresh_tasks.get(root)+ if running is not None and not running.done():+ return running+ task = asyncio.create_task(+ _refresh(root, cfg, provider_id), name=f"local-models-overview-refresh-{root}"+ )+ _refresh_tasks[root] = task+ task.add_done_callback(functools.partial(_refresh_done, root))+ return task+++async def get_overview(+ root: str,+ cfg: Any,+ *,+ provider_id: str = "ollama",+ max_age_s: float = DEFAULT_MAX_AGE_S,+ fresh: bool = False,+) -> tuple[dict[str, Any], str]:+ """``(payload, source)`` — ``"live"`` or ``"cache"``.++ Order of preference: a live payload younger than ``max_age_s`` in memory;+ the disk snapshot (younger than :data:`STALE_AFTER_S`, same server) —+ returned at once with ONE background refresh scheduled; a live build,+ which also seeds memory and disk. ``fresh`` skips straight to the build.+ When the build itself fails (a bug, not an offline server — that is a+ normal payload) and a disk snapshot exists, the snapshot is the answer.+ """+ root = normalize_server_root(root)+ disk: dict[str, Any] | None = None+ if not fresh:+ if (hit := _fresh(root, max_age_s)) is not None:+ return hit, "live"+ disk = await asyncio.to_thread(load_snapshot)+ if disk is not None and disk.get("root") != root:+ disk = None+ if disk is not None and time.time() - float(disk["fetched_at"]) < STALE_AFTER_S:+ _schedule_refresh(root, cfg, provider_id)+ return dict(disk["payload"]), "cache"+ try:+ return await _refresh(root, cfg, provider_id), "live"+ except Exception:+ if disk is None:+ raise+ log.warning(+ "local-models: live overview failed; answering the disk snapshot", exc_info=True+ )+ return dict(disk["payload"]), "cache"diff --git a/jarvis/ui/web/local_models_routes.py b/jarvis/ui/web/local_models_routes.pyindex 4642fb9075..478a72be08 100644--- a/jarvis/ui/web/local_models_routes.py+++ b/jarvis/ui/web/local_models_routes.py@@ -26,7 +26,6 @@ from __future__ import annotationsimport asyncioimport logging-from dataclasses import asdictfrom typing import Anyfrom fastapi import APIRouter, HTTPException, Query, Request@@ -35,13 +34,13 @@ from pydantic import BaseModel, Fieldfrom jarvis.brain import ollama_inventory as inventoryfrom jarvis.brain import (ollama_library,+ ollama_overview,ollama_profiles,ollama_pull,ollama_roles,ollama_runtime,)from jarvis.brain.ollama_inventory import (- OllamaModelInfo,OllamaModelNotFound,OllamaRunningModel,OllamaServerError,@@ -151,30 +150,6 @@ def _roles_using(cfg: Any, name: str) -> list[str]:return roles_using(cfg, name)-def _row(- info: OllamaModelInfo, running: dict[str, OllamaRunningModel], used_by: list[str]-) -> dict[str, Any]:- live = next((r for key, r in running.items() if same_model(key, info.name)), None)- return {- "name": info.name,- "size_bytes": info.size_bytes,- "digest": info.digest,- "modified_at": info.modified_at,- "family": info.family,- "parameter_size": info.parameter_size,- "quantization_level": info.quantization_level,- "context_length": info.context_length,- "capabilities": list(info.capabilities),- "license": info.license,- "probed": info.probed,- "used_by": used_by,- "loaded": live is not None,- "size_vram_bytes": live.size_vram_bytes if live else 0,- "expires_at": live.expires_at if live else "",- "running_context_length": live.context_length if live else None,- }--async def _running_by_name(root: str) -> dict[str, OllamaRunningModel]:"""``/api/ps`` as a map from the shared snapshot; an unanswered probe is anempty map (logged), so a server that lists downloads but stalls on@@ -205,31 +180,10 @@ async def get_inventory(provider_id: str, request: Request) -> InventoryResponsevisible and ``loaded_vram_bytes`` stays honest."""_require_pull_capable(provider_id)- root = _server_root()- cfg = _resolve_cfg(request)- try:- snapshot = await inventory.cached_snapshot(root)- except OllamaServerError as exc:- return InventoryResponse(- provider=provider_id,- server=root,- models=[],- running=[],- disk_bytes=0,- loaded_vram_bytes=0,- error=str(exc),- )- models = snapshot.models- running = {r.name: r for r in snapshot.running}- rows = [LocalModelRow(**_row(m, running, _roles_using(cfg, m.name))) for m in models]- return InventoryResponse(- provider=provider_id,- server=root,- models=rows,- running=[RunningModelRow(**asdict(r)) for r in running.values()],- disk_bytes=sum(m.size_bytes for m in models),- loaded_vram_bytes=sum(r.size_vram_bytes for r in running.values()),+ payload = await ollama_overview.inventory_payload(+ provider_id, _server_root(), _resolve_cfg(request))+ return InventoryResponse(**payload)@router.get("/inventory/{name:path}", response_model=LocalModelDetail)@@ -242,7 +196,9 @@ async def get_inventory_model(provider_id: str, name: str, request: Request) ->except OllamaServerError as exc:raise _http_error(exc) from excrunning = await _running_by_name(root)- payload = _row(info, running, _roles_using(_resolve_cfg(request), info.name))+ payload = ollama_overview.model_row(+ info, running, _roles_using(_resolve_cfg(request), info.name)+ )payload["parameters"] = info.parameterspayload["template"] = info.templatereturn LocalModelDetail(**payload)@@ -412,35 +368,14 @@ class RoleSetResponse(BaseModel):message: str-def _role_row(state: ollama_roles.RoleState) -> RoleRow:- spec = state.spec- return RoleRow(- id=spec.id,- label_key=spec.label_key,- config_key=spec.config_key,- current=state.current,- installed=state.installed,- required=list(spec.required),- recommended_capabilities=list(spec.recommended),- qualifying=list(state.qualifying),- recommended=state.recommended,- writable=spec.writable,- advanced=spec.advanced,- note=state.note,- context_tokens=state.context_tokens,- context_source=state.context_source,- )--@router.get("/roles", response_model=RolesResponse)async def get_roles(provider_id: str, request: Request) -> RolesResponse:"""Every model slot with its pick, what qualifies, and the recommendation."""_require_pull_capable(provider_id)- root = _server_root()- states, error = await ollama_roles.list_roles(root, _resolve_cfg(request))- return RolesResponse(- provider=provider_id, server=root, roles=[_role_row(s) for s in states], error=error+ payload = await ollama_overview.roles_payload(+ provider_id, _server_root(), _resolve_cfg(request))+ return RolesResponse(**payload)@router.put("/roles/{role}", response_model=RoleSetResponse)@@ -824,34 +759,9 @@ class EnvGuideResponse(BaseModel):async def get_server(provider_id: str) -> ServerResponse:"""Runtime picture plus what is loaded and how much disk the downloads take."""_require_pull_capable(provider_id)- # A synchronous urllib probe (up to 1.5 s when the server is down) — off- # the loop so the sibling panels' requests keep flowing meanwhile.- status = await asyncio.to_thread(ollama_runtime.runtime_status)- root = str(status.get("base_url") or _server_root())- running: list[RunningModelRow] = []- disk = 0- error: str | None = None- if status.get("running"):- try:- disk = await inventory.disk_usage(root)- except OllamaServerError as exc:- log.info("local-models: disk usage unavailable at %s: %s", root, exc)- error = str(exc)- running = [RunningModelRow(**asdict(r)) for r in (await _running_by_name(root)).values()]- return ServerResponse(- installed=bool(status.get("installed")),- binary=str(status.get("binary") or ""),- running=bool(status.get("running")),- version=str(status.get("version") or ""),- detail=str(status.get("detail") or ""),- base_url=root,- host_kind=str(status.get("host_kind") or "local"),- models_dir=str(status.get("models_dir") or ""),- running_models=running,- disk_bytes=disk,- loaded_vram_bytes=sum(r.size_vram_bytes for r in running),- error=error,- )+ # The synchronous runtime probe (up to 1.5 s when the server is down)+ # runs off the loop inside ``server_payload``.+ return ServerResponse(**await ollama_overview.server_payload(_server_root()))@router.post(@@ -921,6 +831,51 @@ async def get_server_log(return ServerLogResponse(lines=await asyncio.to_thread(ollama_runtime.tail_log, lines))+class OverviewResponse(BaseModel):+ """ONE payload for the section's first paint (TS mirror ``OverviewResponse``+ in ``src/hooks/useLocalModels.ts``; parity-tested).++ ``server`` / ``roles`` / ``inventory`` / ``recommended`` are exactly what+ the four single endpoints answer; ``source`` says whether this is a live+ build or the disk snapshot from a previous open (``"cache"``, with a+ refresh already running); ``fetched_at`` is the build time, epoch seconds.+ """++ server: ServerResponse+ roles: RolesResponse+ inventory: InventoryResponse+ recommended: dict[str, Any]+ source: str+ fetched_at: float++[email protected]("/overview", response_model=OverviewResponse)+async def get_overview(+ provider_id: str,+ request: Request,+ fresh: int = Query(default=0, ge=0, le=1, description="1 = build live, skip the cache"),+) -> OverviewResponse:+ """Server, roles, inventory and the shortlist in one answer, cache first.++ The last good overview is kept on disk; it is answered at once as+ ``source: "cache"`` while one background refresh runs, so the section+ paints before the server has even been asked. ``?fresh=1`` forces a live+ build (the section uses it after a change it made itself).+ """+ _require_pull_capable(provider_id)+ payload, source = await ollama_overview.get_overview(+ _server_root(), _resolve_cfg(request), provider_id=provider_id, fresh=bool(fresh)+ )+ return OverviewResponse(+ server=ServerResponse(**payload["server"]),+ roles=RolesResponse(**payload["roles"]),+ inventory=InventoryResponse(**payload["inventory"]),+ recommended=dict(payload.get("recommended") or {}),+ source=source,+ fetched_at=float(payload.get("fetched_at") or 0.0),+ )++@router.get("/server/env-guide", response_model=EnvGuideResponse)async def get_server_env_guide(provider_id: str,diff --git a/tests/unit/brain/test_ollama_overview.py b/tests/unit/brain/test_ollama_overview.pynew file mode 100644index 0000000000..e9c280b234--- /dev/null+++ b/tests/unit/brain/test_ollama_overview.py@@ -0,0 +1,198 @@+"""The overview: one payload, disk snapshot first, one background refresh.++What would lie if it broke: an open that waits on the server although a+snapshot exists, a snapshot from another server painted as this one's, a+day-old snapshot painted although the server answers, two refreshes racing+for one open, a half-written snapshot file after a crash.+"""++from __future__ import annotations++import asyncio+import json+import time+from pathlib import Path++import httpx+import pytest++from jarvis.brain import ollama_inventory, ollama_overview, ollama_pull, ollama_runtime+from jarvis.core.config import BrainProviderConfig, JarvisConfig+from tests.fakes.fake_ollama_server import FakeOllamaServer++ROOT = "http://localhost:11434"+++def _names(directory: Path) -> list[str]:+ return [p.name for p in directory.iterdir()]+++def _cfg() -> JarvisConfig:+ cfg = JarvisConfig()+ cfg.brain.providers["ollama"] = BrainProviderConfig(model="qwen3.5:4b")+ return cfg+++def _status(running: bool) -> dict:+ return {+ "installed": True,+ "binary": "/usr/local/bin/ollama",+ "running": running,+ "version": "0.32.15" if running else "",+ "detail": "Ollama is running." if running else "Ollama is installed but not running.",+ "base_url": ROOT,+ "host_kind": "local",+ "models_dir": "/home/me/.ollama/models",+ }+++def fake(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> FakeOllamaServer:+ ollama_inventory._reset_for_tests()+ ollama_overview._reset_for_tests()+ monkeypatch.setenv("JARVIS_DATA_DIR", str(tmp_path))+ server = FakeOllamaServer()+ server.add("qwen3.5:4b", size=3_400_000_000, capabilities=("completion", "tools", "vision"))+ server.add("qwen3-embedding:4b", size=2_500_000_000, capabilities=("embedding",))+ server.load("qwen3.5:4b", size_vram=3_000_000_000)++ def _client(transport: httpx.AsyncBaseTransport | None = None) -> httpx.AsyncClient:+ return httpx.AsyncClient(transport=server.transport())++ monkeypatch.setattr(ollama_inventory, "_make_client", _client)+ monkeypatch.setattr(ollama_runtime, "runtime_status", lambda: _status(not server.offline))++ async def _recommendations() -> dict:+ return {"models": [], "curated_reviewed_on": "2026-08-24", "server_reachable": True}++ monkeypatch.setattr(ollama_pull, "recommendations", _recommendations)+ yield server+ ollama_inventory._reset_for_tests()+ ollama_overview._reset_for_tests()+++async def test_first_open_builds_live_and_saves_the_snapshot(fake, tmp_path: Path) -> None:+ payload, source = await ollama_overview.get_overview(ROOT, _cfg())+ assert source == "live"+ assert payload["server"]["running"] is True+ assert payload["inventory"]["disk_bytes"] == 3_400_000_000 + 2_500_000_000+ assert [r["name"] for r in payload["server"]["running_models"]] == ["qwen3.5:4b"]+ roles = {r["id"]: r for r in payload["roles"]["roles"]}+ assert roles["chat"]["current"] == "qwen3.5:4b" and roles["chat"]["installed"] is True+ assert payload["recommended"]["curated_reviewed_on"] == "2026-08-24"+ assert payload["fetched_at"] == pytest.approx(time.time(), abs=5)+ # One sweep for the whole payload.+ paths = [c[1] for c in fake.calls]+ assert paths.count("/api/tags") == 1 and paths.count("/api/show") == 2++ saved = ollama_overview.load_snapshot()+ assert saved is not None and saved["root"] == ROOT+ assert saved["payload"]["inventory"]["disk_bytes"] == payload["inventory"]["disk_bytes"]+ assert sorted(_names(tmp_path)) == [ollama_overview.SNAPSHOT_FILE_NAME], "no .part left"+++async def test_a_second_open_within_the_window_is_the_memo(fake) -> None:+ first, _ = await ollama_overview.get_overview(ROOT, _cfg())+ fake.calls.clear()+ second, source = await ollama_overview.get_overview(ROOT, _cfg())+ assert source == "live" and second is first+ assert fake.calls == []+++async def test_the_disk_snapshot_paints_at_once_and_one_refresh_runs(fake, tmp_path) -> None:+ """Offline server + a snapshot from the last open: the answer is the+ snapshot, within one tick, and exactly one background refresh starts."""+ live, _ = await ollama_overview.get_overview(ROOT, _cfg())+ ollama_overview._reset_for_tests() # a fresh process: memo empty, file present+ ollama_inventory._reset_for_tests()+ fake.offline = True+ fake.calls.clear()++ started = time.perf_counter()+ payload, source = await ollama_overview.get_overview(ROOT, _cfg())+ assert source == "cache"+ assert payload["inventory"]["disk_bytes"] == live["inventory"]["disk_bytes"]+ assert time.perf_counter() - started < 0.5+ task = ollama_overview._refresh_tasks.get(ROOT)+ assert task is not None and not task.done()+ # A second open while the refresh runs joins it — no second task.+ again, source_again = await ollama_overview.get_overview(ROOT, _cfg())+ assert source_again == "cache"+ assert ollama_overview._refresh_tasks.get(ROOT) is task++ refreshed = await task+ assert refreshed["server"]["running"] is False+ assert "did not answer" in refreshed["inventory"]["error"]+ assert ROOT not in ollama_overview._refresh_tasks+ # The refreshed payload is now the memo, and it reached the disk.+ memo, memo_source = await ollama_overview.get_overview(ROOT, _cfg())+ assert memo_source == "live" and memo is refreshed+ saved = ollama_overview.load_snapshot()+ assert saved is not None and saved["payload"]["server"]["running"] is False+++async def test_a_day_old_snapshot_is_replaced_by_a_live_build(fake) -> None:+ await ollama_overview.get_overview(ROOT, _cfg())+ stale = ollama_overview.load_snapshot()+ assert stale is not None+ stale["payload"]["fetched_at"] = time.time() - ollama_overview.STALE_AFTER_S - 60+ ollama_overview.save_snapshot(ROOT, stale["payload"])+ ollama_overview._reset_for_tests()+ ollama_inventory._reset_for_tests()+ fake.calls.clear()+ _payload, source = await ollama_overview.get_overview(ROOT, _cfg())+ assert source == "live"+ assert [c[1] for c in fake.calls].count("/api/tags") == 1+ assert ollama_overview._refresh_tasks == {}+++async def test_a_snapshot_of_another_server_is_not_painted(fake) -> None:+ await ollama_overview.get_overview(ROOT, _cfg())+ ollama_overview._reset_for_tests()+ ollama_inventory._reset_for_tests()+ _payload, source = await ollama_overview.get_overview("http://gpu-box:11434", _cfg())+ assert source == "live"+++async def test_fresh_skips_memo_and_disk(fake) -> None:+ await ollama_overview.get_overview(ROOT, _cfg())+ fake.calls.clear()+ ollama_inventory._reset_for_tests()+ _payload, source = await ollama_overview.get_overview(ROOT, _cfg(), fresh=True)+ assert source == "live"+ assert [c[1] for c in fake.calls].count("/api/tags") == 1+++def test_a_malformed_snapshot_is_ignored(tmp_path: Path, monkeypatch) -> None:+ monkeypatch.setenv("JARVIS_DATA_DIR", str(tmp_path))+ path = ollama_overview.snapshot_path()+ assert ollama_overview.load_snapshot() is None+ path.write_text("{not json", encoding="utf-8")+ assert ollama_overview.load_snapshot() is None+ path.write_text(json.dumps({"payload": "nope", "fetched_at": 1}), encoding="utf-8")+ assert ollama_overview.load_snapshot() is None+ ollama_overview.save_snapshot(ROOT, {"fetched_at": 12.0, "x": 1})+ assert ollama_overview.load_snapshot() == {+ "root": ROOT,+ "fetched_at": 12.0,+ "payload": {"fetched_at": 12.0, "x": 1},+ }+++async def test_a_failing_refresh_is_logged_not_lost(fake, monkeypatch, caplog) -> None:+ """A bug in the build must not vanish into a garbage-collected task."""+ await ollama_overview.get_overview(ROOT, _cfg())+ ollama_overview._reset_for_tests()++ async def _boom(*_a, **_kw) -> dict:+ raise RuntimeError("build exploded")++ monkeypatch.setattr(ollama_overview, "build_overview", _boom)+ _payload, source = await ollama_overview.get_overview(ROOT, _cfg())+ assert source == "cache"+ task = ollama_overview._refresh_tasks[ROOT]+ with pytest.raises(RuntimeError):+ await task+ await asyncio.sleep(0) # let the done-callback run+ assert ROOT not in ollama_overview._refresh_tasks+ assert any("background refresh" in r.getMessage() for r in caplog.records)diff --git a/tests/unit/ui/web/test_local_models_overview_parity.py b/tests/unit/ui/web/test_local_models_overview_parity.pynew file mode 100644index 0000000000..289d8ec983--- /dev/null+++ b/tests/unit/ui/web/test_local_models_overview_parity.py@@ -0,0 +1,141 @@+"""Parity for the overview wire contract (five-layer pattern, AP-4).++``OverviewResponse`` in ``local_models_routes.py`` (the Python half) and the+TS interface of the same name in ``src/hooks/useLocalModels.ts`` must carry+exactly the same six fields, and the route must actually answer them from+the disk snapshot when the server is silent.+"""++from __future__ import annotations++import json+import re+from pathlib import Path++import httpx+import pytest+from fastapi.testclient import TestClient++from jarvis.brain import ollama_inventory, ollama_overview, ollama_pull, ollama_runtime+from jarvis.core.bus import EventBus+from jarvis.core.config import BrainProviderConfig, JarvisConfig+from jarvis.ui.web import local_models_routes+from jarvis.ui.web.local_models_routes import OverviewResponse+from jarvis.ui.web.server import WebServer+from tests.fakes.fake_ollama_server import FakeOllamaServer++REPO_ROOT = Path(__file__).resolve().parents[4]+TS_FILE = REPO_ROOT / "jarvis/ui/web/frontend/src/hooks/useLocalModels.ts"+ROOT = "http://localhost:11434"+BASE = "/api/providers/ollama/local-models"++EXPECTED = ("server", "roles", "inventory", "recommended", "source", "fetched_at")+++def _ts_interface_keys(name: str) -> list[str] | None:+ src = TS_FILE.read_text(encoding="utf-8")+ match = re.search(rf"export interface {name}\s*\{{([^}}]*)\}}", src)+ if not match:+ return None+ return re.findall(r"^\s*([a-z_]+)\??:", match.group(1), flags=re.MULTILINE)+++def test_pydantic_fields_are_the_six_the_frontend_builds_against() -> None:+ assert tuple(OverviewResponse.model_fields) == EXPECTED+++def test_typescript_mirror_matches_the_pydantic_model() -> None:+ keys = _ts_interface_keys("OverviewResponse")+ if keys is None:+ pytest.skip(+ "interface OverviewResponse is not in useLocalModels.ts yet — the frontend "+ "chunk (A4/A5) adds it; this test then compares the six fields."+ )+ assert keys == list(OverviewResponse.model_fields)+++def fake(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> FakeOllamaServer:+ ollama_inventory._reset_for_tests()+ ollama_overview._reset_for_tests()+ monkeypatch.setenv("JARVIS_DATA_DIR", str(tmp_path))+ server = FakeOllamaServer()+ server.add("qwen3.5:4b", size=3_400_000_000, capabilities=("completion", "tools", "vision"))++ def _client(transport: httpx.AsyncBaseTransport | None = None) -> httpx.AsyncClient:+ return httpx.AsyncClient(transport=server.transport())++ monkeypatch.setattr(ollama_inventory, "_make_client", _client)+ monkeypatch.setattr(local_models_routes, "_server_root", lambda: ROOT)+ monkeypatch.setattr(+ ollama_runtime,+ "runtime_status",+ lambda: {+ "installed": True,+ "binary": "ollama",+ "running": not server.offline,+ "version": "0.32.15",+ "detail": "Ollama is running.",+ "base_url": ROOT,+ "host_kind": "local",+ "models_dir": "",+ },+ )++ async def _recommendations() -> dict:+ return {"models": [], "curated_reviewed_on": "2026-08-24"}++ monkeypatch.setattr(ollama_pull, "recommendations", _recommendations)+ yield server+ ollama_inventory._reset_for_tests()+ ollama_overview._reset_for_tests()+++def server(tmp_path, monkeypatch: pytest.MonkeyPatch) -> WebServer:+ monkeypatch.setenv("JARVIS_DATA_DIR", str(tmp_path))+ cfg = JarvisConfig()+ cfg.ui.dev_mode = True+ cfg.brain.providers["ollama"] = BrainProviderConfig(model="qwen3.5:4b")+ srv = WebServer(cfg, bus=EventBus())+ srv.app.state.config = cfg+ return srv+++def test_the_route_answers_live_then_the_cache(server: WebServer, fake, tmp_path: Path) -> None:+ with TestClient(server.app) as client:+ live = client.get(f"{BASE}/overview")+ assert live.status_code == 200, live.text+ body = live.json()+ assert set(body) == set(EXPECTED)+ assert body["source"] == "live"+ assert body["server"]["running"] is True+ assert body["inventory"]["disk_bytes"] == 3_400_000_000+ assert body["roles"]["roles"][0]["id"] == "chat"+ assert body["recommended"]["curated_reviewed_on"] == "2026-08-24"+ assert body["fetched_at"] > 0+ # Each part is exactly what the single endpoint answers.+ assert body["inventory"] == client.get(f"{BASE}/inventory").json()+ assert body["roles"] == client.get(f"{BASE}/roles").json()+ assert body["server"] == client.get(f"{BASE}/server").json()+ assert (tmp_path / ollama_overview.SNAPSHOT_FILE_NAME).exists()++ # A new process with a silent server: the snapshot paints first.+ ollama_overview._reset_for_tests()+ ollama_inventory._reset_for_tests()+ fake.offline = True+ with TestClient(server.app) as client:+ cached = client.get(f"{BASE}/overview").json()+ assert cached["source"] == "cache"+ assert cached["inventory"]["disk_bytes"] == 3_400_000_000+ forced = client.get(f"{BASE}/overview", params={"fresh": 1}).json()+ assert forced["source"] == "live"+ assert forced["server"]["running"] is False+ assert "did not answer" in forced["inventory"]["error"]+ saved = json.loads((tmp_path / ollama_overview.SNAPSHOT_FILE_NAME).read_text("utf-8"))+ assert saved["payload"]["server"]["running"] is False+++def test_the_overview_refuses_cards_without_a_pull_api(server: WebServer, fake) -> None:+ with TestClient(server.app) as client:+ assert client.get("/api/providers/openai/local-models/overview").status_code == 400