Skip to content
Python

Per-model settings and a recommended-settings table

Devika Verma83131c0a6f27
diff --git a/coworker/engine.py b/coworker/engine.py
index bdd4b91c..c787a9ba 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -878,11 +878,19 @@ class TurnEngine:
# -- auto-compaction (OPE-27) ------------------------------------------------
def _compaction_config(self) -> dict[str, Any]:
+ from . import model_config
+
cfg = dict(self.compaction_settings() or {}) if self.compaction_settings else {}
+ # The user's per-model settings (model_config.py): a saved window stands in for
+ # a model the matrix does not list; a saved threshold overrides the machine's.
+ saved_window = model_config.context_size_for(self.model)
+ saved_pct = model_config.compaction_threshold_for(self.model)
+ if saved_pct:
+ cfg["threshold_pct"] = saved_pct
if not cfg.get("context_window"):
from .providers.matrix import model_context_windows
- cfg["context_window"] = model_context_windows().get(self.model)
+ cfg["context_window"] = model_context_windows().get(self.model) or saved_window
if not cfg["context_window"]:
# Ollama's window is the num_ctx we send (providers/ollama_context.py),
# not the 128k guess — compact before that window context-shifts.
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
index 10d8633a..e71f3c49 100644
--- a/coworker/headless/runner.py
+++ b/coworker/headless/runner.py
@@ -864,8 +864,9 @@ def _run(args: argparse.Namespace) -> int:
provider=provider,
audit_sink=audit_sink,
max_iterations=args.max_iterations,
- # An explicit ceiling rides model_settings into every provider call.
- model_settings=_model_settings(args),
+ # The model's saved settings (model_config.py) first; the run's own flags win.
+ # An isolated run reads nothing from the computer.
+ model_settings=_merged_model_settings(args, model),
# Bounded tool results; the full texts stay with the record under tool-output/.
tool_result_max_bytes=args.tool_result_max_bytes,
tool_result_spill_dir=out / "tool-output",
@@ -1224,6 +1225,14 @@ def _final_answer(engine: Any) -> str:
return ""
+def _merged_model_settings(args: argparse.Namespace, model: str) -> Optional[dict[str, Any]]:
+ from .. import model_config
+
+ saved = {} if getattr(args, "isolated", False) else model_config.model_settings_for(model)
+ merged = {**saved, **(_model_settings(args) or {})}
+ return merged or None
+
+
def _model_settings(args: argparse.Namespace) -> Optional[dict[str, Any]]:
"""Explicit per-run settings that ride model_settings into every provider call:
the output ceiling and the reasoning-effort level."""
diff --git a/coworker/model_config.py b/coworker/model_config.py
new file mode 100644
index 00000000..b94eae6d
--- /dev/null
+++ b/coworker/model_config.py
@@ -0,0 +1,214 @@
+"""Per-model settings the user saves: context size, longest reply, thinking, sampling,
+auto-compact, and which model new sessions start with.
+
+One file in the state folder, `model_config.json`, keyed by the full model id
+(`ollama:qwen3-coder:30b`, `gpt-5.6-sol`). The desktop app's dialog and the CLI write and
+read the same file, so a setting made in one holds in the other.
+
+What a saved value does:
+- `context_size`: the window a local model is loaded with (Ollama: `num_ctx`; it also sizes
+ compaction). For a cloud model it only sizes compaction, for models the matrix does not
+ list.
+- `max_output_tokens`: the longest reply, sent as `max_tokens`.
+- `thinking`: on or off for models with a thinking switch (Ollama's `think`).
+- `reasoning_effort`: the level for models with effort levels.
+- `temperature`, `top_p`: sampling.
+- `compaction_threshold_pct`: when to auto-compact, as a share of the window; overrides
+ the machine-wide setting for this model.
+- `default`: true on the model new sessions start with (the picker's default).
+
+Unset values mean "the recommendation, else the provider's default"
+(providers/recommended.py). `effective()` shows the merge; `model_settings_for()` turns it
+into the keyword arguments every provider call takes.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from .providers.recommended import recommendation_for
+from .secrets import state_dir
+
+FILE_NAME = "model_config.json"
+
+# The keys a record may hold, with how each value is checked.
+_INT_KEYS = ("context_size", "max_output_tokens")
+_FLOAT_KEYS = ("temperature", "top_p", "compaction_threshold_pct")
+_BOOL_KEYS = ("thinking", "default")
+_STR_KEYS = ("reasoning_effort",)
+KEYS = _INT_KEYS + _FLOAT_KEYS + _BOOL_KEYS + _STR_KEYS
+
+_lock = threading.Lock()
+
+
+def _path() -> Path:
+ return state_dir() / FILE_NAME
+
+
+def load() -> dict[str, dict[str, Any]]:
+ """Every saved record, keyed by model id. An unreadable file reads as empty."""
+ try:
+ raw = json.loads(_path().read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return {}
+ if not isinstance(raw, dict):
+ return {}
+ return {
+ str(k): {kk: vv for kk, vv in v.items() if kk in KEYS}
+ for k, v in raw.items()
+ if isinstance(v, dict)
+ }
+
+
+def _save(records: dict[str, dict[str, Any]]) -> None:
+ path = _path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ tmp = path.with_suffix(".json.tmp")
+ tmp.write_text(json.dumps(records, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ tmp.replace(path)
+
+
+def get(model: str) -> dict[str, Any]:
+ """The saved record for one model (empty when none)."""
+ return load().get(model, {})
+
+
+def clean(values: dict[str, Any]) -> tuple[dict[str, Any], Optional[str]]:
+ """Check and normalise a record. Returns (record, error). A key set to None
+ removes that setting."""
+ out: dict[str, Any] = {}
+ for key, value in (values or {}).items():
+ if key not in KEYS:
+ return {}, f"unknown setting {key!r}"
+ if value is None:
+ out[key] = None
+ continue
+ if key in _INT_KEYS:
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+ return {}, f"{key} must be a positive whole number"
+ out[key] = value
+ elif key in _FLOAT_KEYS:
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ return {}, f"{key} must be a number"
+ if key == "compaction_threshold_pct" and not 0.10 <= float(value) <= 0.95:
+ return {}, "compaction_threshold_pct must be between 0.10 and 0.95"
+ if key == "temperature" and not 0 <= float(value) <= 2:
+ return {}, "temperature must be between 0 and 2"
+ if key == "top_p" and not 0 < float(value) <= 1:
+ return {}, "top_p must be between 0 and 1"
+ out[key] = float(value)
+ elif key in _BOOL_KEYS:
+ if not isinstance(value, bool):
+ return {}, f"{key} must be true or false"
+ out[key] = value
+ else:
+ if not isinstance(value, str) or not value.strip():
+ return {}, f"{key} must be text"
+ out[key] = value.strip()
+ return out, None
+
+
+def set(model: str, values: dict[str, Any]) -> tuple[dict[str, Any], Optional[str]]: # noqa: A001
+ """Merge `values` into the model's record (None removes a key) and save. Setting
+ `default` true clears it on every other model. Returns (record, error)."""
+ record, error = clean(values)
+ if error:
+ return {}, error
+ with _lock:
+ records = load()
+ current = dict(records.get(model, {}))
+ for key, value in record.items():
+ if value is None:
+ current.pop(key, None)
+ else:
+ current[key] = value
+ if current.get("default"):
+ for other in records.values():
+ other.pop("default", None)
+ if current:
+ records[model] = current
+ else:
+ records.pop(model, None)
+ _save(records)
+ return current, None
+
+
+def remove(model: str) -> None:
+ with _lock:
+ records = load()
+ if model in records:
+ del records[model]
+ _save(records)
+
+
+def default_model() -> Optional[str]:
+ for model, record in load().items():
+ if record.get("default"):
+ return model
+ return None
+
+
+def effective(model: str) -> dict[str, Any]:
+ """The settings in force for a model: the saved record over the recommendation.
+ Each value says where it came from, for the dialog to show."""
+ saved = get(model)
+ rec = recommendation_for(model)
+ out: dict[str, Any] = {}
+
+ def put(key: str, recommended: Any) -> None:
+ if key in saved:
+ out[key] = {"value": saved[key], "from": "user"}
+ elif recommended is not None:
+ out[key] = {"value": recommended, "from": "recommended"}
+
+ put("context_size", None) # the machine rule fills this in for local models
+ put("max_output_tokens", rec.max_output_tokens if rec else None)
+ put("thinking", (rec.thinking_default if rec and rec.thinking_available else None))
+ put("reasoning_effort", None)
+ put("temperature", rec.sampling.get("temperature") if rec else None)
+ put("top_p", rec.sampling.get("top_p") if rec else None)
+ put("compaction_threshold_pct", None)
+ out["default"] = {"value": bool(saved.get("default")), "from": "user"}
+ if rec:
+ out["recommendation"] = rec.as_dict()
+ return out
+
+
+def model_settings_for(model: str) -> dict[str, Any]:
+ """Keyword arguments for the provider call: what the user saved, else what the
+ model's maker recommends. Context size and compaction are read elsewhere
+ (ollama_context.py, engine._compaction_config)."""
+ saved = get(model)
+ rec = recommendation_for(model)
+ settings: dict[str, Any] = {}
+ max_out = saved.get("max_output_tokens") or (rec.max_output_tokens if rec else None)
+ if max_out:
+ settings["max_tokens"] = int(max_out)
+ for key in ("temperature", "top_p"):
+ value = saved.get(key)
+ if value is None and rec:
+ value = rec.sampling.get(key)
+ if value is not None:
+ settings[key] = float(value)
+ if saved.get("reasoning_effort"):
+ settings["reasoning_effort"] = saved["reasoning_effort"]
+ thinking = saved.get("thinking")
+ if thinking is None and rec and rec.thinking_available:
+ thinking = rec.thinking_default
+ if thinking is not None and "reasoning_effort" not in settings:
+ # Ollama's native `think` rides the request body; other providers ignore it.
+ settings["extra_body"] = {"think": bool(thinking)}
+ return settings
+
+
+def context_size_for(model: str) -> Optional[int]:
+ value = get(model).get("context_size")
+ return int(value) if value else None
+
+
+def compaction_threshold_for(model: str) -> Optional[float]:
+ value = get(model).get("compaction_threshold_pct")
+ return float(value) if value else None
diff --git a/coworker/providers/ollama_context.py b/coworker/providers/ollama_context.py
index f1d7352c..a2090e04 100644
--- a/coworker/providers/ollama_context.py
+++ b/coworker/providers/ollama_context.py
@@ -223,6 +223,13 @@ class OllamaContextTransport(httpx.BaseTransport):
def _num_ctx_for(self, model: str, request: httpx.Request) -> int:
if self.num_ctx is not None:
return self.num_ctx
+ # A context size the user saved for this model wins over every rule.
+ from .. import model_config
+
+ chosen = model_config.context_size_for(f"ollama:{model}")
+ if chosen:
+ _resolved[model] = chosen
+ return chosen
cached = self._by_model.get(model)
if cached:
return cached
@@ -308,6 +315,10 @@ def to_native_chat(body: dict[str, Any], num_ctx: int) -> dict[str, Any]:
native["think"] = False
elif isinstance(effort, str) and effort:
native["think"] = effort
+ # The per-model thinking switch (model_config.py) rides the body as `think`, which
+ # the OpenAI SDK passes through from `extra_body`. An explicit switch wins.
+ if isinstance(body.get("think"), bool):
+ native["think"] = body["think"]
return native
diff --git a/coworker/providers/recommended.py b/coworker/providers/recommended.py
new file mode 100644
index 00000000..f5ead18b
--- /dev/null
+++ b/coworker/providers/recommended.py
@@ -0,0 +1,104 @@
+"""Recommended settings per model, from the model makers' own cards.
+
+The table is `recommended_models.json` next to this file, edited in git. Each entry names
+patterns a model id can match (without its provider prefix, so `ollama:nemotron-3.5-
+lightning:30b-mlx` and vLLM's `nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4` find
+the same entry), the window the model was trained for, the window its maker suggests for
+agent work, the longest reply, whether it can think and whether that is on by default,
+and the sampling values. Where a card gives separate values for reasoning and tool
+calling, the table carries the tool-calling ones: that is OpenWorker's work.
+
+The table is advice. The per-model settings a user saves (coworker/model_config.py) win,
+and the machine's memory still caps the context (providers/local_machine.py).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import functools
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+_TABLE = Path(__file__).with_name("recommended_models.json")
+
+
+@dataclass(frozen=True)
+class Recommendation:
+ name: str
+ context_max: Optional[int] = None
+ context_for_agents: Optional[int] = None
+ max_output_tokens: Optional[int] = None
+ thinking_available: bool = False
+ thinking_default: bool = False
+ sampling: dict[str, float] = field(default_factory=dict)
+ notes: str = ""
+ source: str = ""
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "name": self.name,
+ "context_max": self.context_max,
+ "context_for_agents": self.context_for_agents,
+ "max_output_tokens": self.max_output_tokens,
+ "thinking": {"available": self.thinking_available, "default": self.thinking_default},
+ "sampling": dict(self.sampling),
+ "notes": self.notes,
+ "source": self.source,
+ }
+
+
[email protected]_cache(maxsize=1)
+def _entries() -> tuple[tuple[tuple[str, ...], Recommendation], ...]:
+ try:
+ raw = json.loads(_TABLE.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return ()
+ out = []
+ for item in raw.get("models") or []:
+ if not isinstance(item, dict) or not item.get("match"):
+ continue
+ thinking = item.get("thinking") or {}
+ rec = Recommendation(
+ name=str(item.get("name") or ""),
+ context_max=_int(item.get("context_max")),
+ context_for_agents=_int(item.get("context_for_agents")),
+ max_output_tokens=_int(item.get("max_output_tokens")),
+ thinking_available=bool(thinking.get("available")),
+ thinking_default=bool(thinking.get("default")),
+ sampling={
+ k: float(v)
+ for k, v in (item.get("sampling") or {}).items()
+ if isinstance(v, (int, float))
+ },
+ notes=str(item.get("notes") or ""),
+ source=str(item.get("source") or ""),
+ )
+ out.append((tuple(str(m) for m in item["match"]), rec))
+ return tuple(out)
+
+
+def _int(value: Any) -> Optional[int]:
+ return int(value) if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def bare_name(model: str) -> str:
+ """`ollama:qwen3-coder:30b` → `qwen3-coder:30b`; a name with no known prefix is itself.
+ Model names carry colons of their own (version tags), so only a known provider
+ prefix is stripped."""
+ from .registry import provider_names
+
+ vendor, sep, rest = model.partition(":")
+ if sep and vendor in provider_names():
+ return rest
+ return model
+
+
+def recommendation_for(model: str) -> Optional[Recommendation]:
+ """The table's entry for a model id, or None. Case does not matter."""
+ name = bare_name(model).lower()
+ for patterns, rec in _entries():
+ if any(fnmatch.fnmatchcase(name, p.lower()) for p in patterns):
+ return rec
+ return None
diff --git a/coworker/providers/recommended_models.json b/coworker/providers/recommended_models.json
new file mode 100644
index 00000000..546ac98a
--- /dev/null
+++ b/coworker/providers/recommended_models.json
@@ -0,0 +1,71 @@
+{
+ "version": 1,
+ "about": "Recommended settings per model, from the model makers' own cards and guides. Read by coworker/providers/recommended.py; matched on the model name without its provider prefix. Edit in git. See docs/model-settings.md.",
+ "models": [
+ {
+ "match": ["nemotron-3.5-lightning*", "nvidia/NVIDIA-Nemotron-3.5-Lightning*", "*nemotron-3.5-lightning*"],
+ "name": "NVIDIA Nemotron 3.5 Lightning",
+ "context_max": 1048576,
+ "context_for_agents": 65536,
+ "max_output_tokens": 16000,
+ "thinking": {"available": true, "default": true},
+ "sampling": {"temperature": 1.0, "top_p": 0.95},
+ "notes": "One sampling setting for everything, tool calls included. NVIDIA's DGX Spark playbooks say 32K context minimum and 64K or more for agents.",
+ "source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4"
+ },
+ {
+ "match": ["nemotron-3-nano:30b*", "nemotron-3-nano", "nemotron-3-nano:latest", "nvidia/NVIDIA-Nemotron-3-Nano-30B*", "*nemotron-3-nano-30b*"],
+ "name": "NVIDIA Nemotron 3 Nano 30B",
+ "context_max": 1048576,
+ "context_for_agents": 65536,
+ "max_output_tokens": 10000,
+ "thinking": {"available": true, "default": true},
+ "sampling": {"temperature": 0.6, "top_p": 0.95},
+ "notes": "NVIDIA gives 1.0 / 1.0 for reasoning and 0.6 / 0.95 for tool calling; OpenWorker's work is tool calling.",
+ "source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"
+ },
+ {
+ "match": ["nemotron-3-nano:4b*", "nvidia/NVIDIA-Nemotron-3-Nano-4B*", "*nemotron-3-nano-4b*"],
+ "name": "NVIDIA Nemotron 3 Nano 4B",
+ "context_max": 262144,
+ "context_for_agents": 32768,
+ "max_output_tokens": 8192,
+ "thinking": {"available": true, "default": true},
+ "sampling": {"temperature": 0.6, "top_p": 0.95},
+ "notes": "NVIDIA gives 1.0 / 0.95 for reasoning and 0.6 / 0.95 for tool calling.",
+ "source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16"
+ },
+ {
+ "match": ["nemotron-3-super*", "nvidia/NVIDIA-Nemotron-3-Super*", "*nemotron-3-super*"],
+ "name": "NVIDIA Nemotron 3 Super",
+ "context_max": 1048576,
+ "context_for_agents": 65536,
+ "max_output_tokens": 32000,
+ "thinking": {"available": true, "default": true},
+ "sampling": {"temperature": 1.0, "top_p": 0.95},
+ "notes": "One setting across reasoning, tool calling and chat.",
+ "source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16"
+ },
+ {
+ "match": ["nemotron-3-ultra*", "nvidia/NVIDIA-Nemotron-3-Ultra*", "*nemotron-3-ultra*"],
+ "name": "NVIDIA Nemotron 3 Ultra",
+ "context_max": 1048576,
+ "context_for_agents": 65536,
+ "max_output_tokens": 32000,
+ "thinking": {"available": true, "default": true},
+ "sampling": {"temperature": 1.0, "top_p": 0.95},
+ "source": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4"
+ },
+ {
+ "match": ["qwen3-coder*", "Qwen/Qwen3-Coder*", "*qwen3-coder*"],
+ "name": "Qwen3 Coder",
+ "context_max": 262144,
+ "context_for_agents": 65536,
+ "max_output_tokens": 16384,
+ "thinking": {"available": false, "default": false},
+ "sampling": {"temperature": 0.7, "top_p": 0.8, "top_k": 20, "repeat_penalty": 1.05},
+ "notes": "The model card's suggested sampling for agent and coding use.",
+ "source": "https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct"
+ }
+ ]
+}
diff --git a/coworker/server/app.py b/coworker/server/app.py
index 095c47b5..7bbbb6f6 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -2365,6 +2365,20 @@ def create_app(manager: SessionManager) -> FastAPI:
def settings_models_remove(body: dict) -> dict[str, Any]:
return manager.remove_model((body or {}).get("model", ""))
+ # Per-model settings (model_config.py). Model ids carry colons and slashes, so the
+ # id travels in the body or the query, never the path.
+ @app.get("/v1/settings/model-config")
+ def settings_model_config_get(model: str = "") -> dict[str, Any]:
+ return manager.get_model_config(model)
+
+ @app.post("/v1/settings/model-config")
+ def settings_model_config_set(body: dict) -> dict[str, Any]:
+ return manager.set_model_config((body or {}).get("model", ""), (body or {}).get("values") or {})
+
+ @app.post("/v1/settings/model-config/remove")
+ def settings_model_config_remove(body: dict) -> dict[str, Any]:
+ return manager.remove_model_config((body or {}).get("model", ""))
+
@app.post("/v1/settings/onboarded")
def settings_set_onboarded(body: dict) -> dict[str, Any]:
return manager.set_onboarded(bool((body or {}).get("value", True)))
diff --git a/coworker/server/manager.py b/coworker/server/manager.py
index 9ee82e3c..9e49dfed 100644
--- a/coworker/server/manager.py
+++ b/coworker/server/manager.py
@@ -22,6 +22,7 @@ import uuid
from pathlib import Path
from typing import Any, Optional
+from .. import model_config as _model_config
from ..agent import build_engine
from ..agents import get_agent
from ..connections import (
@@ -893,6 +894,9 @@ class SessionManager:
model=model,
mode=mode,
provider=self.provider,
+ # The model's saved settings (or its maker's recommendation): longest reply,
+ # sampling, thinking. Read at build time.
+ model_settings=_model_config.model_settings_for(model),
# Memory off (§4.3) = stop LEARNING, not amnesia: saved facts still inject
# and stay usable, only the write tools go. Read at build time; running
# sessions finish under the mode they started with.
@@ -4690,6 +4694,8 @@ class SessionManager:
"secrets_path": str(self.secrets.path),
**self.pdf_settings(),
**self.compaction_settings_payload(),
+ # Per-model settings the user saved (model_config.py), keyed by model id.
+ "model_config": _model_config.load(),
}
def _surfaces(self) -> dict[str, bool]:
@@ -4937,8 +4943,38 @@ class SessionManager:
self.model = model
self._prefs["default_model"] = model
self._save_prefs()
+ _model_config.set(model, {"default": True})
return {"ok": True, **self.get_settings()}
+ # -- per-model settings (model_config.py) ---------------------------------------
+
+ def get_model_config(self, model: str = "") -> dict[str, Any]:
+ """One model's settings in force, with where each came from; or every saved
+ record when no model is named."""
+ if model:
+ return {"model": model, **_model_config.effective(model)}
+ return {"models": _model_config.load()}
+
+ def set_model_config(self, model: str, values: dict[str, Any]) -> dict[str, Any]:
+ """Save settings for one model. `default: true` also makes it the model new
+ sessions start with, like the Make default button."""
+ model = (model or "").strip()
+ if not model:
+ return {"ok": False, "error": "empty model"}
+ record, error = _model_config.set(model, values or {})
+ if error:
+ return {"ok": False, "error": error}
+ if record.get("default") and self.model != model:
+ self.model = model
+ self._prefs["default_model"] = model
+ self._save_prefs()
+ self.provider.invalidate() if hasattr(self.provider, "invalidate") else None
+ return {"ok": True, "model": model, **_model_config.effective(model)}
+
+ def remove_model_config(self, model: str) -> dict[str, Any]:
+ _model_config.remove((model or "").strip())
+ return {"ok": True}
+
def set_onboarded(self, value: bool = True) -> dict[str, Any]:
"""Record that first-run setup is complete (so it isn't shown again)."""
self._prefs["onboarded"] = bool(value)
@@ -6125,11 +6161,13 @@ class SessionManager:
def _build_task_engine(self, task, *, session_id: str) -> TurnEngine:
ag = get_agent(task.agent)
Path(task.workspace).mkdir(parents=True, exist_ok=True)
+ task_model = self.resolve_persona_model(task.agent, task.model)
engine = build_engine(
agent=ag,
workspace=task.workspace,
- model=self.resolve_persona_model(task.agent, task.model),
+ model=task_model,
mode=Mode.INTERACTIVE,
+ model_settings=_model_config.model_settings_for(task_model),
approver=self._scheduled_approver(task, session_id),
provider=self.provider,
memory_store=self.memory_store,
diff --git a/docs/model-settings.md b/docs/model-settings.md
new file mode 100644
index 00000000..d6e4e7ab
--- /dev/null
+++ b/docs/model-settings.md
@@ -0,0 +1,73 @@
+# Model settings
+
+Each model can carry its own settings: how much context it is loaded with, the longest
+reply, whether it thinks, its sampling, and when the conversation is compacted. The
+desktop app sets them in the model's settings dialog; the CLI reads the same file.
+
+## Where they live
+
+`model_config.json` in OpenWorker's state folder, keyed by the model id:
+
+```json
+{
+ "ollama:nemotron-3.5-lightning:30b": {
+ "context_size": 65536,
+ "max_output_tokens": 16000,
+ "thinking": true,
+ "temperature": 1.0,
+ "top_p": 0.95,
+ "compaction_threshold_pct": 0.8,
+ "default": true
+ }
+}
+```
+
+| Setting | What it does |
+|---|---|
+| `context_size` | The window a local model is loaded with. For Ollama it is sent as `num_ctx` on every request. It also sizes auto-compaction. For a cloud model the matrix does not list, it only sizes compaction. |
+| `max_output_tokens` | The longest reply, sent as `max_tokens`. |
+| `thinking` | On or off, for models with a thinking switch (Ollama's `think`). |
+| `reasoning_effort` | The level for models with effort levels (`low`, `medium`, `high`). |
+| `temperature`, `top_p` | Sampling. |
+| `compaction_threshold_pct` | When to compact, as a share of the window (0.10 to 0.95). Overrides the machine-wide setting for this model. |
+| `default` | True on the model new sessions start with. Only one model has it. |
+
+A setting that is not saved falls back to the model's recommendation, then to the
+provider's own default.
+
+## Recommended settings
+
+`coworker/providers/recommended_models.json` holds recommended settings per model, taken
+from the model makers' own cards and guides, with a source link on every entry. A model is
+matched on its name without the provider prefix, so an Ollama tag and a vLLM model name
+find the same entry. Where a card gives separate values for reasoning and tool calling,
+the table carries the tool-calling ones.
+
+To add or change an entry, edit the file in git. Each entry has:
+
+- `match`: name patterns (`*` wildcards), checked in order.
+- `context_max`: the window the model was trained for.
+- `context_for_agents`: the window the maker suggests for agent work.
+- `max_output_tokens`, `thinking` (`available`, `default`), `sampling`.
+- `source`: where the values come from.
+
+## Context size on a local model
+
+Without a saved `context_size`, OpenWorker chooses the window from the memory models load
+into on this machine (an NVIDIA card's memory, else system memory): 16K under 16 GB, 32K
+under 32 GB, 64K under 64 GB, 128K above, never more than the model's own limit. A
+`num_ctx` pinned in an Ollama Modelfile is kept. `OPENWORKER_OLLAMA_NUM_CTX` caps any of
+these.
+
+## In a run
+
+`openworker run` reads the saved settings for its model unless `--isolated` is given. A
+flag on the run (`--max-output-tokens`, `--reasoning-effort`) wins over the saved value.
+
+## The API
+
+- `GET /v1/settings/model-config?model=<id>`: the settings in force, each with where it
+ came from (`user` or `recommended`), plus the recommendation.
+- `POST /v1/settings/model-config` with `{"model": "<id>", "values": {...}}`: save. A
+ value of `null` removes that setting.
+- `POST /v1/settings/model-config/remove` with `{"model": "<id>"}`.
diff --git a/tests/test_headless_run.py b/tests/test_headless_run.py
index 60c3f3d1..241ddb3d 100644
--- a/tests/test_headless_run.py
+++ b/tests/test_headless_run.py
@@ -255,6 +255,31 @@ def test_the_first_waits_are_short_and_the_waits_grow(monkeypatch: pytest.Monkey
assert 15 * 60 <= sum(delays) <= 20 * 60 # an outage of minutes is still waited out
+def test_a_models_saved_settings_reach_the_run_unless_isolated(tmp_path: Path) -> None:
+ import tempfile
+
+ state = Path(tempfile.mkdtemp(prefix="ow-run-machine-"))
+ (state / "model_config.json").write_text(
+ json.dumps({"anthropic:claude-sonnet-5": {"max_output_tokens": 777}}), encoding="utf-8"
+ )
+ env = {"COWORKER_STATE_DIR": str(state)}
+ # This computer's settings for the model, keyed by OpenWorker's `provider:model`
+ # form (the run accepts `provider/model` too): the reply ceiling the run sends.
+ proc, _ws, out = _run(tmp_path, "bypass-approvals", [{"text": "Done."}], env=env, isolated=False)
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+ calls = [json.loads(line) for line in (out / "model_calls.jsonl").read_text().splitlines()]
+ assert calls[-1]["max_output_tokens"] == 777
+ # A flag on the run wins over the saved setting.
+ proc, _ws, out = _run(tmp_path, "bypass-approvals", [{"text": "Done."}], env=env, isolated=False,
+ extra=["--max-output-tokens", "555"])
+ calls = [json.loads(line) for line in (out / "model_calls.jsonl").read_text().splitlines()]
+ assert calls[-1]["max_output_tokens"] == 555
+ # An isolated run reads nothing from the computer.
+ proc, _ws, out = _run(tmp_path, "bypass-approvals", [{"text": "Done."}], env=env, isolated=True)
+ calls = [json.loads(line) for line in (out / "model_calls.jsonl").read_text().splitlines()]
+ assert calls[-1]["max_output_tokens"] != 777
+
+
def test_a_finished_answer_with_a_stray_tool_tag_is_kept(tmp_path: Path) -> None:
# Seen live: the answer was complete, ended in `<tool_call>`, and was retried as a
# failed call; the second answer was worse. The tag goes, the answer stays.
diff --git a/tests/test_model_config.py b/tests/test_model_config.py
new file mode 100644
index 00000000..ec061cdf
--- /dev/null
+++ b/tests/test_model_config.py
@@ -0,0 +1,162 @@
+"""Per-model settings (coworker/model_config.py) and the recommended-settings table
+(coworker/providers/recommended.py): what the user saves wins, the maker's
+recommendation fills the rest, and both reach the provider call, the Ollama transport,
+and compaction."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+from coworker import model_config
+from coworker.engine import TurnEngine
+from coworker.providers import local_machine
+from coworker.providers.ollama_context import OllamaContextTransport, to_native_chat
+from coworker.providers.recommended import recommendation_for
+
+
[email protected](autouse=True)
+def _state(tmp_path, monkeypatch):
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path / "state"))
+
+
+# -- the table ----------------------------------------------------------------------------
+
+
+def test_the_table_matches_a_model_under_any_provider_prefix():
+ for model in (
+ "ollama:nemotron-3.5-lightning:30b",
+ "ollama:nemotron-3.5-lightning:30b-mlx",
+ "vllm:nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4",
+ ):
+ rec = recommendation_for(model)
+ assert rec is not None and rec.name == "NVIDIA Nemotron 3.5 Lightning"
+ assert rec.sampling == {"temperature": 1.0, "top_p": 0.95}
+ assert rec.thinking_available and rec.thinking_default
+ assert rec.max_output_tokens == 16000 and rec.context_for_agents == 65536
+ assert rec.source.startswith("https://huggingface.co/nvidia/")
+ assert recommendation_for("ollama:llama3.1:8b") is None
+ assert recommendation_for("gpt-5.6-sol") is None
+
+
+def test_every_table_entry_is_complete_and_sourced():
+ from coworker.providers.recommended import _TABLE
+
+ raw = json.loads(_TABLE.read_text())
+ assert raw["version"] == 1
+ for item in raw["models"]:
+ assert item["match"] and item["name"] and item["source"].startswith("https://"), item
+ assert isinstance(item["context_max"], int) and item["context_max"] > 0
+ assert set(item["thinking"]) == {"available", "default"}
+
+
+# -- the store ------------------------------------------------------------------------------
+
+
+def test_saved_settings_are_checked_merged_and_kept(tmp_path):
+ record, error = model_config.set("ollama:qwen3-coder:30b", {"context_size": 65536, "thinking": False})
+ assert error is None and record == {"context_size": 65536, "thinking": False}
+ record, error = model_config.set("ollama:qwen3-coder:30b", {"temperature": 0.2, "context_size": None})
+ assert error is None and record == {"thinking": False, "temperature": 0.2}
+ assert (tmp_path / "state" / "model_config.json").is_file()
+ assert model_config.get("ollama:qwen3-coder:30b") == {"thinking": False, "temperature": 0.2}
+ for bad in ({"context_size": 0}, {"context_size": "big"}, {"temperature": 3}, {"top_p": 0},
+ {"compaction_threshold_pct": 0.99}, {"thinking": "yes"}, {"nope": 1}):
+ _, error = model_config.set("m", bad)
+ assert error, bad
+ model_config.remove("ollama:qwen3-coder:30b")
+ assert model_config.get("ollama:qwen3-coder:30b") == {}
+
+
+def test_only_one_model_is_the_default():
+ model_config.set("a", {"default": True})
+ model_config.set("b", {"default": True})
+ assert model_config.default_model() == "b"
+ assert model_config.get("a") == {}
+
+
+def test_effective_settings_say_where_each_value_came_from():
+ model_config.set("ollama:nemotron-3.5-lightning:30b", {"max_output_tokens": 8000})
+ eff = model_config.effective("ollama:nemotron-3.5-lightning:30b")
+ assert eff["max_output_tokens"] == {"value": 8000, "from": "user"}
+ assert eff["temperature"] == {"value": 1.0, "from": "recommended"}
+ assert eff["thinking"] == {"value": True, "from": "recommended"}
+ assert eff["recommendation"]["name"] == "NVIDIA Nemotron 3.5 Lightning"
+ assert "temperature" not in model_config.effective("ollama:llama3.1:8b")
+
+
+# -- reaching the provider call -------------------------------------------------------------
+
+
+def test_provider_settings_come_from_the_user_then_the_recommendation():
+ assert model_config.model_settings_for("ollama:llama3.1:8b") == {}
+ assert model_config.model_settings_for("ollama:nemotron-3.5-lightning:30b") == {
+ "max_tokens": 16000, "temperature": 1.0, "top_p": 0.95, "extra_body": {"think": True},
+ }
+ model_config.set("ollama:nemotron-3.5-lightning:30b", {"thinking": False, "temperature": 0.3})
+ assert model_config.model_settings_for("ollama:nemotron-3.5-lightning:30b") == {
+ "max_tokens": 16000, "temperature": 0.3, "top_p": 0.95, "extra_body": {"think": False},
+ }
+ # An effort level for a model with levels; no thinking switch rides along.
+ model_config.set("gpt-5.6-sol", {"reasoning_effort": "high", "max_output_tokens": 32000})
+ assert model_config.model_settings_for("gpt-5.6-sol") == {"max_tokens": 32000, "reasoning_effort": "high"}
+
+
+def test_the_thinking_switch_reaches_ollamas_native_call():
+ body = {"model": "m", "messages": [], "think": False, "temperature": 0.3, "top_p": 0.9, "max_tokens": 500}
+ native = to_native_chat(body, 32768)
+ assert native["think"] is False
+ assert native["options"] == {"num_ctx": 32768, "num_predict": 500, "temperature": 0.3, "top_p": 0.9}
+
+
+class _Inner(httpx.BaseTransport):
+ def __init__(self):
+ self.requests = []
+
+ def handle_request(self, request):
+ self.requests.append(request)
+ if request.url.path.endswith("/api/show"):
+ return httpx.Response(200, json={"model_info": {"general.architecture": "qwen3moe", "qwen3moe.context_length": 262144}})
+ return httpx.Response(200, json={"model": "qwen3-coder:30b", "message": {"role": "assistant", "content": "ok"}, "done": True, "done_reason": "stop"})
+
+
+def test_a_saved_context_size_wins_over_the_machine_rule():
+ inner = _Inner()
+ transport = OllamaContextTransport(inner=inner, memory_bytes=8 * local_machine.GB)
+ req = lambda: httpx.Request("POST", "http://127.0.0.1:11434/v1/chat/completions", json={"model": "qwen3-coder:30b", "messages": []})
+ transport.handle_request(req())
+ sent = [json.loads(r.content) for r in inner.requests if r.url.path == "/api/chat"]
+ assert sent[0]["options"]["num_ctx"] == 16384 # the 8 GB tier
+ model_config.set("ollama:qwen3-coder:30b", {"context_size": 65536})
+ transport.handle_request(req())
+ sent = [json.loads(r.content) for r in inner.requests if r.url.path == "/api/chat"]
+ assert sent[1]["options"]["num_ctx"] == 65536
+
+
+def test_compaction_uses_the_saved_threshold_and_window():
+ engine = SimpleNamespace(model="acme:unlisted-model", compaction_settings=None, _warned_context_fallback=False)
+ before = TurnEngine._compaction_config(engine)
+ assert before["context_window"] is None
+ model_config.set("acme:unlisted-model", {"context_size": 100_000, "compaction_threshold_pct": 0.6})
+ cfg = TurnEngine._compaction_config(engine)
+ assert cfg["context_window"] == 100_000 and cfg["threshold_pct"] == 0.6
+
+
+# -- the server's view ----------------------------------------------------------------------
+
+
+def test_manager_saves_reads_and_removes_model_settings(tmp_path, monkeypatch):
+ from coworker.server.manager import SessionManager
+
+ mgr = SessionManager(data_dir=tmp_path)
+ out = mgr.set_model_config("ollama:qwen3-coder:30b", {"context_size": 32768, "default": True})
+ assert out["ok"] and out["context_size"] == {"value": 32768, "from": "user"}
+ assert mgr.model == "ollama:qwen3-coder:30b" # default: true is the Make default button
+ assert mgr.get_settings()["model_config"]["ollama:qwen3-coder:30b"]["context_size"] == 32768
+ assert mgr.get_model_config("ollama:qwen3-coder:30b")["model"] == "ollama:qwen3-coder:30b"
+ assert mgr.set_model_config("x", {"temperature": 9}) == {"ok": False, "error": "temperature must be between 0 and 2"}
+ assert mgr.remove_model_config("ollama:qwen3-coder:30b") == {"ok": True}
+ assert mgr.get_model_config()["models"] == {}