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(ollama): per-model options — a profile alias carries num_ctx, placement and sampling; keep-alive warms the model

rubenluetke10-beep65aaaef02389
diff --git a/docs/os-parity.md b/docs/os-parity.md
index f677c540e0..88eaea5a8a 100644
--- a/docs/os-parity.md
+++ b/docs/os-parity.md
@@ -248,6 +248,7 @@ experiences today.
| P-30 | Medium | Local STT on the GPU | The on-device CTranslate2 recognizer (faster-whisper) needs the cuBLAS 12 / cuDNN 9 runtime wheels, which the `[full]` profile deliberately does not carry. Without them the engine self-heals onto the CPU and, until 2026-08-22, nothing but a log line said so (36 silent fallbacks in one live log; the cloud fallback then ran at ~1× realtime). The wheels are now the opt-in `[cuda]` extra, the provider card reports the accelerator truth (`accelerator_status`: requested device, effective device, reason code) and offers the install from inside the app (`POST /api/local-gpu/libraries`), and the library probe is a pure on-disk look — the out-of-process inference probe (AP-25) remains the only verdict on whether the GPU WORKS | `jarvis/plugins/stt/fwhisper.py::cuda_runtime_libraries_present`, `GPU_LIBRARY_PACKAGES`, `jarvis/speech/local_models.py::accelerator_status`, `jarvis/speech/local_install.py::start_gpu_libraries_install` | Windows: verified live on the dev box (install → `ctranslate2.get_cuda_device_count() == 1`, base/cuda decode). Linux: the same wheels land in `nvidia/cublas/lib`; the probe also accepts a system-wide CUDA via `ctypes.util.find_library("cublas")` — expected to work, UNVERIFIED on real hardware. macOS: no CUDA exists; the card says `unsupported_os` and the recognizer runs on the CPU with no install offered. Headless/GPU-less Linux: libraries absent → honest `cuda_libraries_missing` when the config asks for `cuda`, silent when it asks for `cpu` |
| P-32 | Low | Local models | The in-app Ollama runtime install (the plug-and-go path for local models: detect → install → start → pull, no terminal) has one silent path per OS and an honest refusal elsewhere: Windows uses winget or the official per-user OllamaSetup.exe (built, not yet live-run on a machine WITHOUT Ollama); macOS automates only Homebrew — a dmg drag cannot be scripted honestly, so brew-less Macs get the download pointer; Linux runs the official install.sh only when non-interactive sudo exists (the script escalates internally; without it the refusal names the one terminal command instead of hanging on an invisible password prompt). Detection and start are cross-platform | `jarvis/brain/ollama_runtime.py`, `jarvis/ui/web/provider_routes.py` (ollama-runtime routes), `jarvis/realtime/local_server/install.py::_setup_local_brain` | Every OS gets the same three-state truth (not installed / stopped / running) and the same buttons; only the INSTALL leg differs. Refusals are one honest sentence with the exact fixing action. All install legs are unit-tested with fakes; no leg has been live-run on a machine without Ollama yet — the cold-machine drill is the recorded release gate |
+| P-32 | Info | Local models | Per-model options (a derived profile alias via `/api/create` carrying `num_ctx`, placement and sampling; a `keep_alive` warm ping via `/api/generate`; `think` as `reasoning_effort` on `/v1`) are pure HTTP against the Ollama server root — no OS-specific leg, no subprocess, identical on Windows, macOS, Linux (headless included) and against a remote host | `jarvis/brain/ollama_profiles.py`, `jarvis/plugins/brain/ollama.py`, `jarvis/core/config_writer.py::set_ollama_model_options` | Same behaviour everywhere; the server does the work, Jarvis only names the alias. Unit-tested with an `httpx.MockTransport` fake server; `reasoning_effort` -> `think` verified live on Ollama 0.32.15 |
| P-31 | Low | Detached views | The "own window" detach (Agentic IDE / Voice into a second pywebview window) creates the window at RUNTIME, after `webview.start()`. pywebview documents runtime multi-window, and the code path is OS-neutral (worker-thread create, distinct title, shared backend), but it has only been RUN against the Windows/WebView2 backend; whether the cocoa and GTK backends accept a runtime `create_window` is unverified from this machine. Browser-lock auth in the second window additionally relies on a shared cookie jar, which is verified for WebView2 only | `jarvis/ui/desktop_app.py::open_detached_window`, `jarvis/platform/probes.py::webview_backend_available`, `jarvis/ui/web/desktop_routes.py` | Every failure is honest and keeps the feature usable: a shell whose backend refuses the runtime create answers `ok: false` with the solo URL and the frontend opens it in the user's real browser tab (via open-external); plain-browser clients open the tab directly; headless answers `no_desktop_shell` the same way. macOS/Linux desktop live check pending: detach, close main, reattach, tray-reopen — on success this row shrinks to the cookie-jar note or disappears |
| P-33 | Low | Music control (YouTube Music) | With the default **background player** (`jarvis/platform/music_player.py` + `music_player_host.py`: a pywebview companion window with its own persistent profile, driven over stdin/stdout JSON lines) pause / resume / next / previous / volume / "what is playing" go through the player's page directly and need only a display plus the `[desktop]` extra (pywebview) — verified live on Windows/WebView2 (a hidden window does NOT start media; minimized does, hence the minimized start); macOS WKWebView and Linux GTK/Qt WebKit are the same code, unverified from this machine, and autoplay policy there may need one press of play (the tool shows the window and says so). In **browser mode**, and wherever the player cannot run, the same verbs go through the OS media session — the registry the keyboard's media keys use — because Google publishes no remote-playback API. Windows reads and steers it through WinRT (`winrt-Windows.Media.Control`, in the `[desktop]` extra; measured live 2026-08-18 against YouTube Music in Chrome, including the two-tabs-same-app-id case) and falls back to blind media keys without the extra. Linux has no binding in the base install and needs the `playerctl` CLI (MPRIS); macOS has no public API at all and needs the Homebrew `nowplaying-cli`, whose MediaRemote access Apple has been narrowing on recent releases | `jarvis/platform/media_session.py::make_media_session_controller`, `WindowsMediaSession`, `LinuxMediaSession`, `MacMediaSession`, `jarvis/plugins/tool/youtube_music_rest.py::_control` | Playing (search + open the `music.youtube.com` deep link) works on every desktop OS. Without the CLI, `now_playing` and the transport verbs answer with the exact install command instead of a fake success, and the play deep link plus the library actions (like, playlists) stay fully usable. Headless: no player exists, so the tool returns the link and says so. Linux `playerctl` and macOS `nowplaying-cli` backends are unit-tested with fake CLI output, not live-run from this machine |
| P-34 | Low | Drop-path bridge | The desktop shell reports the REAL path of a file or folder dropped onto the UI (`jarvis-native-drop` DOM event from `jarvis/ui/native_drop.py`, consumed by `src/lib/nativeDrop.ts` in the Agentic IDE folder picker). Built on pywebview's own cross-platform drop handling (`pywebviewFullPath` — WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux); live-verified for a dropped FOLDER on Windows/WebView2 only | `jarvis/ui/native_drop.py::register_native_drop`, `jarvis/ui/desktop_app.py::_register_native_drop`, `jarvis/ui/web/frontend/src/lib/nativeDrop.ts` | Honest degradation everywhere: without the announcement (plain browser, headless, a shell whose backend does not resolve paths) the picker falls back to searching for the dropped NAME after 2 s, exactly as before. macOS/Linux live check pending: drop a folder onto the folder step and confirm the exact path is used without a candidate list |
diff --git a/jarvis/brain/ollama_profiles.py b/jarvis/brain/ollama_profiles.py
new file mode 100644
index 0000000000..6a47f7373f
--- /dev/null
+++ b/jarvis/brain/ollama_profiles.py
@@ -0,0 +1,371 @@
+"""Per-model Ollama profiles: a derived model carries the knobs ``/v1`` cannot.
+
+Ollama's OpenAI-compatible ``/v1`` endpoint ignores request ``options``,
+``keep_alive`` and ``think`` (the main brain talks to it through
+``jarvis/plugins/brain/ollama.py``). Rather than rewriting the streamer against
+the native ``/api/chat``, the per-model knobs travel three ways:
+
+* **Bakeable** knobs (:data:`BAKEABLE_KEYS`) are baked into a derived model
+ via ``POST /api/create {"model": alias, "from": base, "parameters": ...}`` —
+ the same trick the local-realtime supervisor uses for its ``-voice-8k``
+ alias. The alias shares the weights (metadata only, no download), and its
+ name carries a hash of the baked set so a changed knob yields a new alias
+ and the stale one is deleted. Aliases end in ``-jarvis-<8 hex>`` so the
+ inventory can hide them from the user.
+* ``keep_alive`` rides a warm ping (``POST /api/generate`` with an empty
+ prompt) once per process per (model, keep_alive).
+* ``temperature``, ``num_predict`` and ``think`` ride the ``/v1`` request
+ itself (:func:`to_v1_kwargs`); ``think`` maps to ``reasoning_effort``, which
+ Ollama 0.32.15 honours (checked live 2026-08-24: ``"none"`` answered in 3
+ completion tokens with no reasoning field, ``"high"`` streamed reasoning).
+
+Pure HTTP against the server root — identical on every OS and on a remote
+host (docs/os-parity.md P-32). Nothing here runs at import time (AP-26).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+from typing import Any
+
+import httpx
+
+from jarvis.core.config import OllamaModelOptions
+
+log = logging.getLogger(__name__)
+
+#: Option keys that are baked into the derived model's ``parameters``.
+#: ``num_predict``, ``temperature``, ``keep_alive`` and ``think`` are NOT
+#: here on purpose: they have a per-request channel, and baking them would
+#: force a new alias (and a stale-alias delete) for a knob that costs nothing
+#: to send.
+BAKEABLE_KEYS: tuple[str, ...] = (
+ "num_ctx",
+ "num_gpu",
+ "num_thread",
+ "top_p",
+ "top_k",
+ "min_p",
+ "repeat_penalty",
+ "seed",
+ "stop",
+)
+
+#: Marker every profile alias carries; the inventory filters on it.
+PROFILE_MARKER = "-jarvis-"
+_PROFILE_ALIAS_RE = re.compile(r"^(?P<prefix>.+)-jarvis-(?P<hash>[0-9a-f]{8})$")
+
+#: Context ladder :func:`suggest_options` picks from (tokens).
+_CONTEXT_LADDER: tuple[int, ...] = (4096, 8192, 16384, 32768, 65536, 131072)
+#: Rough KV-cache cost in GB per 1k tokens, scaled by the model's on-disk size
+#: (a 4 GB model ~0.12 GB/1k, an 18 GB model ~0.54 GB/1k). An estimate: the
+#: real figure depends on the architecture and the KV cache type, which is why
+#: every suggestion stays advisory.
+_KV_GB_PER_1K_PER_MODEL_GB = 0.03
+#: Fixed runtime overhead beside the weights (compute buffers, the runner).
+_OVERHEAD_GB = 1.0
+#: Share of system RAM a model may plan with when no accelerator is known —
+#: the same rule ``ollama_pull.fit_verdict`` applies.
+_RAM_SHARE = 0.6
+
+# Per-process memo so a turn never repeats an HTTP round-trip it has already
+# won: (root, alias) once ensured, (root, model, keep_alive) once warmed.
+_ensured: set[tuple[str, str]] = set()
+_warmed: set[tuple[str, str, str]] = set()
+
+# Creating a derived model or loading weights for the warm ping can take a
+# while on a CPU box; connecting to a dead server must still fail fast.
+_TIMEOUT = httpx.Timeout(connect=2.0, read=180.0, write=30.0, pool=30.0)
+
+
+def _fold(base: str) -> str:
+ """``qwen3.5:9b`` -> ``qwen3.5-9b``; ``hf.co/u/r:Q4`` -> ``hf.co-u-r-Q4``."""
+ return base.strip().replace(":", "-").replace("/", "-")
+
+
+def baked_parameters(opts: OllamaModelOptions) -> dict[str, Any]:
+ """The subset of ``opts`` that is baked into the alias, canonical order."""
+ params: dict[str, Any] = {}
+ for key in BAKEABLE_KEYS:
+ value = getattr(opts, key, None)
+ if value is not None:
+ params[key] = value
+ return params
+
+
+def has_bakeable(opts: OllamaModelOptions | None) -> bool:
+ """Whether ``opts`` needs a derived model at all."""
+ return bool(opts is not None and baked_parameters(opts))
+
+
+def profile_name(base: str, opts: OllamaModelOptions) -> str:
+ """``<folded base>-jarvis-<8-char sha256 of the canonical baked dict>``.
+
+ Stable for equal option sets regardless of key order or the presence of
+ non-bakeable knobs, so the same profile is never created twice.
+ """
+ canonical = json.dumps(baked_parameters(opts), sort_keys=True, separators=(",", ":"))
+ digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:8]
+ return f"{_fold(base)}{PROFILE_MARKER}{digest}"
+
+
+def is_profile_alias(name: str) -> bool:
+ """Whether ``name`` is one of our derived models (hidden from inventories)."""
+ return bool(_PROFILE_ALIAS_RE.match((name or "").strip().removesuffix(":latest")))
+
+
+def _stale_aliases(names: list[str], base: str, keep: str) -> list[str]:
+ """Earlier ``<base>-jarvis-*`` aliases that are not ``keep``."""
+ prefix = _fold(base)
+ stale: list[str] = []
+ for raw in names:
+ name = raw.strip().removesuffix(":latest")
+ match = _PROFILE_ALIAS_RE.match(name)
+ if match and match.group("prefix") == prefix and name != keep:
+ stale.append(name)
+ return stale
+
+
+async def _tag_names(client: httpx.AsyncClient, root: str) -> list[str]:
+ resp = await client.get(f"{root}/api/tags")
+ resp.raise_for_status()
+ return [str(m.get("name") or "") for m in resp.json().get("models") or []]
+
+
+async def ensure_profile(
+ root: str,
+ base: str,
+ opts: OllamaModelOptions,
+ *,
+ transport: httpx.AsyncBaseTransport | None = None,
+) -> str:
+ """Return the alias that carries ``opts`` for ``base``, creating it once.
+
+ Idempotent against ``/api/tags``: an alias that already exists is reused
+ without a create call; a base with NO bakeable knob returns ``base``
+ itself. When the hash changed, every earlier ``<base>-jarvis-*`` alias is
+ deleted (a failed delete is logged and does not fail the turn — the alias
+ is a ghost in the list, not a wrong answer). Raises ``RuntimeError`` with
+ an English sentence when the create itself fails; the caller then runs the
+ base model and says so.
+
+ ``transport`` exists for tests (``httpx.MockTransport``); production
+ passes ``None``.
+ """
+ if not has_bakeable(opts):
+ return base
+ alias = profile_name(base, opts)
+ key = (root, alias)
+ if key in _ensured:
+ return alias
+ async with httpx.AsyncClient(timeout=_TIMEOUT, transport=transport) as client:
+ try:
+ names = await _tag_names(client, root)
+ except Exception as exc:
+ raise RuntimeError(
+ f"Ollama at {root} did not answer /api/tags while preparing the "
+ f"profile for {base}: {type(exc).__name__}"
+ ) from exc
+ present = {n.removesuffix(":latest") for n in names}
+ if alias not in present:
+ payload = {
+ "model": alias,
+ "from": base,
+ "parameters": baked_parameters(opts),
+ "stream": False,
+ }
+ try:
+ resp = await client.post(f"{root}/api/create", json=payload)
+ resp.raise_for_status()
+ except Exception as exc:
+ raise RuntimeError(
+ f"could not create the Ollama profile {alias} from {base}: "
+ f"{type(exc).__name__}: {exc}"
+ ) from exc
+ log.info(
+ "ollama profile: created %s from %s with %s",
+ alias,
+ base,
+ json.dumps(baked_parameters(opts), sort_keys=True),
+ )
+ for stale in _stale_aliases(names, base, alias):
+ try:
+ resp = await client.request("DELETE", f"{root}/api/delete", json={"model": stale})
+ resp.raise_for_status()
+ log.info("ollama profile: deleted stale alias %s", stale)
+ except Exception as exc: # noqa: BLE001 — a leftover alias is cosmetic
+ log.warning(
+ "ollama profile: could not delete stale alias %s (%s: %s)",
+ stale,
+ type(exc).__name__,
+ exc,
+ )
+ _ensured.add(key)
+ return alias
+
+
+async def warm(
+ root: str,
+ model: str,
+ keep_alive: str | int,
+ *,
+ transport: httpx.AsyncBaseTransport | None = None,
+) -> bool:
+ """Load ``model`` with ``keep_alive`` via an empty ``/api/generate`` ping.
+
+ Once per process per (root, model, keep_alive); ``keep_alive`` is what the
+ user pinned (Go duration, seconds, ``-1`` forever, ``0`` unload now).
+ Returns ``False`` after logging when the server did not take it — the
+ turn still runs, only the residency promise is not kept. Never raises.
+ """
+ key = (root, model, str(keep_alive))
+ if key in _warmed:
+ return True
+ payload = {"model": model, "keep_alive": keep_alive, "stream": False}
+ try:
+ async with httpx.AsyncClient(timeout=_TIMEOUT, transport=transport) as client:
+ resp = await client.post(f"{root}/api/generate", json=payload)
+ resp.raise_for_status()
+ except Exception as exc: # noqa: BLE001 — the warm ping is best-effort
+ log.warning(
+ "ollama profile: warm ping for %s (keep_alive=%s) failed: %s: %s",
+ model,
+ keep_alive,
+ type(exc).__name__,
+ exc,
+ )
+ return False
+ _warmed.add(key)
+ log.info("ollama profile: %s warmed (keep_alive=%s)", model, keep_alive)
+ return True
+
+
+def reset_process_memo() -> None:
+ """Forget what was ensured/warmed (tests, or after a server restart)."""
+ _ensured.clear()
+ _warmed.clear()
+
+
+def to_v1_kwargs(opts: OllamaModelOptions | None) -> dict[str, Any]:
+ """The knobs the OpenAI-compatible request honours directly.
+
+ ``temperature`` as is; ``num_predict`` > 0 as ``max_tokens`` (``-1`` /
+ ``-2`` are Ollama's "unlimited" / "fill the context" sentinels, which
+ ``/v1`` has no spelling for, so they are left to the server default);
+ ``think`` as ``reasoning_effort`` — ``False`` -> ``"none"``, a level ->
+ that level, ``True`` -> nothing (the model's own default is to think).
+ """
+ if opts is None:
+ return {}
+ kwargs: dict[str, Any] = {}
+ if opts.temperature is not None:
+ kwargs["temperature"] = opts.temperature
+ if opts.num_predict is not None and opts.num_predict > 0:
+ kwargs["max_tokens"] = opts.num_predict
+ if opts.think is False:
+ kwargs["reasoning_effort"] = "none"
+ elif isinstance(opts.think, str):
+ kwargs["reasoning_effort"] = opts.think
+ return kwargs
+
+
+def suggest_options(
+ *,
+ size_gb: float,
+ native_context: int | None,
+ accelerator_gb: float,
+ source: str,
+ ram_gb: float | None,
+) -> tuple[OllamaModelOptions, list[str]]:
+ """Advisory ``(options, reasons)`` for a model of ``size_gb`` on this box.
+
+ ``accelerator_gb``/``source`` come from ``ollama_pull.accelerator_gb()``
+ (``(0.0, "none")`` = no accelerator this probe can vouch for) and
+ ``ram_gb`` from ``ollama_pull.total_memory_gb()`` (``None`` = unreadable).
+ One plain sentence per knob explains the pick. The estimate never
+ promises a fit: the KV-cache rule is a rough per-size average, so the UI
+ labels it "suggested" and Reset is one click.
+ """
+ reasons: list[str] = []
+ opts = OllamaModelOptions()
+
+ if accelerator_gb > 0:
+ budget = accelerator_gb
+ where = (
+ "unified memory shared with the graphics cores"
+ if source == "apple-unified"
+ else "graphics memory"
+ )
+ budget_sentence = f"Planned against the {accelerator_gb:.0f} GB of {where} on this machine."
+ elif ram_gb:
+ budget = ram_gb * _RAM_SHARE
+ budget_sentence = (
+ "No accelerator this probe can vouch for, so the RAM rule applies: "
+ f"about {_RAM_SHARE:.0%} of the {ram_gb:g} GB installed."
+ )
+ else:
+ budget = None
+ budget_sentence = (
+ "This machine's memory could not be read, so only the conservative "
+ "defaults are suggested."
+ )
+ reasons.append(budget_sentence)
+
+ # Context: the largest rung whose weights + KV cache fit the budget.
+ kv_per_1k = max(size_gb, 0.5) * _KV_GB_PER_1K_PER_MODEL_GB
+ ladder = [
+ rung for rung in _CONTEXT_LADDER if native_context is None or rung <= native_context
+ ] or [_CONTEXT_LADDER[0]]
+ chosen = ladder[0]
+ if budget is not None:
+ for rung in ladder:
+ needed = size_gb + _OVERHEAD_GB + kv_per_1k * (rung / 1000)
+ if needed <= budget:
+ chosen = rung
+ estimate = size_gb + _OVERHEAD_GB + kv_per_1k * (chosen / 1000)
+ reasons.append(
+ f"num_ctx {chosen:,}: weights plus a {chosen // 1024}k context need "
+ f"roughly {estimate:.1f} GB, the largest step that stays inside the budget"
+ + (f" (the model's native window is {native_context:,})." if native_context else ".")
+ )
+ else:
+ reasons.append(
+ f"num_ctx {chosen:,}: the smallest step, because the memory budget is unknown."
+ )
+ opts.num_ctx = chosen
+
+ # Placement.
+ if accelerator_gb > 0:
+ if size_gb + _OVERHEAD_GB <= accelerator_gb:
+ opts.num_gpu = -1
+ reasons.append(
+ "num_gpu -1: every layer fits on the accelerator, so it runs at full speed."
+ )
+ else:
+ reasons.append(
+ "num_gpu left to Ollama: the weights are bigger than the accelerator, "
+ "so it splits layers between the card and the CPU on its own."
+ )
+ else:
+ reasons.append(
+ "num_gpu left to Ollama: with no accelerator this probe can vouch for, "
+ "Ollama's own detection decides the placement."
+ )
+
+ # Residency.
+ if accelerator_gb > 0 and opts.num_gpu == -1:
+ opts.keep_alive = "30m"
+ reasons.append(
+ "keep_alive 30m: the model stays loaded on the card between turns, so "
+ "the next answer starts without a reload."
+ )
+ else:
+ opts.keep_alive = "10m"
+ reasons.append(
+ "keep_alive 10m: long enough for a conversation, short enough to give "
+ "the memory back when you stop talking."
+ )
+ return opts, reasons
diff --git a/jarvis/core/config.py b/jarvis/core/config.py
index dca5bfd660..a79d744946 100644
--- a/jarvis/core/config.py
+++ b/jarvis/core/config.py
@@ -14,6 +14,7 @@ from __future__ import annotations
import json
import logging
import os
+import re
import secrets
import sys
import threading
@@ -636,6 +637,192 @@ class TTSConfig(BaseModel):
service_account_path: str | None = None
+#: The closed vocabulary of per-model Ollama options a user may pin under
+#: ``[brain.providers.ollama.models."<tag>"]``. Source of truth for the
+#: config_writer's closed-key check and the TS mirror
+#: (``src/lib/ollamaModelOptions.ts``); a parity test pins the three together
+#: (AP-4). Everything here is an Ollama *request option* except the last two:
+#: ``keep_alive`` rides the warm ping and ``think`` rides the OpenAI-compat
+#: ``reasoning_effort`` field (verified live on Ollama 0.32.15).
+OLLAMA_MODEL_OPTION_KEYS: tuple[str, ...] = (
+ "num_ctx",
+ "num_gpu",
+ "num_thread",
+ "num_predict",
+ "temperature",
+ "top_p",
+ "top_k",
+ "min_p",
+ "repeat_penalty",
+ "seed",
+ "stop",
+ "keep_alive",
+ "think",
+)
+
+#: Graded thinking levels Ollama's ``think`` field accepts besides a bool.
+OLLAMA_THINK_LEVELS: tuple[str, ...] = ("low", "medium", "high", "max")
+
+#: Go duration as Ollama parses ``keep_alive`` ("5m", "2h", "1h30m", "-1").
+_GO_DURATION_RE = re.compile(r"^-?(?:\d+(?:\.\d+)?(?:ns|us|µs|ms|s|m|h))+$")
+
+
+def _clamped_optional_int(value: object, *, low: int, high: int) -> int | None:
+ """Clamp a hand-edited integer into range; ``None`` (or garbage) stays unset.
+
+ Same AP-16 contract as :func:`_clamped_polish_int`, minus the shipped
+ default: an unset per-model knob means "Ollama's own default", which is
+ already a working value, so there is nothing to fall back to.
+ """
+ if value is None or isinstance(value, bool):
+ return None
+ try:
+ number = int(float(value)) # type: ignore[arg-type]
+ except (TypeError, ValueError, OverflowError):
+ return None
+ return max(low, min(high, number))
+
+
+def _clamped_optional_float(value: object, *, low: float, high: float) -> float | None:
+ """The float twin of :func:`_clamped_optional_int`."""
+ if value is None or isinstance(value, bool):
+ return None
+ try:
+ number = float(value) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return None
+ if number != number or number in (float("inf"), float("-inf")): # NaN / ±inf
+ return None
+ return max(low, min(high, number))
+
+
+class OllamaModelOptions(BaseModel):
+ """Per-model knobs for one Ollama tag.
+
+ TOML path: ``[brain.providers.ollama.models."<tag>"]`` ·
+ Attribute path: ``JarvisConfig.brain.providers["ollama"].models["<tag>"]``
+
+ Every field is optional and ``None`` means "leave Ollama's default alone".
+ Values are CLAMPED, never rejected (AP-16): this table is reachable by hand
+ in ``jarvis.toml`` and a typo must not cost a boot. Unknown keys are kept
+ (``extra="allow"``) so a newer build's option survives a downgrade.
+
+ How each knob reaches the server (the OpenAI-compatible ``/v1`` endpoint
+ ignores request options): the bakeable ones (``num_ctx``, ``num_gpu``,
+ ``num_thread``, ``top_p``, ``top_k``, ``min_p``, ``repeat_penalty``,
+ ``seed``, ``stop``) are baked into a derived model via ``/api/create``
+ (``jarvis.brain.ollama_profiles``); ``temperature`` and ``num_predict`` ride
+ the ``/v1`` request as ``temperature`` / ``max_tokens``; ``think`` rides as
+ ``reasoning_effort``; ``keep_alive`` rides the warm ping.
+ """
+
+ model_config = ConfigDict(extra="allow")
+
+ num_ctx: int | None = None
+ num_gpu: int | None = None
+ num_thread: int | None = None
+ num_predict: int | None = None
+ temperature: float | None = None
+ top_p: float | None = None
+ top_k: int | None = None
+ min_p: float | None = None
+ repeat_penalty: float | None = None
+ seed: int | None = None
+ stop: list[str] | None = None
+ keep_alive: str | int | None = None
+ think: bool | str | None = None
+
+ @field_validator("num_ctx", mode="before")
+ @classmethod
+ def _clamp_num_ctx(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=512, high=1_048_576)
+
+ @field_validator("num_gpu", mode="before")
+ @classmethod
+ def _clamp_num_gpu(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=-1, high=999)
+
+ @field_validator("num_thread", mode="before")
+ @classmethod
+ def _clamp_num_thread(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=0, high=512)
+
+ @field_validator("num_predict", mode="before")
+ @classmethod
+ def _clamp_num_predict(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=-2, high=1_048_576)
+
+ @field_validator("temperature", mode="before")
+ @classmethod
+ def _clamp_temperature(cls, value: object) -> float | None:
+ return _clamped_optional_float(value, low=0.0, high=2.0)
+
+ @field_validator("top_p", "min_p", mode="before")
+ @classmethod
+ def _clamp_unit_interval(cls, value: object) -> float | None:
+ return _clamped_optional_float(value, low=0.0, high=1.0)
+
+ @field_validator("top_k", mode="before")
+ @classmethod
+ def _clamp_top_k(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=0, high=1000)
+
+ @field_validator("repeat_penalty", mode="before")
+ @classmethod
+ def _clamp_repeat_penalty(cls, value: object) -> float | None:
+ return _clamped_optional_float(value, low=0.0, high=3.0)
+
+ @field_validator("seed", mode="before")
+ @classmethod
+ def _clamp_seed(cls, value: object) -> int | None:
+ return _clamped_optional_int(value, low=0, high=2**31 - 1)
+
+ @field_validator("stop", mode="before")
+ @classmethod
+ def _coerce_stop(cls, value: object) -> list[str] | None:
+ """A single string becomes a one-element list; junk becomes unset."""
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return [value] if value else None
+ if isinstance(value, (list, tuple)):
+ cleaned = [str(item) for item in value if isinstance(item, str) and item]
+ return cleaned or None
+ return None
+
+ @field_validator("keep_alive", mode="before")
+ @classmethod
+ def _coerce_keep_alive(cls, value: object) -> str | int | None:
+ """Go duration string, integer seconds, or ``-1`` (forever); else unset."""
+ if value is None or isinstance(value, bool):
+ return None
+ if isinstance(value, (int, float)):
+ return max(-1, int(value))
+ if isinstance(value, str):
+ text = value.strip()
+ if not text:
+ return None
+ if text.lstrip("-").isdigit():
+ return max(-1, int(text))
+ return text if _GO_DURATION_RE.match(text) else None
+ return None
+
+ @field_validator("think", mode="before")
+ @classmethod
+ def _coerce_think(cls, value: object) -> bool | str | None:
+ """``bool`` or one of :data:`OLLAMA_THINK_LEVELS`; else unset."""
+ if value is None or isinstance(value, bool):
+ return value
+ if isinstance(value, str):
+ text = value.strip().lower()
+ if text in ("true", "on", "yes"):
+ return True
+ if text in ("false", "off", "no"):
+ return False
+ return text if text in OLLAMA_THINK_LEVELS else None
+ return None
+
+
class BrainProviderConfig(BaseModel):
model_config = ConfigDict(extra="allow", populate_by_name=True)
@@ -667,6 +854,28 @@ class BrainProviderConfig(BaseModel):
# ``> 0`` → fixed token cap for the thinking portion.
# Currently only evaluated by ``GeminiBrain``; other providers ignore it.
thinking_budget: int | None = None
+ # Per-model Ollama options keyed by model tag (``"qwen3.5:9b"``), read by
+ # the Ollama brain plugin on every turn. Only meaningful for the Ollama
+ # card; other providers ignore the table. TOML-only by design — not pinned
+ # in config-soll.json (see config_writer.set_ollama_model_options).
+ models: dict[str, OllamaModelOptions] = Field(default_factory=dict)
+ # Hugging Face GGUF browsing for the Ollama card. OFF by default so an
+ # install that wants no outbound Hugging Face traffic makes none; read via
+ # :func:`ollama_hf_enabled` by the local-models routes.
+ hf_enabled: bool = False
+
+ @field_validator("models", mode="before")
+ @classmethod
+ def _drop_non_table_models(cls, value: object) -> dict[str, Any]:
+ """A hand-edited ``models`` that is not a table of tables is ignored
+ rather than rejected (AP-16) — a typo here must not cost a boot."""
+ if not isinstance(value, dict):
+ return {}
+ return {
+ str(tag): opts
+ for tag, opts in value.items()
+ if isinstance(opts, (dict, OllamaModelOptions))
+ }
@property
def cu_model(self) -> str | None:
@@ -5309,6 +5518,19 @@ def _cached_endpoint_route(
return route
+def ollama_hf_enabled(config: JarvisConfig | None = None) -> bool:
+ """Whether Hugging Face GGUF browsing is switched on for the Ollama card.
+
+ The ONE reader of ``[brain.providers.ollama].hf_enabled`` (AP-31): the
+ local-models Hugging Face routes answer 404 with a sentence while this is
+ false, so an install that never turned it on makes no outbound Hugging
+ Face request. ``config`` exists for tests; production passes ``None``.
+ """
+ conf = config or load_config()
+ provider = conf.brain.providers.get("ollama")
+ return bool(provider is not None and provider.hf_enabled)
+
+
def resolve_provider_endpoint(
provider_id: str,
*,
diff --git a/jarvis/core/config_writer.py b/jarvis/core/config_writer.py
index 25efc91f82..b7230886fc 100644
--- a/jarvis/core/config_writer.py
+++ b/jarvis/core/config_writer.py
@@ -29,7 +29,13 @@ from pathlib import Path
import tomlkit
from tomlkit import TOMLDocument
-from .config import DEFAULT_CONFIG_FILE, PROJECT_ROOT, clear_config_cache
+from .config import (
+ DEFAULT_CONFIG_FILE,
+ OLLAMA_MODEL_OPTION_KEYS,
+ PROJECT_ROOT,
+ OllamaModelOptions,
+ clear_config_cache,
+)
log = logging.getLogger(__name__)
@@ -2187,6 +2193,165 @@ def set_provider_base_url(
)
+#: Closed list of per-provider boolean flags :func:`set_provider_flag` may
+#: write. Each entry is a real field on ``BrainProviderConfig`` with a reader;
+#: adding one here without a reader is the AP-31 shape.
+PROVIDER_FLAG_KEYS: tuple[str, ...] = ("hf_enabled",)
+
+
+def _provider_block(doc: TOMLDocument, provider: str) -> tomlkit.items.Table:
+ """``[brain.providers.<provider>]`` of ``doc``, created when absent.
+
+ ``providers`` is a super-table via the factory (``tomlkit.table(True)``) —
+ assigning ``is_super_table`` shadows a METHOD and a later ``dumps()``
+ crashes (see :func:`set_brain_provider_model`).
+ """
+ brain = doc.get("brain")
+ if brain is None:
+ brain = tomlkit.table()
+ doc["brain"] = brain
+ providers = brain.get("providers")
+ if providers is None:
+ providers = tomlkit.table(True)
+ brain["providers"] = providers
+ block = providers.get(provider)
+ if block is None:
+ block = tomlkit.table()
+ providers[provider] = block
+ return block
+
+
+def _read_doc(path: Path) -> tuple[TOMLDocument, bool]:
+ raw = path.read_text(encoding="utf-8")
+ had_bom = raw.startswith(_BOM)
+ if had_bom:
+ raw = raw[len(_BOM) :]
+ return tomlkit.parse(raw), had_bom
+
+
+def _write_doc(path: Path, doc: TOMLDocument, had_bom: bool) -> None:
+ out = tomlkit.dumps(doc)
+ if had_bom:
+ out = _BOM + out
+ _atomic_write(path, out)
+
+
+def set_ollama_model_options(
+ model: str,
+ options: dict[str, object],
+ *,
+ provider: str = "ollama",
+ path: Path = DEFAULT_CONFIG_FILE,
+) -> dict[str, object]:
+ """Persist the per-model option table ``[brain.providers.ollama.models."<tag>"]``.
+
+ REPLACE semantics: ``options`` is the whole new option set for ``model``;
+ a key absent from it is removed from the table, and an empty (or all-
+ ``None``) set removes the table like :func:`clear_ollama_model_options`.
+ Keys must come from the closed :data:`OLLAMA_MODEL_OPTION_KEYS` list —
+ anything else raises ``ValueError`` (pattern: ``ULTRAWIKI_SLOT_KEYS``).
+ Values pass through :class:`OllamaModelOptions`, so an out-of-range number
+ is clamped and a value of the wrong shape is dropped, never written — the
+ file holds only what the reader will accept. Returns the values written.
+
+ TOML-only by design, deliberately NOT pinned in ``config-soll.json``: the # i18n-allow
+ table is keyed by arbitrary model tags, and pinning it would bring back the
+ "flipped back" symptom (BUG-010 class) the first time a sync helper is
+ missed — the same rationale as ``[ultrawiki]``. The drift-guard therefore
+ never touches this table. Atomic write under the module lock (AP-7); the
+ tag is written as a quoted key (``"qwen3.5:9b"``) by tomlkit itself.
+ """
+ tag = (model or "").strip()
+ if not tag:
+ raise ValueError("model tag must not be empty")
+ unknown = sorted(set(options) - set(OLLAMA_MODEL_OPTION_KEYS))
+ if unknown:
+ raise ValueError(
+ f"unknown Ollama model option key(s) {', '.join(unknown)} "
+ f"(allowed: {', '.join(OLLAMA_MODEL_OPTION_KEYS)})"
+ )
+ clamped = OllamaModelOptions.model_validate(options).model_dump(exclude_none=True)
+ values: dict[str, object] = {k: clamped[k] for k in OLLAMA_MODEL_OPTION_KEYS if k in clamped}
+ if not values:
+ clear_ollama_model_options(tag, provider=provider, path=path)
+ return {}
+
+ path = _ensure_writable_config_path(path)
+ with _WRITE_LOCK:
+ doc, had_bom = _read_doc(path)
+ block = _provider_block(doc, provider)
+ models = block.get("models")
+ if models is None:
+ models = tomlkit.table(True)
+ block["models"] = models
+ table = tomlkit.table()
+ for key, value in values.items():
+ table[key] = value
+ models[tag] = table
+ _write_doc(path, doc, had_bom)
+ clear_config_cache()
+ return values
+
+
+def clear_ollama_model_options(
+ model: str,
+ *,
+ provider: str = "ollama",
+ path: Path = DEFAULT_CONFIG_FILE,
+) -> bool:
+ """Remove ``[brain.providers.ollama.models."<tag>"]``; ``True`` when it existed.
+
+ The "Reset" of the Tune sheet. A missing table is a no-op, not an error.
+ TOML-only for the same reason as :func:`set_ollama_model_options`.
+ """
+ tag = (model or "").strip()
+ if not tag:
+ raise ValueError("model tag must not be empty")
+ path = _ensure_writable_config_path(path)
+ with _WRITE_LOCK:
+ doc, had_bom = _read_doc(path)
+ models = (
+ (doc.get("brain") or {}).get("providers", {}).get(provider, {}).get("models")
+ )
+ if models is None or tag not in models:
+ return False
+ del models[tag]
+ _write_doc(path, doc, had_bom)
+ clear_config_cache()
+ return True
+
+
+def set_provider_flag(
+ provider: str, key: str, value: bool, *, path: Path = DEFAULT_CONFIG_FILE
+) -> None:
+ """Persist one boolean flag under ``[brain.providers.<provider>]``.
+
+ ``key`` must come from the closed :data:`PROVIDER_FLAG_KEYS` list. TOML-
+ only: these flags are not pinned in ``config-soll.json`` (same rationale # i18n-allow
+ as :func:`set_ollama_model_options`), so a plain atomic write is final.
+ """
+ if key not in PROVIDER_FLAG_KEYS:
+ raise ValueError(
+ f"unknown provider flag {key!r} (allowed: {', '.join(PROVIDER_FLAG_KEYS)})"
+ )
+ path = _ensure_writable_config_path(path)
+ with _WRITE_LOCK:
+ doc, had_bom = _read_doc(path)
+ block = _provider_block(doc, provider)
+ block[key] = bool(value)
+ _write_doc(path, doc, had_bom)
+ clear_config_cache()
+
+
+def set_ollama_hf_enabled(enabled: bool, *, path: Path = DEFAULT_CONFIG_FILE) -> None:
+ """Switch Hugging Face GGUF browsing on the Ollama card on or off.
+
+ Thin wrapper over :func:`set_provider_flag`; read by
+ :func:`jarvis.core.config.ollama_hf_enabled`.
+ """
+ set_provider_flag("ollama", "hf_enabled", bool(enabled), path=path)
+
+
def set_local_realtime_launch_command(
launch_command: str, *, path: Path = DEFAULT_CONFIG_FILE
) -> None:
diff --git a/jarvis/plugins/brain/ollama.py b/jarvis/plugins/brain/ollama.py
index ec6f9b4a7c..adb8e3347a 100644
--- a/jarvis/plugins/brain/ollama.py
+++ b/jarvis/plugins/brain/ollama.py
@@ -37,11 +37,13 @@ from __future__ import annotations
import logging
import os
from collections.abc import AsyncIterator
+from dataclasses import fields, replace
from typing import Any
import httpx
from jarvis.core import config as cfg
+from jarvis.core.config import OllamaModelOptions
from jarvis.core.protocols import BrainDelta, BrainRequest
from ._openai_base import stream_complete
@@ -199,9 +201,7 @@ class OllamaBrain:
)
return self._client
- async def _resolve_model(
- self, *, need_tools: bool = False, need_vision: bool = False
- ) -> str:
+ async def _resolve_model(self, *, need_tools: bool = False, need_vision: bool = False) -> str:
"""The configured model, else the smallest CAPABLE download.
Hard rules for the silent default (three live incidents 2026-07-25):
@@ -324,9 +324,7 @@ class OllamaBrain:
async def complete(self, req: BrainRequest) -> AsyncIterator[BrainDelta]:
client = self._ensure_client()
need_vision = _request_has_images(req)
- model = await self._resolve_model(
- need_tools=bool(req.tools), need_vision=need_vision
- )
+ model = await self._resolve_model(need_tools=bool(req.tools), need_vision=need_vision)
if need_vision and self._model and not await self._pinned_model_can_see(model):
# A pinned text-only model is the user's own choice, so we do not
# silently swap it — but we also refuse to answer about a picture
@@ -343,12 +341,74 @@ class OllamaBrain:
# The negotiated model DOES see — keep the instance flag honest for
# the next synchronous resolver question.
self.supports_vision = True
+ run_model, req = await self._apply_model_options(model, req)
# Invariant at this point: either the request carries no images, or the
# model just negotiated declares ``vision`` — so the streamer may encode
# them.
- async for delta in stream_complete(client, model, req, supports_vision=True):
+ async for delta in stream_complete(client, run_model, req, supports_vision=True):
yield delta
+ def _model_options(self, model: str) -> OllamaModelOptions | None:
+ """The user's per-model knobs for ``model`` from
+ ``[brain.providers.ollama.models."<tag>"]``, or ``None``.
+
+ Keyed by the RESOLVED tag, so a discovered model is tuned exactly like
+ a pinned one. A config that cannot be read is logged and treated as
+ "no options" — the turn must not die on a settings glitch (AP-30).
+ """
+ try:
+ provider = cfg.load_config().brain.providers.get("ollama")
+ except Exception as exc: # noqa: BLE001 — a config glitch must not kill the turn
+ log.warning("ollama: could not read per-model options: %s", exc)
+ return None
+ if provider is None:
+ return None
+ return provider.models.get(model) or provider.models.get(f"{model}:latest")
+
+ async def _apply_model_options(self, model: str, req: BrainRequest) -> tuple[str, BrainRequest]:
+ """Turn the per-model options into ``(model to stream, request)``.
+
+ Bakeable knobs go through a derived profile alias (``/api/create``);
+ ``keep_alive`` through the warm ping; ``temperature`` / ``num_predict``
+ / ``think`` override the request — but only where the caller left the
+ field at its default, so a deterministic tool step that asked for
+ ``temperature=0`` or ``reasoning_effort="none"`` keeps its own choice.
+ ``num_ctx`` also narrows ``context_window`` so the manager budgets
+ against the real window instead of the class floor.
+ """
+ opts = self._model_options(model)
+ if opts is None:
+ return model, req
+ from jarvis.brain.ollama_profiles import ( # noqa: PLC0415 — lazy (AP-26)
+ ensure_profile,
+ has_bakeable,
+ to_v1_kwargs,
+ warm,
+ )
+
+ root = self._resolve_root()
+ run_model = model
+ if has_bakeable(opts):
+ try:
+ run_model = await ensure_profile(root, model, opts)
+ except Exception as exc: # noqa: BLE001 — degrade to the base model, say so
+ log.warning(
+ "ollama: profile for %s unavailable, running the base model (%s)",
+ model,
+ exc,
+ )
+ run_model = model
+ if opts.num_ctx:
+ self.context_window = opts.num_ctx
+ if opts.keep_alive is not None:
+ await warm(root, run_model, opts.keep_alive)
+ overrides: dict[str, Any] = {}
+ defaults = {f.name: f.default for f in fields(BrainRequest)}
+ for key, value in to_v1_kwargs(opts).items():
+ if getattr(req, key, None) == defaults.get(key):
+ overrides[key] = value
+ return run_model, (replace(req, **overrides) if overrides else req)
+
def estimate_cost(self, req: BrainRequest) -> float:
# Local inference has no per-token bill.
return 0.0
diff --git a/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.test.ts b/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.test.ts
new file mode 100644
index 0000000000..9e8d9b53e9
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ OLLAMA_BAKEABLE_KEYS,
+ OLLAMA_MODEL_OPTION_KEYS,
+ compactOllamaModelOptions,
+ needsProfileAlias,
+} from "./ollamaModelOptions";
+
+describe("ollamaModelOptions", () => {
+ it("lists every key once and every bakeable key is a known key", () => {
+ expect(new Set(OLLAMA_MODEL_OPTION_KEYS).size).toBe(OLLAMA_MODEL_OPTION_KEYS.length);
+ for (const key of OLLAMA_BAKEABLE_KEYS) {
+ expect(OLLAMA_MODEL_OPTION_KEYS).toContain(key);
+ }
+ });
+
+ it("compacts unset knobs out of a PUT body", () => {
+ expect(
+ compactOllamaModelOptions({
+ num_ctx: 16384,
+ num_gpu: null,
+ temperature: undefined,
+ stop: [],
+ think: false,
+ }),
+ ).toEqual({ num_ctx: 16384, think: false });
+ });
+
+ it("knows when a set needs a profile alias", () => {
+ expect(needsProfileAlias({ temperature: 0.2, keep_alive: "30m", think: "low" })).toBe(false);
+ expect(needsProfileAlias({ num_ctx: 8192 })).toBe(true);
+ expect(needsProfileAlias({ stop: [] })).toBe(false);
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.ts b/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.ts
new file mode 100644
index 0000000000..c5e254be84
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/lib/ollamaModelOptions.ts
@@ -0,0 +1,83 @@
+/**
+ * Per-model Ollama options — the TypeScript half of the AP-4 contract.
+ *
+ * Mirrors `OLLAMA_MODEL_OPTION_KEYS` / `OllamaModelOptions` in
+ * `jarvis/core/config.py`; `tests/unit/core/test_ollama_model_options_parity.py`
+ * reads the key list below (one key per line, quoted) and the interface body,
+ * so keep both shapes as they are when adding a knob.
+ *
+ * `null`/absent means "leave Ollama's default alone". Ranges (clamped by the
+ * backend, never rejected): num_ctx 512..1048576, num_gpu -1..999, num_thread
+ * 0..512, num_predict -2..1048576, temperature 0..2, top_p/min_p 0..1, top_k
+ * 0..1000, repeat_penalty 0..3, seed 0..2^31-1, keep_alive Go duration ("30m")
+ * | seconds | -1 forever | 0 unload, think boolean | "low" | "medium" | "high"
+ * | "max".
+ */
+export const OLLAMA_MODEL_OPTION_KEYS = [
+ "num_ctx",
+ "num_gpu",
+ "num_thread",
+ "num_predict",
+ "temperature",
+ "top_p",
+ "top_k",
+ "min_p",
+ "repeat_penalty",
+ "seed",
+ "stop",
+ "keep_alive",
+ "think",
+] as const;
+
+export type OllamaModelOptionKey = (typeof OLLAMA_MODEL_OPTION_KEYS)[number];
+
+export type OllamaThinkLevel = "low" | "medium" | "high" | "max";
+
+export interface OllamaModelOptions {
+ num_ctx?: number | null;
+ num_gpu?: number | null;
+ num_thread?: number | null;
+ num_predict?: number | null;
+ temperature?: number | null;
+ top_p?: number | null;
+ top_k?: number | null;
+ min_p?: number | null;
+ repeat_penalty?: number | null;
+ seed?: number | null;
+ stop?: string[] | null;
+ keep_alive?: string | number | null;
+ think?: boolean | OllamaThinkLevel | null;
+}
+
+/** Keys that force a derived profile alias on the server (see ollama_profiles.py). */
+export const OLLAMA_BAKEABLE_KEYS: readonly OllamaModelOptionKey[] = [
+ "num_ctx",
+ "num_gpu",
+ "num_thread",
+ "top_p",
+ "top_k",
+ "min_p",
+ "repeat_penalty",
+ "seed",
+ "stop",
+];
+
+/** Drop every unset knob so a PUT body carries only what the user pinned. */
+export function compactOllamaModelOptions(options: OllamaModelOptions): OllamaModelOptions {
+ const out: OllamaModelOptions = {};
+ for (const key of OLLAMA_MODEL_OPTION_KEYS) {
+ const value = options[key];
+ if (value === undefined || value === null) continue;
+ if (Array.isArray(value) && value.length === 0) continue;
+ (out as Record<string, unknown>)[key] = value;
+ }
+ return out;
+}
+
+/** Whether the set needs a profile alias (a first use then takes a few seconds). */
+export function needsProfileAlias(options: OllamaModelOptions): boolean {
+ return OLLAMA_BAKEABLE_KEYS.some((key) => {
+ const value = options[key];
+ return value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0);
+ });
+}
diff --git a/tests/unit/brain/test_ollama_profiles.py b/tests/unit/brain/test_ollama_profiles.py
new file mode 100644
index 0000000000..5587205946
--- /dev/null
+++ b/tests/unit/brain/test_ollama_profiles.py
@@ -0,0 +1,262 @@
+"""Ollama profiles: a stable alias name, one create per option set, honest advice.
+
+The server is a fake behind ``httpx.MockTransport`` (a real httpx feature, no
+``unittest.mock``): it records every call so the tests can pin how many
+round-trips a turn costs, which is the whole point of the idempotency memo.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from jarvis.brain import ollama_profiles as profiles
+from jarvis.brain.ollama_profiles import (
+ BAKEABLE_KEYS,
+ ensure_profile,
+ is_profile_alias,
+ profile_name,
+ suggest_options,
+ to_v1_kwargs,
+ warm,
+)
+from jarvis.core.config import OllamaModelOptions
+
+ROOT = "http://fake:11434"
+
+
+class FakeOllamaServer:
+ """Just enough of ``/api/tags``, ``/api/create``, ``/api/delete``, ``/api/generate``."""
+
+ def __init__(self, models: list[str]) -> None:
+ self.models = list(models)
+ self.calls: list[tuple[str, str, dict[str, Any] | None]] = []
+ self.fail_create = False
+
+ def handler(self, request: httpx.Request) -> httpx.Response:
+ body = json.loads(request.content) if request.content else None
+ self.calls.append((request.method, request.url.path, body))
+ if request.url.path == "/api/tags":
+ return httpx.Response(200, json={"models": [{"name": n} for n in self.models]})
+ if request.url.path == "/api/create":
+ if self.fail_create:
+ return httpx.Response(500, json={"error": "boom"})
+ self.models.append(f"{body['model']}:latest")
+ return httpx.Response(200, json={"status": "success"})
+ if request.url.path == "/api/delete":
+ self.models = [m for m in self.models if m.removesuffix(":latest") != body["model"]]
+ return httpx.Response(200)
+ if request.url.path == "/api/generate":
+ return httpx.Response(200, json={"model": body["model"], "done": True})
+ return httpx.Response(404)
+
+ @property
+ def transport(self) -> httpx.MockTransport:
+ return httpx.MockTransport(self.handler)
+
+ def paths(self, method: str | None = None) -> list[str]:
+ return [p for m, p, _ in self.calls if method is None or m == method]
+
+
[email protected](autouse=True)
+def _fresh_memo() -> None:
+ profiles.reset_process_memo()
+
+
+# ── Naming ───────────────────────────────────────────────────────────────
+
+
+def test_profile_name_is_stable_and_folds_the_tag() -> None:
+ a = profile_name("qwen3.5:9b", OllamaModelOptions(num_ctx=16384, num_gpu=-1))
+ b = profile_name("qwen3.5:9b", OllamaModelOptions(num_gpu=-1, num_ctx=16384, keep_alive="2h"))
+ assert a == b # key order and non-bakeable knobs do not matter
+ assert a.startswith("qwen3.5-9b-jarvis-")
+ assert len(a.rsplit("-", 1)[1]) == 8
+ assert profile_name("hf.co/u/r:Q4", OllamaModelOptions(num_ctx=4096)).startswith(
+ "hf.co-u-r-Q4-jarvis-"
+ )
+
+
+def test_profile_name_changes_with_any_bakeable_knob() -> None:
+ base = OllamaModelOptions(num_ctx=8192)
+ names = {profile_name("m:1", base)}
+ for key in BAKEABLE_KEYS:
+ if key == "num_ctx":
+ continue
+ value: Any = ["x"] if key == "stop" else 1
+ names.add(profile_name("m:1", OllamaModelOptions(num_ctx=8192, **{key: value})))
+ assert len(names) == len(BAKEABLE_KEYS)
+
+
+def test_is_profile_alias() -> None:
+ assert is_profile_alias("qwen3.5-9b-jarvis-0123abcd")
+ assert is_profile_alias("qwen3.5-9b-jarvis-0123abcd:latest")
+ assert not is_profile_alias("qwen3.5:9b")
+ assert not is_profile_alias("qwen3.5:4b-voice-8k")
+
+
+# ── ensure_profile ───────────────────────────────────────────────────────
+
+
+async def test_ensure_profile_creates_once_and_is_idempotent() -> None:
+ server = FakeOllamaServer(["qwen3.5:9b"])
+ opts = OllamaModelOptions(num_ctx=16384, keep_alive="30m")
+ alias = await ensure_profile(ROOT, "qwen3.5:9b", opts, transport=server.transport)
+ assert alias == profile_name("qwen3.5:9b", opts)
+ create = [b for m, p, b in server.calls if p == "/api/create"]
+ assert create == [
+ {"model": alias, "from": "qwen3.5:9b", "parameters": {"num_ctx": 16384}, "stream": False}
+ ]
+ # Second call: the process memo answers, no HTTP at all.
+ before = len(server.calls)
+ assert await ensure_profile(ROOT, "qwen3.5:9b", opts, transport=server.transport) == alias
+ assert len(server.calls) == before
+ # A fresh process finds the alias on the server and skips the create.
+ profiles.reset_process_memo()
+ assert await ensure_profile(ROOT, "qwen3.5:9b", opts, transport=server.transport) == alias
+ assert server.paths("POST").count("/api/create") == 1
+
+
+async def test_ensure_profile_deletes_the_stale_alias_when_the_hash_changes() -> None:
+ old = profile_name("qwen3.5:9b", OllamaModelOptions(num_ctx=8192))
+ other = profile_name("gemma4:12b", OllamaModelOptions(num_ctx=8192))
+ server = FakeOllamaServer(["qwen3.5:9b", f"{old}:latest", f"{other}:latest"])
+ new_opts = OllamaModelOptions(num_ctx=16384)
+ alias = await ensure_profile(ROOT, "qwen3.5:9b", new_opts, transport=server.transport)
+ deleted = [b["model"] for m, p, b in server.calls if p == "/api/delete"]
+ assert deleted == [old] # the other base's alias is left alone
+ assert f"{alias}:latest" in server.models
+ assert f"{other}:latest" in server.models
+
+
+async def test_ensure_profile_without_bakeable_knobs_returns_the_base() -> None:
+ server = FakeOllamaServer(["qwen3.5:9b"])
+ opts = OllamaModelOptions(temperature=0.2, keep_alive="30m", think=False)
+ alias = await ensure_profile(ROOT, "qwen3.5:9b", opts, transport=server.transport)
+ assert alias == "qwen3.5:9b"
+ assert server.calls == []
+
+
+async def test_ensure_profile_raises_an_english_sentence_on_create_failure() -> None:
+ server = FakeOllamaServer(["qwen3.5:9b"])
+ server.fail_create = True
+ with pytest.raises(RuntimeError, match="could not create the Ollama profile"):
+ await ensure_profile(
+ ROOT, "qwen3.5:9b", OllamaModelOptions(num_ctx=4096), transport=server.transport
+ )
+
+
+# ── warm ─────────────────────────────────────────────────────────────────
+
+
+async def test_warm_pings_once_per_model_and_keep_alive() -> None:
+ server = FakeOllamaServer(["qwen3.5:9b"])
+ assert await warm(ROOT, "qwen3.5:9b", "30m", transport=server.transport) is True
+ assert await warm(ROOT, "qwen3.5:9b", "30m", transport=server.transport) is True
+ assert server.paths() == ["/api/generate"]
+ assert server.calls[0][2] == {"model": "qwen3.5:9b", "keep_alive": "30m", "stream": False}
+ assert await warm(ROOT, "qwen3.5:9b", -1, transport=server.transport) is True
+ assert server.paths().count("/api/generate") == 2
+
+
+async def test_warm_never_raises() -> None:
+ def _dead(request: httpx.Request) -> httpx.Response:
+ raise httpx.ConnectError("refused")
+
+ assert await warm(ROOT, "qwen3.5:9b", "5m", transport=httpx.MockTransport(_dead)) is False
+
+
+# ── to_v1_kwargs ─────────────────────────────────────────────────────────
+
+
+def test_to_v1_kwargs_maps_the_request_channel() -> None:
+ """``think`` -> ``reasoning_effort`` is what Ollama 0.32.15 honours on ``/v1``
+ (checked live 2026-08-24: "none" = 3 completion tokens and no reasoning
+ field; "high" = a reasoning field)."""
+ assert to_v1_kwargs(None) == {}
+ assert to_v1_kwargs(OllamaModelOptions(num_ctx=8192)) == {}
+ assert to_v1_kwargs(OllamaModelOptions(temperature=0.2, num_predict=512, think=False)) == {
+ "temperature": 0.2,
+ "max_tokens": 512,
+ "reasoning_effort": "none",
+ }
+ assert to_v1_kwargs(OllamaModelOptions(think="low")) == {"reasoning_effort": "low"}
+ assert to_v1_kwargs(OllamaModelOptions(think=True)) == {}
+ # Ollama's unlimited sentinels have no /v1 spelling and stay with the server.
+ assert to_v1_kwargs(OllamaModelOptions(num_predict=-1)) == {}
+
+
+# ── suggest_options — the five-case matrix ───────────────────────────────
+
+
+def test_no_accelerator_uses_the_ram_rule_honestly() -> None:
+ opts, reasons = suggest_options(
+ size_gb=4.0, native_context=262_144, accelerator_gb=0.0, source="none", ram_gb=16.0
+ )
+ assert opts.num_gpu is None # placement left to Ollama, never a promise
+ assert opts.num_ctx == 32768 # 5 + 0.12 * 32.8 = 8.9 <= 9.6 (60 % of 16); 64k = 12.9
+ assert opts.keep_alive == "10m"
+ assert any("RAM rule" in r for r in reasons)
+ assert any("no accelerator" in r.lower() for r in reasons)
+
+
+def test_eight_gb_card_keeps_a_seven_gb_model_partly_on_the_cpu() -> None:
+ opts, reasons = suggest_options(
+ size_gb=7.2, native_context=131_072, accelerator_gb=8.0, source="nvidia-smi", ram_gb=32.0
+ )
+ assert opts.num_gpu is None # 7.2 + 1 > 8: Ollama splits the layers itself
+ assert opts.num_ctx == 4096 # nothing bigger fits the 8 GB budget
+ assert opts.keep_alive == "10m"
+ assert any("splits layers" in r for r in reasons)
+
+
+def test_sixteen_gb_card_runs_a_mid_model_fully_on_the_gpu() -> None:
+ opts, reasons = suggest_options(
+ size_gb=7.2, native_context=131_072, accelerator_gb=16.0, source="nvidia-smi", ram_gb=32.0
+ )
+ assert opts.num_gpu == -1
+ assert opts.num_ctx == 32768 # 8.2 + 0.216 * 32.8 = 15.3 <= 16; 64k would be 22.4
+ assert opts.keep_alive == "30m"
+ assert any("graphics memory" in r for r in reasons)
+
+
+def test_apple_unified_memory_counts_as_the_accelerator() -> None:
+ opts, reasons = suggest_options(
+ size_gb=18.0,
+ native_context=262_144,
+ accelerator_gb=32.0,
+ source="apple-unified",
+ ram_gb=32.0,
+ )
+ assert opts.num_gpu == -1
+ assert opts.num_ctx == 16384 # 19 + 0.54 * 16.4 = 27.9 <= 32; 32k = 36.7
+ assert any("unified memory" in r for r in reasons)
+
+
+def test_headless_box_with_unreadable_memory_stays_conservative() -> None:
+ opts, reasons = suggest_options(
+ size_gb=4.0, native_context=None, accelerator_gb=0.0, source="none", ram_gb=None
+ )
+ assert opts.num_ctx == 4096
+ assert opts.num_gpu is None
+ assert opts.keep_alive == "10m"
+ assert any("could not be read" in r for r in reasons)
+
+
+def test_native_context_caps_the_ladder() -> None:
+ opts, _ = suggest_options(
+ size_gb=1.0, native_context=8192, accelerator_gb=24.0, source="nvidia-smi", ram_gb=64.0
+ )
+ assert opts.num_ctx == 8192
+
+
+def test_every_knob_has_one_sentence() -> None:
+ opts, reasons = suggest_options(
+ size_gb=3.4, native_context=262_144, accelerator_gb=16.0, source="nvidia-smi", ram_gb=32.0
+ )
+ set_keys = [k for k in ("num_ctx", "num_gpu", "keep_alive") if getattr(opts, k) is not None]
+ assert len(reasons) == 1 + 3 # the budget sentence + one per knob (placement always speaks)
+ assert set_keys == ["num_ctx", "num_gpu", "keep_alive"]
diff --git a/tests/unit/core/test_ollama_model_options.py b/tests/unit/core/test_ollama_model_options.py
new file mode 100644
index 0000000000..7ae9651f0a
--- /dev/null
+++ b/tests/unit/core/test_ollama_model_options.py
@@ -0,0 +1,225 @@
+"""Per-model Ollama options: values that never brick, a writer that round-trips.
+
+Two properties matter here. First, AP-16: the table
+``[brain.providers.ollama.models."<tag>"]`` is reachable by hand in
+``jarvis.toml``, so an out-of-range number is clamped and a value of the wrong
+shape is dropped — never a ``ValidationError`` that costs a boot. Second, the
+writer: it is the only sanctioned way to touch the table (AP-7), it refuses
+keys outside the closed list, and what it writes is exactly what
+``load_config`` reads back — BOM included.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from jarvis.core.config import (
+ OLLAMA_MODEL_OPTION_KEYS,
+ BrainProviderConfig,
+ JarvisConfig,
+ OllamaModelOptions,
+ load_config,
+ ollama_hf_enabled,
+)
+from jarvis.core.config_writer import (
+ PROVIDER_FLAG_KEYS,
+ clear_ollama_model_options,
+ set_ollama_hf_enabled,
+ set_ollama_model_options,
+ set_provider_flag,
+)
+
+#: ``field -> (below the floor, above the ceiling, clamped floor, clamped ceiling)``.
+NUMERIC_BOUNDS: dict[str, tuple[float, float, float, float]] = {
+ "num_ctx": (1, 99_999_999, 512, 1_048_576),
+ "num_gpu": (-9, 5000, -1, 999),
+ "num_thread": (-1, 9999, 0, 512),
+ "num_predict": (-99, 99_999_999, -2, 1_048_576),
+ "temperature": (-1.0, 9.0, 0.0, 2.0),
+ "top_p": (-0.5, 4.0, 0.0, 1.0),
+ "min_p": (-0.5, 4.0, 0.0, 1.0),
+ "top_k": (-3, 99_999, 0, 1000),
+ "repeat_penalty": (-1.0, 42.0, 0.0, 3.0),
+ "seed": (-7, 2**40, 0, 2**31 - 1),
+}
+
+
+# ----------------------------------------------------------------------
+# Clamping (AP-16)
+# ----------------------------------------------------------------------
+
+
+def test_everything_is_unset_by_default() -> None:
+ opts = OllamaModelOptions()
+ for key in OLLAMA_MODEL_OPTION_KEYS:
+ assert getattr(opts, key) is None, key
+
+
[email protected]("field", sorted(NUMERIC_BOUNDS))
+def test_numeric_knobs_are_clamped_never_rejected(field: str) -> None:
+ below, above, floor, ceiling = NUMERIC_BOUNDS[field]
+ assert getattr(OllamaModelOptions(**{field: below}), field) == floor
+ assert getattr(OllamaModelOptions(**{field: above}), field) == ceiling
+ # Garbage falls back to "unset" — Ollama's own default is a working value.
+ assert getattr(OllamaModelOptions(**{field: "nonsense"}), field) is None
+ assert getattr(OllamaModelOptions(**{field: float("nan")}), field) is None
+
+
+def test_keep_alive_accepts_go_durations_and_seconds() -> None:
+ assert OllamaModelOptions(keep_alive="30m").keep_alive == "30m"
+ assert OllamaModelOptions(keep_alive="1h30m").keep_alive == "1h30m"
+ assert OllamaModelOptions(keep_alive=600).keep_alive == 600
+ assert OllamaModelOptions(keep_alive="-1").keep_alive == -1
+ assert OllamaModelOptions(keep_alive=-99).keep_alive == -1
+ assert OllamaModelOptions(keep_alive="forever").keep_alive is None
+ assert OllamaModelOptions(keep_alive=True).keep_alive is None
+
+
+def test_think_accepts_bool_and_graded_levels() -> None:
+ assert OllamaModelOptions(think=True).think is True
+ assert OllamaModelOptions(think="off").think is False
+ assert OllamaModelOptions(think="HIGH").think == "high"
+ assert OllamaModelOptions(think="ultra").think is None
+ assert OllamaModelOptions(think=3).think is None
+
+
+def test_stop_takes_a_string_or_a_list() -> None:
+ assert OllamaModelOptions(stop="###").stop == ["###"]
+ assert OllamaModelOptions(stop=["</s>", "", 7]).stop == ["</s>"]
+ assert OllamaModelOptions(stop=[]).stop is None
+ assert OllamaModelOptions(stop=42).stop is None
+
+
+def test_unknown_keys_survive() -> None:
+ """A newer build's knob must not be dropped by an older one (extra="allow")."""
+ opts = OllamaModelOptions(num_batch=256)
+ assert opts.model_dump()["num_batch"] == 256
+
+
+def test_the_whole_block_at_once_never_raises() -> None:
+ """The AP-16 sweep: every key wrong at the same time still loads."""
+ junk = {key: object() for key in OLLAMA_MODEL_OPTION_KEYS}
+ opts = OllamaModelOptions(**junk)
+ for key in OLLAMA_MODEL_OPTION_KEYS:
+ assert getattr(opts, key) is None, key
+
+
+def test_provider_config_defaults_and_typo_tolerance() -> None:
+ provider = BrainProviderConfig()
+ assert provider.models == {}
+ assert provider.hf_enabled is False
+ # A ``models`` that is not a table of tables is ignored, not fatal.
+ assert BrainProviderConfig(models="oops").models == {}
+ assert BrainProviderConfig(models={"a:1": {"num_ctx": 9}, "b": 3}).models["a:1"].num_ctx == 512
+ assert "b" not in BrainProviderConfig(models={"a:1": {}, "b": 3}).models
+
+
+def test_a_config_written_before_the_feature_still_loads() -> None:
+ cfg = JarvisConfig(brain={"providers": {"ollama": {"model": "qwen3.5:9b"}}})
+ ollama = cfg.brain.providers["ollama"]
+ assert ollama.model == "qwen3.5:9b"
+ assert ollama.models == {}
+ assert ollama_hf_enabled(cfg) is False
+
+
+# ----------------------------------------------------------------------
+# Writer round trip (AP-7)
+# ----------------------------------------------------------------------
+
+
+def toml_file(tmp_path: Path) -> Path:
+ path = tmp_path / "jarvis.toml"
+ path.write_text(
+ '# keep me\n[brain]\nprimary = "ollama"\n\n'
+ '[brain.providers.ollama]\nmodel = "qwen3.5:9b"\n',
+ encoding="utf-8",
+ )
+ return path
+
+
+def test_writer_round_trips_through_load_config(toml_file: Path) -> None:
+ written = set_ollama_model_options(
+ "qwen3.5:9b",
+ {
+ "num_ctx": 16384,
+ "num_gpu": -1,
+ "keep_alive": "30m",
+ "think": False,
+ "stop": ["</s>"],
+ "temperature": 99, # clamped on the way in
+ "top_k": None, # unset -> not written
+ },
+ path=toml_file,
+ )
+ assert written == {
+ "num_ctx": 16384,
+ "num_gpu": -1,
+ "temperature": 2.0,
+ "stop": ["</s>"],
+ "keep_alive": "30m",
+ "think": False,
+ }
+ raw = toml_file.read_text(encoding="utf-8")
+ assert raw.startswith("# keep me") # BOM and comment preserved
+ assert '[brain.providers.ollama.models."qwen3.5:9b"]' in raw
+ assert 'model = "qwen3.5:9b"' in raw # sibling key untouched
+
+ opts = load_config(toml_file).brain.providers["ollama"].models["qwen3.5:9b"]
+ assert opts.num_ctx == 16384
+ assert opts.num_gpu == -1
+ assert opts.temperature == 2.0
+ assert opts.stop == ["</s>"]
+ assert opts.keep_alive == "30m"
+ assert opts.think is False
+ assert opts.top_k is None
+
+
+def test_writer_replaces_the_whole_set(toml_file: Path) -> None:
+ set_ollama_model_options("qwen3.5:9b", {"num_ctx": 8192, "top_k": 40}, path=toml_file)
+ set_ollama_model_options("qwen3.5:9b", {"num_ctx": 4096}, path=toml_file)
+ opts = load_config(toml_file).brain.providers["ollama"].models["qwen3.5:9b"]
+ assert opts.num_ctx == 4096
+ assert opts.top_k is None
+
+
+def test_two_tags_live_side_by_side(toml_file: Path) -> None:
+ set_ollama_model_options("qwen3.5:9b", {"num_ctx": 8192}, path=toml_file)
+ set_ollama_model_options("hf.co/user/repo:Q4_K_M", {"num_ctx": 4096}, path=toml_file)
+ models = load_config(toml_file).brain.providers["ollama"].models
+ assert models["qwen3.5:9b"].num_ctx == 8192
+ assert models["hf.co/user/repo:Q4_K_M"].num_ctx == 4096
+
+
+def test_writer_refuses_unknown_keys(toml_file: Path) -> None:
+ with pytest.raises(ValueError, match="num_batch"):
+ set_ollama_model_options("qwen3.5:9b", {"num_batch": 256}, path=toml_file)
+ with pytest.raises(ValueError):
+ set_ollama_model_options(" ", {"num_ctx": 4096}, path=toml_file)
+
+
+def test_clear_removes_the_table_and_reports_it(toml_file: Path) -> None:
+ set_ollama_model_options("qwen3.5:9b", {"num_ctx": 8192}, path=toml_file)
+ assert clear_ollama_model_options("qwen3.5:9b", path=toml_file) is True
+ assert clear_ollama_model_options("qwen3.5:9b", path=toml_file) is False
+ assert 'qwen3.5:9b"]' not in toml_file.read_text(encoding="utf-8")
+ assert load_config(toml_file).brain.providers["ollama"].models == {}
+
+
+def test_an_empty_set_clears_like_reset(toml_file: Path) -> None:
+ set_ollama_model_options("qwen3.5:9b", {"num_ctx": 8192}, path=toml_file)
+ assert set_ollama_model_options("qwen3.5:9b", {"num_ctx": None}, path=toml_file) == {}
+ assert load_config(toml_file).brain.providers["ollama"].models == {}
+
+
+def test_hf_flag_round_trips(toml_file: Path) -> None:
+ assert ollama_hf_enabled(load_config(toml_file)) is False
+ set_ollama_hf_enabled(True, path=toml_file)
+ assert ollama_hf_enabled(load_config(toml_file)) is True
+ set_provider_flag("ollama", "hf_enabled", False, path=toml_file)
+ assert ollama_hf_enabled(load_config(toml_file)) is False
+ assert "hf_enabled" in PROVIDER_FLAG_KEYS
+ with pytest.raises(ValueError):
+ set_provider_flag("ollama", "model", True, path=toml_file) # type: ignore[arg-type]
diff --git a/tests/unit/core/test_ollama_model_options_parity.py b/tests/unit/core/test_ollama_model_options_parity.py
new file mode 100644
index 0000000000..b8747a2f34
--- /dev/null
+++ b/tests/unit/core/test_ollama_model_options_parity.py
@@ -0,0 +1,84 @@
+"""Parity test for the layers that share the per-model Ollama option vocabulary
+(five-layer pattern, AP-4).
+
+1. ``jarvis/core/config.py::OLLAMA_MODEL_OPTION_KEYS`` — the tuple (source of truth)
+2. ``jarvis/core/config.py::OllamaModelOptions`` — the Pydantic fields
+3. ``jarvis/brain/ollama_profiles.py::BAKEABLE_KEYS`` — a subset the profile bakes
+4. ``jarvis/ui/web/frontend/src/lib/ollamaModelOptions.ts`` — the TS const array + interface
+5. the route body (``OllamaModelOptionsBody`` in ``local_models_routes.py``)
+ — checked when that module exists, so the chunk that adds the routes
+ inherits the gate without touching this file.
+
+A drift shows up here as one failing test instead of a knob the sheet offers
+and the writer refuses, or a key the writer accepts and the plugin never reads.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from pathlib import Path
+
+from jarvis.brain.ollama_profiles import BAKEABLE_KEYS
+from jarvis.core.config import OLLAMA_MODEL_OPTION_KEYS, OllamaModelOptions
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+TS_FILE = REPO_ROOT / "jarvis/ui/web/frontend/src/lib/ollamaModelOptions.ts"
+
+
+def _ts_const_array(name: str) -> list[str]:
+ src = TS_FILE.read_text(encoding="utf-8")
+ match = re.search(rf"export const {name}[^=]*= \[([^\]]*)\] as const;", src)
+ assert match, f"{name} const array missing from {TS_FILE.name}"
+ return re.findall(r'^\s*"([a-z_]+)",\s*$', match.group(1), flags=re.MULTILINE)
+
+
+def _ts_interface_keys(name: str) -> list[str]:
+ src = TS_FILE.read_text(encoding="utf-8")
+ match = re.search(rf"export interface {name} \{{([^}}]*)\}}", src)
+ assert match, f"interface {name} missing from {TS_FILE.name}"
+ return re.findall(r"^\s*([a-z_]+)\??:", match.group(1), flags=re.MULTILINE)
+
+
+def test_the_tuple_has_no_duplicates() -> None:
+ assert len(set(OLLAMA_MODEL_OPTION_KEYS)) == len(OLLAMA_MODEL_OPTION_KEYS)
+
+
+def test_pydantic_fields_match_the_tuple_in_order() -> None:
+ assert tuple(OllamaModelOptions.model_fields) == OLLAMA_MODEL_OPTION_KEYS
+
+
+def test_bakeable_keys_are_a_subset_of_the_tuple() -> None:
+ assert set(BAKEABLE_KEYS) <= set(OLLAMA_MODEL_OPTION_KEYS)
+ # The per-request channel is exactly the complement.
+ assert set(OLLAMA_MODEL_OPTION_KEYS) - set(BAKEABLE_KEYS) == {
+ "num_predict",
+ "temperature",
+ "keep_alive",
+ "think",
+ }
+
+
+def test_typescript_mirror_matches_the_tuple() -> None:
+ assert _ts_const_array("OLLAMA_MODEL_OPTION_KEYS") == list(OLLAMA_MODEL_OPTION_KEYS)
+ assert _ts_interface_keys("OllamaModelOptions") == list(OLLAMA_MODEL_OPTION_KEYS)
+
+
+def test_typescript_bakeable_keys_match() -> None:
+ src = TS_FILE.read_text(encoding="utf-8")
+ match = re.search(r"export const OLLAMA_BAKEABLE_KEYS[^=]*= \[([^\]]*)\];", src)
+ assert match, "OLLAMA_BAKEABLE_KEYS missing from the TS mirror"
+ keys = re.findall(r'"([a-z_]+)"', match.group(1))
+ assert keys == list(BAKEABLE_KEYS)
+
+
+def test_route_body_matches_when_the_routes_exist() -> None:
+ """Chunk 4 adds ``OllamaModelOptionsBody``; until then this is a no-op."""
+ try:
+ module = importlib.import_module("jarvis.ui.web.local_models_routes")
+ except ImportError:
+ return
+ body = getattr(module, "OllamaModelOptionsBody", None)
+ if body is None:
+ return
+ assert tuple(body.model_fields) == OLLAMA_MODEL_OPTION_KEYS
diff --git a/tests/unit/plugins/brain/test_ollama.py b/tests/unit/plugins/brain/test_ollama.py
index 976f94e94e..aebf09a308 100644
--- a/tests/unit/plugins/brain/test_ollama.py
+++ b/tests/unit/plugins/brain/test_ollama.py
@@ -363,9 +363,7 @@ async def test_image_turn_picks_a_vision_capable_download(monkeypatch, fake_tags
assert await brain._resolve_model(need_vision=True) == "qwen3-vl:8b"
-async def test_image_turn_without_a_vision_download_errors_honestly(
- monkeypatch, fake_tags
-) -> None:
+async def test_image_turn_without_a_vision_download_errors_honestly(monkeypatch, fake_tags) -> None:
_no_override(monkeypatch)
fake_tags.payload = {"models": [{"name": "qwen3.5:4b", "size": 1_000}]}
fake_tags.show_caps = {"qwen3.5:4b": ["completion", "tools"]}
@@ -378,9 +376,7 @@ async def test_image_turn_without_a_vision_download_errors_honestly(
assert brain.supports_vision is False
-async def test_unprobeable_model_is_never_used_for_an_image_turn(
- monkeypatch, fake_tags
-) -> None:
+async def test_unprobeable_model_is_never_used_for_an_image_turn(monkeypatch, fake_tags) -> None:
"""Vision is the ONE requirement that fails CLOSED: a model whose
``/api/show`` probe does not answer may back a chat turn, never an image
turn — a blind answer is indistinguishable from a sighted one."""
@@ -449,3 +445,137 @@ def test_tags_payload_shape_matches_documented_api() -> None:
payload = json.loads('{"models": [{"name": "qwen3.5:9b", "size": 1}]}')
names = [m.get("name") for m in payload["models"]]
assert names == ["qwen3.5:9b"]
+
+
+# ── Per-model options (profile alias, warm ping, request overrides) ──────
+class _FakeStreamer:
+ """Records what ``complete`` hands to the shared streamer."""
+
+ calls: list[tuple[str, Any]] = []
+
+ @classmethod
+ async def stream(cls, client: Any, model: str, req: Any, **kwargs: Any):
+ cls.calls.append((model, req))
+ from jarvis.core.protocols import BrainDelta
+
+ yield BrainDelta(content="ok", finish_reason="stop")
+
+
+class _FakeProfiles:
+ """Stands in for ``ollama_profiles.ensure_profile`` / ``warm``."""
+
+ ensured: list[tuple[str, str, Any]] = []
+ warmed: list[tuple[str, str, Any]] = []
+ fail: bool = False
+
+ @classmethod
+ async def ensure_profile(cls, root: str, base: str, opts: Any, **kwargs: Any) -> str:
+ if cls.fail:
+ raise RuntimeError("server said no")
+ cls.ensured.append((root, base, opts))
+ return f"{base.replace(':', '-')}-jarvis-deadbeef"
+
+ @classmethod
+ async def warm(cls, root: str, model: str, keep_alive: Any, **kwargs: Any) -> bool:
+ cls.warmed.append((root, model, keep_alive))
+ return True
+
+
+def wired(monkeypatch):
+ import openai
+
+ from jarvis.brain import ollama_profiles
+ from jarvis.plugins.brain import ollama as plugin
+
+ monkeypatch.setattr(openai, "AsyncOpenAI", _FakeOpenAI)
+ monkeypatch.setattr(plugin, "stream_complete", _FakeStreamer.stream)
+ monkeypatch.setattr(ollama_profiles, "ensure_profile", _FakeProfiles.ensure_profile)
+ monkeypatch.setattr(ollama_profiles, "warm", _FakeProfiles.warm)
+ monkeypatch.delenv("OLLAMA_HOST", raising=False)
+ _FakeStreamer.calls = []
+ _FakeProfiles.ensured = []
+ _FakeProfiles.warmed = []
+ _FakeProfiles.fail = False
+ return _FakeProfiles
+
+
+def _config_with_options(monkeypatch, models: dict[str, dict[str, Any]]) -> None:
+ conf = JarvisConfig(brain=BrainConfig(providers={"ollama": BrainProviderConfig(models=models)}))
+ monkeypatch.setattr(cfg, "load_config", lambda: conf)
+
+
+def _req(**kwargs: Any):
+ from jarvis.core.protocols import BrainMessage, BrainRequest
+
+ return BrainRequest(messages=(BrainMessage(role="user", content="hi"),), **kwargs)
+
+
+async def _run(brain: OllamaBrain, req: Any) -> None:
+ async for _ in brain.complete(req):
+ pass
+
+
+async def test_no_options_means_no_profile_no_warm_no_override(monkeypatch, wired) -> None:
+ _config_with_options(monkeypatch, {})
+ brain = OllamaBrain(model="qwen3.5:9b")
+ await _run(brain, _req())
+ model, req = _FakeStreamer.calls[0]
+ assert model == "qwen3.5:9b"
+ assert req.temperature == 0.7 and req.reasoning_effort is None
+ assert wired.ensured == [] and wired.warmed == []
+ assert brain.context_window == OllamaBrain.context_window
+
+
+async def test_bakeable_options_stream_through_the_profile_alias(monkeypatch, wired) -> None:
+ _config_with_options(
+ monkeypatch,
+ {"qwen3.5:9b": {"num_ctx": 16384, "num_gpu": -1, "keep_alive": "30m", "think": False}},
+ )
+ brain = OllamaBrain(model="qwen3.5:9b")
+ await _run(brain, _req())
+ model, req = _FakeStreamer.calls[0]
+ assert model == "qwen3.5-9b-jarvis-deadbeef"
+ assert [(b, o.num_ctx) for _, b, o in wired.ensured] == [("qwen3.5:9b", 16384)]
+ # The warm ping targets the alias (that is what the turn will load).
+ assert wired.warmed == [(DEFAULT_SERVER_ROOT, "qwen3.5-9b-jarvis-deadbeef", "30m")]
+ assert brain.context_window == 16384
+ assert req.reasoning_effort == "none"
+
+
+async def test_request_only_options_never_create_a_profile(monkeypatch, wired) -> None:
+ _config_with_options(monkeypatch, {"qwen3.5:9b": {"temperature": 0.1, "num_predict": 300}})
+ brain = OllamaBrain(model="qwen3.5:9b")
+ await _run(brain, _req())
+ model, req = _FakeStreamer.calls[0]
+ assert model == "qwen3.5:9b"
+ assert wired.ensured == [] and wired.warmed == []
+ assert req.temperature == 0.1 and req.max_tokens == 300
+
+
+async def test_a_caller_that_chose_its_own_knob_keeps_it(monkeypatch, wired) -> None:
+ """A deterministic tool step's temperature=0 / reasoning "none" wins over the profile."""
+ _config_with_options(monkeypatch, {"qwen3.5:9b": {"temperature": 0.9, "think": "high"}})
+ brain = OllamaBrain(model="qwen3.5:9b")
+ await _run(brain, _req(temperature=0.0, reasoning_effort="none"))
+ _, req = _FakeStreamer.calls[0]
+ assert req.temperature == 0.0 and req.reasoning_effort == "none"
+
+
+async def test_profile_failure_degrades_to_the_base_model(monkeypatch, wired) -> None:
+ _config_with_options(monkeypatch, {"qwen3.5:9b": {"num_ctx": 8192}})
+ wired.fail = True
+ brain = OllamaBrain(model="qwen3.5:9b")
+ await _run(brain, _req())
+ model, _ = _FakeStreamer.calls[0]
+ assert model == "qwen3.5:9b"
+ assert brain.context_window == 8192
+
+
+async def test_discovered_model_is_tuned_like_a_pinned_one(monkeypatch, wired, fake_tags) -> None:
+ _config_with_options(monkeypatch, {"qwen3.5:4b": {"num_ctx": 4096}})
+ fake_tags.payload = {"models": [{"name": "qwen3.5:4b", "size": 1_000}]}
+ brain = OllamaBrain()
+ await _run(brain, _req())
+ model, _ = _FakeStreamer.calls[0]
+ assert model == "qwen3.5-4b-jarvis-deadbeef"