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): roles — the four model slots read and written from one place

rubenluetke10-beepf4048372eba8
diff --git a/jarvis/brain/ollama_roles.py b/jarvis/brain/ollama_roles.py
new file mode 100644
index 0000000000..97f7db6edd
--- /dev/null
+++ b/jarvis/brain/ollama_roles.py
@@ -0,0 +1,356 @@
+"""The model slots Ollama fills, read and written from ONE place.
+
+Today the local brain is spread over four config keys the user never sees
+side by side: the chat model, the tool/screen model, the deep model and the
+wiki's embedding model — plus three read-only consumers (the managed voice
+server, the quick ack, dictation polish) that follow or pin their own tag.
+This module names every slot as a :class:`RoleSpec`, reads its current pick
+from a loaded config, judges which INSTALLED downloads qualify for it (by the
+capabilities ``/api/show`` declares) and points at the shortlist's pick for
+this machine, so the "Local models" section can show the four rows with one
+button each instead of four different pickers in four different views.
+
+Writing goes through the existing config writers only
+(``config_writer.set_brain_provider_model`` / ``set_ultrawiki_slot``), so a
+role change lands in ``jarvis.toml`` AND the drift baseline exactly like a
+pick made on the provider card — the drift guard sees no difference (AP-7,
+BUG-010 class). The tier defaults stay ``""`` (= plugin-side discovery);
+nothing here pins a model by default.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from jarvis.brain import ollama_inventory as inventory
+from jarvis.brain import ollama_pull
+from jarvis.brain.ollama_inventory import OllamaModelInfo, OllamaServerError, same_model
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+ "ROLES",
+ "WRITABLE_ROLE_IDS",
+ "RoleSpec",
+ "RoleState",
+ "current_pick",
+ "list_roles",
+ "qualifying_models",
+ "role_spec",
+ "roles_using",
+ "set_role",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RoleSpec:
+ """One job a local model does, and where the brain reads its pick."""
+
+ id: str
+ #: i18n key of the row label (``local_models.role_<id>``).
+ label_key: str
+ #: Dotted config path, for the "where does this live" footnote.
+ config_key: str
+ #: Capabilities (``/api/show`` vocabulary) a model MUST declare.
+ required: tuple[str, ...]
+ #: Capabilities that make a model a better fit but are not a gate.
+ recommended: tuple[str, ...]
+ #: The shortlist role whose pick serves this slot
+ #: (:data:`jarvis.brain.ollama_pull.ROLE_ORDER` vocabulary).
+ pull_role: str
+ #: Whether :func:`set_role` may write it. Read-only roles are shown under
+ #: "More roles" so the user sees which tag they follow, and where.
+ writable: bool = True
+ #: Hidden in the Simple view.
+ advanced: bool = False
+
+
+ROLES: tuple[RoleSpec, ...] = (
+ RoleSpec(
+ id="chat",
+ label_key="local_models.role_chat",
+ config_key="brain.providers.ollama.model",
+ required=("completion",),
+ recommended=("tools",),
+ pull_role="chat",
+ ),
+ RoleSpec(
+ id="tools_screen",
+ label_key="local_models.role_tools_screen",
+ config_key="brain.providers.ollama.tool_model",
+ required=("tools", "vision"),
+ recommended=(),
+ pull_role="vision",
+ ),
+ RoleSpec(
+ id="deep",
+ label_key="local_models.role_deep",
+ config_key="brain.providers.ollama.deep_model",
+ required=("tools",),
+ recommended=("thinking",),
+ pull_role="coder",
+ ),
+ RoleSpec(
+ id="embedding",
+ label_key="local_models.role_embedding",
+ config_key="ultrawiki.embedding_model",
+ required=("embedding",),
+ recommended=(),
+ pull_role="embedding",
+ ),
+ # Read-only consumers. The managed voice server prefers the chat pick
+ # (``preflight._preferred_brain_model`` reads the same key) and keeps its
+ # own ``-voice-8k`` alias; the ack and polish models have their own
+ # pickers on their own cards.
+ RoleSpec(
+ id="voice",
+ label_key="local_models.role_voice",
+ config_key="brain.providers.ollama.model",
+ required=("completion",),
+ recommended=("tools",),
+ pull_role="chat",
+ writable=False,
+ advanced=True,
+ ),
+ RoleSpec(
+ id="ack",
+ label_key="local_models.role_ack",
+ config_key="ack_brain.providers.ollama.model",
+ required=("completion",),
+ recommended=(),
+ pull_role="chat",
+ writable=False,
+ advanced=True,
+ ),
+ RoleSpec(
+ id="polish",
+ label_key="local_models.role_polish",
+ config_key="dictation.polish_model",
+ required=("completion",),
+ recommended=(),
+ pull_role="chat",
+ writable=False,
+ advanced=True,
+ ),
+)
+
+WRITABLE_ROLE_IDS: tuple[str, ...] = tuple(r.id for r in ROLES if r.writable)
+
+
+@dataclass(frozen=True, slots=True)
+class RoleState:
+ """A role as the section renders it."""
+
+ spec: RoleSpec
+ #: The configured tag, or ``""`` = the plugin discovers one.
+ current: str
+ #: Whether ``current`` is on the server right now.
+ installed: bool
+ #: Installed tags that declare every required capability.
+ qualifying: tuple[str, ...]
+ #: The shortlist's pick for this machine (``""`` when it has none).
+ recommended: str
+ #: One sentence when the slot is not Ollama-backed right now.
+ note: str = ""
+
+
+# ── Reading ──────────────────────────────────────────────────────────────
+
+
+def role_spec(role_id: str) -> RoleSpec:
+ for spec in ROLES:
+ if spec.id == role_id:
+ return spec
+ raise ValueError(f"Unknown role '{role_id}' (known: {', '.join(r.id for r in ROLES)}).")
+
+
+def _ollama_provider(cfg: Any) -> Any:
+ providers = getattr(getattr(cfg, "brain", None), "providers", None) or {}
+ return providers.get("ollama") if isinstance(providers, dict) else None
+
+
+def _str(value: object) -> str:
+ return str(value or "").strip()
+
+
+def current_pick(cfg: Any, role_id: str) -> tuple[str, str]:
+ """``(tag, note)`` the config holds for ``role_id``.
+
+ ``tag`` is ``""`` for discovery; ``note`` is one sentence when the slot
+ is served by something other than Ollama (the wiki embedding with a
+ cloud provider, dictation polish on another provider), so the row can
+ say so instead of showing an unrelated tag as if Ollama ran it.
+ """
+ if cfg is None:
+ return "", ""
+ provider = _ollama_provider(cfg)
+ if role_id in ("chat", "voice"):
+ return _str(getattr(provider, "model", "")), ""
+ if role_id == "tools_screen":
+ return (
+ _str(getattr(provider, "tool_model", "")) or _str(getattr(provider, "cu_model", "")),
+ "",
+ )
+ if role_id == "deep":
+ return _str(getattr(provider, "deep_model", "")), ""
+ if role_id == "embedding":
+ wiki = getattr(cfg, "ultrawiki", None)
+ backend = _str(getattr(wiki, "embedding_provider", ""))
+ model = _str(getattr(wiki, "embedding_model", ""))
+ if backend and backend != "ollama":
+ return "", f"The wiki embeds with {backend}, not with Ollama."
+ return model, ""
+ if role_id == "ack":
+ ack = getattr(cfg, "ack_brain", None)
+ providers = getattr(ack, "providers", None)
+ return _str(getattr(getattr(providers, "ollama", None), "model", "")), ""
+ if role_id == "polish":
+ dictation = getattr(cfg, "dictation", None)
+ backend = _str(getattr(dictation, "polish_provider", ""))
+ model = _str(getattr(dictation, "polish_model", ""))
+ if backend and backend not in ("auto", "ollama"):
+ return "", f"Dictation polish runs on {backend}, not on Ollama."
+ return model, ""
+ raise ValueError(f"Unknown role '{role_id}'.")
+
+
+def qualifying_models(spec: RoleSpec, models: list[OllamaModelInfo]) -> tuple[str, ...]:
+ """Installed tags that declare every capability ``spec`` requires.
+
+ A row whose ``/api/show`` failed (``probed=False``) is left out: "unknown"
+ must not read as "qualifies", or a screen reader without vision gets
+ assigned and fails on the first screenshot.
+ """
+ out: list[str] = []
+ for info in models:
+ if not info.probed:
+ continue
+ if all(cap in info.capabilities for cap in spec.required):
+ out.append(info.name)
+ return tuple(out)
+
+
+def _recommended_for(spec: RoleSpec, rows: list[dict[str, Any]]) -> str:
+ """The shortlist's pick for ``spec`` on this machine.
+
+ :func:`ollama_pull._pick_recommended` marks nothing for a role that has
+ a curated model installed already — the user has chosen. Then the
+ largest INSTALLED curated model of that role is named instead, so the
+ "Use recommended" button always has something honest to assign.
+ """
+ for row in rows:
+ if spec.pull_role in (row.get("recommended_for") or []):
+ return str(row["id"])
+ installed = [
+ row
+ for row in rows
+ if row.get("installed")
+ and (row.get("role") == spec.pull_role or ollama_pull._serves_vision(spec.pull_role, row))
+ ]
+ if installed:
+ return str(max(installed, key=lambda r: float(r.get("size_gb") or 0))["id"])
+ return ""
+
+
+async def list_roles(
+ root: str, cfg: Any, *, transport: Any = None
+) -> tuple[list[RoleState], str | None]:
+ """Every role with its pick, what qualifies, and the recommendation.
+
+ Returns ``(states, error)``; ``error`` is the server's English sentence
+ when ``/api/tags`` did not answer — the states are still complete (with
+ empty ``qualifying`` and ``installed=False``) so the rows render.
+ """
+ error: str | None = None
+ try:
+ models = await inventory.list_models(root, transport=transport)
+ except OllamaServerError as exc:
+ log.info("ollama-roles: inventory unavailable at %s: %s", root, exc)
+ models = []
+ error = str(exc)
+ try:
+ shortlist = (await ollama_pull.recommendations()).get("models") or []
+ except Exception as exc: # noqa: BLE001 — the shortlist is advisory, the rows are not
+ log.warning("ollama-roles: shortlist unavailable: %s", exc)
+ shortlist = []
+
+ states: list[RoleState] = []
+ for spec in ROLES:
+ current, note = current_pick(cfg, spec.id)
+ qualifying = qualifying_models(spec, models)
+ states.append(
+ RoleState(
+ spec=spec,
+ current=current,
+ installed=bool(current) and any(same_model(m.name, current) for m in models),
+ qualifying=qualifying,
+ recommended=_recommended_for(spec, shortlist),
+ note=note,
+ )
+ )
+ return states, error
+
+
+# ── Writing ──────────────────────────────────────────────────────────────
+
+
+def set_role(role_id: str, model: str, *, cfg: Any = None) -> dict[str, str]:
+ """Persist ``model`` as the pick of ``role_id``; ``""`` = discovery.
+
+ Dispatches to the writer the provider card already uses for that key, so
+ the TOML and the drift baseline agree; ``cfg`` (the live config object) is
+ updated in place when given, so the next read answers the new value
+ without a restart. Returns ``{"role", "model", "config_key"}``.
+
+ Raises ``ValueError`` for an unknown or read-only role, and for an empty
+ embedding model (the wiki needs a name; there is no discovery there).
+ """
+ spec = role_spec(role_id)
+ if not spec.writable:
+ raise ValueError(
+ f"'{role_id}' follows {spec.config_key} and is changed on its own card, not here."
+ )
+ tag = _str(model)
+ from jarvis.core import config_writer # lazy: tomlkit + file locks off the read path
+
+ provider = _ollama_provider(cfg)
+ if spec.id == "chat":
+ config_writer.set_brain_provider_model("ollama", model=tag)
+ if provider is not None:
+ provider.model = tag
+ elif spec.id == "tools_screen":
+ # Same pair the cu-model setter writes: canonical + legacy key.
+ config_writer.set_brain_provider_model("ollama", tool_model=tag, cu_model=tag)
+ if provider is not None:
+ provider.tool_model = tag
+ provider.cu_model = tag
+ elif spec.id == "deep":
+ config_writer.set_brain_provider_model("ollama", deep_model=tag)
+ if provider is not None:
+ provider.deep_model = tag
+ elif spec.id == "embedding":
+ if not tag:
+ raise ValueError("The embedding role needs a model name; the wiki cannot discover one.")
+ wiki = getattr(cfg, "ultrawiki", None)
+ if _str(getattr(wiki, "embedding_provider", "ollama")) != "ollama":
+ config_writer.set_ultrawiki_slot("embedding_provider", "ollama")
+ if wiki is not None:
+ wiki.embedding_provider = "ollama"
+ config_writer.set_ultrawiki_slot("embedding_model", tag)
+ if wiki is not None:
+ wiki.embedding_model = tag
+ return {"role": spec.id, "model": tag, "config_key": spec.config_key}
+
+
+def roles_using(cfg: Any, name: str) -> list[str]:
+ """Writable role ids whose configured pick is ``name`` (``:latest`` tolerant)."""
+ out: list[str] = []
+ for spec in ROLES:
+ if not spec.writable:
+ continue
+ current, _note = current_pick(cfg, spec.id)
+ if current and same_model(current, name):
+ out.append(spec.id)
+ return out
diff --git a/tests/unit/brain/test_ollama_roles.py b/tests/unit/brain/test_ollama_roles.py
new file mode 100644
index 0000000000..40abbae768
--- /dev/null
+++ b/tests/unit/brain/test_ollama_roles.py
@@ -0,0 +1,232 @@
+"""Roles: the four Ollama slots read from the config, judged against the
+installed downloads, pointed at the shortlist's pick, and written through
+the existing config writers only.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from jarvis.brain import ollama_pull, ollama_roles
+from jarvis.core import config_writer
+from jarvis.core.config import BrainProviderConfig, JarvisConfig
+from tests.fakes.fake_ollama_server import FakeOllamaServer
+
+ROOT = "http://localhost:11434"
+
+
+def _cfg() -> JarvisConfig:
+ cfg = JarvisConfig()
+ cfg.brain.providers["ollama"] = BrainProviderConfig(
+ model="qwen3.5:4b", deep_model="gemma4:12b-it-qat"
+ )
+ cfg.ultrawiki.embedding_provider = "ollama"
+ cfg.ultrawiki.embedding_model = "qwen3-embedding:4b"
+ return cfg
+
+
+def fake() -> FakeOllamaServer:
+ server = FakeOllamaServer()
+ server.add("qwen3.5:4b", capabilities=("completion", "tools", "vision"))
+ server.add("gemma4:12b-it-qat", capabilities=("completion", "tools", "thinking"))
+ server.add("qwen3-embedding:4b", capabilities=("embedding",))
+ server.add("broken:1b", show_fails=True)
+ return server
+
+
+def shortlist(monkeypatch: pytest.MonkeyPatch) -> list[dict]:
+ rows = [
+ {
+ "id": "qwen3.8:27b",
+ "role": "chat",
+ "vision": True,
+ "size_gb": 18.0,
+ "installed": False,
+ "recommended": True,
+ "recommended_for": ["chat", "vision"],
+ },
+ {
+ "id": "ornith:9b",
+ "role": "coder",
+ "vision": False,
+ "size_gb": 5.6,
+ "installed": False,
+ "recommended": True,
+ "recommended_for": ["coder"],
+ },
+ {
+ "id": "qwen3-embedding:4b",
+ "role": "embedding",
+ "vision": False,
+ "size_gb": 2.5,
+ "installed": True,
+ "recommended": False,
+ "recommended_for": [],
+ },
+ {
+ "id": "embeddinggemma",
+ "role": "embedding",
+ "vision": False,
+ "size_gb": 0.3,
+ "installed": True,
+ "recommended": False,
+ "recommended_for": [],
+ },
+ ]
+
+ async def _recommendations() -> dict:
+ return {"models": rows}
+
+ monkeypatch.setattr(ollama_pull, "recommendations", _recommendations)
+ return rows
+
+
+def writes(monkeypatch: pytest.MonkeyPatch) -> list[tuple]:
+ calls: list[tuple] = []
+ monkeypatch.setattr(
+ config_writer,
+ "set_brain_provider_model",
+ lambda provider, **kw: calls.append(("brain", provider, kw)),
+ )
+ monkeypatch.setattr(
+ config_writer,
+ "set_ultrawiki_slot",
+ lambda key, value: calls.append(("ultrawiki", key, value)),
+ )
+ return calls
+
+
+def test_the_four_writable_roles_come_first_in_order() -> None:
+ assert ollama_roles.WRITABLE_ROLE_IDS == ("chat", "tools_screen", "deep", "embedding")
+ assert [r.id for r in ollama_roles.ROLES][4:] == ["voice", "ack", "polish"]
+ assert all(r.advanced and not r.writable for r in ollama_roles.ROLES[4:])
+
+
+def test_current_pick_reads_every_slot() -> None:
+ cfg = _cfg()
+ cfg.brain.providers["ollama"].cu_model = "legacy:1b"
+ assert ollama_roles.current_pick(cfg, "chat") == ("qwen3.5:4b", "")
+ # Canonical tool_model wins; the legacy cu_model is the fallback.
+ assert ollama_roles.current_pick(cfg, "tools_screen") == ("legacy:1b", "")
+ cfg.brain.providers["ollama"].tool_model = "qwen3.5:4b"
+ assert ollama_roles.current_pick(cfg, "tools_screen") == ("qwen3.5:4b", "")
+ assert ollama_roles.current_pick(cfg, "deep") == ("gemma4:12b-it-qat", "")
+ assert ollama_roles.current_pick(cfg, "embedding") == ("qwen3-embedding:4b", "")
+ assert ollama_roles.current_pick(cfg, "voice") == ("qwen3.5:4b", "")
+ assert ollama_roles.current_pick(cfg, "ack")[0] == cfg.ack_brain.providers.ollama.model
+ assert ollama_roles.current_pick(None, "chat") == ("", "")
+
+
+def test_a_slot_served_elsewhere_says_so_instead_of_showing_a_foreign_tag() -> None:
+ cfg = _cfg()
+ cfg.ultrawiki.embedding_provider = "openai"
+ cfg.ultrawiki.embedding_model = "text-embedding-3-small"
+ current, note = ollama_roles.current_pick(cfg, "embedding")
+ assert current == ""
+ assert "openai" in note
+
+
+async def test_list_roles_judges_qualifying_models_by_capability(fake, shortlist) -> None:
+ states, error = await ollama_roles.list_roles(ROOT, _cfg(), transport=fake.transport())
+ assert error is None
+ by_id = {s.spec.id: s for s in states}
+ assert by_id["chat"].current == "qwen3.5:4b"
+ assert by_id["chat"].installed is True
+ # Unprobed rows never qualify; the embedder has no completion capability.
+ assert by_id["chat"].qualifying == ("qwen3.5:4b", "gemma4:12b-it-qat")
+ assert by_id["tools_screen"].qualifying == ("qwen3.5:4b",)
+ assert by_id["tools_screen"].current == ""
+ assert by_id["deep"].qualifying == ("qwen3.5:4b", "gemma4:12b-it-qat")
+ assert by_id["embedding"].qualifying == ("qwen3-embedding:4b",)
+
+
+async def test_list_roles_points_at_the_shortlists_pick_or_the_largest_installed_one(
+ fake, shortlist
+) -> None:
+ states, _ = await ollama_roles.list_roles(ROOT, _cfg(), transport=fake.transport())
+ by_id = {s.spec.id: s for s in states}
+ assert by_id["chat"].recommended == "qwen3.8:27b"
+ # The multimodal chat pick serves the screen role too.
+ assert by_id["tools_screen"].recommended == "qwen3.8:27b"
+ assert by_id["deep"].recommended == "ornith:9b"
+ # The picker marks nothing once the role has a curated model installed;
+ # the largest installed one is named so the button still has an answer.
+ assert by_id["embedding"].recommended == "qwen3-embedding:4b"
+
+
+async def test_list_roles_keeps_the_rows_when_the_server_is_offline(fake, shortlist) -> None:
+ fake.offline = True
+ states, error = await ollama_roles.list_roles(ROOT, _cfg(), transport=fake.transport())
+ assert error and "did not answer" in error
+ assert len(states) == len(ollama_roles.ROLES)
+ assert all(s.qualifying == () and s.installed is False for s in states)
+ assert states[0].current == "qwen3.5:4b"
+
+
+async def test_list_roles_survives_a_failing_shortlist(fake, monkeypatch) -> None:
+ async def _boom() -> dict:
+ raise RuntimeError("registry down")
+
+ monkeypatch.setattr(ollama_pull, "recommendations", _boom)
+ states, error = await ollama_roles.list_roles(ROOT, _cfg(), transport=fake.transport())
+ assert error is None
+ assert all(s.recommended == "" for s in states)
+
+
+def test_set_role_writes_through_the_provider_card_writers(writes) -> None:
+ cfg = _cfg()
+ out = ollama_roles.set_role("chat", "gemma4:12b-it-qat", cfg=cfg)
+ ollama_roles.set_role("tools_screen", "qwen3.5:4b", cfg=cfg)
+ ollama_roles.set_role("deep", "", cfg=cfg)
+ assert out == {
+ "role": "chat",
+ "model": "gemma4:12b-it-qat",
+ "config_key": "brain.providers.ollama.model",
+ }
+ assert writes == [
+ ("brain", "ollama", {"model": "gemma4:12b-it-qat"}),
+ ("brain", "ollama", {"tool_model": "qwen3.5:4b", "cu_model": "qwen3.5:4b"}),
+ ("brain", "ollama", {"deep_model": ""}),
+ ]
+ provider = cfg.brain.providers["ollama"]
+ assert provider.model == "gemma4:12b-it-qat"
+ assert provider.tool_model == "qwen3.5:4b"
+ assert provider.cu_model == "qwen3.5:4b"
+ assert provider.deep_model == ""
+
+
+def test_set_role_embedding_switches_the_wiki_to_ollama_when_needed(writes) -> None:
+ cfg = _cfg()
+ cfg.ultrawiki.embedding_provider = "openai"
+ ollama_roles.set_role("embedding", "embeddinggemma", cfg=cfg)
+ assert writes == [
+ ("ultrawiki", "embedding_provider", "ollama"),
+ ("ultrawiki", "embedding_model", "embeddinggemma"),
+ ]
+ assert cfg.ultrawiki.embedding_provider == "ollama"
+ assert cfg.ultrawiki.embedding_model == "embeddinggemma"
+ with pytest.raises(ValueError):
+ ollama_roles.set_role("embedding", "", cfg=cfg)
+
+
+def test_set_role_refuses_read_only_and_unknown_roles(writes) -> None:
+ with pytest.raises(ValueError, match="own card"):
+ ollama_roles.set_role("voice", "x", cfg=_cfg())
+ with pytest.raises(ValueError, match="Unknown role"):
+ ollama_roles.set_role("nope", "x", cfg=_cfg())
+ assert writes == []
+
+
+def test_roles_using_is_latest_tolerant() -> None:
+ cfg = _cfg()
+ assert ollama_roles.roles_using(cfg, "qwen3.5:4b") == ["chat"]
+ cfg.brain.providers["ollama"].model = "gemma4"
+ assert ollama_roles.roles_using(cfg, "gemma4:latest") == ["chat"]
+ assert ollama_roles.roles_using(cfg, "qwen3-embedding:4b") == ["embedding"]