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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""One mlx_unavailable verdict covers several packages, so the message must name the specific blocker."""
from __future__ import annotations
import sys
from pathlib import Path
import pytest
_BACKEND = Path(__file__).resolve().parent.parent
if str(_BACKEND) not in sys.path:
sys.path.insert(0, str(_BACKEND))
import utils.mlx_repair as mr # noqa: E402
def _fake_versions(monkeypatch, installed: dict[str, str]):
"""Report `installed` as the distributions present, and nothing else."""
from importlib.metadata import PackageNotFoundError
def version(name: str) -> str:
if name in installed:
return installed[name]
raise PackageNotFoundError(name)
monkeypatch.setattr("importlib.metadata.version", version)
def _healthy(**overrides: str) -> dict[str, str]:
"""Healthy means the mlx_repair floors, so raising a floor does not break unrelated tests."""
return {**mr._MLX_MIN_VERSIONS, **overrides}
def test_a_healthy_stack_reports_no_blockers(monkeypatch):
_fake_versions(monkeypatch, _healthy())
monkeypatch.setattr(mr, "_mlx_runtime_import_blocker", lambda: None)
assert mr.mlx_stack_blockers() == []
assert mr.mlx_stack_available() is True
def test_a_missing_package_is_named_with_the_version_it_needs(monkeypatch):
_fake_versions(monkeypatch, {k: v for k, v in _healthy().items() if k != "mlx-vlm"})
monkeypatch.setattr(mr, "_mlx_runtime_import_blocker", lambda: None)
blockers = mr.mlx_stack_blockers()
assert any("mlx-vlm is not installed" in blocker for blocker in blockers)
assert any("0.4.4" in blocker for blocker in blockers)
assert mr.mlx_stack_available() is False
def test_a_backtracked_package_names_the_version_it_found(monkeypatch):
_fake_versions(monkeypatch, _healthy(**{"mlx-vlm": "0.1.0"}))
monkeypatch.setattr(mr, "_mlx_runtime_import_blocker", lambda: None)
blockers = mr.mlx_stack_blockers()
assert blockers == ["mlx-vlm 0.1.0 is older than 0.4.4"]
def test_every_bad_package_is_listed_not_just_the_first(monkeypatch):
_fake_versions(monkeypatch, {"mlx": "0.1.0"})
monkeypatch.setattr(mr, "_mlx_runtime_import_blocker", lambda: None)
blockers = mr.mlx_stack_blockers()
assert len(blockers) == 3, blockers
def test_an_import_that_raises_is_reported_with_its_error(monkeypatch):
# Versions satisfied but import fails, as with an mlx-vlm built against another transformers.
_fake_versions(monkeypatch, _healthy())
def explode(module: str):
raise ImportError("cannot import name 'AutoProcessor' from 'transformers'")
monkeypatch.setattr(mr.importlib, "import_module", explode)
blockers = mr.mlx_stack_blockers()
assert len(blockers) == 1
assert "does not import" in blockers[0]
assert "AutoProcessor" in blockers[0]
assert mr.mlx_stack_available() is False
def test_versions_are_checked_before_imports(monkeypatch):
"""A too-old package must be named without loading it into this process."""
_fake_versions(monkeypatch, _healthy(**{"mlx-vlm": "0.1.0"}))
def never(module: str):
raise AssertionError("imported a package the version check already rejected")
monkeypatch.setattr(mr.importlib, "import_module", never)
assert mr.mlx_stack_blockers() == ["mlx-vlm 0.1.0 is older than 0.4.4"]
def test_the_detail_line_never_raises_and_stays_short(monkeypatch):
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "_MLX_BLOCKERS_MEASURED", None)
def explode() -> list[str]:
raise RuntimeError("no")
monkeypatch.setattr(mr, "mlx_stack_blockers", explode)
assert hw._mlx_stack_detail() is None
monkeypatch.setattr(mr, "mlx_stack_blockers", lambda: [])
assert hw._mlx_stack_detail() is None
monkeypatch.setattr(mr, "mlx_stack_blockers", lambda: ["a", "b", "c", "d"])
detail = hw._mlx_stack_detail()
assert detail == "a; b; c"
@pytest.mark.parametrize("reason", ["intel_mac", "no_gpu", "detection_failed", None])
def test_only_the_mlx_verdict_carries_a_detail(monkeypatch, reason):
"""Nothing else has anything specific to add, so nothing else may claim to."""
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "CHAT_ONLY_REASON", reason)
monkeypatch.setattr(hw, "CHAT_ONLY_DETAIL", None)
assert hw.CHAT_ONLY_DETAIL is None
def test_a_failed_forced_redetect_restores_the_detail(monkeypatch):
"""A failed forced re-detect must restore the blocker detail too, not just the mlx_unavailable
verdict."""
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "DEVICE", hw.DeviceType.CPU)
monkeypatch.setattr(hw, "CHAT_ONLY", True)
monkeypatch.setattr(hw, "CHAT_ONLY_REASON", "mlx_unavailable")
monkeypatch.setattr(hw, "CHAT_ONLY_DETAIL", "mlx-vlm 0.1.0 is older than 0.4.4")
hw.DETECTION_COMPLETE.set()
def explode():
hw.CHAT_ONLY_REASON = None
hw.CHAT_ONLY_DETAIL = None
raise RuntimeError("probe died")
monkeypatch.setattr(hw, "_detect_hardware_locked", explode)
with pytest.raises(RuntimeError):
hw.detect_hardware()
assert hw.CHAT_ONLY_REASON == "mlx_unavailable"
assert hw.CHAT_ONLY_DETAIL == "mlx-vlm 0.1.0 is older than 0.4.4"
def test_a_discarded_verdict_takes_the_detail_with_it(monkeypatch):
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "CHAT_ONLY_REASON", "mlx_unavailable")
monkeypatch.setattr(hw, "CHAT_ONLY_DETAIL", "mlx-lm is not installed (needs >=0.31.2)")
hw._discard_detection_locked()
assert hw.CHAT_ONLY_REASON is None
assert hw.CHAT_ONLY_DETAIL is None
def test_health_reads_the_detail_inside_the_guarded_snapshot(monkeypatch):
"""A forced re-detect starting mid-read must not pair one pass's reason with another's
detail, which is what reading the global after the snapshot allowed."""
import main
monkeypatch.setattr(main._hw_module, "DEVICE", main._hw_module.DeviceType.CPU)
monkeypatch.setattr(main._hw_module, "CHAT_ONLY", True)
monkeypatch.setattr(main._hw_module, "CHAT_ONLY_REASON", "mlx_unavailable")
monkeypatch.setattr(main._hw_module, "CHAT_ONLY_DETAIL", "mlx-vlm 0.1.0 is older than 0.4.4")
main._hw_module.DETECTION_COMPLETE.set()
snapshot = main._hardware_snapshot()
assert snapshot is not None
assert len(snapshot) == 3, "the detail has to come out of the same guarded read"
assert snapshot[1] == "mlx_unavailable"
assert snapshot[2] == "mlx-vlm 0.1.0 is older than 0.4.4"
monkeypatch.setattr(main._hw_module, "CHAT_ONLY_DETAIL", None)
assert snapshot[2] == "mlx-vlm 0.1.0 is older than 0.4.4"
# The mlx imports may hang, so the gate and the detail share one measurement.
def test_the_gate_measures_the_stack_once(monkeypatch):
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "_MLX_BLOCKERS_MEASURED", None)
calls: list[int] = []
def counted() -> list[str]:
calls.append(1)
return ["mlx-vlm 0.1.0 is older than 0.4.4"]
monkeypatch.setattr(mr, "mlx_stack_blockers", counted)
assert hw._has_usable_mlx_stack() is False
assert hw._mlx_stack_detail() == "mlx-vlm 0.1.0 is older than 0.4.4"
assert len(calls) == 1, f"the stack was probed {len(calls)} times for one verdict"
def test_a_measurement_is_used_once_and_not_kept(monkeypatch):
"""A list left over from an earlier pass describes a stack since re-measured."""
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "_MLX_BLOCKERS_MEASURED", None)
monkeypatch.setattr(mr, "mlx_stack_blockers", lambda: ["mlx is not installed"])
hw._has_usable_mlx_stack()
assert hw._mlx_stack_detail() == "mlx is not installed"
assert hw._MLX_BLOCKERS_MEASURED is None
monkeypatch.setattr(mr, "mlx_stack_blockers", lambda: ["mlx-lm is not installed"])
assert hw._mlx_stack_detail() == "mlx-lm is not installed"
def test_a_healthy_gate_still_reads_as_usable(monkeypatch):
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "_MLX_BLOCKERS_MEASURED", None)
monkeypatch.setattr(mr, "mlx_stack_blockers", lambda: [])
assert hw._has_usable_mlx_stack() is True
def test_an_unreadable_gate_falls_back_to_the_bare_import(monkeypatch):
"""mlx_repair should always import; a host where it cannot is not forced chat-only."""
from utils.hardware import hardware as hw
monkeypatch.setattr(hw, "_MLX_BLOCKERS_MEASURED", ["stale"])
def explode() -> list[str]:
raise RuntimeError("mlx_repair is unimportable")
monkeypatch.setattr(mr, "mlx_stack_blockers", explode)
monkeypatch.setattr(hw, "_has_mlx", lambda: True)
assert hw._has_usable_mlx_stack() is True
assert hw._MLX_BLOCKERS_MEASURED is None
# Blocker lines go to /api/health and a native tooltip, so they stay one bounded line.
def test_a_long_import_error_is_folded_to_one_bounded_line(monkeypatch):
_fake_versions(monkeypatch, _healthy())
def explode(module: str):
raise ImportError(
"dlopen failed:\n tried: '/opt/one/lib.so' (no such file)\n"
" tried: '/opt/two/lib.so' (mach-o, but wrong architecture)\n" + "x" * 400
)
monkeypatch.setattr(mr.importlib, "import_module", explode)
blocker = mr.mlx_stack_blockers()[0]
assert "\n" not in blocker
assert len(blocker) < 200, f"{len(blocker)} chars reaches the tooltip: {blocker}"
assert blocker.endswith("...)"), blocker
assert blocker.startswith("mlx.core does not import (ImportError:")
def test_a_malformed_installed_version_is_bounded_too(monkeypatch):
"""Version metadata is read from disk, and an interrupted install can leave junk."""
junk = "1.0\n" + "y" * 500
_fake_versions(monkeypatch, _healthy(mlx = junk))
monkeypatch.setattr(mr, "_mlx_runtime_import_blocker", lambda: None)
blocker = mr.mlx_stack_blockers()[0]
assert "\n" not in blocker
assert len(blocker) < 200, f"{len(blocker)} chars reaches the tooltip"
assert blocker.startswith("mlx 1.0 y")
def _fake_hardware(monkeypatch, calls: list[str]):
"""Stand the real hardware module's re-detection down, keeping the module identity."""
from utils.hardware import hardware as hw
from contextlib import nullcontext
monkeypatch.setattr(hw, "detect_hardware", lambda: calls.append("detect"))
monkeypatch.setattr(hw, "owning_detection_epoch", lambda epoch: nullcontext())
monkeypatch.setattr(hw, "current_detection_epoch", lambda: None)
return hw
def test_a_repair_that_failed_validation_still_remeasures(monkeypatch):
called: list[str] = []
_fake_hardware(monkeypatch, called)
monkeypatch.setattr(mr, "attempt_mlx_repair", lambda: False)
monkeypatch.setattr(mr, "_environment_mutated", True)
mr._run_repair_and_redetect()
assert called == ["detect"], "the stale detail was left describing a replaced stack"
def test_a_repair_that_never_ran_does_not_remeasure(monkeypatch):
"""Nothing changed, so re-running the mlx imports would cost latency for nothing."""
called: list[str] = []
_fake_hardware(monkeypatch, called)
monkeypatch.setattr(mr, "attempt_mlx_repair", lambda: False)
monkeypatch.setattr(mr, "_environment_mutated", False)
mr._run_repair_and_redetect()
assert called == []
def test_a_successful_repair_still_remeasures(monkeypatch):
called: list[str] = []
_fake_hardware(monkeypatch, called)
monkeypatch.setattr(mr, "attempt_mlx_repair", lambda: True)
monkeypatch.setattr(mr, "_environment_mutated", True)
mr._run_repair_and_redetect()
assert called == ["detect"]
# uv --reinstall-package replaces as it goes: a mid-way failure already changed the stack.
@pytest.mark.parametrize(
"outcome",
["timeout", "nonzero"],
)
def test_an_install_that_died_part_way_still_counts_as_mutating(monkeypatch, outcome):
import subprocess as sp
monkeypatch.setattr(mr, "_environment_mutated", False)
monkeypatch.setattr(mr, "_uv_install_cmd", lambda *a, **k: ["uv", "pip", "install"])
monkeypatch.setattr(mr, "_transformers_constraint_args", lambda: ([], None))
monkeypatch.setattr(mr, "_mlx_install_env", dict)
def run(*a, **k):
if outcome == "timeout":
raise sp.TimeoutExpired(cmd = "uv", timeout = 1)
return sp.CompletedProcess(args = "uv", returncode = 1, stdout = "boom")
monkeypatch.setattr(mr.subprocess, "run", run)
assert mr.attempt_mlx_repair() is False
assert mr._environment_mutated is True, (
"a half-applied reinstall leaves the pre-repair detail describing a stack that "
"is no longer on disk"
)
def test_a_venv_uv_refuses_is_not_marked_mutated(monkeypatch):
"""uv gave up before resolving an interpreter, so it installed nothing."""
import subprocess as sp
monkeypatch.setattr(mr, "_environment_mutated", False)
monkeypatch.setattr(mr, "_uv_install_cmd", lambda *a, **k: ["uv", "pip", "install"])
monkeypatch.setattr(mr, "_transformers_constraint_args", lambda: ([], None))
monkeypatch.setattr(mr, "_mlx_install_env", dict)
monkeypatch.setattr(
mr.subprocess,
"run",
lambda *a, **k: sp.CompletedProcess(
args = "uv",
returncode = 2,
stdout = mr._UNRESOLVED_PYTHON_MARKER + " at /x",
),
)
assert mr.attempt_mlx_repair() is False
assert mr._environment_mutated is False
def test_uv_missing_never_marks_the_environment(monkeypatch):
monkeypatch.setattr(mr, "_environment_mutated", False)
monkeypatch.setattr(mr, "_uv_install_cmd", lambda *a, **k: None)
monkeypatch.setattr(mr, "_transformers_constraint_args", lambda: ([], None))
assert mr.attempt_mlx_repair() is False
assert mr._environment_mutated is False
def test_a_missing_grammar_engine_names_the_package_instead_of_ignoring_the_schema(monkeypatch):
from core.inference import grammar_constraint as gc
monkeypatch.setattr(gc, "LLGUIDANCE_AVAILABLE", False)
with pytest.raises(gc.ResponseFormatError, match = "llguidance"):
gc.constraint_spec_from_response_format({"type": "json_object"})