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.

30.7 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

"""Tests for the diffusion engine router (diffusers vs native sd.cpp selection)."""

from __future__ import annotations

from types import SimpleNamespace

import pytest

from core.inference import diffusion_engine_router as r
from core.inference.diffusion_families import detect_family
from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_SD_CPP

_ENVS = (
    "UNSLOTH_DIFFUSION_ENGINE",
    "UNSLOTH_DIFFUSION_SD_CPP",
    "UNSLOTH_DIFFUSION_SD_CPP_MPS",
    "UNSLOTH_DIFFUSION_SD_CPP_INSTALL",
)


@pytest.fixture(autouse = True)
def _clean_env_and_state(monkeypatch):
    r._supported_family_capabilities.cache_clear()
    for e in _ENVS:
        monkeypatch.delenv(e, raising = False)
    # Light stub so selection never imports the heavy diffusers or sd.cpp backends.
    monkeypatch.setattr(
        r,
        "get_active_diffusion_engine",
        lambda: SimpleNamespace(
            status = lambda: {"loaded": False, "repo_id": None}, unload = lambda: None
        ),
    )
    monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
    monkeypatch.setattr(r, "_server_binary_runnable", lambda *_a, **_k: True)
    # Module state set by plain assignment; monkeypatch cannot undo it, so save and restore.
    saved_engine = r._active_engine_name
    saved_reason = r._fallback_reason
    saved_pick = r._engine_pick
    saved_pending = r._pending_engine_pick
    try:
        yield
    finally:
        r._active_engine_name = saved_engine
        r._fallback_reason = saved_reason
        r._engine_pick = saved_pick
        r._pending_engine_pick = saved_pending
        r._supported_family_capabilities.cache_clear()


def _set_device(monkeypatch, backend):
    monkeypatch.setattr(
        r,
        "resolve_diffusion_device_target",
        lambda: SimpleNamespace(backend = backend, device = backend),
    )


def _set_binary(monkeypatch, path):
    monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: path)


def _set_runnable(monkeypatch, version = "sd-cli v0"):
    """Stub the runnability probe so a stubbed binary path is treated as executable
    (the router now probes ``SdCppEngine(...).version()`` before committing to native)."""
    monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: version))


def _select(fam_name = "z-image"):
    """Activate the engine for a family and return which engine was chosen."""
    r.select_and_activate_engine(detect_family(fam_name))
    return r.active_engine_name()


def test_cpu_with_binary_and_supported_family_picks_sd_cpp(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    assert _select() == ENGINE_SD_CPP
    assert r.active_engine_name() == ENGINE_SD_CPP


def test_cpu_with_only_sd_server_picks_sd_cpp(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, None)
    monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: None))
    monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: "/usr/bin/sd-server")
    assert _select() == ENGINE_SD_CPP


def test_present_but_not_runnable_binary_falls_back(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: None))
    assert _select() == ENGINE_DIFFUSERS
    assert "binary unavailable" in (r.active_status()["fallback_reason"] or "")


@pytest.mark.parametrize("gpu", ["cuda", "rocm", "xpu"])
def test_gpu_backends_use_diffusers(monkeypatch, gpu):
    _set_device(monkeypatch, gpu)
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    assert _select() == ENGINE_DIFFUSERS
    assert "uses diffusers" in (r.active_status()["fallback_reason"] or "")


def test_forced_diffusers_overrides_cpu(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "diffusers")
    assert _select() == ENGINE_DIFFUSERS
    assert "forced" in (r.active_status()["fallback_reason"] or "")


def test_sd_cpp_disabled_uses_diffusers(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP", "0")
    assert _select() == ENGINE_DIFFUSERS
    assert "disabled" in (r.active_status()["fallback_reason"] or "")


def test_mps_default_diffusers_but_optin_sd_cpp(monkeypatch):
    _set_device(monkeypatch, "mps")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    assert _select() == ENGINE_DIFFUSERS
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MPS", "1")
    assert _select() == ENGINE_SD_CPP


def test_unsupported_family_falls_back(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    monkeypatch.setattr(r, "family_sd_cpp_supported", lambda fam: False)
    assert _select() == ENGINE_DIFFUSERS
    assert "no native sd.cpp asset mapping" in (r.active_status()["fallback_reason"] or "")


def test_missing_binary_falls_back(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, None)
    assert _select() == ENGINE_DIFFUSERS
    assert "binary unavailable" in (r.active_status()["fallback_reason"] or "")


def test_force_sd_cpp_on_gpu_when_binary_present(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "sd_cpp")
    assert _select() == ENGINE_SD_CPP


def test_force_sd_cpp_without_binary_falls_back(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, None)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "sd_cpp")
    assert _select() == ENGINE_DIFFUSERS


@pytest.mark.parametrize(
    "backend, expected",
    [("rocm", "rocm"), ("cuda", "cuda"), ("xpu", "vulkan"), ("cpu", "auto"), ("mps", "auto")],
)
def test_install_accelerator_maps_backend(backend, expected):
    assert r._install_accelerator_for(backend) == expected


def test_force_native_install_uses_gpu_accelerator(monkeypatch):
    # Forcing sd_cpp on a ROCm host with no binary must install the ROCm build, else the forced-native generation silently runs on CPU.
    _set_device(monkeypatch, "rocm")
    _set_runnable(monkeypatch)
    seen = {}

    def _fake_ensure(**kwargs):
        seen.update(kwargs)
        return "/usr/bin/sd-cli"

    monkeypatch.setattr(r, "ensure_sd_cpp_binary", _fake_ensure)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "sd_cpp")
    assert _select() == ENGINE_SD_CPP
    assert seen.get("accelerator") == "rocm"


def test_active_status_injects_engine_and_reason(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, None)
    _select()
    st = r.active_status()
    assert st["engine"] == ENGINE_DIFFUSERS
    assert st["fallback_reason"] and "binary unavailable" in st["fallback_reason"]


def test_status_family_capabilities_are_probed_once(monkeypatch):
    calls = []
    monkeypatch.setattr(
        r,
        "pipeline_available_family_names",
        lambda: calls.append("probe") or ("z-image", "flux.1"),
    )

    assert r.active_status()["supported_families"] == ["z-image", "flux.1"]
    assert r.active_status()["supported_families"] == ["z-image", "flux.1"]
    assert calls == ["probe"]


def test_switch_unloads_old_engine_before_publishing_new(monkeypatch):
    # The evictor unloads the active engine, so publish the new one only after the old unloaded.
    seen = {}

    def _fake_engine():
        return SimpleNamespace(
            unload = lambda: seen.__setitem__("active_during_unload", r.active_engine_name()),
            status = lambda: {"loaded": False, "repo_id": None},
        )

    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: _fake_engine())
    r._active_engine_name = ENGINE_SD_CPP
    r._activate(ENGINE_DIFFUSERS, "switch test")
    assert seen["active_during_unload"] == ENGINE_SD_CPP
    assert r.active_engine_name() == ENGINE_DIFFUSERS


def test_no_switch_keeps_engine_and_refreshes_reason(monkeypatch):
    calls = {"unload": 0}

    def _fake_engine():
        return SimpleNamespace(
            unload = lambda: calls.__setitem__("unload", calls["unload"] + 1),
            status = lambda: {"loaded": False, "repo_id": None},
        )

    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: _fake_engine())
    r._active_engine_name = ENGINE_DIFFUSERS
    r._activate(ENGINE_DIFFUSERS, "still diffusers")
    assert calls["unload"] == 0
    assert r.active_engine_name() == ENGINE_DIFFUSERS
    assert r.active_status()["fallback_reason"] == "still diffusers"


def test_activate_serializes_switch_and_concurrent_query(monkeypatch):
    # Regression: without the transition lock a second _activate during a slow unload() reads the stale active engine, so the query must block until the switch ends.
    import threading

    r._active_engine_name = ENGINE_DIFFUSERS
    r._fallback_reason = None

    release_unload = threading.Event()
    unload_started = threading.Event()

    def _slow_unload():
        unload_started.set()
        release_unload.wait(2.0)

    engine = SimpleNamespace(status = lambda: {"loaded": False, "repo_id": None}, unload = _slow_unload)
    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: engine)

    switch_done = threading.Event()

    def _switch():
        r._activate(ENGINE_SD_CPP, None)
        switch_done.set()

    t = threading.Thread(target = _switch)
    t.start()
    assert unload_started.wait(2.0)

    query_done = threading.Event()

    def _query():
        r._activate(ENGINE_DIFFUSERS, None)
        query_done.set()

    q = threading.Thread(target = _query)
    q.start()
    assert not query_done.wait(0.4)

    release_unload.set()
    t.join(2.0)
    q.join(2.0)
    assert switch_done.is_set() and query_done.is_set()


def test_begin_load_on_refuses_an_engine_that_was_switched_away(monkeypatch):
    # Engine capture and registration must be atomic: a competing switch can unload it in between.
    diffusers = SimpleNamespace(name = "diffusers")
    sd_cpp = SimpleNamespace(name = "sd_cpp")
    active = {"engine": diffusers}
    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: active["engine"])

    started: list[str] = []
    assert r.begin_load_on(diffusers, lambda: started.append("ok") or "status") == "status"
    assert started == ["ok"]

    active["engine"] = sd_cpp
    with pytest.raises(RuntimeError, match = "engine changed"):
        r.begin_load_on(diffusers, lambda: started.append("leaked"))
    assert started == ["ok"]


def test_begin_load_on_holds_the_transition_lock_while_registering(monkeypatch):
    import threading

    engine = SimpleNamespace(name = "diffusers")
    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: engine)

    inside = threading.Event()
    release = threading.Event()

    def _slow_start():
        inside.set()
        release.wait(2.0)
        return "status"

    t = threading.Thread(target = lambda: r.begin_load_on(engine, _slow_start))
    t.start()
    assert inside.wait(2.0)
    assert r._transition_lock.locked()
    release.set()
    t.join(2.0)


def test_switch_aborts_when_the_old_engine_fails_to_unload(monkeypatch):
    # A failed teardown keeps the old engine published so the resident model stays reclaimable.
    def _fake_engine():
        def _boom():
            raise RuntimeError("sd-server would not die")

        return SimpleNamespace(unload = _boom, status = lambda: {"loaded": True, "repo_id": "x"})

    monkeypatch.setattr(r, "get_active_diffusion_engine", lambda: _fake_engine())
    r._active_engine_name = ENGINE_SD_CPP
    with pytest.raises(RuntimeError, match = "Could not switch the diffusion engine"):
        r._activate(ENGINE_DIFFUSERS, "switch test")
    assert r.active_engine_name() == ENGINE_SD_CPP


def test_predict_engine_matches_the_selection_without_activating(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    r._active_engine_name = ENGINE_DIFFUSERS
    assert r.predict_engine(detect_family("z-image"), model_kind = "gguf") == ENGINE_SD_CPP
    assert r.active_engine_name() == ENGINE_DIFFUSERS


def test_predict_engine_counts_an_installable_binary_as_available(monkeypatch):
    # The first native load installs the binary, so predict native even with nothing on disk.
    _set_device(monkeypatch, "cpu")
    installs: list[dict] = []

    def _ensure(**kwargs):
        installs.append(kwargs)
        return None

    monkeypatch.setattr(r, "ensure_sd_cpp_binary", _ensure)
    monkeypatch.setattr(r, "ensure_sd_server_binary", _ensure)
    assert r.predict_engine(detect_family("z-image"), model_kind = "gguf") == ENGINE_SD_CPP
    assert installs and all(k.get("allow_install") is False for k in installs)


def test_predict_engine_falls_back_when_install_is_disabled_and_nothing_is_installed(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_INSTALL", "0")
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, None)
    monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
    assert r.predict_engine(detect_family("z-image"), model_kind = "gguf") == ENGINE_DIFFUSERS


@pytest.mark.parametrize(
    "kwargs, device",
    [
        ({"model_kind": "pipeline"}, "cpu"),  # native is GGUF-only
        ({"model_kind": "single_file"}, "cpu"),
        ({"model_kind": "gguf"}, "cuda"),  # a usable GPU always means diffusers
    ],
)
def test_predict_engine_returns_diffusers_where_the_load_would(monkeypatch, kwargs, device):
    _set_device(monkeypatch, device)
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    assert r.predict_engine(detect_family("z-image"), **kwargs) == ENGINE_DIFFUSERS


def test_predict_engine_returns_diffusers_for_a_family_without_native_assets(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    assert r.predict_engine(detect_family("sdxl"), model_kind = "gguf") == ENGINE_DIFFUSERS


def _write_binary(tmp_path, name, *, marker: bool):
    """A stand-in sd.cpp executable, with or without the 2.1 architecture literal in it."""
    path = tmp_path / name
    body = b"ELF-ish padding " * 64
    if marker:
        body += b"qwen_image_2_1.hpp"
    path.write_bytes(body + b" trailing")
    return str(path)


def test_a_build_that_predates_the_family_does_not_get_the_native_route(monkeypatch, tmp_path):
    # Old runnable sd.cpp builds are never upgraded and may lack newer architectures (Qwen-Image-2.1).
    _set_device(monkeypatch, "cpu")
    _set_runnable(monkeypatch)
    _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old", marker = False))
    assert _select("qwen-image-2.1") == ENGINE_DIFFUSERS
    assert "predates" in (r._fallback_reason or "")

    _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-new", marker = True))
    assert _select("qwen-image-2.1") == ENGINE_SD_CPP


def test_the_gate_only_speaks_for_families_that_declare_a_marker(monkeypatch, tmp_path):
    # Families with no marker (z-image) must still route native: no marker is not "cannot run".
    _set_device(monkeypatch, "cpu")
    _set_runnable(monkeypatch)
    _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old2", marker = False))
    assert _select("z-image") == ENGINE_SD_CPP


def test_the_prediction_agrees_with_the_selection_about_an_incapable_build(monkeypatch, tmp_path):
    _set_device(monkeypatch, "cpu")
    _set_runnable(monkeypatch)
    _set_binary(monkeypatch, _write_binary(tmp_path, "sd-cli-old3", marker = False))
    fam = detect_family("qwen-image-2.1")
    assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_DIFFUSERS
    _set_binary(monkeypatch, None)
    monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
    assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_SD_CPP


def test_the_prediction_counts_the_upgrade_a_load_performs_for_a_moved_pin(monkeypatch, tmp_path):
    # #12470: the load replaces a moved-pin build before selecting, so the plan must not stage diffusers.
    _set_device(monkeypatch, "cpu")
    _set_runnable(monkeypatch)
    old = _write_binary(tmp_path, "sd-cli-old4", marker = False)
    _set_binary(monkeypatch, old)
    monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
    moved: list = []
    monkeypatch.setattr(r, "_pin_moved", lambda binary, accel: moved.append(binary) or True)
    fam = detect_family("qwen-image-2.1")
    assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_SD_CPP
    assert moved == [old]
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_INSTALL", "0")
    assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_DIFFUSERS


# ── per-load engine pick (/images/load's ``engine``) ──────────────────────────


def _select_with(fam_name = "z-image", **kwargs):
    r.select_and_activate_engine(detect_family(fam_name), **kwargs)
    return r.active_engine_name()


def test_a_load_can_ask_for_native_on_a_gpu_host(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    # Auto keeps the GPU host's own choice; the pick moves only this load.
    assert _select_with(model_kind = "gguf") == ENGINE_DIFFUSERS
    assert _select_with(model_kind = "gguf", engine = "auto") == ENGINE_DIFFUSERS
    assert _select_with(model_kind = "gguf", engine = "sd_cpp") == ENGINE_SD_CPP
    assert (
        r.predict_engine(detect_family("z-image"), model_kind = "gguf", engine = "sd_cpp")
        == ENGINE_SD_CPP
    )
    assert _select_with(model_kind = "gguf") == ENGINE_DIFFUSERS


def test_a_load_can_ask_for_diffusers_on_a_cpu_host(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    assert _select_with(model_kind = "gguf") == ENGINE_SD_CPP
    assert _select_with(model_kind = "gguf", engine = "diffusers") == ENGINE_DIFFUSERS
    assert r._fallback_reason == "selected for this load"
    assert (
        r.predict_engine(detect_family("z-image"), model_kind = "gguf", engine = "diffusers")
        == ENGINE_DIFFUSERS
    )


def test_a_native_pick_that_cannot_run_is_refused_before_any_unload(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, None)
    unloads = []
    monkeypatch.setattr(
        r,
        "get_active_diffusion_engine",
        lambda: SimpleNamespace(status = lambda: {"loaded": True}, unload = lambda: unloads.append(1)),
    )
    r._active_engine_name = ENGINE_DIFFUSERS
    fallbacks = []
    with pytest.raises(
        ValueError,
        match = "native sd.cpp engine cannot load this model here: native sd.cpp binary unavailable",
    ):
        _select_with(
            model_kind = "gguf", engine = "sd_cpp", before_fallback = lambda: fallbacks.append(1)
        )
    assert unloads == [] and fallbacks == [] and r.active_engine_name() == ENGINE_DIFFUSERS
    # Without a pick the old silent fallback stands.
    assert _select_with(model_kind = "gguf") == ENGINE_DIFFUSERS


@pytest.mark.parametrize(
    "fam_name, kind, engine, match",
    [
        ("z-image", "pipeline", "sd_cpp", "GGUF models only"),
        ("lumina-2", "gguf", "sd_cpp", "no support for the lumina-2 model family"),
    ],
)
def test_native_picks_the_engine_cannot_serve_are_refused(
    monkeypatch, fam_name, kind, engine, match
):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    with pytest.raises(ValueError, match = match):
        r.refuse_engine_pick(detect_family(fam_name), engine = engine, model_kind = kind)
    with pytest.raises(ValueError, match = match):
        _select_with(fam_name, model_kind = kind, engine = engine)


def test_a_diffusers_pick_needs_the_pipeline_class(monkeypatch):
    monkeypatch.setattr(r, "family_pipeline_available", lambda fam: False)
    with pytest.raises(ValueError, match = "Diffusers cannot build the z-image model family"):
        r.refuse_engine_pick(detect_family("z-image"), engine = "diffusers", model_kind = "gguf")
    r.refuse_engine_pick(detect_family("z-image"), engine = "auto", model_kind = "gguf")
    r.refuse_engine_pick(detect_family("z-image"), engine = None, model_kind = "gguf")


def test_an_unknown_engine_pick_is_refused():
    with pytest.raises(ValueError, match = "engine must be one of auto, diffusers, sd_cpp"):
        r.refuse_engine_pick(detect_family("z-image"), engine = "vulkan", model_kind = "gguf")


def test_the_env_override_wins_over_a_load_pick(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "diffusers")
    assert _select_with(model_kind = "gguf", engine = "sd_cpp") == ENGINE_DIFFUSERS
    # Not refused either: the pin decides, and the status says so.
    r.refuse_engine_pick(detect_family("lumina-2"), engine = "sd_cpp", model_kind = "gguf")
    assert r.engine_choice_status({"loaded": False})["engine_forced"] == ENGINE_DIFFUSERS


@pytest.mark.parametrize(
    "status, eligible, lora",
    [
        # A FLUX.2 klein GGUF on diffusers: LoRA hidden there, applies natively.
        (
            {
                "loaded": True,
                "model_kind": "gguf",
                "family": "flux.2-klein",
                "engine": "diffusers",
                "supports_lora": False,
            },
            True,
            True,
        ),
        # Already native.
        (
            {
                "loaded": True,
                "model_kind": "gguf",
                "family": "flux.2-klein",
                "engine": "sd_cpp",
                "supports_lora": True,
            },
            True,
            False,
        ),
        # Qwen-Image runs natively but sd.cpp applies no LoRA to it.
        (
            {
                "loaded": True,
                "model_kind": "gguf",
                "family": "qwen-image",
                "engine": "diffusers",
                "supports_lora": False,
            },
            True,
            False,
        ),
        # A pipeline pick is diffusers-only.
        (
            {
                "loaded": True,
                "model_kind": "pipeline",
                "family": "flux.2-klein",
                "engine": "diffusers",
                "supports_lora": True,
            },
            False,
            False,
        ),
        # No sd.cpp assets for the family.
        (
            {
                "loaded": True,
                "model_kind": "gguf",
                "family": "lumina-2",
                "engine": "diffusers",
                "supports_lora": False,
            },
            False,
            False,
        ),
        ({"loaded": False}, False, False),
    ],
)
def test_engine_choice_status(status, eligible, lora):
    out = r.engine_choice_status(status)
    assert {k: out[k] for k in ("engine_forced", "native_engine_eligible", "lora_via_native")} == {
        "engine_forced": None,
        "native_engine_eligible": eligible,
        "lora_via_native": lora,
    }


def test_the_engine_pick_is_reported_as_resolved_provenance(monkeypatch):
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    loaded = {
        "loaded": True,
        "model_kind": "gguf",
        "family": "z-image",
        "resolved": {"speed_mode": {"value": "off"}},
    }

    def resolved_engine():
        out = r.engine_choice_status({**loaded, "engine": r.active_engine_name()})
        assert out["resolved"]["speed_mode"] == {"value": "off"}
        return out["resolved"]["engine"]

    def load_with(**kwargs):
        # The route records the pick once the engine accepted the load.
        _select_with(**kwargs)
        r.note_engine_pick(kwargs.get("engine"))

    load_with(model_kind = "gguf", engine = "sd_cpp")
    entry = resolved_engine()
    assert (
        entry["value"] == ENGINE_SD_CPP
        and entry["requested"] == ENGINE_SD_CPP
        and entry["source"] == "explicit"
    )
    load_with(model_kind = "gguf")
    entry = resolved_engine()
    assert (
        entry["value"] == ENGINE_DIFFUSERS
        and entry["source"] == "auto"
        and "GPU backend" in entry["reason"]
    )
    # A refused pick leaves the resident model's provenance alone.
    _set_binary(monkeypatch, None)
    with pytest.raises(ValueError):
        _select_with(model_kind = "gguf", engine = "sd_cpp")
    assert resolved_engine()["source"] == "auto"
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "diffusers")
    entry = resolved_engine()
    assert entry["source"] == "auto" and "UNSLOTH_DIFFUSION_ENGINE=diffusers" in entry["reason"]
    assert "resolved" not in r.engine_choice_status({"loaded": False})


def test_selection_alone_does_not_relabel_the_resident_model(monkeypatch):
    # A same-engine reload whose admission / preflight / arbiter then fails keeps the old model resident: the
    # pick is recorded only by note_engine_pick, after the engine accepted the load.
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    r._engine_pick = None
    assert _select_with(model_kind = "gguf", engine = "sd_cpp") == ENGINE_SD_CPP
    assert r._engine_pick is None
    r.note_engine_pick("sd_cpp")
    assert r._engine_pick == ENGINE_SD_CPP
    r.note_engine_pick(None)
    assert r._engine_pick is None


def test_the_plan_refuses_a_native_pick_the_load_would_refuse(monkeypatch):
    # No runnable binary and no install allowed: the load raises, so the plan must not stage a diffusers plan.
    _set_device(monkeypatch, "cuda")
    _set_binary(monkeypatch, None)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_INSTALL", "0")
    fam = detect_family("z-image")
    with pytest.raises(ValueError, match = "native sd.cpp engine cannot load this model here"):
        r.predict_engine(fam, model_kind = "gguf", engine = "sd_cpp")
    with pytest.raises(ValueError, match = "native sd.cpp engine cannot load this model here"):
        _select_with(model_kind = "gguf", engine = "sd_cpp")
    # Auto still plans the fallback it will take.
    assert r.predict_engine(fam, model_kind = "gguf") == ENGINE_DIFFUSERS
    assert r.predict_engine(fam, model_kind = "gguf", engine = "auto") == ENGINE_DIFFUSERS


def test_a_native_pick_honours_the_native_disable(monkeypatch):
    _set_device(monkeypatch, "cpu")
    _set_binary(monkeypatch, "/usr/bin/sd-cli")
    _set_runnable(monkeypatch)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP", "0")
    fam = detect_family("z-image")
    with pytest.raises(ValueError, match = "disabled on this server"):
        r.refuse_engine_pick(fam, engine = "sd_cpp", model_kind = "gguf")
    with pytest.raises(ValueError, match = "disabled on this server"):
        r.predict_engine(fam, model_kind = "gguf", engine = "sd_cpp")
    with pytest.raises(ValueError, match = "disabled on this server"):
        _select_with(model_kind = "gguf", engine = "sd_cpp")
    assert _select_with(model_kind = "gguf") == ENGINE_DIFFUSERS
    # The administrator's pin still overrides the disable.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "sd_cpp")
    r.refuse_engine_pick(fam, engine = "sd_cpp", model_kind = "gguf")
    assert _select_with(model_kind = "gguf", engine = "sd_cpp") == ENGINE_SD_CPP


def test_component_file_loads_are_not_native_eligible():
    # Separate text-encoder / VAE files are diffusers-only: the plan and the load refuse them on native.
    out = r.engine_choice_status(
        {
            "loaded": True,
            "model_kind": "gguf",
            "family": "flux.2-klein",
            "engine": "diffusers",
            "supports_lora": False,
            "component_files": {"vae": "ae.safetensors"},
        }
    )
    assert out["native_engine_eligible"] is False and out["lora_via_native"] is False


def test_the_engine_pick_commits_only_when_the_background_load_lands():
    # begin_load only starts the worker; a same-engine reload keeps the old state resident while it fetches, and a
    # worker failure before publishing keeps it for good. The pick follows the published state, not the start.
    old_state = object()
    engine = SimpleNamespace(_state = old_state)
    r._engine_pick = None
    r._pending_engine_pick = None
    r.note_engine_pick("sd_cpp", engine)
    assert r._engine_resolved(ENGINE_SD_CPP)["source"] == "auto"
    # Torn down mid-load: nothing loaded to label yet.
    engine._state = None
    assert r._engine_resolved(ENGINE_SD_CPP)["source"] == "auto"
    engine._state = object()
    entry = r._engine_resolved(ENGINE_SD_CPP)
    assert entry["source"] == "explicit" and entry["requested"] == ENGINE_SD_CPP
    # A later reload that fails before publishing leaves the landed pick in place.
    r.note_engine_pick(None, engine)
    assert r._engine_resolved(ENGINE_SD_CPP)["requested"] == ENGINE_SD_CPP
    # A load that landed before the next one started is committed, not lost.
    r.note_engine_pick("diffusers", engine)
    engine._state = object()
    r.note_engine_pick(None, engine)
    assert r._engine_pick == ENGINE_DIFFUSERS


def test_a_load_that_publishes_before_begin_load_returns_still_commits_its_pick():
    # begin_load starts the worker before it returns; a cached load can publish in that gap. The route snapshots the
    # state before starting it, so the published state still reads as new.
    old_state = object()
    engine = SimpleNamespace(_state = old_state)
    r._engine_pick = None
    r._pending_engine_pick = None
    before = r.loaded_state_of(engine)
    engine._state = object()  # the worker published before the route noted the pick
    r.note_engine_pick("sd_cpp", engine, before)
    assert r._engine_pick == ENGINE_SD_CPP
    assert r._engine_resolved(ENGINE_SD_CPP)["source"] == "explicit"


def test_the_native_disable_hides_the_native_actions(monkeypatch):
    # A pick refuse_engine_pick would 400 is never advertised: no Native select, no "Reload with native engine".
    status = {
        "loaded": True,
        "model_kind": "gguf",
        "family": "flux.2-klein",
        "engine": "diffusers",
        "supports_lora": False,
    }
    assert r.engine_choice_status(status)["lora_via_native"] is True
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP", "0")
    out = r.engine_choice_status(status)
    assert out["native_engine_eligible"] is False and out["lora_via_native"] is False
    with pytest.raises(ValueError, match = "disabled on this server"):
        r.refuse_engine_pick(detect_family("flux.2-klein"), engine = "sd_cpp", model_kind = "gguf")
    # The administrator's sd_cpp pin overrides the disable, as it does for the load.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", "sd_cpp")
    assert r.engine_choice_status(status)["native_engine_eligible"] is True