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.

14.0 KB
Raw Blame
# 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"})