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.

51.2 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

"""Unit tests for the sd-cli command builder: argv construction and the policy-to-flag mappings only."""

from __future__ import annotations

import pytest

from core.inference.diffusion_memory import (
    OFFLOAD_GROUP,
    OFFLOAD_MODEL,
    OFFLOAD_NONE,
    OFFLOAD_SEQUENTIAL,
)
from core.inference.sd_cpp_args import (
    CPU_BACKEND_FLAGS,
    SdCppGenParams,
    SdCppModelFiles,
    SdCppUpscaleParams,
    SdCppVideoGenParams,
    build_img_gen_request,
    build_sd_cpp_command,
    build_sd_cpp_server_command,
    build_sd_cpp_upscale_command,
    build_sd_cpp_video_command,
    device_backend_flags,
    is_ggml_unsupported_op_abort,
    metal_text_encoder_flags,
    native_speed_flags,
    offload_flags,
    text_encoder_flags_for_family,
)


def _pair(cmd: list[str], flag: str):
    """Value following ``flag`` in ``cmd``, or None if the flag is absent."""
    return cmd[cmd.index(flag) + 1] if flag in cmd else None


def test_te_flags_by_family():
    assert text_encoder_flags_for_family("z-image") == ("--llm",)
    assert text_encoder_flags_for_family("qwen-image") == ("--qwen2vl",)
    assert text_encoder_flags_for_family("flux.1") == ("--clip_l", "--t5xxl")
    assert text_encoder_flags_for_family("flux.2-klein") == ("--llm",)
    # Not --qwen2vl: 2.1 conditions on Qwen3-VL and the qwen2vl path adds Qwen2-VL preprocessing.
    assert text_encoder_flags_for_family("qwen-image-2.1") == ("--llm",)
    assert text_encoder_flags_for_family("unknown") == ()


# ── Metal text-encoder placement ────────────────────────────────────────────


import core.inference.sd_cpp_args as _sd_cpp_args_module

_REAL_PARAVIRTUAL_PROBE = _sd_cpp_args_module.metal_is_paravirtual


@pytest.fixture(autouse = True)
def _physical_metal(monkeypatch):
    # The paravirtual probe shells out on darwin; every test here runs as physical Apple Silicon unless it says so.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
    # Commands are built for a Linux host unless a test sets the platform, so a Mac runner gets the same
    # commands as Linux (Metal drops direct conv and adds --clip-on-cpu).
    monkeypatch.setattr("sys.platform", "linux")
    # The real probe is cached and reads sysctl; follow the patched platform.machine() instead.
    import platform

    monkeypatch.setattr(
        sd_cpp_args,
        "apple_silicon_machine",
        lambda: platform.machine().lower() in ("arm64", "aarch64"),
    )


def test_metal_keeps_the_text_encoder_off_the_gpu(monkeypatch):
    # ggml Metal aborts on non-contiguous RMS_NORM with no CPU fallback (exits -6 on macOS).
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
    monkeypatch.setattr("sys.platform", "darwin")
    assert metal_text_encoder_flags() == ["--clip-on-cpu"]
    for other in ("linux", "win32"):
        monkeypatch.setattr("sys.platform", other)
        assert metal_text_encoder_flags() == []
    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", "1")
    assert metal_text_encoder_flags() == []


def test_metal_text_encoder_flag_reaches_both_command_builders(monkeypatch):
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
    monkeypatch.setattr("sys.platform", "darwin")
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    server = build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
    )
    cli = build_sd_cpp_command(
        binary = "sd-cli",
        files = files,
        params = SdCppGenParams(prompt = "x"),
        output_path = "/o/x.png",
    )
    video = build_sd_cpp_video_command(
        binary = "sd-cli",
        files = SdCppModelFiles(
            diffusion_model = "/m/h3.gguf",
            vae = "/m/video.safetensors",
            llm = "/m/qwen.gguf",
        ),
        params = SdCppVideoGenParams(prompt = "x", width = 960, height = 544, num_frames = 124),
        output_path = "/o/x.webm",
    )
    assert server.count("--clip-on-cpu") == 1
    assert cli.count("--clip-on-cpu") == 1
    assert video.count("--clip-on-cpu") == 1
    dual = build_sd_cpp_server_command(
        binary = "sd-server",
        files = files,
        host = "127.0.0.1",
        port = 1234,
        offload = offload_flags("model"),
    )
    assert dual.count("--clip-on-cpu") == 1
    monkeypatch.setattr("sys.platform", "linux")
    assert "--clip-on-cpu" not in build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
    )


def test_paravirtual_metal_runs_the_whole_graph_on_the_cpu_backend(monkeypatch):
    # The bundled ggml segfaults on a paravirtual Metal GPU, so a VM gets --backend cpu.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", raising = False)
    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    assert metal_text_encoder_flags() == ["--backend", "cpu"]
    # The encoder kill switch does not put a VM back on its GPU.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU", "1")
    assert metal_text_encoder_flags() == ["--backend", "cpu"]
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU")
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    server = build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234
    )
    cli = build_sd_cpp_command(
        binary = "sd-cli", files = files, params = SdCppGenParams(prompt = "x"), output_path = "/o/x.png"
    )
    for argv in (server, cli):
        i = argv.index("--backend")
        assert argv[i + 1] == "cpu"
        assert argv.count("--backend") == 1
        assert "--clip-on-cpu" not in argv
    # A low_vram policy that already offloads keeps its flags and still gets the CPU backend exactly once.
    model = build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, offload = offload_flags("model")
    )
    assert model.count("--backend") == 1 and model[model.index("--backend") + 1] == "cpu"
    # An explicit --backend pin in the offload flags wins; no dangling "cpu" argument is appended.
    pinned = sd_cpp_args.metal_placement_flags(["--backend", "diffusion=MTL0,te=cpu,vae=MTL0"])
    assert pinned == []
    monkeypatch.setattr("sys.platform", "linux")
    assert metal_text_encoder_flags() == []


def test_paravirtual_probe_is_darwin_only_and_survives_a_missing_probe(monkeypatch):
    import builtins

    import core.inference.sd_cpp_args as sd_cpp_args

    probe = _REAL_PARAVIRTUAL_PROBE
    probe.cache_clear()
    monkeypatch.setattr("sys.platform", "linux")
    assert probe() is False
    probe.cache_clear()
    monkeypatch.setattr("sys.platform", "darwin")
    orig_import = builtins.__import__

    def _no_llama(name, *args, **kwargs):
        if name == "core.inference.llama_cpp":
            raise ImportError("probe unavailable")
        return orig_import(name, *args, **kwargs)

    monkeypatch.setattr(builtins, "__import__", _no_llama)
    assert probe() is False
    probe.cache_clear()
    assert sd_cpp_args.metal_is_paravirtual is not probe


# ── offload policy -> sd-cli flags ──────────────────────────────────────────


def test_native_speed_on_apple_metal_drops_direct_conv(monkeypatch):
    # ggml-metal's direct CONV_2D trips the GPU watchdog; flash attention stays.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    assert native_speed_flags("default") == ["--diffusion-fa"]
    assert native_speed_flags("max") == ["--diffusion-fa"]
    assert native_speed_flags("off") == []
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    server = build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, native_speed = "default"
    )
    assert "--diffusion-fa" in server and "--diffusion-conv-direct" not in server
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
    # Intel Macs ship a CPU-only build.
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
    monkeypatch.setattr("platform.machine", lambda: "x86_64")
    assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]


def test_native_speed_keeps_direct_conv_on_a_forced_cpu_backend(monkeypatch):
    # The CPU-backend restart and an explicit --backend cpu run on the CPU, where direct conv is the profile's win.
    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    full = ["--diffusion-fa", "--diffusion-conv-direct"]
    assert native_speed_flags("default", ["--backend", "cpu"]) == full
    assert native_speed_flags("default", ["--backend", "diffusion=MTL0"]) == ["--diffusion-fa"]
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    restart = build_sd_cpp_server_command(
        binary = "sd-server",
        files = files,
        host = "127.0.0.1",
        port = 1234,
        native_speed = "default",
        extra_args = ["--backend", "cpu"],
    )
    assert "--diffusion-conv-direct" in restart


def test_engine_generate_keeps_direct_conv_on_a_forced_cpu_backend(monkeypatch):
    from core.inference.sd_cpp_engine import SdCppEngine

    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    captured = {}
    eng = SdCppEngine(binary = "/x/sd-cli")
    monkeypatch.setattr(eng, "_require_binary", lambda: "/x/sd-cli")
    monkeypatch.setattr(eng, "_prepare_out", lambda p: p)
    monkeypatch.setattr(eng, "_run", lambda cmd, *a, **k: captured.setdefault("cmd", cmd))
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    eng.generate(
        files,
        SdCppGenParams(prompt = "x"),
        output_path = "/o/x.png",
        native_speed = "default",
        extra_args = ["--backend", "cpu"],
    )
    assert "--diffusion-conv-direct" in captured["cmd"]


def test_native_speed_honours_an_explicit_metal_pin_on_a_paravirtual_gpu(monkeypatch):
    # An offload --backend pin suppresses the paravirtual CPU placement, so the graph is on Metal again.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    pin = ["--backend", "diffusion=MTL0,te=cpu,vae=MTL0"]
    assert native_speed_flags("default", pin) == ["--diffusion-fa"]
    assert native_speed_flags("default", ["--backend", "diffusion=cpu,te=cpu,vae=cpu"]) == [
        "--diffusion-fa",
        "--diffusion-conv-direct",
    ]
    files = SdCppModelFiles(diffusion_model = "/m/x.gguf")
    server = build_sd_cpp_server_command(
        binary = "sd-server",
        files = files,
        host = "127.0.0.1",
        port = 1234,
        offload = pin,
        native_speed = "default",
    )
    assert "--diffusion-conv-direct" not in server
    unpinned = build_sd_cpp_server_command(
        binary = "sd-server", files = files, host = "127.0.0.1", port = 1234, native_speed = "default"
    )
    assert "--diffusion-conv-direct" in unpinned


def test_metal_detection_does_not_trust_the_python_architecture(monkeypatch):
    # An x86_64 Python under Rosetta on Apple Silicon still drives the Metal GPU.
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "x86_64")
    monkeypatch.setattr(sd_cpp_args, "apple_silicon_machine", lambda: True)
    assert native_speed_flags("default") == ["--diffusion-fa"]
    # An explicit Metal pin is Metal whatever the machine reports.
    monkeypatch.setattr(sd_cpp_args, "apple_silicon_machine", lambda: False)
    assert native_speed_flags("default", ["--backend", "diffusion=MTL0"]) == ["--diffusion-fa"]
    assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]


def test_video_load_route_skips_the_video_claim_for_a_forced_cpu_h3_load():
    import inspect

    import routes.video as video_routes

    source = inspect.getsource(video_routes)
    guard = source.index("await asyncio.to_thread(forces_cpu_backend, device)")
    branch = source.index("if forced_cpu:", guard)
    # Neither acquires nor releases VIDEO: an old MPS model keeps its claim until the worker tears it down.
    assert source[branch : source.index('elif device != "cpu":', branch)].strip() == (
        "if forced_cpu:\n            status_dict = await asyncio.to_thread(begin)"
    )
    # ``begin`` only re-checks the Always media gate under the arbiter lock; it takes no GPU claim.
    begin_def = source.rindex("def begin():", 0, branch)
    assert source[begin_def : source.index("\n\n", begin_def)].strip() == (
        "def begin():\n"
        "            return begin_media_load(VIDEO, multi_model_mode, media_names, _begin_load)"
    )
    assert branch < source.index("return acquire_for_request(\n                            VIDEO,")


def test_partial_backend_specs_leave_the_diffusion_model_on_metal(monkeypatch):
    # sd.cpp auto-fits unassigned modules, so te=cpu / vae=cpu alone still runs the denoiser on Metal.
    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    fa_only = ["--diffusion-fa"]
    full = ["--diffusion-fa", "--diffusion-conv-direct"]
    assert native_speed_flags("default", ["--backend", "te=cpu"]) == fa_only
    assert native_speed_flags("default", ["--backend", "vae=cpu,te=cpu"]) == fa_only
    assert native_speed_flags("default", ["--backend", "diffusion=cpu"]) == full
    # An explicit diffusion entry beats the bare default, as in sd.cpp.
    assert (
        native_speed_flags("default", ["--backend", "cpu", "--backend", "diffusion=MTL0"])
        == fa_only
    )
    assert native_speed_flags("default", ["--backend", "MTL0,diffusion=cpu"]) == full


def test_forces_cpu_backend_only_for_a_paravirtual_mps_device(monkeypatch):
    import core.inference.sd_cpp_args as sd_cpp_args

    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    assert sd_cpp_args.forces_cpu_backend("mps") is True
    assert sd_cpp_args.forces_cpu_backend("cuda") is False
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
    assert sd_cpp_args.forces_cpu_backend("mps") is False


def test_image_load_route_skips_the_diffusion_claim_for_a_forced_cpu_native_load():
    import inspect

    import routes.inference as inference_routes

    source = inspect.getsource(inference_routes)
    start = source.index("off_torch = await asyncio.to_thread(off_torch_sd_cpp_device)")
    window = source[start : start + 25000]
    # Off the event loop: the paravirtual probe can shell out to sysctl / system_profiler.
    guard = window.index("await asyncio.to_thread(forces_cpu_backend, device)")
    assert window.index("activated = active_engine_name()") < guard < window.index("if needs_gpu:")
    assert "needs_gpu = False" in window[guard : guard + 200]


def test_upscale_on_paravirtual_metal_runs_on_the_cpu_backend(monkeypatch):
    import core.inference.sd_cpp_args as sd_cpp_args

    params = SdCppUpscaleParams(input_image = "/i/in.png", upscale_model = "/m/esrgan.pth")
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: True)
    cmd = build_sd_cpp_upscale_command("sd-cli", params, output_path = "/o/out.png")
    assert cmd.count("--backend") == 1 and cmd[cmd.index("--backend") + 1] == "cpu"
    # An explicit caller --backend wins: no second, concatenated spec.
    pinned = build_sd_cpp_upscale_command(
        "sd-cli", params, output_path = "/o/out.png", extra_args = ["--backend", "MTL0"]
    )
    assert pinned.count("--backend") == 1 and pinned[-1] == "MTL0"
    monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: False)
    assert "--backend" not in build_sd_cpp_upscale_command(
        "sd-cli", params, output_path = "/o/out.png"
    )


def test_native_speed_flags():
    assert native_speed_flags(None) == []
    assert native_speed_flags("off") == []
    assert native_speed_flags("") == []
    # conv-direct: ~9% faster CPU sampling at identical RSS.
    assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]
    assert native_speed_flags("max") == ["--diffusion-fa", "--diffusion-conv-direct"]
    with pytest.raises(ValueError):
        native_speed_flags("ludicrous")


def test_native_speed_flags_drop_conv_direct_on_vulkan_and_rocm(monkeypatch):
    monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
    monkeypatch.setattr(_sd_cpp_args_module, "_runs_on_apple_metal", lambda *_a, **_k: False)
    fa_only = ["--diffusion-fa"]
    full = ["--diffusion-fa", "--diffusion-conv-direct"]
    for accel in ("vulkan", "rocm", "ROCm"):
        assert native_speed_flags("default", [], accel) == fa_only
        assert native_speed_flags("max", [], accel) == fa_only
    for accel in ("cuda", "cpu", None):
        assert native_speed_flags("default", [], accel) == full
    assert (
        native_speed_flags("default", ["--backend", "diffusion=Vulkan0,te=cpu"], "cuda") == fa_only
    )
    assert native_speed_flags("default", ["--backend", "diffusion=ROCm1"], None) == fa_only
    assert native_speed_flags("default", ["--backend", "diffusion=CUDA0"], "vulkan") == full
    assert native_speed_flags("default", ["--backend", "diffusion=cpu"], "vulkan") == full
    monkeypatch.setenv("UNSLOTH_SD_CPP_CONV_DIRECT", "1")
    assert native_speed_flags("default", [], "vulkan") == full
    monkeypatch.setenv("UNSLOTH_SD_CPP_CONV_DIRECT", "0")
    assert native_speed_flags("default", [], "cuda") == fa_only


def test_server_command_carries_accelerator(monkeypatch):
    monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
    monkeypatch.setattr(_sd_cpp_args_module, "_runs_on_apple_metal", lambda *_a, **_k: False)
    files = SdCppModelFiles(diffusion_model = "/m/dit.gguf")
    kw = dict(host = "127.0.0.1", port = 1, native_speed = "default")
    assert "--diffusion-conv-direct" not in build_sd_cpp_server_command(
        "sd-server", files, accelerator = "vulkan", **kw
    )
    assert "--diffusion-conv-direct" in build_sd_cpp_server_command(
        "sd-server", files, accelerator = "cuda", **kw
    )


def test_offload_none_is_empty():
    assert offload_flags(OFFLOAD_NONE) == []


def test_offload_group_streams_with_flash_attention():
    flags = offload_flags(OFFLOAD_GROUP)
    assert "--offload-to-cpu" in flags
    assert "--diffusion-fa" in flags
    assert "--clip-on-cpu" not in flags
    assert "--vae-on-cpu" not in flags


def test_offload_model_pushes_everything_to_cpu_and_tiles():
    flags = offload_flags(OFFLOAD_MODEL)
    for expected in (
        "--offload-to-cpu",
        "--clip-on-cpu",
        "--vae-on-cpu",
        "--vae-tiling",
        "--diffusion-fa",
    ):
        assert expected in flags
    assert offload_flags(OFFLOAD_SEQUENTIAL) == flags


def test_offload_can_keep_the_vae_off_the_cpu_path():
    """H3 audio VAE asserts F16 on the CPU path, so only --vae-on-cpu is dropped under low_vram."""
    for policy in (OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
        flags = offload_flags(policy, vae_on_cpu = False)
        assert "--vae-on-cpu" not in flags
        for expected in ("--offload-to-cpu", "--clip-on-cpu", "--vae-tiling", "--diffusion-fa"):
            assert expected in flags, f"{policy}: {expected} should survive"
    assert "--vae-on-cpu" in offload_flags(OFFLOAD_MODEL)
    assert offload_flags(OFFLOAD_GROUP, vae_on_cpu = False) == offload_flags(OFFLOAD_GROUP)


def test_offload_forced_flags_dedup():
    flags = offload_flags(OFFLOAD_MODEL, vae_tiling = True, diffusion_fa = True)
    assert flags.count("--vae-tiling") == 1
    assert flags.count("--diffusion-fa") == 1
    none_forced = offload_flags(OFFLOAD_NONE, vae_tiling = True, diffusion_fa = True)
    assert none_forced == ["--diffusion-fa", "--vae-tiling"]


def test_build_zimage_command_minimal():
    files = SdCppModelFiles(
        diffusion_model = "/m/z.gguf",
        vae = "/m/ae.sft",
        llm = "/m/qwen3.gguf",
    )
    params = SdCppGenParams(prompt = "a cat", width = 512, height = 768, steps = 8, cfg_scale = 1.0, seed = 42)
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/out/x.png")

    assert cmd[0] == "/bin/sd-cli"
    assert _pair(cmd, "--mode") == "img_gen"
    assert _pair(cmd, "--diffusion-model") == "/m/z.gguf"
    assert _pair(cmd, "--vae") == "/m/ae.sft"
    assert _pair(cmd, "--llm") == "/m/qwen3.gguf"
    assert _pair(cmd, "--prompt") == "a cat"
    assert _pair(cmd, "--width") == "512"
    assert _pair(cmd, "--height") == "768"
    assert _pair(cmd, "--steps") == "8"
    assert _pair(cmd, "--cfg-scale") == "1"
    assert _pair(cmd, "--seed") == "42"
    assert _pair(cmd, "--output") == "/out/x.png"
    assert "--t5xxl" not in cmd
    assert "--qwen2vl" not in cmd


def test_build_flux1_dual_text_encoders():
    files = SdCppModelFiles(
        diffusion_model = "/m/flux.gguf",
        vae = "/m/ae.sft",
        clip_l = "/m/clip_l.sft",
        t5xxl = "/m/t5.gguf",
    )
    params = SdCppGenParams(prompt = "x", guidance = 3.5)
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    assert _pair(cmd, "--clip_l") == "/m/clip_l.sft"
    assert _pair(cmd, "--t5xxl") == "/m/t5.gguf"
    assert _pair(cmd, "--guidance") == "3.5"
    assert "--llm" not in cmd


def test_build_appends_offload_and_extra_args_last():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(prompt = "x")
    off = offload_flags(OFFLOAD_GROUP)
    cmd = build_sd_cpp_command(
        "/bin/sd-cli",
        files,
        params,
        output_path = "/o.png",
        offload = off,
        threads = 8,
        verbose = True,
        extra_args = ["--rng", "cuda"],
    )
    assert "--offload-to-cpu" in cmd
    assert _pair(cmd, "--threads") == "8"
    assert "-v" in cmd
    assert cmd[-2:] == ["--rng", "cuda"]


def test_build_negative_prompt_and_batch():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(prompt = "x", negative_prompt = "blurry")
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    assert _pair(cmd, "--negative-prompt") == "blurry"
    # The runner collects only the literal --output path, so a CLI batch would drop images.
    with pytest.raises(ValueError, match = "single-image"):
        build_sd_cpp_command(
            "/bin/sd-cli",
            files,
            SdCppGenParams(prompt = "x", batch_count = 3),
            output_path = "/o.png",
        )


def test_build_omits_unset_optional_params():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(prompt = "x")
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    for flag in (
        "--steps",
        "--cfg-scale",
        "--guidance",
        "--seed",
        "--sampling-method",
        "--batch-count",
        "--threads",
        "-v",
    ):
        assert flag not in cmd


def test_build_requires_diffusion_model_and_prompt():
    with pytest.raises(ValueError):
        build_sd_cpp_command(
            "/bin/sd-cli",
            SdCppModelFiles(diffusion_model = ""),
            SdCppGenParams(prompt = "x"),
            output_path = "/o.png",
        )
    with pytest.raises(ValueError):
        build_sd_cpp_command(
            "/bin/sd-cli",
            SdCppModelFiles(diffusion_model = "/m/z.gguf"),
            SdCppGenParams(prompt = "   "),
            output_path = "/o.png",
        )


def test_build_img2img_adds_init_and_strength():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/ae.sft", llm = "/m/q.gguf")
    params = SdCppGenParams(prompt = "make it autumn", init_img = "/in/src.png", strength = 0.6)
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    assert _pair(cmd, "--init-img") == "/in/src.png"
    assert _pair(cmd, "--strength") == "0.6"
    assert _pair(cmd, "--mode") == "img_gen"


def test_build_inpaint_adds_mask():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(prompt = "x", init_img = "/in/src.png", mask = "/in/mask.png", strength = 0.8)
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    assert _pair(cmd, "--mask") == "/in/mask.png"
    assert _pair(cmd, "--init-img") == "/in/src.png"


def test_build_inpaint_mask_without_init_img_rejected():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(prompt = "x", mask = "/in/mask.png")
    with pytest.raises(ValueError, match = "init_img is required"):
        build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")


def test_build_rejects_none_prompt():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    with pytest.raises(ValueError, match = "prompt is required"):
        build_sd_cpp_command(
            "/bin/sd-cli", files, SdCppGenParams(prompt = None), output_path = "/o.png"
        )


def test_build_edit_repeats_ref_image():
    files = SdCppModelFiles(diffusion_model = "/m/flux.gguf")
    params = SdCppGenParams(prompt = "add a hat", ref_images = ("/r/a.png", "/r/b.png"))
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    idxs = [i for i, t in enumerate(cmd) if t == "--ref-image"]
    assert len(idxs) == 2
    assert [cmd[i + 1] for i in idxs] == ["/r/a.png", "/r/b.png"]


def test_img2img_unset_dims_lets_sdcpp_derive_from_source():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_command(
        "/bin/sd-cli",
        files,
        SdCppGenParams(prompt = "x", init_img = "/in/src.png"),
        output_path = "/o.png",
    )
    assert "--width" not in cmd and "--height" not in cmd
    cmd2 = build_sd_cpp_command(
        "/bin/sd-cli",
        files,
        SdCppGenParams(prompt = "x", ref_images = ("/r/a.png",)),
        output_path = "/o.png",
    )
    assert "--width" not in cmd2 and "--height" not in cmd2


def test_img2img_explicit_dims_are_emitted():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_command(
        "/bin/sd-cli",
        files,
        SdCppGenParams(prompt = "x", init_img = "/in/src.png", width = 768, height = 512),
        output_path = "/o.png",
    )
    assert _pair(cmd, "--width") == "768" and _pair(cmd, "--height") == "512"


def test_txt2img_unset_dims_keep_1024_default():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_command(
        "/bin/sd-cli", files, SdCppGenParams(prompt = "x"), output_path = "/o.png"
    )
    assert _pair(cmd, "--width") == "1024" and _pair(cmd, "--height") == "1024"


def test_build_lora_dir_and_apply_mode():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    params = SdCppGenParams(
        prompt = "a portrait <lora:mystyle:0.8>",
        lora_dir = "/loras",
        lora_apply_mode = "at_runtime",
    )
    cmd = build_sd_cpp_command("/bin/sd-cli", files, params, output_path = "/o.png")
    assert _pair(cmd, "--lora-model-dir") == "/loras"
    assert _pair(cmd, "--lora-apply-mode") == "at_runtime"
    assert _pair(cmd, "--prompt") == "a portrait <lora:mystyle:0.8>"


def test_txt2img_omits_image_conditioning_flags():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_command(
        "/bin/sd-cli", files, SdCppGenParams(prompt = "x"), output_path = "/o.png"
    )
    for flag in ("--init-img", "--strength", "--mask", "--ref-image", "--lora-model-dir"):
        assert flag not in cmd


def test_build_upscale_command():
    params = SdCppUpscaleParams(
        input_image = "/in/small.png", upscale_model = "/m/esrgan.pth", repeats = 2
    )
    cmd = build_sd_cpp_upscale_command("/bin/sd-cli", params, output_path = "/out/big.png")
    assert _pair(cmd, "--mode") == "upscale"
    assert _pair(cmd, "--init-img") == "/in/small.png"
    assert _pair(cmd, "--upscale-model") == "/m/esrgan.pth"
    assert _pair(cmd, "--upscale-repeats") == "2"
    assert _pair(cmd, "--output") == "/out/big.png"
    assert "--prompt" not in cmd and "--llm" not in cmd


def test_build_upscale_rejects_non_positive_repeats():
    with pytest.raises(ValueError, match = "repeats"):
        build_sd_cpp_upscale_command(
            "/bin/sd-cli",
            SdCppUpscaleParams(input_image = "/i.png", upscale_model = "/m/e.pth", repeats = 0),
            output_path = "/o.png",
        )


def test_build_upscale_default_repeats_omits_flag():
    cmd = build_sd_cpp_upscale_command(
        "/bin/sd-cli",
        SdCppUpscaleParams(input_image = "/i.png", upscale_model = "/m/e.pth"),
        output_path = "/o.png",
    )
    assert "--upscale-repeats" not in cmd


def test_build_upscale_requires_input_and_model():
    with pytest.raises(ValueError):
        build_sd_cpp_upscale_command(
            "/bin/sd-cli",
            SdCppUpscaleParams(input_image = "", upscale_model = "/m/e.pth"),
            output_path = "/o.png",
        )
    with pytest.raises(ValueError):
        build_sd_cpp_upscale_command(
            "/bin/sd-cli",
            SdCppUpscaleParams(input_image = "/i.png", upscale_model = ""),
            output_path = "/o.png",
        )


def test_server_command_has_model_and_listen_but_no_request_params():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/ae.sft", llm = "/m/q.gguf")
    cmd = build_sd_cpp_server_command(
        "/bin/sd-server", files, host = "127.0.0.1", port = 5678, vae_format = "flux2"
    )
    assert _pair(cmd, "--diffusion-model") == "/m/z.gguf"
    assert _pair(cmd, "--vae") == "/m/ae.sft"
    assert _pair(cmd, "--llm") == "/m/q.gguf"
    assert _pair(cmd, "--vae-format") == "flux2"
    assert _pair(cmd, "--listen-ip") == "127.0.0.1"
    assert _pair(cmd, "--listen-port") == "5678"
    for flag in (
        "--prompt",
        "--seed",
        "--steps",
        "--cfg-scale",
        "--guidance",
        "--width",
        "--height",
        "--batch-count",
    ):
        assert flag not in cmd


def test_server_command_maps_offload_and_speed_and_dedupes():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_server_command(
        "/bin/sd-server",
        files,
        host = "127.0.0.1",
        port = 1,
        offload = ["--offload-to-cpu", "--diffusion-fa"],
        native_speed = "default",
        threads = 8,
    )
    assert _pair(cmd, "--threads") == "8"
    assert cmd.count("--diffusion-fa") == 1
    assert "--offload-to-cpu" in cmd


def test_server_command_scratch_dir_expands_to_lora_upscaler_embd():
    files = SdCppModelFiles(diffusion_model = "/m/z.gguf")
    cmd = build_sd_cpp_server_command(
        "/bin/sd-server", files, host = "127.0.0.1", port = 1, scratch_dir = "/tmp/scratch"
    )
    assert _pair(cmd, "--lora-model-dir") == "/tmp/scratch"
    assert _pair(cmd, "--hires-upscalers-dir") == "/tmp/scratch"
    assert _pair(cmd, "--embd-dir") == "/tmp/scratch"
    bare = build_sd_cpp_server_command("/bin/sd-server", files, host = "127.0.0.1", port = 1)
    assert "--lora-model-dir" not in bare and "--hires-upscalers-dir" not in bare


def test_server_command_requires_diffusion_model():
    with pytest.raises(ValueError):
        build_sd_cpp_server_command(
            "/bin/sd-server", SdCppModelFiles(diffusion_model = ""), host = "127.0.0.1", port = 1
        )


def test_img_gen_request_maps_core_fields():
    req = build_img_gen_request(
        prompt = "a fox",
        negative_prompt = "blurry",
        width = 512,
        height = 768,
        steps = 8,
        seed = 42,
        batch_count = 3,
        sample_method = "euler",
        cfg_scale = 4.0,
    )
    assert req["prompt"] == "a fox" and req["negative_prompt"] == "blurry"
    assert req["width"] == 512 and req["height"] == 768
    assert req["seed"] == 42 and req["batch_count"] == 3
    assert req["sample_params"]["sample_steps"] == 8
    assert req["sample_params"]["sample_method"] == "euler"
    assert req["sample_params"]["guidance"]["txt_cfg"] == 4.0
    assert req["output_format"] == "png"


def test_img_gen_request_flux_uses_distilled_guidance():
    req = build_img_gen_request(prompt = "x", steps = 4, distilled_guidance = 3.5, flow_shift = 3.0)
    g = req["sample_params"]["guidance"]
    assert g["distilled_guidance"] == 3.5
    assert "txt_cfg" not in g
    assert req["sample_params"]["flow_shift"] == 3.0


def test_img_gen_request_requires_prompt():
    with pytest.raises(ValueError):
        build_img_gen_request(prompt = "   ", steps = 4)


def test_ggml_unsupported_op_abort_is_recognised_only_with_both_markers():
    abort = (
        "sd-server connection lost during img_gen poll (process exited, code -6)\n"
        "Last output:\n"
        "[ERROR] ggml_extend.hpp:70   - ggml_metal_op_encode_impl: error: unsupported op 'MUL_MAT'\n"
        "1   sd-server   0x00000001044f8df4 ggml_abort + 156"
    )
    assert is_ggml_unsupported_op_abort(abort) is True
    assert (
        is_ggml_unsupported_op_abort("error: unsupported op 'RMS_NORM'\nggml_abort + 156") is True
    )
    assert is_ggml_unsupported_op_abort("unsupported op 'MUL_MAT'") is False
    assert is_ggml_unsupported_op_abort("ggml_abort + 156") is False
    assert is_ggml_unsupported_op_abort("process exited, code -9") is False
    assert is_ggml_unsupported_op_abort("") is False


def test_server_command_appends_extra_args_last():
    # The abort rescue passes --backend cpu as extra_args and sd.cpp is last-wins.
    cmd = build_sd_cpp_server_command(
        "/x/sd-server",
        SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/vae.sft"),
        host = "127.0.0.1",
        port = 1234,
        native_speed = "default",
        extra_args = list(CPU_BACKEND_FLAGS),
    )
    assert cmd[-2:] == ["--backend", "cpu"]
    assert cmd[0] == "/x/sd-server"


def test_minimax_h3_video_command_has_all_joint_av_components():
    files = SdCppModelFiles(
        diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
        vae = "/m/video.safetensors",
        audio_vae = "/m/audio.safetensors",
        llm = "/m/qwen.gguf",
    )
    cmd = build_sd_cpp_video_command(
        "/bin/sd-cli",
        files,
        SdCppVideoGenParams(
            prompt = "a fox runs through snow",
            width = 960,
            height = 544,
            num_frames = 124,
            fps = 24,
            steps = 30,
            seed = 42,
        ),
        output_path = "/out/result.webm",
        offload = ["--diffusion-fa", "--offload-to-cpu"],
    )
    assert _pair(cmd, "--mode") == "vid_gen"
    assert _pair(cmd, "--audio-vae") == "/m/audio.safetensors"
    assert _pair(cmd, "--llm") == "/m/qwen.gguf"
    assert _pair(cmd, "--video-frames") == "124"
    assert _pair(cmd, "--fps") == "24"
    assert _pair(cmd, "--cfg-scale") == "1"
    assert "--rng" in cmd and _pair(cmd, "--rng") == "cpu"
    assert cmd[-2:] == ["--diffusion-fa", "--offload-to-cpu"]


def test_video_build_appends_extra_args_verbatim_and_last():
    """Video build appends extra_args verbatim and last, so --rng cuda overrides the builder's default."""
    files = SdCppModelFiles(
        diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
        vae = "/m/video.safetensors",
        audio_vae = "/m/audio.safetensors",
        llm = "/m/qwen.gguf",
    )
    cmd = build_sd_cpp_video_command(
        "/bin/sd-cli",
        files,
        SdCppVideoGenParams(
            prompt = "a fox runs through snow",
            width = 960,
            height = 544,
            num_frames = 124,
            fps = 24,
            seed = 1,
        ),
        output_path = "/o.webm",
        extra_args = ["--rng", "cuda"],
    )
    assert cmd[-2:] == ["--rng", "cuda"]
    assert cmd[-1] != "cuda" or cmd[-2] == "--rng"
    assert cmd.count("--rng") == 2


def _h3_video_cmd(**params):
    return build_sd_cpp_video_command(
        "/bin/sd-cli",
        SdCppModelFiles(
            diffusion_model = "/m/minimax_h3_fl2va-Q4_K_M.gguf",
            vae = "/m/video.safetensors",
            audio_vae = "/m/audio.safetensors",
            llm = "/m/qwen.gguf",
        ),
        SdCppVideoGenParams(
            prompt = "a fox runs through snow",
            width = 960,
            height = 544,
            num_frames = 124,
            **params,
        ),
        output_path = "/out/result.webm",
    )


def test_minimax_h3_video_command_omits_keyframe_flags_for_text_only():
    cmd = _h3_video_cmd()
    assert "--init-img" not in cmd
    assert "--end-img" not in cmd


def test_minimax_h3_video_command_carries_each_keyframe():
    assert _pair(_h3_video_cmd(init_img = "/k/first.png"), "--init-img") == "/k/first.png"
    assert "--end-img" not in _h3_video_cmd(init_img = "/k/first.png")

    end_only = _h3_video_cmd(end_img = "/k/last.png")
    assert _pair(end_only, "--end-img") == "/k/last.png"
    assert "--init-img" not in end_only

    both = _h3_video_cmd(init_img = "/k/first.png", end_img = "/k/last.png")
    assert _pair(both, "--init-img") == "/k/first.png"
    assert _pair(both, "--end-img") == "/k/last.png"


def test_minimax_h3_video_command_packs_references_in_reading_order():
    cmd = _h3_video_cmd(
        ref_images = ("/r/cat.png", "/r/style.png"),
        ref_videos = ("/r/motion", "/r/orbit"),
        ref_video_audios = ("/r/motion.wav",),
        ref_audios = ("/r/voice.wav",),
    )
    assert [c for c in cmd if c.startswith("--ref")] == [
        "--ref-image",
        "--ref-image",
        "--ref-video",
        "--ref-video",
        "--ref-video-audio",
        "--ref-audio",
    ]
    assert cmd[cmd.index("--ref-image") + 1] == "/r/cat.png"
    assert cmd[cmd.index("--ref-video") + 1] == "/r/motion"
    assert cmd[cmd.index("--ref-audio") + 1] == "/r/voice.wav"


def test_minimax_h3_video_command_refuses_keyframes_with_references():
    with pytest.raises(ValueError, match = "different denoiser partitions"):
        _h3_video_cmd(init_img = "/k/first.png", ref_images = ("/r/cat.png",))
    with pytest.raises(ValueError, match = "different denoiser partitions"):
        _h3_video_cmd(end_img = "/k/last.png", ref_audios = ("/r/voice.wav",))


def test_minimax_h3_video_command_refuses_an_unpairable_soundtrack():
    with pytest.raises(ValueError, match = "reference video to pair with"):
        _h3_video_cmd(ref_videos = ("/r/motion",), ref_video_audios = ("/r/a.wav", "/r/b.wav"))


def test_minimax_h3_video_command_carries_the_video_flow_shift():
    # sd.cpp derives the audio schedule against a hardcoded 3.0, so only the video shift is a flag.
    assert "--flow-shift" not in _h3_video_cmd()
    assert _pair(_h3_video_cmd(flow_shift = 8.5), "--flow-shift") == "8.5"
    assert _pair(_h3_video_cmd(flow_shift = 12.0), "--flow-shift") == "12"


def test_device_backend_flags_pin_all_three_graphs():
    # sd.cpp defaults to ordinal 0 unless told otherwise, so a selection only takes effect through --backend.
    assert device_backend_flags("CUDA1") == ["--backend", "diffusion=CUDA1,te=CUDA1,vae=CUDA1"]
    assert device_backend_flags(None) == []
    assert device_backend_flags("") == []


def test_device_backend_flags_leave_the_offloaded_modules_on_the_cpu():
    # --clip-on-cpu / --vae-on-cpu ARE te=cpu / vae=cpu and the parser is last-wins, so pinning them would undo low_vram.
    low_vram = offload_flags(OFFLOAD_MODEL)
    assert "--clip-on-cpu" in low_vram and "--vae-on-cpu" in low_vram
    assert device_backend_flags("CUDA1", low_vram) == [
        "--backend",
        "diffusion=CUDA1,te=cpu,vae=cpu",
    ]
    assert device_backend_flags("CUDA1", offload_flags(OFFLOAD_GROUP)) == [
        "--backend",
        "diffusion=CUDA1,te=CUDA1,vae=CUDA1",
    ]


def test_device_backend_flags_are_appended_not_folded_into_the_policy():
    # The policy list must stay unchanged: a deferred install can replace the build later.
    policy = offload_flags(OFFLOAD_GROUP)
    before = list(policy)
    device_backend_flags("CUDA1", policy)
    assert policy == before


def test_conv_direct_force_on_reaches_apple_metal(monkeypatch):
    monkeypatch.setattr("sys.platform", "darwin")
    monkeypatch.setattr("platform.machine", lambda: "arm64")
    monkeypatch.delenv("UNSLOTH_SD_CPP_CONV_DIRECT", raising = False)
    assert native_speed_flags("default") == ["--diffusion-fa"]
    monkeypatch.setenv(
        "UNSLOTH_SD_CPP_CONV_DIRECT", "1"
    )  # an explicit force beats the Metal default
    assert native_speed_flags("default") == ["--diffusion-fa", "--diffusion-conv-direct"]


# ── Metal mmap (leejet/stable-diffusion.cpp#2037) ───────────────────────────


def _managed_install(tmp_path, tag):
    import json

    root = tmp_path / "stable-diffusion.cpp"
    (root / "bin").mkdir(parents = True)
    binary = root / "bin" / "sd-cli"
    binary.write_text("")
    (root / ".unsloth-sd-cpp-install.json").write_text(
        json.dumps({"tag": tag, "accelerator": "cpu"})
    )
    _sd_cpp_args_module._installed_sd_cpp_tag.cache_clear()
    return str(binary)


def _all_builders(binary, extra_args = None):
    files = SdCppModelFiles(
        diffusion_model = "/m/model.gguf", vae = "/m/vae.safetensors", llm = "/m/te.gguf"
    )
    yield build_sd_cpp_command(
        binary, files, SdCppGenParams(prompt = "a cat"), output_path = "/o.png", extra_args = extra_args
    )
    yield build_sd_cpp_video_command(
        binary,
        files,
        SdCppVideoGenParams(prompt = "a cat", width = 256, height = 256, num_frames = 5),
        output_path = "/o.webm",
        extra_args = extra_args,
    )
    yield build_sd_cpp_server_command(
        binary, files, host = "127.0.0.1", port = 1, extra_args = extra_args
    )


@pytest.mark.parametrize(
    "tag, expected",
    [
        ("master-982-0518b34-u67cba2c", True),  # the pinned bundle
        ("master-982-0518b34-ueb0e729", True),  # the previous pin
        ("master-982-0518b34-uba6ac30", True),  # an older pin
        ("master-982-0518b34-uaba3a1c", True),  # an older pin
        ("master-982-0518b34-ud331c66", True),  # an older pin
        ("master-968-8cd731e-ubdb47d1", True),  # the pin before it
        ("master-951-f89d9b1-uafac7a7", True),  # an older pin
        ("master-907-500ef5f", True),  # the build that merged #2037
        ("master-906-abcdef0", False),  # --mmap there hands Metal an unaddressable CPU buffer
        ("master-813-bfbef5b-u6321a69", False),
        ("b1234", False),  # undatable: fail closed
    ],
)
def test_mmap_rides_every_macos_builder_from_the_metal_mmap_build(
    monkeypatch, tmp_path, tag, expected
):
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
    monkeypatch.setattr("sys.platform", "darwin")
    binary = _managed_install(tmp_path, tag)
    for cmd in _all_builders(binary):
        assert ("--mmap" in cmd) is expected
        assert cmd.count("--mmap") <= 1


def test_mmap_is_macos_only_and_never_on_an_unrecorded_binary(monkeypatch, tmp_path):
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
    binary = _managed_install(tmp_path, "master-951-f89d9b1-uafac7a7")
    for other in ("linux", "win32"):
        monkeypatch.setattr("sys.platform", other)
        assert all("--mmap" not in cmd for cmd in _all_builders(binary))
    monkeypatch.setattr("sys.platform", "darwin")
    stray = tmp_path / "elsewhere" / "sd-cli"
    stray.parent.mkdir()
    stray.write_text("")
    assert all("--mmap" not in cmd for cmd in _all_builders(str(stray)))


def test_mmap_env_override_and_no_duplicate(monkeypatch, tmp_path):
    monkeypatch.setattr("sys.platform", "darwin")
    new = _managed_install(tmp_path, "master-951-f89d9b1-uafac7a7")
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")
    assert all("--mmap" not in cmd for cmd in _all_builders(new))
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")
    assert all("--mmap" in cmd for cmd in _all_builders("/usr/local/bin/sd-cli"))
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP")
    for cmd in _all_builders(new, extra_args = ["--mmap"]):
        assert cmd.count("--mmap") == 1


# ── CPU mmap (repack-aware builds) ──────────────────────────────────────────

_REPACK_HELP = "  --mmap  whether to memory-map model (CPU: weights the CPU repacks are still loaded and repacked)\n"
_OLD_HELP = "  --mmap  whether to memory-map model\n"


def _cpu_install(
    tmp_path,
    monkeypatch,
    help_text,
    accelerator = "cpu",
):
    import json

    import core.inference.sd_cpp_backend as backend

    root = tmp_path / f"sd-{accelerator}-{abs(hash(help_text)) % 10**6}"
    (root / "bin").mkdir(parents = True)
    binary = root / "bin" / "sd-cli"
    binary.write_text("")
    (root / ".unsloth-sd-cpp-install.json").write_text(
        json.dumps({"tag": "master-982-0518b34-u67cba2c", "accelerator": accelerator})
    )
    for fn in (
        _sd_cpp_args_module._installed_sd_cpp_tag,
        _sd_cpp_args_module._installed_sd_cpp_accelerator,
        _sd_cpp_args_module._cpu_mmap_repack_in_help,
    ):
        fn.cache_clear()
    monkeypatch.setattr(backend, "_sd_cpp_probe_output", lambda b, *a, **k: help_text)
    return str(binary)


@pytest.mark.parametrize("platform", ["linux", "win32"])
def test_cpu_mmap_on_repack_aware_cpu_builds_only(monkeypatch, tmp_path, platform):
    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
    monkeypatch.setattr("sys.platform", platform)
    new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
    for cmd in _all_builders(new):
        assert cmd.count("--mmap") == 1
    # The pinned build maps repackable weights and runs them unrepacked: never sent there.
    old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
    assert all("--mmap" not in cmd for cmd in _all_builders(old))
    for accel in ("cuda", "vulkan", "rocm"):
        gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = accel)
        assert all("--mmap" not in cmd for cmd in _all_builders(gpu))


def test_cpu_mmap_follows_an_explicit_backend(monkeypatch, tmp_path):
    from core.inference.sd_cpp_args import mmap_flags

    monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
    monkeypatch.setattr("sys.platform", "linux")
    gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = "vulkan")
    assert mmap_flags(gpu, None, ["--backend", "cpu"]) == ["--mmap"]
    cpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
    assert mmap_flags(cpu, None, ["--backend", "diffusion=vulkan0"]) == []
    assert mmap_flags(cpu, ["--mmap"], None) == []
    assert mmap_flags(None, None, None) == []
    # an unreadable / unprobeable binary fails closed
    assert (
        _cpu_install(tmp_path, monkeypatch, None)
        and mmap_flags(str(tmp_path / "missing" / "sd-cli")) == []
    )


def test_cpu_mmap_env_override(monkeypatch, tmp_path):
    from core.inference.sd_cpp_args import mmap_flags

    monkeypatch.setattr("sys.platform", "linux")
    new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")
    assert mmap_flags(new) == []
    monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")
    old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
    assert mmap_flags(old) == ["--mmap"]


@pytest.mark.parametrize(
    "ccs,expected",
    [
        ([(8, 0)], "1024"),  # A100
        ([(9, 0)], "1024"),  # H100
        ([(10, 0)], "1024"),  # B200
        ([(10, 3)], "1024"),
        ([(12, 0)], "4096"),  # RTX PRO 6000 / RTX 50
        ([(8, 9)], None),  # L4 / RTX 40: MMQ stays faster
        ([(8, 6)], None),
        ([(8, 7)], None),
        ([(7, 5)], None),
        ([(11, 0)], None),
        ([(8, 0), (10, 0)], "1024"),
        ([(8, 0), (8, 9)], None),  # sd.cpp may land on either card
        ([(10, 0), (12, 0)], None),
        ([], None),
    ],
)
def test_quant_cublas_env_follows_the_measured_architectures(ccs, expected):
    env = _sd_cpp_args_module.quant_cublas_env(ccs, environ = {}, weight_types = frozenset({"Q8_0"}))
    assert env == ({} if expected is None else {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": expected})


@pytest.mark.parametrize("user_value", ["0", "512"])
def test_quant_cublas_env_never_overrides_the_user(user_value):
    environ = {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": user_value}
    assert (
        _sd_cpp_args_module.quant_cublas_env(
            [(10, 0)], environ = environ, weight_types = frozenset({"Q8_0"})
        )
        == {}
    )


@pytest.mark.parametrize(
    "weight_types,expected",
    [
        (frozenset({"Q8_0"}), "1024"),
        (frozenset({"Q4_K"}), None),  # k-quants keep MMQ
        (frozenset({"Q4_K", "Q5_K"}), None),
        (frozenset({"Q8_0", "Q4_K"}), None),  # a mixed file would route its k-quants too
        (frozenset({"Q4_0"}), None),
        (frozenset(), None),  # unquantized: nothing to route
        (None, None),  # unknown (safetensors, unreadable)
    ],
)
def test_quant_cublas_env_only_for_q8_0_diffusion_ggufs(weight_types, expected):
    env = _sd_cpp_args_module.quant_cublas_env([(10, 0)], environ = {}, weight_types = weight_types)
    assert env == ({} if expected is None else {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": expected})


def test_gguf_quantized_weight_types_reads_the_tensor_table(tmp_path):
    gguf = pytest.importorskip("gguf")
    import numpy as np

    def write(name, tensors):
        path = tmp_path / name
        w = gguf.GGUFWriter(str(path), "test")
        for tname, arr, qtype in tensors:
            if qtype is None:
                w.add_tensor(tname, arr)
            elif arr is None:  # gguf-py cannot quantize k-quants: write zeroed blocks of that type
                blocks = np.zeros((4, gguf.GGML_QUANT_SIZES[qtype][1]), dtype = np.uint8)
                w.add_tensor(tname, blocks, raw_dtype = qtype)
            else:
                w.add_tensor(tname, gguf.quants.quantize(arr, qtype), raw_dtype = qtype)
        w.write_header_to_file()
        w.write_kv_data_to_file()
        w.write_tensors_to_file()
        w.close()
        return str(path)

    x = np.ones((4, 256), dtype = np.float32)
    q8 = write(
        "q8.gguf",
        [("a", x, gguf.GGMLQuantizationType.Q8_0), ("n", np.ones(4, dtype = np.float32), None)],
    )
    mixed = write(
        "mixed.gguf",
        [("a", x, gguf.GGMLQuantizationType.Q8_0), ("b", x, gguf.GGMLQuantizationType.Q4_0)],
    )
    types_of = _sd_cpp_args_module.gguf_quantized_weight_types
    assert types_of(q8) == frozenset({"Q8_0"})
    assert types_of(mixed) == frozenset({"Q8_0", "Q4_0"})
    assert types_of(str(tmp_path / "missing.gguf")) is None
    assert types_of(str(tmp_path / "model.safetensors")) is None
    assert types_of(None) is None

    k_quant = write("te_q4k.gguf", [("w", None, gguf.GGMLQuantizationType.Q4_K)])
    assert types_of(k_quant) == frozenset({"Q4_K"})

    def route(path):
        return _sd_cpp_args_module.quant_cublas_env(
            [(10, 0)], environ = {}, weight_types = types_of(path)
        )

    assert route(q8) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
    assert route(mixed) == {}
    assert route(k_quant) == {}
    assert route(str(tmp_path / "missing.gguf")) == {}