Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""The H3 preflight must refuse every host before the four-file download, CPU fallback included."""
from __future__ import annotations
import threading
import types
from pathlib import Path
import pytest
from core.inference.video import VideoBackend, _detect_load_family
from core.inference.video_families import VIDEO_CANCELLED_MSG
def _shared_setup_1(backend, device, h3_host, platform):
from core.inference import sd_cpp_backend
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
swapped = {"done": False}
real_probe = sd_cpp_backend._sd_cpp_probe_output
return host, real_probe, sd_cpp_backend, swapped
H3_REPO = "leejet/MiniMax-H3-GGUF"
H3_FILE = "minimax_h3_fl2va-Q4_K_M.gguf"
_BANNER = "stable-diffusion.cpp version unknown, commit unknown\n"
_H3_HELP = _BANNER + " --ref-video MiniMax-H3 Ref2VA reference video frame directory\n"
_PRE_H3_HELP = _BANNER + " -M, --mode run mode, one of [img_gen, vid_gen, upscale]\n"
# Debian/Ubuntu's find-and-replace `sd`, and Homebrew ships the same tool on macOS.
_UNRELATED_HELP = "sd 1.0.0\nFind & replace CLI\n\nUSAGE:\n sd <find> <replace-with>\n"
# (label, DiffusionDeviceTarget.backend, .device)
HARDWARE = [
("nvidia", "cuda", "cuda"),
("amd", "rocm", "cuda"),
("apple", "mps", "mps"),
("cpu", "cpu", "cpu"),
]
# WSL is the linux platform string; listed separately because PATH can reach a Windows install.
PLATFORMS = ["linux", "wsl", "darwin", "win32"]
class _PlanInfo:
def __init__(self, siblings) -> None:
self.siblings = siblings
class _Engine:
def __init__(self, binary) -> None:
self.binary = binary
def version(self):
return "stub-version"
@pytest.fixture
def h3_host(monkeypatch, tmp_path):
"""Drive `_run_load_h3_native` on a chosen host with a chosen binary, recording downloads."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
def _setup(
*,
platform: str,
backend: str,
device: str,
help_text: str | None,
managed: bool = False,
lists_accelerator: bool = True,
paravirtual: bool = False,
):
monkeypatch.setattr(
sd_cpp_engine.sys, "platform", "linux" if platform == "wsl" else platform
)
monkeypatch.setattr(
video_mod,
"resolve_diffusion_device_target",
lambda: types.SimpleNamespace(backend = backend, device = device, dtype = None),
)
from core.inference import sd_cpp_args
monkeypatch.setattr(sd_cpp_args, "metal_is_paravirtual", lambda: paravirtual)
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(sd_cpp_backend, "is_managed_binary", lambda _b: managed)
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
binary = None if help_text is None else "/opt/sd/sd-cli"
monkeypatch.setattr(sd_cpp_backend, "ensure_sd_cpp_binary", lambda **_kwargs: binary)
device_probes: list[str] = []
def _probe(_binary, *args):
if args == ("--list-devices",):
device_probes.append(_binary)
if lists_accelerator:
return "CUDA0\tNVIDIA H100 PCIe\nCPU\tIntel(R) Xeon(R)\n"
return "CPU\tIntel(R) Xeon(R)\n"
return help_text
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
asset_calls: list[str] = []
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, repo, *_args, **_kwargs):
asset_calls.append(repo)
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
downloads: list[str] = []
def _download(_repo, wanted, *_args, **_kwargs):
downloads.append(wanted)
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
def run(cancel_event: threading.Event | None = None):
fam = _detect_load_family(H3_REPO, None, "minimax-h3")
assert fam is not None
backend_obj = VideoBackend()
backend_obj._run_load_h3_native(
fam = fam,
token = None,
cancel_event = cancel_event or threading.Event(),
repo_id = H3_REPO,
gguf_filename = H3_FILE,
)
return backend_obj
return types.SimpleNamespace(
run = run,
downloads = downloads,
asset_calls = asset_calls,
device_probes = device_probes,
)
return _setup
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
@pytest.mark.parametrize(
"state,help_text,expected",
[
("unrelated_binary", _UNRELATED_HELP, "is not stable-diffusion.cpp"),
("pre_h3_binary", _PRE_H3_HELP, "does not advertise MiniMax-H3"),
("no_binary", None, "could not be installed or started"),
],
)
def test_h3_preflight_refuses_before_downloading(
h3_host, platform, hw_label, backend, device, state, help_text, expected
):
"""Every refusal costs zero downloads, since the bundle is tens of GB and must not be fetched first."""
host = h3_host(platform = platform, backend = backend, device = device, help_text = help_text)
with pytest.raises(RuntimeError, match = expected):
host.run()
assert host.downloads == []
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_preflight_admits_a_capable_build_and_downloads_once(
h3_host, platform, hw_label, backend, device
):
"""The other direction: a genuine H3 build is not refused anywhere, and the load proceeds to
fetch exactly the four files. Guards against an identity check that is too strict."""
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
backend_obj = host.run()
assert len(host.downloads) == 4
assert backend_obj._state is not None
assert backend_obj._state.device == device
def test_h3_on_a_paravirtual_mac_commits_cpu_and_drops_the_video_claim(h3_host, monkeypatch):
# sd.cpp runs a paravirtual Metal GPU on the CPU backend, so the load must not keep the VIDEO claim.
from core.inference import gpu_arbiter
released = []
monkeypatch.setattr(
gpu_arbiter, "release_if", lambda owner, pred: released.append(owner) or pred()
)
host = h3_host(
platform = "darwin", backend = "mps", device = "mps", help_text = _H3_HELP, paravirtual = True
)
backend_obj = host.run()
assert backend_obj._state is not None and backend_obj._state.device == "cpu"
assert released == [gpu_arbiter.VIDEO]
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
"hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_gpu_host_falls_back_to_the_cpu_build(h3_host, platform, hw_label, backend, device):
"""Upstream publishes no Linux CUDA archive, so a GPU host routinely ends up on the CPU
prebuilt. It must still load, committed on the CPU rather than on a GPU it never ran on."""
host = h3_host(
platform = platform,
backend = backend,
device = device,
help_text = _H3_HELP,
lists_accelerator = False,
)
backend_obj = host.run()
assert len(host.downloads) == 4
assert backend_obj._state is not None
assert backend_obj._state.device == "cpu"
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_cancellation_during_the_preflight_stops_before_the_asset_calls(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""The ensure takes no cancel_event and can spend minutes installing the prebuilt, so a cancel
arriving during it is already late. It must not then cost four more model_info round trips."""
from core.inference import sd_cpp_backend
cancelled = threading.Event()
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
original = sd_cpp_backend.ensure_h3_sd_cpp_binary
def _cancel_midway(**kwargs):
cancelled.set()
return original(**kwargs)
monkeypatch.setattr(sd_cpp_backend, "ensure_h3_sd_cpp_binary", _cancel_midway)
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
host.run(cancel_event = cancelled)
assert host.downloads == []
# A cancelled load must stop before the four sequential size-estimate round trips.
assert host.asset_calls == []
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_revets_a_user_supplied_binary_swapped_during_the_download(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""User-supplied binaries are re-vetted after the download, so a mid-fetch swap is caught."""
from core.inference import sd_cpp_backend
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
swapped = {"done": False}
real_probe = sd_cpp_backend._sd_cpp_probe_output
def _probe(binary, *args):
if args == ("--help",) and swapped["done"]:
return _PRE_H3_HELP
return real_probe(binary, *args)
def _download(*args, **kwargs):
swapped["done"] = True
return _real_download(*args, **kwargs)
_real_download = None
import utils.hf_xet_fallback as xet
_real_download = xet.hf_hub_download_with_xet_fallback
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
with pytest.raises(RuntimeError, match = "changed while this model was loading"):
host.run()
assert len(host.downloads) == 4
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_revet_checks_identity_not_just_the_h3_marker(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""The re-vet checks binary identity too, since --ref-video is a plain option other tools expose."""
host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)
def _probe(binary, *args):
if args == ("--help",) and swapped["done"]:
return "reference-video-cli 2.1\n --ref-video PATH reference clip\n"
return real_probe(binary, *args)
import utils.hf_xet_fallback as xet
real_download = xet.hf_hub_download_with_xet_fallback
def _download(*args, **kwargs):
swapped["done"] = True
return real_download(*args, **kwargs)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
with pytest.raises(RuntimeError, match = "changed while this model was loading"):
host.run()
assert len(host.downloads) == 4
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
"hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_revet_catches_a_user_binary_whose_accelerator_changed(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""The device list is re-probed at commit, since a GPU device committed around a CPU binary is wrong."""
host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)
def _probe(binary, *args):
# Identity and capability pass; only the device list changed, which the H3 re-vet cannot see.
if args == ("--list-devices",) and swapped["done"]:
return "CPU\tIntel(R) Xeon(R)\n"
return real_probe(binary, *args)
import utils.hf_xet_fallback as xet
real_download = xet.hf_hub_download_with_xet_fallback
def _download(*args, **kwargs):
swapped["done"] = True
return real_download(*args, **kwargs)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
with pytest.raises(RuntimeError, match = "built for a different accelerator"):
host.run()
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize(
"hw_label,backend,device", [h for h in HARDWARE if h[1] in ("cuda", "rocm")]
)
def test_h3_revet_tolerates_an_unreadable_accelerator_reprobe(
h3_host, platform, hw_label, backend, device, monkeypatch
):
""" "Could not tell" is not "it changed". sd_cpp_lists_accelerator_device folds an unreadable
probe into True, so comparing THAT against a recorded False would refuse the CPU fallback that
recorded it -- the load must proceed on the reading it already has."""
host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)
def _probe(binary, *args):
if args == ("--list-devices",) and swapped["done"]:
return None
return real_probe(binary, *args)
import utils.hf_xet_fallback as xet
real_download = xet.hf_hub_download_with_xet_fallback
def _download(*args, **kwargs):
swapped["done"] = True
return real_download(*args, **kwargs)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
backend_obj = host.run()
assert backend_obj._state is not None
assert backend_obj._state.device == device
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_probes_devices_only_where_the_answer_is_used(
h3_host, platform, hw_label, backend, device
):
"""--list-devices is probed only on GPU targets, since CPU and MPS never use the answer."""
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
host.run()
expected = 2 if backend not in ("cpu", "mps") else 0
assert len(host.device_probes) == expected
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", HARDWARE)
def test_h3_cancellation_precedes_the_binary_install(h3_host, platform, hw_label, backend, device):
"""A preflight download has no cancel_event, so a load cancelled early must not reach it."""
from core.inference import sd_cpp_backend
host = h3_host(platform = platform, backend = backend, device = device, help_text = _H3_HELP)
ensures: list[str] = []
original = sd_cpp_backend.ensure_h3_sd_cpp_binary
def _spy(**kwargs):
ensures.append("called")
return original(**kwargs)
sd_cpp_backend.ensure_h3_sd_cpp_binary = _spy
try:
cancelled = threading.Event()
cancelled.set()
with pytest.raises(RuntimeError):
host.run(cancel_event = cancelled)
finally:
sd_cpp_backend.ensure_h3_sd_cpp_binary = original
assert ensures == []
assert host.downloads == []
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", [h for h in HARDWARE if h[1] == "rocm"])
def test_h3_revet_catches_a_managed_tree_rebuilt_for_another_accelerator(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""A ROCm build installed over the tree mid-download answers the boolean re-vet exactly as the Vulkan rung did."""
host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)
def _accelerator_of(binary):
return "rocm" if swapped["done"] else "vulkan"
import utils.hf_xet_fallback as xet
real_download = xet.hf_hub_download_with_xet_fallback
def _download(*args, **kwargs):
swapped["done"] = True
return real_download(*args, **kwargs)
monkeypatch.setattr(sd_cpp_backend, "_installed_accelerator_of", _accelerator_of)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
with pytest.raises(RuntimeError, match = "built for a different accelerator"):
host.run()
@pytest.mark.parametrize("platform", PLATFORMS)
@pytest.mark.parametrize("hw_label,backend,device", [h for h in HARDWARE if h[1] == "rocm"])
def test_h3_revet_does_not_invent_a_change_for_an_unrecorded_tree(
h3_host, platform, hw_label, backend, device, monkeypatch
):
"""None is "cannot tell", not "it changed"; refusing on it would refuse every SD_CLI_PATH build."""
host, real_probe, sd_cpp_backend, swapped = _shared_setup_1(backend, device, h3_host, platform)
import utils.hf_xet_fallback as xet
real_download = xet.hf_hub_download_with_xet_fallback
def _download(*args, **kwargs):
swapped["done"] = True
return real_download(*args, **kwargs)
monkeypatch.setattr(
sd_cpp_backend,
"_installed_accelerator_of",
lambda binary: None if swapped["done"] else "vulkan",
)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
host.run()
def _h3_load_with_vae_fetch(monkeypatch, h3_host, error, *, local_files_only):
"""Run a native H3 load whose video VAE fetch raises ``error``; the other files resolve."""
from core.inference.video_minimax_h3 import H3_VIDEO_VAE
import utils.hf_xet_fallback as xet
h3_host(platform = "linux", backend = "cpu", device = "cpu", help_text = _H3_HELP)
real_download = xet.hf_hub_download_with_xet_fallback
def _download(repo, wanted, *args, **kwargs):
if wanted == H3_VIDEO_VAE:
raise error
return real_download(repo, wanted, *args, **kwargs)
monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
fam = _detect_load_family(H3_REPO, None, "minimax-h3")
VideoBackend()._run_load_h3_native(
fam = fam,
token = None,
cancel_event = threading.Event(),
repo_id = H3_REPO,
gguf_filename = H3_FILE,
local_files_only = local_files_only,
)
def test_h3_cache_only_load_names_the_missing_vae_and_the_fix(h3_host, monkeypatch):
"""VAEs cached before the vae/official/ move miss on a cache-only load; say which file and how to fetch it."""
from huggingface_hub.errors import LocalEntryNotFoundError
from core.inference.video_minimax_h3 import H3_VIDEO_VAE
from hub.utils.hf_errors import modelscope_missing
from utils.native_path_leases import redact_native_paths
with pytest.raises(RuntimeError) as caught:
_h3_load_with_vae_fetch(
monkeypatch, h3_host, LocalEntryNotFoundError("cannot find"), local_files_only = True
)
text = str(caught.value)
assert f"video VAE ({H3_VIDEO_VAE})" in text
assert "Load MiniMax-H3 once while online (or reconnect)" in text
assert isinstance(caught.value.__cause__, LocalEntryNotFoundError)
# The load worker stores exactly this as the progress error the UI and API read.
assert (modelscope_missing(caught.value) or redact_native_paths(text)) == text
def test_h3_online_load_miss_is_unchanged(h3_host, monkeypatch):
from huggingface_hub.errors import LocalEntryNotFoundError
error = LocalEntryNotFoundError("hub unreachable")
with pytest.raises(LocalEntryNotFoundError) as caught:
_h3_load_with_vae_fetch(monkeypatch, h3_host, error, local_files_only = False)
assert caught.value is error
def test_h3_cache_only_load_keeps_an_unrelated_error(h3_host, monkeypatch):
error = OSError("disk full")
with pytest.raises(OSError) as caught:
_h3_load_with_vae_fetch(monkeypatch, h3_host, error, local_files_only = True)
assert caught.value is error