Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

14.6 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

"""Shared begin_load contract: every keyword the route passes must bind on both image engines."""

from __future__ import annotations

import ast
import asyncio
import inspect
import textwrap
import threading
import types
from pathlib import Path
from unittest.mock import create_autospec

import pytest

from core.inference.diffusion import DiffusionBackend
from core.inference.sd_cpp_backend import SdCppDiffusionBackend


def _route_begin_load_keywords() -> list[str]:
    """Parses the begin_load keywords off the route so the test cannot drift from it."""
    import routes.inference as route_module

    source = textwrap.dedent(inspect.getsource(route_module.load_diffusion_model_gated))
    for node in ast.walk(ast.parse(source)):
        if not (isinstance(node, ast.FunctionDef) and node.name == "_start_engine_load"):
            continue
        for call in ast.walk(node):
            if (
                isinstance(call, ast.Call)
                and isinstance(call.func, ast.Attribute)
                and call.func.attr == "begin_load"
            ):
                # ``**kwargs`` would arrive as a None-named keyword; the route spells every one out.
                return [kw.arg for kw in call.keywords if kw.arg is not None]
    raise AssertionError("_start_engine_load no longer calls engine.begin_load")


def test_the_route_still_passes_local_files_only():
    # Without this, the assertions below still pass if the route drops local_files_only.
    assert "local_files_only" in _route_begin_load_keywords()


@pytest.mark.parametrize("engine", [DiffusionBackend, SdCppDiffusionBackend])
def test_both_engines_accept_every_keyword_the_route_passes(engine):
    """``inspect.signature().bind`` is the exact check the interpreter makes at call time."""
    keywords = _route_begin_load_keywords()
    signature = inspect.signature(engine.begin_load)
    # Unbound function needs no engine; bind checks names and arity, never values.
    signature.bind(
        None,
        "unsloth/FLUX.1-dev-GGUF",
        **{name: None for name in keywords},
    )


def test_the_two_begin_load_signatures_declare_local_files_only_alike():
    """Both engines declare local_files_only alike; a **kwargs catch-all would silently drop it."""
    params = {
        engine: inspect.signature(engine.begin_load).parameters
        for engine in (DiffusionBackend, SdCppDiffusionBackend)
    }
    for engine, parameters in params.items():
        assert "local_files_only" in parameters, engine
        declared = parameters["local_files_only"]
        assert declared.kind is inspect.Parameter.KEYWORD_ONLY, engine
        assert declared.default is False, engine
    assert not any(
        p.kind is inspect.Parameter.VAR_KEYWORD for p in params[SdCppDiffusionBackend].values()
    ), "a **kwargs catch-all would accept the flag and ignore it"


# ── The route, driven onto the native engine ───────────────────────────────


def _drive_the_images_load(
    monkeypatch,
    *,
    user_initiated: bool,
    engine_choice = None,
    begin_load_error = None,
    notes = None,
):
    """Run ``POST /images/load``'s body with the NATIVE engine selected; return the mock engine.

    Autospec'd off the real class, so the call the route makes is bound against the real
    ``begin_load`` signature: this is what turns the shipped TypeError into a test failure.
    """
    import core.inference.diffusion_device as device_module
    import core.inference.diffusion_engine_router as router_module
    from core.inference.sd_cpp_engine import ENGINE_SD_CPP
    from models.inference import DiffusionLoadRequest
    from routes.inference import load_diffusion_model_gated

    engine = create_autospec(SdCppDiffusionBackend, instance = True)
    engine.begin_load.return_value = {"loaded": False, "repo_id": None}
    if begin_load_error is not None:
        engine.begin_load.side_effect = begin_load_error
    if notes is not None:
        # The before-load snapshot is taken before begin_load starts the worker.
        monkeypatch.setattr(
            router_module,
            "loaded_state_of",
            lambda e: notes.append(("snapshot", engine.begin_load.call_count, e is engine)),
        )
        monkeypatch.setattr(
            router_module,
            "note_engine_pick",
            lambda pick, loaded_by = None, before = None: notes.append(
                (pick, engine.begin_load.call_count, loaded_by is engine)
            ),
        )
    engine.preflight_base_access.return_value = None

    monkeypatch.setattr(router_module, "predict_engine", lambda *a, **k: ENGINE_SD_CPP)
    monkeypatch.setattr(router_module, "active_engine_name", lambda: ENGINE_SD_CPP)
    monkeypatch.setattr(router_module, "engine_for", lambda name: engine)
    monkeypatch.setattr(router_module, "select_and_activate_engine", lambda *a, **k: engine)
    monkeypatch.setattr(router_module, "begin_load_on", lambda _engine, start: start())
    monkeypatch.setattr(router_module, "annotate_status", lambda status: status)
    monkeypatch.setattr(
        device_module,
        "resolve_diffusion_device_target",
        lambda: types.SimpleNamespace(device = "cpu"),
    )
    monkeypatch.setattr("routes.inference._guard_diffusion_load_against_training", lambda: None)

    async def _no_ordinal(_gpu_ids):
        return None

    monkeypatch.setattr("routes.inference._selected_gpu_ordinal", _no_ordinal)

    asyncio.run(
        load_diffusion_model_gated(
            DiffusionLoadRequest(
                model_path = "unsloth/FLUX.1-dev-GGUF",
                gguf_filename = "flux1-dev-Q4_K_M.gguf",
                engine = engine_choice,
            ),
            "test-user",
            user_initiated = user_initiated,
        )
    )
    return engine


@pytest.mark.parametrize("user_initiated", [True, False])
def test_the_images_page_can_load_on_the_native_engine(monkeypatch, user_initiated):
    engine = _drive_the_images_load(monkeypatch, user_initiated = user_initiated)

    engine.begin_load.assert_called_once()
    assert engine.begin_load.call_args.kwargs["local_files_only"] is (not user_initiated)


def test_the_engine_pick_is_recorded_only_once_the_engine_accepted_the_load(monkeypatch):
    # Recorded after begin_load, not at selection: a refusal past selection keeps the resident model's provenance.
    notes = []
    _drive_the_images_load(monkeypatch, user_initiated = True, engine_choice = "sd_cpp", notes = notes)
    assert notes == [("snapshot", 0, True), ("sd_cpp", 1, True)]
    notes.clear()
    with pytest.raises(Exception):
        _drive_the_images_load(
            monkeypatch,
            user_initiated = True,
            engine_choice = "sd_cpp",
            begin_load_error = RuntimeError("busy"),
            notes = notes,
        )
    assert notes == [("snapshot", 0, True)]


# ── The native loader honours it ───────────────────────────────────────────


def _no_hub(monkeypatch):
    """Make every huggingface_hub API call this load could reach an outright failure."""
    import huggingface_hub

    def _forbidden(*_a, **_k):
        raise AssertionError("a cache-only load reached the Hub")

    monkeypatch.setattr(huggingface_hub.HfApi, "model_info", _forbidden)
    monkeypatch.setattr(huggingface_hub.HfApi, "get_paths_info", _forbidden)
    monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", _forbidden)


def test_a_cache_only_native_load_makes_no_hub_call(monkeypatch):
    """Cache-only native loads make no Hub call; the size probe and preflight would fail open silently."""
    from core.inference.diffusion_families import detect_family
    from core.inference.sd_cpp_backend import SdCppDiffusionBackend as Native

    _no_hub(monkeypatch)
    backend = Native(engine = None)
    monkeypatch.setattr(
        Native,
        "_resolve_backend",
        lambda self: ("oneshot", None, types.SimpleNamespace(version = lambda: "master")),
    )
    fetched: list = []

    def _fetch(
        self,
        assets,
        token,
        cancel_event = None,
        local_files_only = False,
        vision_optional = True,
    ):
        fetched.append(local_files_only)
        raise RuntimeError("stop here; the Hub calls under test all precede the fetch")

    monkeypatch.setattr(Native, "_fetch_assets", _fetch)

    repo = "unsloth/FLUX.1-dev-GGUF"
    Native._run_load(
        backend,
        repo_id = repo,
        gguf_filename = "flux1-dev-Q4_K_M.gguf",
        base = "black-forest-labs/FLUX.1-dev",
        fam = detect_family(repo),
        hf_token = None,
        local_files_only = True,
        _load_token = 1,
    )

    assert fetched == [True]


def test_the_native_fetch_resolves_from_cache_only(monkeypatch, tmp_path):
    """``local_files_only`` reaches huggingface_hub, where it is the only thing that stops a pull."""
    import utils.hf_xet_fallback as xet
    from core.inference.sd_cpp_backend import SdCppDiffusionBackend as Native

    seen: list = []
    cached = tmp_path / "flux1-dev-Q4_K_M.gguf"
    cached.write_bytes(b"")

    def _download(repo_id, filename, token, **kwargs):
        seen.append((repo_id, filename, kwargs.get("local_files_only")))
        return str(cached)

    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    Native(engine = None)._fetch_assets(
        [("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", "diffusion_model")],
        None,
        local_files_only = True,
    )

    assert seen == [("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", True)]


def test_an_uncached_asset_fails_with_a_local_error_naming_it(monkeypatch):
    """The miss must READ as a miss. huggingface_hub's own text names neither repo nor file, and
    this string is what /images/load-progress puts in front of the user."""
    from huggingface_hub.errors import LocalEntryNotFoundError

    import utils.hf_xet_fallback as xet
    from core.inference.sd_cpp_backend import SdCppDiffusionBackend as Native

    def _download(*_a, **_k):
        raise LocalEntryNotFoundError("Cannot find the requested files in the disk cache")

    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)

    with pytest.raises(RuntimeError) as caught:
        Native(engine = None)._fetch_assets(
            [("black-forest-labs/FLUX.1-dev", "ae.safetensors", "vae")],
            None,
            local_files_only = True,
        )
    message = str(caught.value)
    assert "ae.safetensors" in message
    assert "unsloth/FLUX.1-dev" in message


def test_an_uncached_vision_projector_does_not_fail_an_offline_load(monkeypatch, tmp_path):
    """Text-to-image never reads --llm_vision, so an uncached projector must not fail an offline
    restore; only the projector is optional, and the encoder still fails loudly"""
    from huggingface_hub.errors import LocalEntryNotFoundError

    import utils.hf_xet_fallback as xet
    from core.inference.sd_cpp_backend import SdCppDiffusionBackend as Native

    cached = tmp_path / "Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf"
    cached.write_bytes(b"")

    def _download(repo_id, filename, token, **kwargs):
        if filename == "mmproj-F16.gguf":
            raise LocalEntryNotFoundError("Cannot find the requested files in the disk cache")
        return str(cached)

    monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
    repo = "unsloth/Qwen3-VL-8B-Instruct-GGUF"
    paths = Native(engine = None)._fetch_assets(
        [(repo, cached.name, "llm"), (repo, "mmproj-F16.gguf", "llm_vision")],
        None,
        local_files_only = True,
    )
    assert paths == {"llm": str(cached)}

    with pytest.raises(RuntimeError, match = "mmproj-F16.gguf"):
        Native(engine = None)._fetch_assets(
            [(repo, "mmproj-F16.gguf", "llm")], None, local_files_only = True
        )


def test_the_default_still_takes_the_xet_fallback_ladder(monkeypatch, tmp_path):
    """Nothing changes with the flag off: the shared Xet -> HTTP path is still the one used, and
    ``local_files_only`` is not forwarded to a shared layer that may predate it."""
    import utils.hf_xet_fallback as xet

    seen: list = []

    def _shared(repo_id, filename, token, **kwargs):
        seen.append(kwargs)
        return str(tmp_path / filename)

    monkeypatch.setattr(xet, "_shared_hf_hub_download_with_xet_fallback", _shared)

    xet.hf_hub_download_with_xet_fallback(
        "unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", None, cache_dir = str(tmp_path)
    )

    assert len(seen) == 1
    assert "local_files_only" not in seen[0]


def test_the_offline_download_never_reaches_the_shared_ladder(monkeypatch, tmp_path):
    """Offline downloads go straight to huggingface_hub: an older zoo drops local_files_only kwargs."""
    import huggingface_hub

    import utils.hf_xet_fallback as xet

    def _forbidden(*_a, **_k):
        raise AssertionError("the shared Xet ladder must not run for a cache-only download")

    monkeypatch.setattr(xet, "_shared_hf_hub_download_with_xet_fallback", _forbidden)
    seen: list = []

    def _hub(**kwargs):
        seen.append(kwargs)
        return str(tmp_path / "flux1-dev-Q4_K_M.gguf")

    monkeypatch.setattr(huggingface_hub, "hf_hub_download", _hub)

    xet.hf_hub_download_with_xet_fallback(
        "unsloth/FLUX.1-dev-GGUF",
        "flux1-dev-Q4_K_M.gguf",
        None,
        cache_dir = str(tmp_path),
        local_files_only = True,
    )

    assert seen and seen[0]["local_files_only"] is True


def test_a_cancelled_offline_download_still_stops(monkeypatch, tmp_path):
    """The cancellation contract is the ladder's, not huggingface_hub's, so the bypass keeps it."""
    import utils.hf_xet_fallback as xet

    cancel = threading.Event()
    cancel.set()
    with pytest.raises(RuntimeError):
        xet.hf_hub_download_with_xet_fallback(
            "unsloth/FLUX.1-dev-GGUF",
            "flux1-dev-Q4_K_M.gguf",
            None,
            cache_dir = str(tmp_path),
            local_files_only = True,
            cancel_event = cancel,
        )


def test_the_binary_install_is_not_covered_by_the_flag():
    """The sd.cpp binary install is outside local_files_only; it resolves before assets are fetched."""
    source = inspect.getsource(SdCppDiffusionBackend._run_load)
    resolve = source.index("self._resolve_backend()")
    fetch = source.index("self._fetch_assets(")
    assert resolve < fetch, "the binary is resolved before the assets; the comment above assumes it"
    assert Path(inspect.getsourcefile(SdCppDiffusionBackend)).name == "sd_cpp_backend.py"