Skip to content

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.

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.py
new file mode 100644
index 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.py
index 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 annotations
import asyncio
import logging
-from dataclasses import asdict
from typing import Any
from fastapi import APIRouter, HTTPException, Query, Request
@@ -35,13 +34,13 @@ from pydantic import BaseModel, Field
from jarvis.brain import ollama_inventory as inventory
from 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 an
empty map (logged), so a server that lists downloads but stalls on
@@ -205,31 +180,10 @@ async def get_inventory(provider_id: str, request: Request) -> InventoryResponse
visible 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 exc
running = 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.parameters
payload["template"] = info.template
return 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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