Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Run Claude Code and Codex on MLX models (#16811)

Long Yixingc6f381e5ca43
diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.py
index 4b0e38bf7d8..39c175c4378 100644
--- a/studio/backend/core/inference/orchestrator.py
+++ b/studio/backend/core/inference/orchestrator.py
@@ -433,6 +433,7 @@ def _mirrored_model_entry(model_info: dict, model_name: str) -> dict:
"audio_family": model_info.get("audio_family"),
"audio_options": model_info.get("audio_options"),
"gguf_variant": model_info.get("gguf_variant"),
+ "precision_folder": model_info.get("precision_folder"),
"audio_workflows": model_info.get("audio_workflows"),
"audio_reference_text": model_info.get("audio_reference_text"),
"audio_required_inputs": model_info.get("audio_required_inputs"),
diff --git a/studio/backend/core/inference/passthrough_healing.py b/studio/backend/core/inference/passthrough_healing.py
index 948bad2bf38..757c35db30a 100644
--- a/studio/backend/core/inference/passthrough_healing.py
+++ b/studio/backend/core/inference/passthrough_healing.py
@@ -265,6 +265,14 @@ def _closed_signal_span(buffer: str) -> Optional[tuple[int, int]]:
return min(spans, key = lambda span: span[0]) if spans else None
+def _inside_open_wrapper(buffer: str, start: int) -> bool:
+ for open_tag, close_tag in (("<tool_call>", "</tool_call>"), ("<|tool_call>", "<tool_call|>")):
+ opened = buffer.rfind(open_tag, 0, start)
+ if opened >= 0 and buffer.find(close_tag, opened) < 0:
+ return True
+ return False
+
+
# A strict parse needs a JSON/Gemma close tag or </function>; else only a balanced Mistral/rehearsal bracket call parses.
_STRICT_CLOSE_TOKENS = ("</tool_call>", "<|end_message|>", "<tool_call|>", "</function>")
_CALLS_TAG = "[TOOL_CALLS]"
@@ -520,6 +528,13 @@ class StreamToolCallHealer:
and _closed_signal_span(self._buffer) is None
):
parsed, spans = [], []
+ # Qwen3.5's <function=...> closes inside a still-open <tool_call>; promoting it now would relay the wrapper as text.
+ if (
+ parsed
+ and len(self._buffer) <= _MAX_HOLD_CHARS
+ and _inside_open_wrapper(self._buffer, spans[0][0])
+ ):
+ return events
if not parsed:
# Its close tags are gate tokens, so a closed gate means no closed span.
closed_span = _closed_signal_span(self._buffer) if may_parse else None
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 0f92414c73c..e54d7055f8b 100644
--- a/studio/backend/core/inference/worker.py
+++ b/studio/backend/core/inference/worker.py
@@ -893,6 +893,7 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:
"audio_family",
"audio_options",
"gguf_variant",
+ "precision_folder",
"audio_workflows",
"audio_reference_text",
"audio_required_inputs",
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 49a4b79b205..8b81b13dc37 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -19108,7 +19108,11 @@ async def _load_model_impl(
if not llama_backend.holds_no_vram:
await asyncio.to_thread(_reassert_chat_claim, multi_model_mode)
return reused
- if not (request.gguf_variant or is_direct_gguf_request):
+ from hub.utils.mlx_variants import is_precision_folder
+
+ if not is_direct_gguf_request and (
+ not request.gguf_variant or is_precision_folder(request.gguf_variant)
+ ):
_inherit_resident_load_in_4bit(backend, request, model_identifier)
await asyncio.to_thread(reap_dead_worker, backend)
if (
@@ -19130,9 +19134,11 @@ async def _load_model_impl(
_same_loaded_identifier(backend.active_model_name, model_identifier)
and (backend.models.get(backend.active_model_name) or {}).get("engine", "auto")
== request.engine
- # A resident precision folder (6-bit/) is not the root checkpoint a variantless request names.
- and not (backend.models.get(backend.active_model_name) or {}).get(
- "precision_folder"
+ # Folder names are case-sensitive, so 6-BIT is not the resident 6-bit/.
+ and (request.gguf_variant or "").strip()
+ == str(
+ (backend.models.get(backend.active_model_name) or {}).get("precision_folder")
+ or ""
)
and _mlx_runtime_settings_match(backend, request)
and _non_gguf_runtime_settings_match(backend, request)
@@ -46451,11 +46457,15 @@ def _flatten_content_parts_for_local_template(messages: list[dict]) -> list[dict
def _structured_tool_history_for_local_template(messages: list[dict]) -> list[dict]:
- """Local templates only: tool_calls arguments parsed to mappings; HTTP unchanged; unparseable as-is."""
+ """Local templates only: tool_calls arguments parsed to mappings; HTTP unchanged; unparseable as-is.
+ A call-only turn gets empty content: llama-server accepts it absent, but templates such as
+ Qwen3's read message.content and raise."""
out = []
for msg in messages:
tool_calls = msg.get("tool_calls")
if isinstance(tool_calls, list) and tool_calls:
+ if msg.get("content") is None:
+ msg = {**msg, "content": ""}
new_calls = []
for tc in tool_calls:
fn = tc.get("function") if isinstance(tc, dict) else None
diff --git a/studio/backend/tests/test_mlx_precision_variants.py b/studio/backend/tests/test_mlx_precision_variants.py
index d594bb14e95..cae165184d6 100644
--- a/studio/backend/tests/test_mlx_precision_variants.py
+++ b/studio/backend/tests/test_mlx_precision_variants.py
@@ -498,9 +498,19 @@ def test_memory_estimate_prices_the_picked_folder(monkeypatch, tmp_path):
assert mlx_memory._snapshot_config(picked)["model_type"] == "raon1_mini"
[email protected]("resident_folder, expected", [(None, "reuse"), ("6-bit", "load")])
-def test_a_root_request_never_reuses_a_resident_precision_folder(
- monkeypatch, resident_folder, expected
+ "resident_folder, requested, expected",
+ [
+ (None, None, "reuse"),
+ ("6-bit", None, "reload"),
+ ("6-bit", "6-bit", "reuse"),
+ ("6-bit", "8bit", "reload"),
+ ("6-bit", "6-BIT", "reload"),
+ (None, "6-bit", "reload"),
+ ],
+)
+def test_a_request_reuses_only_the_resident_precision_folder(
+ monkeypatch, resident_folder, requested, expected
):
from hub.services.models import account_access
from models.inference import LoadRequest
@@ -550,10 +560,12 @@ def test_a_root_request_never_reuses_a_resident_precision_folder(
with pytest.raises(Exception):
asyncio.run(
inference._load_model_impl(
- LoadRequest(model_path = _REPO), fastapi_request, current_subject = "user"
+ LoadRequest(model_path = _REPO, gguf_variant = requested),
+ fastapi_request,
+ current_subject = "user",
)
)
- assert calls[:1] == [expected]
+ assert (calls[:1] == ["reuse"]) == (expected == "reuse")
def test_a_caller_refused_the_cache_learns_nothing_from_it(monkeypatch, tmp_path):
@@ -586,3 +598,16 @@ def test_offline_lists_a_cached_precision_folder(monkeypatch, tmp_path):
with pytest.raises(HTTPException) as missing:
asyncio.run(gguf_variants.get_gguf_variants_answer("org/absent", offline = True))
assert missing.value.status_code == 404
+
+
+def test_the_resident_folder_survives_the_worker_hop():
+ from core.inference.orchestrator import _mirrored_model_entry
+
+ assert (
+ _mirrored_model_entry({"precision_folder": "6-bit"}, _REPO)["precision_folder"] == "6-bit"
+ )
+ worker = (Path(__file__).resolve().parents[1] / "core/inference/worker.py").read_text(
+ encoding = "utf-8"
+ )
+ projection = worker[worker.index('"gguf_variant",\n') :][:200]
+ assert '"precision_folder",' in projection
diff --git a/studio/backend/tests/test_passthrough_healing.py b/studio/backend/tests/test_passthrough_healing.py
index 870bb1fc80b..cc095586dd4 100644
--- a/studio/backend/tests/test_passthrough_healing.py
+++ b/studio/backend/tests/test_passthrough_healing.py
@@ -351,6 +351,43 @@ def test_stream_keeps_a_bracket_call_inside_an_open_block_in_its_arguments():
assert "run " in json.loads(call["function"]["arguments"])["command"]
[email protected]("step", [1, 5])
+def test_stream_drops_the_tool_call_wrapper_around_a_function_call(step):
+ def call(command):
+ return (
+ "<tool_call>\n<function=Bash>\n<parameter=command>\n"
+ f"{command}\n</parameter>\n</function>\n</tool_call>"
+ )
+
+ text = f"Listing.\n\n{call('ls')}\n{call('pwd')}\nDone."
+ healer = StreamToolCallHealer({"Bash"})
+ events = []
+ for start in range(0, len(text), step):
+ events += healer.feed(text[start : start + step])
+ events += healer.finalize()
+ calls = _events_calls(events)
+ assert [json.loads(c["function"]["arguments"]) for c in calls] == [
+ {"command": "ls"},
+ {"command": "pwd"},
+ ]
+ assert len({c["id"] for c in calls}) == 2
+ assert _events_text(events) == "Listing.\n\n\n\nDone."
+
+
+def test_an_unclosed_wrapper_still_streams_past_the_hold_limit():
+ healer = StreamToolCallHealer({"Bash"})
+ events = healer.feed(
+ "<tool_call>\n<function=Bash>\n<parameter=command>\nls\n</parameter>\n</function>\n"
+ )
+ for _ in range(8000):
+ events += healer.feed("more text ")
+ assert _events_calls(events), "the call must not wait for finalize past the hold limit"
+ assert len(healer._buffer) < 70000
+ events += healer.finalize()
+ (call,) = _events_calls(events)
+ assert json.loads(call["function"]["arguments"]) == {"command": "ls"}
+
+
def test_stream_delivers_a_bracket_call_wrapped_in_a_closed_block():
healer = StreamToolCallHealer({"Bash"})
events = healer.feed('<tool_call>[TOOL_CALLS]Bash[ARGS]{"command": "ls"}</tool_call>')
diff --git a/studio/backend/tests/test_sf_client_tools_passthrough.py b/studio/backend/tests/test_sf_client_tools_passthrough.py
index 60099ba4a98..549b591cf98 100644
--- a/studio/backend/tests/test_sf_client_tools_passthrough.py
+++ b/studio/backend/tests/test_sf_client_tools_passthrough.py
@@ -354,6 +354,29 @@ def test_nudge_retry_cut_at_length_keeps_the_cut(monkeypatch):
assert choice["message"]["content"] == _CUT_XML
[email protected]("content", [None, ""])
+def test_call_only_turn_reaches_the_local_template_with_content(monkeypatch, content):
+ backend = _ScriptedBackend(_fixed("done"))
+ call = {
+ "id": "c1",
+ "type": "function",
+ "function": {"name": "lookup", "arguments": '{"q": "x"}'},
+ }
+ payload = _request(
+ tools = [LOOKUP_TOOL],
+ stream = False,
+ messages = [
+ ChatMessage(role = "user", content = "hi"),
+ ChatMessage(role = "assistant", content = content, tool_calls = [call]),
+ ChatMessage(role = "tool", content = "r", tool_call_id = "c1"),
+ ],
+ )
+ _call(payload, monkeypatch, backend)
+ (turn,) = [m for m in backend.calls[0]["messages"] if m["role"] == "assistant"]
+ assert turn["content"] == ""
+ assert turn["tool_calls"][0]["function"]["arguments"] == {"q": "x"}
+
+
def test_undeclared_call_stays_text(monkeypatch):
xml = '<tool_call>{"name": "other", "arguments": {}}</tool_call>'
backend = _ScriptedBackend(_fixed(xml))
diff --git a/studio/frontend/src/features/settings/components/agent-command.ts b/studio/frontend/src/features/settings/components/agent-command.ts
index 313b4f58f38..60265b17280 100644
--- a/studio/frontend/src/features/settings/components/agent-command.ts
+++ b/studio/frontend/src/features/settings/components/agent-command.ts
@@ -122,7 +122,7 @@ export function buildAgentShellCommands(
};
}
-// Codex (/v1/responses) and Claude Code (/v1/messages) are llama-server only.
+// `isGguf` below means GGUF or MLX: both serve /v1/messages and /v1/responses, transformers does not.
export const GGUF_ONLY_AGENTS: readonly string[] = ["codex", "claude"];
export function agentRunsOnActiveModel(
@@ -183,9 +183,10 @@ export function resolveGgufCompatibility(
export function statusGgufVerdict(
resident: string | null | undefined,
isGguf: boolean | null | undefined,
+ isMlx?: boolean | null,
): boolean | null {
- if (resident == null) return null;
- return isGguf ?? null;
+ if (resident == null || isGguf == null) return null;
+ return isGguf || isMlx === true;
}
export function sameBaseModelId(a: string, b: string): boolean {
@@ -223,3 +224,25 @@ export function compatibilityFromSources(
}
return resolveGgufCompatibility(fromStore, status.isGguf);
}
+
+// A root-loaded MLX resident keeps its root: any folder would reload it at another precision.
+export function pickAgentVariant(
+ available: ReadonlySet<string>,
+ choice: {
+ remembered: string | null;
+ preferred: string | null;
+ defaultVariant: string | null | undefined;
+ first: string | null;
+ keepRoot: boolean;
+ },
+): string | null {
+ const offered = (variant: string | null | undefined) =>
+ variant && available.has(variant) ? variant : null;
+ const remembered = offered(choice.remembered);
+ if (remembered || choice.keepRoot) {
+ return remembered;
+ }
+ return (
+ offered(choice.preferred) ?? offered(choice.defaultVariant) ?? choice.first
+ );
+}
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 1b195ac1be6..572bc6cd71d 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -615,13 +615,15 @@ export function UsageExamples({
(s) => s.activeNativePathToken,
);
const loadedIsGguf = useChatRuntimeStore((s) => s.loadedIsGguf);
+ const loadedIsMlx = useChatRuntimeStore((s) => s.loadedIsMlx);
// null when these fields do not describe the model the snippet names (before status, or under an
// external selection).
const activeCheckpoint = useChatRuntimeStore((s) => s.params.checkpoint);
const storeIsGguf: boolean | null =
!activeCheckpoint || isExternalModelId(activeCheckpoint)
? null
- : isServedByLlamaCpp({
+ : loadedIsMlx === true ||
+ isServedByLlamaCpp({
loadedIsGguf,
activeGgufVariant,
activeNativePathToken,
@@ -661,7 +663,11 @@ export function UsageExamples({
// Both unknown, as the CLI gate reads them: no field, or is_gguf False with no model.
const resident =
status.active_model ?? status.model_identifier ?? null;
- const answer = statusGgufVerdict(resident, status.is_gguf);
+ const answer = statusGgufVerdict(
+ resident,
+ status.is_gguf,
+ status.is_mlx,
+ );
setStatusAnswer({ key: storeModelKey, resident, isGguf: answer });
return answer !== null;
})
diff --git a/studio/frontend/src/features/settings/tabs/agents-tab.tsx b/studio/frontend/src/features/settings/tabs/agents-tab.tsx
index 0a2a4e14dbe..aac08fb2694 100644
--- a/studio/frontend/src/features/settings/tabs/agents-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/agents-tab.tsx
@@ -65,6 +65,7 @@ import {
buildAgentShellCommands,
isLoopbackHost,
normalizeHost,
+ pickAgentVariant,
quoteShellArg,
} from "../components/agent-command";
import {
@@ -267,22 +268,10 @@ function localGgufEntries(
return entries;
}
-function pickVariant(
- available: Set<string>,
- candidates: (string | null | undefined)[],
-): string | null {
- for (const candidate of candidates) {
- if (candidate && available.has(candidate)) {
- return candidate;
- }
- }
- return null;
-}
-
-function activeGgufSelection(
+function activeAgentModelSelection(
status: InferenceStatusResponse | null,
): { model: string; variant: string | null; named: boolean } | null {
- if (!status?.is_gguf) {
+ if (!(status?.is_gguf || status?.is_mlx)) {
return null;
}
if (!status.model_identifier) {
@@ -539,6 +528,8 @@ export function AgentsTab() {
null,
);
const [statusSettled, setStatusSettled] = useState(false);
+ // State, not the ref: status can land after the variants listing and must re-pick then.
+ const [rootMlxResident, setRootMlxResident] = useState<string | null>(null);
const activeModelRef = useRef<{
model: string;
variant: string | null;
@@ -838,7 +829,7 @@ export function AgentsTab() {
});
}, []);
- // Follow the resident GGUF away too, or the command would switch the shared server back.
+ // Follow the resident model away too, or the command would switch the shared server back.
// An explicit pick wins, except a native-grant label, which is not loadable.
const dropActiveModel = useCallback(
(attachOnly: string | null, wasActive: string | null) => {
@@ -861,10 +852,15 @@ export function AgentsTab() {
const applyStatus = useCallback(
(status: InferenceStatusResponse) => {
- const active = activeGgufSelection(status);
+ const active = activeAgentModelSelection(status);
activeModelRef.current = active
? { model: active.model, variant: active.variant }
: null;
+ setRootMlxResident(
+ active && status.is_mlx && active.variant === null
+ ? modelKey(active.model)
+ : null,
+ );
const wasAttachOnly = attachOnlyModel;
setActiveStatusModel(active?.model ?? null);
setAttachOnlyModel(active && !active.named ? active.model : null);
@@ -942,6 +938,7 @@ export function AgentsTab() {
useEffect(() => {
let cancelled = false;
+ const keepRoot = rootMlxResident === modelKey(selectedModel);
// After discovery a scanned directory's path is its identity; only a loose .gguf is variantless.
const localDir =
@@ -997,14 +994,13 @@ export function AgentsTab() {
if (remembered && !available.has(remembered)) {
chosenVariant.current = null;
}
- const nextVariant =
- pickVariant(available, [
- rememberedVariant(selectedModel),
- preferredVariant,
- info.default_variant,
- ]) ??
- uniqueVariants[0]?.quant ??
- null;
+ const nextVariant = pickAgentVariant(available, {
+ remembered: rememberedVariant(selectedModel),
+ preferred: preferredVariant,
+ defaultVariant: info.default_variant,
+ first: uniqueVariants[0]?.quant ?? null,
+ keepRoot,
+ });
setSelectedVariant(nextVariant);
})
.catch(() => {
@@ -1013,12 +1009,13 @@ export function AgentsTab() {
}
setVariantsFailed(true);
setVariants([]);
- setSelectedVariant(preferredVariant);
- if (preferredVariant) {
+ const fallback = keepRoot ? null : preferredVariant;
+ setSelectedVariant(fallback);
+ if (fallback) {
setVariants([
{
filename: "",
- quant: preferredVariant,
+ quant: fallback,
// biome-ignore lint/style/useNamingConvention: API response field
size_bytes: 0,
},
@@ -1039,10 +1036,11 @@ export function AgentsTab() {
hfToken,
preferredVariant,
rememberedVariant,
+ rootMlxResident,
selectedModel,
]);
- // No GGUF warning for `codex`/`claude`: the picker only offers GGUF models.
+ // No GGUF warning for `codex`/`claude`: the picker only offers GGUF models and a resident MLX one.
return (
<div className="settings-page">
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 49ef050266b..60ed5f53225 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -2854,7 +2854,7 @@ export const ar = {
configurationDocs: "التوثيق",
configurationFlagsSuffix: "لمعرفة الخيارات (flags).",
modelNote:
- "يتطلب Codex وClaude Code نموذج GGUF يقدّمه llama-server. أما الوكلاء الآخرون فيمكنهم استخدام النماذج المبنية على transformers أيضًا؛ احذف ‎--model لاستخدام النموذج المُحمَّل بالفعل في Unsloth.",
+ "يتطلب Claude Code وCodex نموذج GGUF يقدّمه llama-server أو نموذج MLX. أما الوكلاء الآخرون فيمكنهم استخدام النماذج المبنية على transformers أيضًا؛ احذف ‎--model لاستخدام النموذج المُحمَّل بالفعل في Unsloth.",
subagent: {
title: "استخدام نموذج محلي كوكيل فرعي",
description:
diff --git a/studio/frontend/src/i18n/locales/cs.ts b/studio/frontend/src/i18n/locales/cs.ts
index 179c27a49b0..950b21aaf65 100644
--- a/studio/frontend/src/i18n/locales/cs.ts
+++ b/studio/frontend/src/i18n/locales/cs.ts
@@ -3104,7 +3104,7 @@ export const cs = {
configurationDocs: "dokumentace",
configurationFlagsSuffix: "s popisem příznaků.",
modelNote:
- "Codex a Claude Code vyžadují model GGUF obsluhovaný přes llama-server. Ostatní agenti mohou používat i modely založené na transformers; odeberte --model, chcete-li použít model, který je už načtený v Unsloth.",
+ "Claude Code a Codex vyžadují model GGUF obsluhovaný přes llama-server nebo model MLX. Ostatní agenti mohou používat i modely založené na transformers; odeberte --model, chcete-li použít model, který je už načtený v Unsloth.",
subagent: {
title: "Použít místní model jako subagenta",
description:
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index 7c74bf57463..adc4eb322e2 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -2888,7 +2888,7 @@ export const de = {
configurationDocs: "Dokumentation",
configurationFlagsSuffix: "zu den Flags.",
modelNote:
- "Codex und Claude Code benötigen ein GGUF-Modell, das von llama-server bereitgestellt wird. Andere Agenten können auch Transformer-basierte Modelle verwenden; lassen Sie --model weg, um das bereits in Unsloth geladene Modell zu nutzen.",
+ "Claude Code und Codex benötigen ein GGUF-Modell, das von llama-server bereitgestellt wird, oder ein MLX-Modell. Andere Agenten können auch Transformer-basierte Modelle verwenden; lassen Sie --model weg, um das bereits in Unsloth geladene Modell zu nutzen.",
subagent: {
title: "Ein lokales Modell als Subagent verwenden",
description:
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 1ec711dbf12..68217d1355e 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -2874,7 +2874,7 @@ export const en = {
configurationDocs: "docs",
configurationFlagsSuffix: "for flags.",
modelNote:
- "Codex and Claude Code require a GGUF model served by llama-server. Other agents can also use transformer-backed models; remove --model to use the model already loaded in Unsloth.",
+ "Claude Code and Codex need a GGUF model served by llama-server, or an MLX model. Other agents can also use transformer-backed models; remove --model to use the model already loaded in Unsloth.",
subagent: {
title: "Use a local model as a subagent",
description:
diff --git a/studio/frontend/src/i18n/locales/es-419.ts b/studio/frontend/src/i18n/locales/es-419.ts
index 6086fa89f8a..c17630e806c 100644
--- a/studio/frontend/src/i18n/locales/es-419.ts
+++ b/studio/frontend/src/i18n/locales/es-419.ts
@@ -3129,7 +3129,7 @@ export const es419 = {
configurationDocs: "documentación",
configurationFlagsSuffix: "para ver las opciones.",
modelNote:
- "Codex y Claude Code requieren un modelo GGUF servido por llama-server. Otros agentes también pueden usar modelos basados en transformers; quita --model para usar el modelo que ya está cargado en Unsloth.",
+ "Claude Code y Codex requieren un modelo GGUF servido por llama-server o un modelo MLX. Otros agentes también pueden usar modelos basados en transformers; quita --model para usar el modelo que ya está cargado en Unsloth.",
subagent: {
title: "Usar un modelo local como subagente",
description:
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 1f9cd66b4e0..8bb4280c966 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -2882,7 +2882,7 @@ export const es = {
configurationDocs: "documentación",
configurationFlagsSuffix: "para ver los flags.",
modelNote:
- "Codex y Claude Code requieren un modelo GGUF servido por llama-server. Otros agentes también pueden usar modelos basados en transformers; quita --model para usar el modelo ya cargado en Unsloth.",
+ "Claude Code y Codex requieren un modelo GGUF servido por llama-server o un modelo MLX. Otros agentes también pueden usar modelos basados en transformers; quita --model para usar el modelo ya cargado en Unsloth.",
subagent: {
title: "Usar un modelo local como subagente",
description:
diff --git a/studio/frontend/src/i18n/locales/fa.ts b/studio/frontend/src/i18n/locales/fa.ts
index a926b688c19..efe414fe70e 100644
--- a/studio/frontend/src/i18n/locales/fa.ts
+++ b/studio/frontend/src/i18n/locales/fa.ts
@@ -3072,7 +3072,7 @@ export const fa = {
configurationDocs: "مستندات",
configurationFlagsSuffix: "مراجعه کنید.",
modelNote:
- "Codex و Claude Code به یک مدل GGUF نیاز دارند که با llama-server ارائه شود. عامل‌های دیگر می‌توانند از مدل‌های مبتنی بر transformers نیز استفاده کنند؛ برای استفاده از مدلی که از قبل در Unsloth بارگذاری شده است، --model را حذف کنید.",
+ "Claude Code و Codex به یک مدل GGUF که با llama-server ارائه شود یا یک مدل MLX نیاز دارند. عامل‌های دیگر می‌توانند از مدل‌های مبتنی بر transformers نیز استفاده کنند؛ برای استفاده از مدلی که از قبل در Unsloth بارگذاری شده است، --model را حذف کنید.",
subagent: {
title: "استفاده از مدل محلی به‌عنوان زیرعامل",
description:
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 4c495a61d09..082c6db5cf5 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -2885,7 +2885,7 @@ export const fr = {
configurationDocs: "documentation",
configurationFlagsSuffix: "pour les flags.",
modelNote:
- "Codex et Claude Code nécessitent un modèle GGUF servi par llama-server. Les autres agents peuvent aussi utiliser des modèles basés sur transformers ; retirez --model pour utiliser le modèle déjà chargé dans Unsloth.",
+ "Claude Code et Codex nécessitent un modèle GGUF servi par llama-server, ou un modèle MLX. Les autres agents peuvent aussi utiliser des modèles basés sur transformers ; retirez --model pour utiliser le modèle déjà chargé dans Unsloth.",
subagent: {
title: "Utiliser un modèle local comme sous-agent",
description:
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index 54532cb306b..30cc0de88b6 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -2924,7 +2924,7 @@ export const he = {
configurationDocs: "תיעוד",
configurationFlagsSuffix: "עבור דגלים.",
modelNote:
- "Codex ו-Claude Code דורשים מודל GGUF המוגש על ידי llama-server. סוכנים אחרים יכולים להשתמש גם במודלים מבוססי Transformers; הסר את --model כדי להשתמש במודל שכבר טעון ב-Unsloth.",
+ "Claude Code ו-Codex דורשים מודל GGUF המוגש על ידי llama-server, או מודל MLX. סוכנים אחרים יכולים להשתמש גם במודלים מבוססי Transformers; הסר את --model כדי להשתמש במודל שכבר טעון ב-Unsloth.",
subagent: {
title: "השתמש במודל מקומי כתת-סוכן",
description:
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index 3da067f123a..d63dcfc968b 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -2860,7 +2860,7 @@ export const hi = {
configurationDocs: "दस्तावेज़",
configurationFlagsSuffix: "देखें।",
modelNote:
- "Codex और Claude Code को llama-server द्वारा सर्व किया गया GGUF मॉडल चाहिए। दूसरे एजेंट Transformers-आधारित मॉडल भी उपयोग कर सकते हैं; Unsloth में पहले से लोड किए गए मॉडल का उपयोग करने के लिए --model हटा दें।",
+ "Claude Code और Codex को llama-server द्वारा सर्व किया गया GGUF मॉडल या MLX मॉडल चाहिए। दूसरे एजेंट Transformers-आधारित मॉडल भी उपयोग कर सकते हैं; Unsloth में पहले से लोड किए गए मॉडल का उपयोग करने के लिए --model हटा दें।",
subagent: {
title: "लोकल मॉडल को सबएजेंट के रूप में उपयोग करें",
description:
diff --git a/studio/frontend/src/i18n/locales/id.ts b/studio/frontend/src/i18n/locales/id.ts
index 3412ae63eb2..db364dd1725 100644
--- a/studio/frontend/src/i18n/locales/id.ts
+++ b/studio/frontend/src/i18n/locales/id.ts
@@ -3088,7 +3088,7 @@ export const id = {
configurationDocs: "dokumentasi",
configurationFlagsSuffix: "untuk flag.",
modelNote:
- "Codex dan Claude Code memerlukan model GGUF yang dilayani oleh llama-server. Agen lain juga dapat menggunakan model berbasis transformer; hapus --model untuk menggunakan model yang sudah dimuat di Unsloth.",
+ "Claude Code dan Codex memerlukan model GGUF yang dilayani oleh llama-server, atau model MLX. Agen lain juga dapat menggunakan model berbasis transformer; hapus --model untuk menggunakan model yang sudah dimuat di Unsloth.",
subagent: {
title: "Gunakan model lokal sebagai subagen",
description:
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 5fba7c6d6c2..24f4fcc08ed 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -2785,7 +2785,7 @@ export const it = {
configurationDocs: "documentazione",
configurationFlagsSuffix: "per i flag.",
modelNote:
- "Codex e Claude Code richiedono un modello GGUF servito da llama-server. Gli altri agenti possono usare anche modelli basati su transformer; rimuovi --model per usare il modello già caricato in Unsloth.",
+ "Claude Code e Codex richiedono un modello GGUF servito da llama-server o un modello MLX. Gli altri agenti possono usare anche modelli basati su transformer; rimuovi --model per usare il modello già caricato in Unsloth.",
subagent: {
title: "Usa un modello locale come subagente",
description:
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index b7a3c3ac92a..521040c4f14 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -2836,7 +2836,7 @@ export const ja = {
configurationDocs: "ドキュメント",
configurationFlagsSuffix: "を参照してください。",
modelNote:
- "Codex と Claude Code には llama-server が提供する GGUF モデルが必要です。他のエージェントは transformers ベースのモデルも利用できます。Unsloth に読み込み済みのモデルを使うには --model を外してください。",
+ "Claude Code と Codex には、llama-server が提供する GGUF モデルか MLX モデルが必要です。他のエージェントは transformers ベースのモデルも利用できます。Unsloth に読み込み済みのモデルを使うには --model を外してください。",
subagent: {
title: "ローカルモデルをサブエージェントとして使う",
description:
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index 26fc748bac5..028a0417072 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -2848,7 +2848,7 @@ export const ko = {
configurationDocs: "문서를",
configurationFlagsSuffix: "참고하세요.",
modelNote:
- "Codex와 Claude Code에는 llama-server가 제공하는 GGUF 모델이 필요합니다. 다른 에이전트는 transformers 기반 모델도 사용할 수 있습니다. Unsloth에 이미 로드된 모델을 사용하려면 --model을 제거하세요.",
+ "Claude Code와 Codex에는 llama-server가 제공하는 GGUF 모델 또는 MLX 모델이 필요합니다. 다른 에이전트는 transformers 기반 모델도 사용할 수 있습니다. Unsloth에 이미 로드된 모델을 사용하려면 --model을 제거하세요.",
subagent: {
title: "로컬 모델을 서브에이전트로 사용",
description:
diff --git a/studio/frontend/src/i18n/locales/nl.ts b/studio/frontend/src/i18n/locales/nl.ts
index 278653a329d..8b451bae38a 100644
--- a/studio/frontend/src/i18n/locales/nl.ts
+++ b/studio/frontend/src/i18n/locales/nl.ts
@@ -3126,7 +3126,7 @@ export const nl = {
configurationDocs: "documentatie",
configurationFlagsSuffix: "voor flags.",
modelNote:
- "Codex en Claude Code vereisen een GGUF-model dat door llama-server wordt aangeboden. Andere agents kunnen ook modellen op basis van Transformers gebruiken; verwijder --model om het model te gebruiken dat al in Unsloth is geladen.",
+ "Claude Code en Codex vereisen een GGUF-model dat door llama-server wordt aangeboden, of een MLX-model. Andere agents kunnen ook modellen op basis van Transformers gebruiken; verwijder --model om het model te gebruiken dat al in Unsloth is geladen.",
subagent: {
title: "Een lokaal model als subagent gebruiken",
description:
diff --git a/studio/frontend/src/i18n/locales/pl.ts b/studio/frontend/src/i18n/locales/pl.ts
index 56277d6832b..6ad9eeb2b64 100644
--- a/studio/frontend/src/i18n/locales/pl.ts
+++ b/studio/frontend/src/i18n/locales/pl.ts
@@ -3122,7 +3122,7 @@ export const pl = {
configurationDocs: "dokumentację",
configurationFlagsSuffix: "na temat flag.",
modelNote:
- "Codex i Claude Code wymagają modelu GGUF udostępnianego przez llama-server. Inni agenci mogą też używać modeli opartych na transformers; usuń --model, aby użyć modelu już wczytanego w Unsloth.",
+ "Claude Code i Codex wymagają modelu GGUF udostępnianego przez llama-server lub modelu MLX. Inni agenci mogą też używać modeli opartych na transformers; usuń --model, aby użyć modelu już wczytanego w Unsloth.",
subagent: {
title: "Użyj modelu lokalnego jako podagenta",
description:
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 7c155375e6c..969287c487a 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -2867,7 +2867,7 @@ export const ptBR = {
configurationDocs: "documentação",
configurationFlagsSuffix: "para ver as flags.",
modelNote:
- "O Codex e o Claude Code exigem um modelo GGUF servido pelo llama-server. Outros agentes também podem usar modelos baseados em transformers; remova --model para usar o modelo já carregado no Unsloth.",
+ "O Claude Code e o Codex exigem um modelo GGUF servido pelo llama-server ou um modelo MLX. Outros agentes também podem usar modelos baseados em transformers; remova --model para usar o modelo já carregado no Unsloth.",
subagent: {
title: "Usar um modelo local como subagente",
description:
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index a708d807db0..c4494e8725d 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -2864,7 +2864,7 @@ export const ru = {
configurationDocs: "документации",
configurationFlagsSuffix: "о флагах.",
modelNote:
- "Codex и Claude Code требуют модель GGUF, обслуживаемую llama-server. Другие агенты могут работать и с моделями на основе transformers; уберите --model, чтобы использовать модель, уже загруженную в Unsloth.",
+ "Claude Code и Codex требуют модель GGUF, обслуживаемую llama-server, или модель MLX. Другие агенты могут работать и с моделями на основе transformers; уберите --model, чтобы использовать модель, уже загруженную в Unsloth.",
subagent: {
title: "Использовать локальную модель в качестве субагента",
description:
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index 8be9014ec75..839a33f2905 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -3003,7 +3003,7 @@ export const sv = {
configurationDocs: "dokumentationen",
configurationFlagsSuffix: "för flaggor.",
modelNote:
- "Codex och Claude Code kräver en GGUF-modell som körs av llama-server. Andra agenter kan även använda transformerbaserade modeller; ta bort --model för att använda modellen som redan är inläst i Unsloth.",
+ "Claude Code och Codex kräver en GGUF-modell som körs av llama-server, eller en MLX-modell. Andra agenter kan även använda transformerbaserade modeller; ta bort --model för att använda modellen som redan är inläst i Unsloth.",
subagent: {
title: "Använd en lokal modell som underagent",
description:
diff --git a/studio/frontend/src/i18n/locales/th.ts b/studio/frontend/src/i18n/locales/th.ts
index 5179d2d22c5..6da9b8c13a4 100644
--- a/studio/frontend/src/i18n/locales/th.ts
+++ b/studio/frontend/src/i18n/locales/th.ts
@@ -2962,7 +2962,7 @@ export const th = {
configurationDocs: "เอกสาร",
configurationFlagsSuffix: "สำหรับแฟล็ก",
modelNote:
- "Codex และ Claude Code ต้องใช้โมเดล GGUF ที่ให้บริการโดย llama-server เอเจนต์อื่นใช้โมเดลที่ทำงานด้วย transformers ได้ด้วย นำ --model ออกเพื่อใช้โมเดลที่โหลดอยู่ใน Unsloth แล้ว",
+ "Claude Code และ Codex ต้องใช้โมเดล GGUF ที่ให้บริการโดย llama-server หรือโมเดล MLX เอเจนต์อื่นใช้โมเดลที่ทำงานด้วย transformers ได้ด้วย นำ --model ออกเพื่อใช้โมเดลที่โหลดอยู่ใน Unsloth แล้ว",
subagent: {
title: "ใช้โมเดลภายในเครื่องเป็นเอเจนต์ย่อย",
description:
diff --git a/studio/frontend/src/i18n/locales/tr.ts b/studio/frontend/src/i18n/locales/tr.ts
index de70fe4c1f5..3841cd0eae9 100644
--- a/studio/frontend/src/i18n/locales/tr.ts
+++ b/studio/frontend/src/i18n/locales/tr.ts
@@ -3083,7 +3083,7 @@ export const tr = {
configurationDocs: "belgelere",
configurationFlagsSuffix: "göz atın.",
modelNote:
- "Codex ve Claude Code, llama-server tarafından sunulan bir GGUF modeli gerektirir. Diğer ajanlar transformer tabanlı modelleri de kullanabilir; Unsloth'ta zaten yüklü olan modeli kullanmak için --model seçeneğini kaldırın.",
+ "Claude Code ve Codex, llama-server tarafından sunulan bir GGUF modeli veya bir MLX modeli gerektirir. Diğer ajanlar transformer tabanlı modelleri de kullanabilir; Unsloth'ta zaten yüklü olan modeli kullanmak için --model seçeneğini kaldırın.",
subagent: {
title: "Yerel bir modeli alt ajan olarak kullanın",
description:
diff --git a/studio/frontend/src/i18n/locales/uk.ts b/studio/frontend/src/i18n/locales/uk.ts
index 87be2f22f44..e0fd4cfa3ed 100644
--- a/studio/frontend/src/i18n/locales/uk.ts
+++ b/studio/frontend/src/i18n/locales/uk.ts
@@ -3111,7 +3111,7 @@ export const uk = {
configurationDocs: "документацію",
configurationFlagsSuffix: "щодо прапорців.",
modelNote:
- "Codex і Claude Code потребують моделі GGUF, яку обслуговує llama-server. Інші агенти можуть також використовувати моделі на основі transformers; вилучіть --model, щоб використати модель, уже завантажену в Unsloth.",
+ "Claude Code і Codex потребують моделі GGUF, яку обслуговує llama-server, або моделі MLX. Інші агенти можуть також використовувати моделі на основі transformers; вилучіть --model, щоб використати модель, уже завантажену в Unsloth.",
subagent: {
title: "Використовувати локальну модель як субагента",
description:
diff --git a/studio/frontend/src/i18n/locales/vi.ts b/studio/frontend/src/i18n/locales/vi.ts
index 9591e932fd1..95076e33742 100644
--- a/studio/frontend/src/i18n/locales/vi.ts
+++ b/studio/frontend/src/i18n/locales/vi.ts
@@ -3086,7 +3086,7 @@ export const vi = {
configurationDocs: "tài liệu",
configurationFlagsSuffix: "để biết các cờ.",
modelNote:
- "Codex và Claude Code yêu cầu mô hình GGUF do llama-server phục vụ. Các tác tử khác cũng có thể dùng mô hình chạy bằng transformers; bỏ --model để dùng mô hình đã nạp sẵn trong Unsloth.",
+ "Claude Code và Codex yêu cầu mô hình GGUF do llama-server phục vụ, hoặc mô hình MLX. Các tác tử khác cũng có thể dùng mô hình chạy bằng transformers; bỏ --model để dùng mô hình đã nạp sẵn trong Unsloth.",
subagent: {
title: "Dùng mô hình cục bộ làm tác tử phụ",
description:
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index ac55c4390bc..8b92f0957b5 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -2817,7 +2817,7 @@ export const zhCN = {
configurationDocs: "文档",
configurationFlagsSuffix: "了解标志。",
modelNote:
- "Codex 和 Claude Code 需要通过 llama-server 提供服务的 GGUF 模型。其他智能体也可以使用基于 transformers 的模型;去掉 --model 即可使用 Unsloth 中已加载的模型。",
+ "Claude Code 和 Codex 需要通过 llama-server 提供服务的 GGUF 模型,或 MLX 模型。其他智能体也可以使用基于 transformers 的模型;去掉 --model 即可使用 Unsloth 中已加载的模型。",
subagent: {
title: "将本地模型用作子智能体",
description:
diff --git a/studio/frontend/src/i18n/locales/zh-TW.ts b/studio/frontend/src/i18n/locales/zh-TW.ts
index 870f8b2feb0..7723d84adb3 100644
--- a/studio/frontend/src/i18n/locales/zh-TW.ts
+++ b/studio/frontend/src/i18n/locales/zh-TW.ts
@@ -2942,7 +2942,7 @@ export const zhTW = {
configurationDocs: "說明文件",
configurationFlagsSuffix: "以了解可用旗標。",
modelNote:
- "Codex 與 Claude Code 需要由 llama-server 提供的 GGUF 模型。其他代理程式也可以使用以 Transformers 為後端的模型;移除 --model 即可使用 Unsloth 中已載入的模型。",
+ "Claude Code 和 Codex 需要由 llama-server 提供的 GGUF 模型,或 MLX 模型。其他代理程式也可以使用以 Transformers 為後端的模型;移除 --model 即可使用 Unsloth 中已載入的模型。",
subagent: {
title: "將本機模型用作子代理程式",
description:
diff --git a/studio/frontend/tests/agent-picker-state-space.test.ts b/studio/frontend/tests/agent-picker-state-space.test.ts
index 3c7c91c9854..ae9c571cfd1 100644
--- a/studio/frontend/tests/agent-picker-state-space.test.ts
+++ b/studio/frontend/tests/agent-picker-state-space.test.ts
@@ -9,6 +9,7 @@ import {
UNIVERSAL_AGENT,
agentRunsOnActiveModel,
fallbackAgent,
+ pickAgentVariant,
pickCompatibleAgent,
resolveGgufCompatibility,
statusGgufVerdict,
@@ -289,6 +290,15 @@ test("a server that names what it holds still decides", () => {
assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B", undefined), null);
});
+test("an MLX model runs Claude Code and Codex like a GGUF", () => {
+ const mlx = statusGgufVerdict("mlx-community/Qwen3-4B-4bit", false, true);
+ assert.equal(mlx, true);
+ assert.equal(pickCompatibleAgent([], "claude", mlx as boolean, VISIBLE_AGENTS), null);
+ assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B", false, undefined), false);
+ assert.equal(statusGgufVerdict("unsloth/Qwen3-1.7B", false, false), false);
+ assert.equal(statusGgufVerdict(null, false, true), null);
+});
+
test("a verdict about one model never gates a different one", () => {
// Status and catalog polls run on separate timers, so a swap can reach one first.
assert.equal(
@@ -393,3 +403,37 @@ test("an answer about the model on screen still decides, and the server wins", (
true,
);
});
+
+test("a root-loaded MLX resident keeps its root checkpoint instead of a folder", () => {
+ const folders = new Set(["2-bit", "4bit"]);
+ const choice = {
+ remembered: null,
+ preferred: "2-bit",
+ defaultVariant: "4bit",
+ first: "2-bit",
+ keepRoot: true,
+ };
+ assert.equal(pickAgentVariant(folders, choice), null);
+ assert.equal(
+ pickAgentVariant(folders, { ...choice, remembered: "4bit" }),
+ "4bit",
+ );
+ assert.equal(
+ pickAgentVariant(folders, { ...choice, keepRoot: false }),
+ "2-bit",
+ );
+ assert.equal(
+ pickAgentVariant(folders, { ...choice, keepRoot: false, preferred: null }),
+ "4bit",
+ );
+ assert.equal(
+ pickAgentVariant(new Set(["Q8_0"]), {
+ ...choice,
+ keepRoot: false,
+ preferred: null,
+ defaultVariant: null,
+ first: "Q8_0",
+ }),
+ "Q8_0",
+ );
+});
diff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.py
index c53cfbcce52..c36615adb92 100644
--- a/unsloth_cli/commands/start.py
+++ b/unsloth_cli/commands/start.py
@@ -965,6 +965,13 @@ def _subagent_model_id(
)
if status.get("is_gguf"):
variant = status.get("gguf_variant")
+ elif _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip()):
+ # The API resolves no :folder suffix for an MLX resident (bf16 reads as a GGUF quant), so pin nothing.
+ try:
+ if _model_status(base, key, model_id).get("is_mlx"):
+ variant = None
+ except Exception:
+ pass
if variant and _is_hub_model_id(model_id):
return _display_model_spec(model_id, str(variant))
if variant:
@@ -2171,6 +2178,20 @@ def _resident_runtime_payload(status: dict, payload: dict) -> dict:
return carried
+def _resident_variant(status: dict) -> Optional[str]:
+ return status.get("gguf_variant") if status.get("is_gguf") or status.get("is_mlx") else None
+
+
+def _resident_serves_variant(status: dict, wanted: Optional[str]) -> bool:
+ resident = _resident_variant(status)
+ if not resident:
+ return False
+ # Hub folder names are case-sensitive; llama.cpp quant labels are not.
+ if status.get("is_mlx"):
+ return str(resident).strip() == str(wanted).strip()
+ return str(resident).strip().lower() == str(wanted).strip().lower()
+
+
def _load_settings_differ(status: dict, load: LoadOptions, overrides: frozenset) -> bool:
"""Whether applying these settings can restart the resident. Unproven equality counts as a difference: a silent restart is worse than a spurious warning."""
if not status:
@@ -2187,12 +2208,8 @@ def _load_settings_differ(status: dict, load: LoadOptions, overrides: frozenset)
return True
for name in overrides:
if name == "gguf_variant":
- resident = status.get("gguf_variant") if status.get("is_gguf") else None
# Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would read as equal here yet still really reload on the server. The preload gate below already compares this way, and the two have to agree.
- if (
- not resident
- or str(resident).strip().lower() != str(load.gguf_variant).strip().lower()
- ):
+ if not _resident_serves_variant(status, load.gguf_variant):
return True
elif name == "max_seq_length":
# Requested, not resolved: llama.cpp clamps n_ctx at fit time.
@@ -2339,13 +2356,8 @@ def _resolve_model(
status = _model_status(base, key, requested)
except Exception:
status = {}
- resident_variant = status.get("gguf_variant") if status.get("is_gguf") else None
# Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would skip the gate here yet still really reload on the server.
- resident_serves_request = (
- bool(resident_variant)
- and str(resident_variant).strip().lower()
- == str(load.gguf_variant).strip().lower()
- )
+ resident_serves_request = _resident_serves_variant(status, load.gguf_variant)
if not resident_serves_request:
preload_check(base, key, requested, load.gguf_variant)
active_id = active.get("id") if active else None
@@ -2378,8 +2390,13 @@ def _resolve_model(
status = _model_status(base, key, active_id)
except Exception:
status = {}
- resident = status.get("gguf_variant") if status.get("is_gguf") else None
- if resident and _normalized_variant(resident) != _normalized_variant(load.gguf_variant):
+ resident = _resident_variant(status)
+ switching = (
+ not _resident_serves_variant(status, load.gguf_variant)
+ if status.get("is_mlx")
+ else _normalized_variant(resident) != _normalized_variant(load.gguf_variant)
+ )
+ if resident and switching:
typer.echo(
f"Switching the Unsloth server from {active_id}:{resident} "
f"to {requested}:{load.gguf_variant}."
@@ -2427,14 +2444,18 @@ def _resolve_model(
)
else:
payload["gguf_variant"] = load.gguf_variant
- elif attach_public_id is not None and status_snapshot.get("is_gguf"):
+ elif attach_public_id is not None and (
+ status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
+ ):
# Re-send the running quant: a repo id carries none, so from_identifier would auto-pick (GGUF_QUANT_PREFERENCE, UD-Q4_K_XL first) and changing only the context would evict a chosen Q8_0 to download a different quant. Skip a .gguf path, which loads as itself; the server gates on the same suffix.
resident_variant = status_snapshot.get("gguf_variant")
if resident_variant and not str(requested).lower().endswith(".gguf"):
payload["gguf_variant"] = resident_variant
elif loaded_match is not None and not str(requested).lower().endswith(".gguf"):
# Same for a named model already served, read from the slot serving it.
- if status_snapshot.get("is_gguf") and status_snapshot.get("gguf_variant"):
+ if (
+ status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
+ ) and status_snapshot.get("gguf_variant"):
payload["gguf_variant"] = status_snapshot["gguf_variant"]
if "max_seq_length" in overrides:
payload["max_seq_length"] = load.max_seq_length
@@ -2553,6 +2574,14 @@ def _hf_offline() -> bool:
def _hub_gguf_files(repo: str) -> Optional[list]:
+ names = _hub_repo_files(repo)
+ if names is None:
+ return None
+ ggufs = [n for n in names if n.lower().endswith(".gguf")]
+ return [n for n in ggufs if not _is_auxiliary_gguf(n)]
+
+
+def _hub_repo_files(repo: str) -> Optional[list]:
if _hf_offline():
return None
endpoint = os.environ.get("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
@@ -2568,9 +2597,11 @@ def _hub_gguf_files(repo: str) -> Optional[list]:
siblings = info.get("siblings")
if not isinstance(siblings, list) or not siblings:
return None
- names = [s.get("rfilename") for s in siblings if isinstance(s, dict)]
- ggufs = [n for n in names if isinstance(n, str) and n.lower().endswith(".gguf")]
- return [n for n in ggufs if not _is_auxiliary_gguf(n)]
+ return [
+ s["rfilename"]
+ for s in siblings
+ if isinstance(s, dict) and isinstance(s.get("rfilename"), str)
+ ]
# Keep in sync with utils/gguf_names.py; the remote CLI cannot require backend imports.
@@ -2844,12 +2875,63 @@ def _fail_agent_needs_gguf(agent: _GgufAgent, model_id: str) -> NoReturn:
_fail(message)
+# Mirrors the frontend's NO_MLX_REASONS: an Apple Silicon host that still cannot load MLX.
+_NO_MLX_REASONS = frozenset(
+ {"mlx_unavailable", "no_torch", "intel_mac", "rosetta", "detection_failed"}
+)
+
+# Mirrors the backend's PRECISION_FOLDER_SOURCE: an MLX precision subfolder (6-bit/), not a GGUF quant.
+_MLX_PRECISION_FOLDER_RE = re.compile(
+ "(?:mlx[-_]?)?(?:[0-9]{1,2}[-_]?bits?(?:[-_][a-z0-9]+)*"
+ "|bf16|fp16|f16|fp32|f32|fp8|mxfp4|nvfp4)",
+ re.IGNORECASE,
+)
+
+
+def _asks_gguf_quant(variant: Optional[str]) -> bool:
+ return bool(variant) and not _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip())
+
+
+def _this_host_loads_mlx() -> bool:
+ import platform
+ return sys.platform == "darwin" and platform.machine() == "arm64"
+
+
+def _server_loads_mlx(base: str, key: str) -> bool:
+ deadline = time.monotonic() + 30
+ while True:
+ try:
+ health = _http_json("GET", f"{base}/api/health?detect_hardware=true", key, timeout = 30)
+ except Exception:
+ return False
+ if not (isinstance(health, dict) and health.get("hardware_detecting")):
+ break
+ if time.monotonic() >= deadline:
+ return False
+ time.sleep(1)
+ return (
+ isinstance(health, dict)
+ and health.get("device_type") == "mac"
+ and health.get("apple_silicon") is True
+ and health.get("chat_only_reason") not in _NO_MLX_REASONS
+ )
+
+
+def _refuse_non_gguf(
+ agent: _GgufAgent, model_id: str, base: str, key: str, variant: Optional[str]
+) -> None:
+ # A requested quant or a .gguf file asks for GGUF, which an MLX load would silently drop.
+ if variant or model_id.lower().endswith(".gguf") or not _server_loads_mlx(base, key):
+ _fail_agent_needs_gguf(agent, model_id)
+
+
def _preflight_agent_gguf(
agent: _GgufAgent,
model: Optional[str],
*,
serve: bool = True,
launch: bool = True,
+ gguf_variant: Optional[str] = None,
) -> None:
# Hub-listing preflight for the auto-start path only: with a server running, identifiers
# resolve against its cwd/cache/token, so _attach_gguf_check asks the server instead.
@@ -2864,7 +2946,7 @@ def _preflight_agent_gguf(
return
if find_studio_server() is not None:
return
- repo, _ = _split_repo_variant(model)
+ repo, inline_variant = _split_repo_variant(model)
# A bare foo.gguf naming no local file is a shorthand, canonicalized like any owner-less name.
if "/" not in repo and (not _is_model_path(repo) or repo.lower().endswith(".gguf")):
# The server canonicalizes owner-less shorthands to unsloth/<name>.
@@ -2877,8 +2959,14 @@ def _preflight_agent_gguf(
if not _is_hub_model_id(repo):
return
files = _hub_gguf_files(repo)
- if files is not None and not files:
+ variant = gguf_variant or inline_variant
+ asks_gguf = _asks_gguf_quant(variant) or repo.lower().endswith(".gguf")
+ if files is not None and not files and (asks_gguf or not _this_host_loads_mlx()):
_fail_agent_needs_gguf(agent, repo)
+ if files is not None and not files and variant:
+ names = _hub_repo_files(repo)
+ if names is not None and f"{variant.strip()}/config.json" not in names:
+ _fail(f"{repo} has no precision folder {variant}.")
def _attach_gguf_check(
@@ -2982,6 +3070,17 @@ def _attach_gguf_check(
):
continue
# Server answer from the load resolver settles the round, even empty: a root-blind lister can miss a file the load still finds.
+ # MLX precision folders download on load, so the downloaded-only allow-list does not apply.
+ if (
+ isinstance(variants, list)
+ and isinstance(info, dict)
+ and info.get("variant_format") == "mlx"
+ ):
+ folders = {row.get("quant") for row in variants if isinstance(row, dict)}
+ if variant and variant.strip() not in folders:
+ _fail_gguf_variant_missing(candidate, variant, variants)
+ _refuse_non_gguf(agent, candidate, base, key, None)
+ return
if isinstance(variants, list) and isinstance(info, dict):
offered = info.get("loadable_variants")
# No allow-list means a direct file, which loads as itself whatever the quant, so the variantless verdict decides.
@@ -2998,7 +3097,9 @@ def _attach_gguf_check(
return
if not variant and isinstance(info.get("loadable"), bool):
if not info["loadable"]:
- _fail_agent_needs_gguf(agent, candidate)
+ if variants:
+ _fail_agent_needs_gguf(agent, candidate)
+ _refuse_non_gguf(agent, candidate, base, key, variant)
return
if isinstance(variants, list) and variants:
# llama.cpp kills the resident model before resolving the quant, so settle it here; local answers take exact labels only.
@@ -3057,7 +3158,8 @@ def _attach_gguf_check(
return
except OSError:
return
- _fail_agent_needs_gguf(agent, candidate)
+ _refuse_non_gguf(agent, candidate, base, key, variant)
+ return
def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: str) -> None:
@@ -3074,7 +3176,7 @@ def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: st
return
is_gguf = status.get("is_gguf")
# InferenceStatusResponse declares is_gguf non-optional under a response_model, so a current server always sends it. Absent means "not that endpoint", never "non-GGUF".
- if is_gguf is None or is_gguf:
+ if is_gguf is None or is_gguf or status.get("is_mlx"):
return
# is_gguf carries a False default, so an idle server answers False while naming no model. The request that follows gets the server's own "No GGUF model loaded" anyway.
if not (status.get("active_model") or status.get("model_identifier")):
@@ -7576,7 +7678,9 @@ def claude(
else "curl -fsSL https://claude.ai/install.sh | bash"
)
# Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
- _preflight_agent_gguf(_CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch)
+ _preflight_agent_gguf(
+ _CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch, gguf_variant = gguf_variant
+ )
# Only a bare or resumed interactive launch is refused: its prompt is the stock one and the TUI would hide a warning. Other forwarded args (-p, --tools, a --no-launch recipe a driver extends) can shrink the prompt, so they only warn.
# CLAUDE_CODE_SIMPLE is the env form of --bare: a minimal prompt that may fit, so it only warns too.
simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").strip().lower() not in (
@@ -7767,7 +7871,9 @@ def codex(
)
install_hint = _npm_install_hint("@openai/codex")
# Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
- _preflight_agent_gguf(_CODEX_GGUF_AGENT, model, serve = serve, launch = launch)
+ _preflight_agent_gguf(
+ _CODEX_GGUF_AGENT, model, serve = serve, launch = launch, gguf_variant = gguf_variant
+ )
executable = _require_agent_for_launch("codex", install_hint, launch and not app)
version = executable and _codex_executable_version(executable)
if version and version < _CODEX_PROFILE_FILE_MIN_VERSION:
diff --git a/unsloth_cli/tests/test_start.py b/unsloth_cli/tests/test_start.py
index 385300c831e..ced47008fc1 100644
--- a/unsloth_cli/tests/test_start.py
+++ b/unsloth_cli/tests/test_start.py
@@ -37,6 +37,7 @@ from typer.testing import CliRunner
import unsloth_cli.commands.start as start
BASE = "http://127.0.0.1:8888"
+_REAL_SERVER_LOADS_MLX = start._server_loads_mlx
MODEL = {"id": "unsloth/gemma-4-26B-A4B-it-GGUF", "context_length": 131072}
@@ -1334,6 +1335,18 @@ def test_subagent_model_id_uses_loaded_variant(monkeypatch):
assert start._subagent_model_id(BASE, "key", MODEL, None, None) == MODEL["id"] + ":Q5_K_M"
+def test_subagent_model_id_keeps_a_bare_id_for_an_mlx_folder(monkeypatch):
+ monkeypatch.setattr(
+ start,
+ "_http_json",
+ lambda *args, **kwargs: {"is_gguf": False, "is_mlx": True, "gguf_variant": "bf16"},
+ )
+ entry = {"id": "mlx-community/Qwen3-4B"}
+ assert start._subagent_model_id(BASE, "key", entry, None, None) == "mlx-community/Qwen3-4B"
+ assert start._subagent_model_id(BASE, "key", entry, f"{entry['id']}:bf16", None) == entry["id"]
+ assert start._subagent_model_id(BASE, "key", entry, entry["id"], "bf16") == entry["id"]
+
+
def _kept_model_status(url):
# Primary Qwen3-4B at Q4_K_M, Qwen3-1.7B kept alongside at Q8_0.
if "model=unsloth%2FQwen3-1.7B-GGUF" in url:
@@ -4968,6 +4981,28 @@ def test_connect_gguf_only_agents_reject_non_gguf_model(fake_studio, monkeypatch
assert result.exit_code == 0, result.output
[email protected]("subcommand", ["claude", "codex"])
+def test_connect_gguf_only_agents_run_on_an_mlx_model(fake_studio, monkeypatch, subcommand):
+ inner = start._http_json
+
+ def http_json(
+ method,
+ url,
+ token,
+ payload = None,
+ timeout = 30,
+ error = None,
+ ):
+ if url.split("?")[0].endswith("/api/inference/status"):
+ return {"is_gguf": False, "is_mlx": True, "model_identifier": "unsloth/Qwen3-0.6B"}
+ return inner(method, url, token, payload, timeout, error)
+
+ monkeypatch.setattr(start, "_http_json", http_json)
+ result = CliRunner().invoke(start.start_app, [subcommand, "--no-launch"])
+ assert result.exit_code == 0, result.output
+ assert "needs a GGUF model" not in result.output
+
+
def test_connect_nonloopback_keyless_refuses_to_send_credential(fake_studio, monkeypatch):
monkeypatch.setattr(start, "find_studio_server", lambda: "http://studio.evil.example:8888")
result = CliRunner().invoke(start.start_app, ["opencode", "--no-launch"])
@@ -5239,6 +5274,13 @@ def _studio_is_this_machine(monkeypatch):
monkeypatch.setattr(start, "verify_studio_identity", lambda base, **_kw: True)
[email protected](autouse = True)
+def _gguf_only_host(monkeypatch):
+ # The GGUF gate defers on an MLX host, and this suite also runs on Apple Silicon.
+ monkeypatch.setattr(start, "_this_host_loads_mlx", lambda: False)
+ monkeypatch.setattr(start, "_server_loads_mlx", lambda base, key: False)
+
+
@pytest.fixture(autouse = True)
def _reset_auto_served():
# Never leave a fake server in the module slot: the atexit backstop would signal it.
@@ -5902,6 +5944,48 @@ def test_resolve_model_reload_option_keeps_the_running_quant(monkeypatch):
]
[email protected]("requested", ["mlx-community/Qwen3-4B", None])
+def test_resolve_model_reload_option_keeps_the_resident_mlx_folder(monkeypatch, requested):
+ repo = "mlx-community/Qwen3-4B"
+ models = [{"id": repo, "loaded": True}]
+ payloads = []
+
+ def load(base, key, model, load, payload):
+ payloads.append(payload)
+ return {"status": "loaded", "model": model}
+
+ status = {
+ "is_gguf": False,
+ "is_mlx": True,
+ "gguf_variant": "6-bit",
+ "active_model": repo,
+ "model_identifier": repo,
+ }
+ monkeypatch.setattr(start, "_loaded_models", lambda base, key: models)
+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: status)
+ monkeypatch.setattr(start, "_load_model_with_progress", load)
+
+ start._resolve_model(BASE, "key", requested, start.LoadOptions(max_seq_length = 8192))
+
+ assert [p.get("gguf_variant") for p in payloads] == ["6-bit"]
+
+
+def test_an_unchanged_mlx_folder_is_not_a_settings_change():
+ status = {"is_gguf": False, "is_mlx": True, "gguf_variant": "6-bit"}
+ assert not start._load_settings_differ(
+ status, start.LoadOptions(gguf_variant = "6-bit"), frozenset({"gguf_variant"})
+ )
+ assert start._load_settings_differ(
+ status, start.LoadOptions(gguf_variant = "8bit"), frozenset({"gguf_variant"})
+ )
+ assert start._load_settings_differ(
+ status, start.LoadOptions(gguf_variant = "6-BIT"), frozenset({"gguf_variant"})
+ )
+ assert start._resident_serves_variant(status, "6-bit")
+ assert not start._resident_serves_variant(status, "6-BIT")
+ assert start._resident_serves_variant({"is_gguf": True, "gguf_variant": "Q8_0"}, "q8_0")
+
+
def test_resolve_model_refused_load_reports_survivor(monkeypatch, capsys):
models = [{"id": "owner/model-GGUF", "loaded": True}]
@@ -11561,6 +11645,158 @@ def test_require_gguf_for_agent_reads_the_requested_models_slot(monkeypatch, cap
assert "Claude Code needs a GGUF model" in capsys.readouterr().err
+def test_require_gguf_for_agent_accepts_an_mlx_model(monkeypatch, capsys):
+ monkeypatch.setattr(
+ start,
+ "_http_json",
+ lambda *a, **k: {
+ "is_gguf": False,
+ "is_mlx": True,
+ "active_model": "mlx-community/Qwen3-4B-4bit",
+ },
+ )
+ for agent in (start._CLAUDE_GGUF_AGENT, start._CODEX_GGUF_AGENT):
+ start._require_gguf_for_agent(agent, BASE, "sk-test", "mlx-community/Qwen3-4B-4bit")
+ assert "needs a GGUF model" not in capsys.readouterr().err
+
+
+ ("health", "loads_mlx"),
+ [
+ ({"device_type": "mac", "apple_silicon": True, "chat_only_reason": None}, True),
+ (
+ {"device_type": "mac", "apple_silicon": True, "chat_only_reason": "mlx_unavailable"},
+ False,
+ ),
+ ({"device_type": "mac", "apple_silicon": False}, False),
+ ({"device_type": "linux", "apple_silicon": False}, False),
+ ({"status": "healthy"}, False),
+ (OSError("down"), False),
+ ],
+)
+def test_server_loads_mlx_reads_the_servers_platform(monkeypatch, health, loads_mlx):
+ urls = _fake_variants(monkeypatch, health)
+ assert _REAL_SERVER_LOADS_MLX(BASE, "sk-test") is loads_mlx
+ assert urls == [f"{BASE}/api/health?detect_hardware=true"]
+
+
+def test_server_loads_mlx_waits_out_hardware_detection(monkeypatch):
+ answers = iter(
+ [
+ {"status": "healthy", "hardware_detecting": True},
+ {"status": "healthy", "hardware_detecting": True},
+ {"device_type": "mac", "apple_silicon": True, "chat_only_reason": None},
+ ]
+ )
+ monkeypatch.setattr(start, "_http_json", lambda *a, **k: next(answers))
+ monkeypatch.setattr(start.time, "sleep", lambda s: None)
+ assert _REAL_SERVER_LOADS_MLX(BASE, "sk-test") is True
+
+
+def test_attach_check_defers_a_non_gguf_repo_on_an_mlx_server(monkeypatch, capsys):
+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)
+ monkeypatch.setattr(start, "_server_loads_mlx", lambda base, key: True)
+ _fake_variants(monkeypatch, {"variants": [], "has_vision": False})
+ start._attach_gguf_check(
+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "mlx-community/Qwen3-4B-4bit"
+ )
+ _fake_variants(monkeypatch, {"variants": [], "loadable": False})
+ start._attach_gguf_check(
+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "mlx-community/Qwen3-4B-4bit"
+ )
+ assert "needs a GGUF model" not in capsys.readouterr().err
+ _fake_variants(
+ monkeypatch,
+ {
+ "variants": [{"quant": "BF16", "filename": "BF16/model.gguf"}],
+ "loadable": False,
+ "loadable_variants": ["BF16"],
+ },
+ )
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "/models/Foo-GGUF")
+ _fake_variants(monkeypatch, {"variants": [], "loadable": None, "loadable_variants": None})
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(
+ start._CODEX_GGUF_AGENT, BASE, "sk-test", "mlx-community/Qwen3-4B-4bit", "Q8_0"
+ )
+ monkeypatch.setattr(start, "_direct_gguf_companion_is_uncertain", lambda repo: True)
+ _fake_variants(monkeypatch, {"variants": [], "loadable": False})
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(
+ start._CLAUDE_GGUF_AGENT, BASE, "sk-test", "/models/MTP/model-Q8_0-MTP.gguf"
+ )
+
+
+def test_claude_preflight_accepts_non_gguf_repo_on_an_mlx_host(monkeypatch, capsys):
+ _fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})
+ monkeypatch.setattr(start, "_this_host_loads_mlx", lambda: True)
+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit")
+ assert "needs a GGUF model" not in capsys.readouterr().err
+ with pytest.raises(typer.Exit):
+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit:Q8_0")
+ with pytest.raises(typer.Exit):
+ start._preflight_agent_gguf(
+ start._CLAUDE_GGUF_AGENT, "mlx-community/Qwen3-0.6B-4bit", gguf_variant = "Q8_0"
+ )
+
+
+def test_mlx_precision_folder_variant_runs_on_an_mlx_host(monkeypatch, capsys):
+ repo = "mlx-community/Qwen3-4B"
+ _fake_hub_listing(monkeypatch, {repo: []})
+ monkeypatch.setattr(
+ start,
+ "_hub_repo_files",
+ lambda repo: ["config.json", "6-bit/config.json", "8bit/config.json"],
+ )
+ monkeypatch.setattr(start, "_this_host_loads_mlx", lambda: True)
+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, f"{repo}:6-bit")
+ start._preflight_agent_gguf(start._CODEX_GGUF_AGENT, repo, gguf_variant = "8bit")
+ assert "needs a GGUF model" not in capsys.readouterr().err
+ with pytest.raises(typer.Exit):
+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, f"{repo}:4bit")
+ assert "has no precision folder 4bit" in capsys.readouterr().err
+ with pytest.raises(typer.Exit):
+ start._preflight_agent_gguf(start._CLAUDE_GGUF_AGENT, f"{repo}:8BIT")
+ monkeypatch.setattr(start, "_hub_gguf_files", lambda repo: None)
+ monkeypatch.setattr(start, "_server_loads_mlx", lambda base, key: True)
+ mlx_answer = {
+ "variants": [
+ {"quant": "6-bit", "filename": "6-bit/"},
+ {"quant": "8bit", "filename": "8bit/"},
+ ],
+ "loadable_variants": [],
+ "variant_format": "mlx",
+ }
+ _fake_variants(monkeypatch, mlx_answer)
+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", repo, "6-bit")
+ start._attach_gguf_check(start._CLAUDE_GGUF_AGENT, BASE, "sk-test", repo)
+ assert "needs a GGUF model" not in capsys.readouterr().err
+ for wanted in ("Q8_0", "4bit", "6-BIT"):
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", repo, wanted)
+ for answer in (
+ {"variants": [], "loadable": False},
+ {"variants": [], "loadable": None, "loadable_variants": None},
+ ):
+ _fake_variants(monkeypatch, answer)
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", repo, "6-bit")
+ _fake_variants(monkeypatch, mlx_answer)
+ monkeypatch.setattr(start, "_server_loads_mlx", lambda base, key: False)
+ with pytest.raises(typer.Exit):
+ start._attach_gguf_check(start._CODEX_GGUF_AGENT, BASE, "sk-test", repo, "6-bit")
+
+
+def test_mlx_precision_folder_pattern_matches_the_backend():
+ source = (
+ Path(start.__file__).resolve().parents[2] / "studio/backend/hub/utils/snapshot_filters.py"
+ ).read_text(encoding = "utf-8")
+ namespace = {}
+ exec(source[source.index("PRECISION_FOLDER_SOURCE =") :].split("\n)\n")[0] + "\n)", namespace)
+ assert start._MLX_PRECISION_FOLDER_RE.pattern == namespace["PRECISION_FOLDER_SOURCE"]
+
+
def test_claude_preflight_rejects_non_gguf_repo(monkeypatch, capsys):
_fake_hub_listing(monkeypatch, {"mlx-community/Qwen3-0.6B-4bit": []})
with pytest.raises(typer.Exit):