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
"""FLUX.2 GGUF inner_dim must be checked from a range-read header, before any base download."""
from __future__ import annotations
import inspect
import re
import threading
import time
import types
import pytest
from core.inference import diffusion_compat
from core.inference.diffusion import DiffusionBackend, _LoadingState
from core.inference.diffusion_families import (
detect_family,
gguf_flux2_inner_dim_from_header,
sd_cpp_text_encoders_for,
)
KLEIN_4B_BASE = "black-forest-labs/FLUX.2-klein-4B"
KLEIN_9B_BASE = "black-forest-labs/FLUX.2-klein-9B"
KLEIN_4B_GGUF = "unsloth/FLUX.2-klein-4B-GGUF"
KLEIN_4B_FILE = "flux-2-klein-4b-Q4_K_M.gguf"
FLUX2_FAMILY = types.SimpleNamespace(name = "flux.2-klein", single_file_is_pipeline = False)
def _gguf_header(
inner_dim: int,
tmp_path,
*,
name = "double_stream_modulation_img.lin.weight",
siblings = 4,
probe_last = False,
):
"""Real GGUF header with no tensor data, from the shipped writer, as a range request would return."""
import numpy as np
from gguf import GGMLQuantizationType, GGUFWriter
path = tmp_path / f"header-{inner_dim}-{siblings}-{int(probe_last)}.gguf"
writer = GGUFWriter(str(path), "flux")
def _probe():
# FLUX.2 sizes this projection as (6 * inner_dim, inner_dim); GGUF stores dims reversed.
writer.add_tensor_info(
name,
[6 * inner_dim, inner_dim],
np.dtype(np.float16),
6 * inner_dim * inner_dim * 2,
raw_dtype = GGMLQuantizationType.F16,
)
if not probe_last:
_probe()
for i in range(siblings):
writer.add_tensor_info(
f"blk.{i}.weight",
[64, 64],
np.dtype(np.float16),
64 * 64 * 2,
raw_dtype = GGMLQuantizationType.F16,
)
if probe_last:
_probe()
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_ti_data_to_file()
writer.close()
return path.read_bytes()
class _FakeResponse:
"""The slice of ``requests.Response`` the header read uses."""
def __init__(
self,
status_code,
body = b"",
):
self.status_code = status_code
self._body = body
def iter_content(self, chunk_size = 1):
for i in range(0, len(self._body), chunk_size):
yield self._body[i : i + chunk_size]
def __enter__(self):
return self
def __exit__(self, *_exc):
return False
def _stub_range_reads(
monkeypatch,
bodies,
*,
status = 206,
):
"""Serves header bytes over a stubbed Hub session; any hf_hub_download call fails the test."""
requests: list[tuple[str, str]] = []
class _Session:
def get(
self,
url,
headers = None,
timeout = None,
stream = False,
):
requests.append((url, (headers or {}).get("Range", "")))
body = next((b for name, b in bodies.items() if url.endswith(name)), None)
if body is None:
return _FakeResponse(404)
return _FakeResponse(status, body)
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
monkeypatch.setattr(
"huggingface_hub.hf_hub_download",
lambda *a, **k: pytest.fail("the compatibility preflight must not download the file"),
)
diffusion_compat._reset_inner_dim_cache()
return requests
@pytest.fixture(autouse = True)
def _clean_probe_cache():
# The memo is process-global by design; a leak between tests would hide a missing probe.
diffusion_compat._reset_inner_dim_cache()
yield
diffusion_compat._reset_inner_dim_cache()
@pytest.mark.parametrize("inner_dim", [3072, 4096, 6144])
def test_the_inner_dim_is_read_from_a_header_with_no_tensor_data(inner_dim, tmp_path):
assert gguf_flux2_inner_dim_from_header(_gguf_header(inner_dim, tmp_path)) == inner_dim
def test_a_plain_reader_cannot_read_the_same_prefix(tmp_path):
# GGUFReader also builds numpy views over tensor DATA, so it raises on a header prefix.
from gguf import GGUFReader
from core.inference.diffusion_families import gguf_flux2_inner_dim
prefix = tmp_path / "prefix-only.gguf"
prefix.write_bytes(_gguf_header(3072, tmp_path))
with pytest.raises(Exception):
GGUFReader(str(prefix))
assert gguf_flux2_inner_dim(prefix) is None
assert gguf_flux2_inner_dim_from_header(prefix.read_bytes()) == 3072
@pytest.mark.parametrize(
"header",
[b"", b"not a gguf at all", b"GGUF" + b"\x00" * 64],
ids = ["empty", "garbage", "truncated"],
)
def test_an_unreadable_header_yields_no_opinion(header):
assert gguf_flux2_inner_dim_from_header(header) is None
def test_a_header_without_the_probe_tensor_yields_no_opinion(tmp_path):
header = _gguf_header(3072, tmp_path, name = "blk.0.attn.weight")
assert gguf_flux2_inner_dim_from_header(header) is None
@pytest.mark.parametrize("probe_last", [False, True], ids = ["probe-first", "probe-last"])
def test_no_truncation_of_a_valid_header_can_invent_a_dim(probe_last, tmp_path):
# Every prefix of a real header must read as the real dim or as nothing, never inner_dim 0.
header = _gguf_header(4096, tmp_path, probe_last = probe_last)
assert gguf_flux2_inner_dim_from_header(header) == 4096
verdicts = {gguf_flux2_inner_dim_from_header(header[:cut]) for cut in range(1, len(header))}
assert verdicts <= {None, 4096}, f"a truncated header invented {verdicts - {None, 4096}}"
def test_a_header_declaring_a_huge_checkpoint_is_cheap(tmp_path):
# Satisfying data views from a prefix would allocate the full declared size (~37 GiB here).
import time
header = _gguf_header(4096, tmp_path, siblings = 1200)
started = time.monotonic()
assert gguf_flux2_inner_dim_from_header(header) == 4096
assert time.monotonic() - started < 5.0
def test_a_mismatched_pair_is_refused_from_the_header_alone(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
with pytest.raises(ValueError) as excinfo:
diffusion_compat.assert_flux2_pick_compatible(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
detail = str(excinfo.value)
assert KLEIN_4B_FILE in detail and KLEIN_9B_BASE in detail
assert "klein-4B" in detail and "klein-9B" in detail
assert len(requests) == 1
url, byte_range = requests[0]
assert url.endswith(f"{KLEIN_4B_GGUF}/resolve/main/{KLEIN_4B_FILE}")
assert byte_range == f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}"
def test_a_matching_pair_passes(monkeypatch, tmp_path):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_4B_BASE
)
is None
)
def test_an_unreadable_header_fails_open(monkeypatch):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: b"not a gguf"})
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
is None
)
def test_an_offline_host_fails_open(monkeypatch):
def _boom(*_a, **_k):
raise OSError("no route to host")
monkeypatch.setattr(
"huggingface_hub.utils.get_session", lambda: types.SimpleNamespace(get = _boom)
)
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
is None
)
def test_a_trickling_server_cannot_hold_the_picker_open(monkeypatch):
# Per-read timeout: a trickling server never times out; only half-close ends iter_content.
interrupted = threading.Event()
class _Trickle:
status_code = 206
def __init__(self):
self.raw = types.SimpleNamespace(shutdown = interrupted.set)
def iter_content(self, chunk_size = 1):
if not interrupted.wait(10):
raise AssertionError("the header read was never interrupted")
raise OSError("Connection broken: IncompleteRead(12 bytes read)")
def close(self):
pass
def __enter__(self):
return self
def __exit__(self, *_exc):
return False
monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
monkeypatch.setattr(
"huggingface_hub.utils.get_session",
lambda: types.SimpleNamespace(get = lambda *a, **k: _Trickle()),
)
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
out: list[bytes] = []
reader = threading.Thread(
target = lambda: out.append(
diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None)
),
daemon = True,
)
reader.start()
reader.join(8)
assert not reader.is_alive(), "the header read outlived its own deadline"
assert out == [b""]
def test_an_old_urllib3_with_no_shutdown_still_cannot_hold_the_picker_open(monkeypatch):
# urllib3 below 2.3.0 lacks HTTPResponse.shutdown, so the worker thread is abandoned.
still_reading = threading.Event()
class _Unwakeable:
status_code = 206
raw = None
def iter_content(self, chunk_size = 1):
still_reading.set()
time.sleep(30)
yield b"never arrives"
def close(self):
pass
def __enter__(self):
return self
def __exit__(self, *_exc):
return False
monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
monkeypatch.setattr(
"huggingface_hub.utils.get_session",
lambda: types.SimpleNamespace(get = lambda *a, **k: _Unwakeable()),
)
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
started = time.monotonic()
assert diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None) == b""
elapsed = time.monotonic() - started
assert still_reading.is_set(), "the fixture never got as far as blocking"
# Deadline plus abandon grace, with room for a loaded CI box.
assert elapsed < 5, f"the picker waited {elapsed:.1f}s on a read it cannot interrupt"
def test_a_server_that_ignores_the_range_header_is_abandoned(monkeypatch, tmp_path):
# A 200 means the whole checkpoint is on the wire, so the body is dropped unread (fail open).
body_reads: list[int] = []
class _WholeFile(_FakeResponse):
def iter_content(self, chunk_size = 1):
body_reads.append(chunk_size)
yield b""
class _Session:
def get(
self,
url,
headers = None,
timeout = None,
stream = False,
):
return _WholeFile(200, _gguf_header(3072, tmp_path))
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
is None
)
assert body_reads == []
@pytest.mark.parametrize(
"base",
["someone/a-base-we-do-not-ship", "/models/my-local-flux2"],
ids = ["unknown-repo", "local-path"],
)
def test_a_base_outside_the_size_table_costs_no_request_at_all(base, monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
assert (
diffusion_compat.flux2_pick_mismatch(FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, base)
is None
)
assert requests == []
def test_a_known_ungated_mirror_is_checked_like_its_upstream(monkeypatch, tmp_path):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
from core.inference.diffusion_families import canonical_base
mirror = "unsloth/FLUX.2-klein-9B"
assert canonical_base(mirror).lower() == KLEIN_9B_BASE.lower(), "mirror table changed"
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, mirror
)
assert reason is not None and mirror in reason
def test_a_non_flux2_family_costs_no_request_at_all(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {"z.gguf": _gguf_header(3072, tmp_path)})
assert (
diffusion_compat.flux2_pick_mismatch(
types.SimpleNamespace(name = "z-image"),
"unsloth/Z-Image-Turbo-GGUF",
"z.gguf",
KLEIN_9B_BASE,
)
is None
)
assert requests == []
def test_a_non_gguf_single_file_costs_no_request_at_all(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {"model.safetensors": _gguf_header(3072, tmp_path)})
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, "model.safetensors", KLEIN_9B_BASE
)
is None
)
assert requests == []
def test_pasting_a_token_re_probes_a_pick_that_missed_anonymously(monkeypatch, tmp_path):
# The memo keeps a miss, but a token paste must re-probe or a gated GGUF stays unguarded.
bodies: dict[str, bytes] = {}
requests = _stub_range_reads(monkeypatch, bodies)
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
is None
)
assert len(requests) == 1
diffusion_compat.flux2_pick_mismatch(FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE)
assert len(requests) == 1
bodies[KLEIN_4B_FILE] = _gguf_header(3072, tmp_path)
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE, "hf_token_value"
)
assert len(requests) == 2
assert reason is not None and KLEIN_9B_BASE in reason
def test_the_header_probe_is_memoised_across_the_three_checks(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
for _ in range(3):
with pytest.raises(ValueError):
diffusion_compat.assert_flux2_pick_compatible(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
assert len(requests) == 1
def test_a_remembered_hub_failure_does_not_outlive_the_download(monkeypatch, tmp_path):
# A memoised negative must not shadow a local file that appeared after the download.
requests = _stub_range_reads(monkeypatch, {})
assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None
assert len(requests) == 1
staged = tmp_path / "blobs" / KLEIN_4B_FILE
staged.parent.mkdir(parents = True, exist_ok = True)
staged.write_bytes(_gguf_header(4096, tmp_path))
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(staged))
assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) == 4096
assert len(requests) == 1
def test_a_remembered_hub_failure_still_suppresses_a_re_probe_while_nothing_is_on_disk(
monkeypatch, tmp_path
):
requests = _stub_range_reads(monkeypatch, {})
for _ in range(3):
assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None
assert len(requests) == 1
def test_a_checkpoint_swapped_in_place_is_read_again(monkeypatch, tmp_path):
"""Same directory and filename, different checkpoint: keying the memo on the name alone answers
the new file with the old dim, refusing a valid 9B pairing until restart."""
local = tmp_path / "on-device"
local.mkdir()
target = local / KLEIN_4B_FILE
target.write_bytes(_gguf_header(3072, tmp_path))
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.flux2_inner_dim_for_pick(str(local), KLEIN_4B_FILE) == 3072
# Headers differ in length too: os.stat resolution can tie a same-size overwrite.
target.write_bytes(_gguf_header(4096, tmp_path, siblings = 9))
assert (
diffusion_compat.flux2_inner_dim_for_pick(str(local), KLEIN_4B_FILE) == 4096
), "the memo answered for the file that used to be at this path"
def test_a_bad_token_does_not_poison_the_good_one_that_replaces_it(monkeypatch, tmp_path):
"""Keying on the token's mere PRESENCE made every non-empty credential one key. A first probe
with an expired token cached its miss there, and pasting a working token afterwards inherited
it for the rest of the process -- the preflight silently off for that pick."""
served: dict[str, bytes] = {}
requests: list[tuple[str, str]] = []
class _GatedSession:
def get(
self,
url,
headers = None,
timeout = None,
stream = False,
):
token = (headers or {}).get("authorization", "")
requests.append((url, token))
if "good" not in token:
return _FakeResponse(401)
return _FakeResponse(206, served[KLEIN_4B_FILE])
served[KLEIN_4B_FILE] = _gguf_header(4096, tmp_path)
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _GatedSession())
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
diffusion_compat._reset_inner_dim_cache()
assert (
diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "expired") is None
)
assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "good") == 4096
before = len(requests)
assert diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, KLEIN_4B_FILE, "good") == 4096
assert len(requests) == before
def test_the_memo_never_holds_the_token_itself():
"""It is a process-global dict; a traceback or a heap dump renders it."""
diffusion_compat._reset_inner_dim_cache()
secret = "hf_averyrealsecrettoken"
assert secret not in diffusion_compat._token_fingerprint(secret)
assert diffusion_compat._token_fingerprint(None) == ""
assert diffusion_compat._token_fingerprint("a") != diffusion_compat._token_fingerprint("b")
def test_a_gguf_already_on_disk_is_read_instead_of_fetched(monkeypatch, tmp_path):
local = tmp_path / "local-repo"
local.mkdir()
(local / KLEIN_4B_FILE).write_bytes(_gguf_header(4096, tmp_path))
requests = _stub_range_reads(monkeypatch, {})
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, str(local), KLEIN_4B_FILE, KLEIN_4B_BASE
)
assert reason is not None and "klein-9B" in reason
assert requests == []
def test_a_local_header_past_the_prefix_cap_falls_back_to_the_full_reader(monkeypatch, tmp_path):
import numpy as np
from gguf import GGUFWriter
from core.inference.diffusion_families import gguf_flux2_inner_dim_from_header
local = tmp_path / "big-header-repo"
local.mkdir()
path = local / "wide.gguf"
writer = GGUFWriter(str(path), "flux")
writer.add_tensor(
"double_stream_modulation_img.lin.weight", np.zeros((48, 8), dtype = np.float16)
)
for i in range(1200):
writer.add_tensor(f"blk.{i}.{'x' * 220}.weight", np.zeros((8, 8), dtype = np.float16))
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
prefix = path.read_bytes()[: diffusion_compat._GGUF_HEADER_BYTES]
assert gguf_flux2_inner_dim_from_header(prefix) is None, "fixture must overflow the cap"
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.flux2_inner_dim_for_pick(str(local), "wide.gguf") == 8
def test_the_download_plan_reports_the_mismatch_instead_of_raising(monkeypatch, tmp_path):
# Reported, not raised: the images page falls back to /images/load on any plan failure.
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
monkeypatch.setattr(
"core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
)
monkeypatch.setattr(
DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
)
monkeypatch.setattr(
DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
)
monkeypatch.setattr(
"core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
)
plan = DiffusionBackend().download_plan(KLEIN_4B_GGUF, gguf_filename = KLEIN_4B_FILE)
assert KLEIN_9B_BASE in (plan["incompatible_reason"] or "")
from models.inference import DiffusionDownloadPlanResponse
assert KLEIN_9B_BASE in (DiffusionDownloadPlanResponse(**plan).incompatible_reason or "")
def test_a_planner_that_omits_the_field_still_answers():
# Native and video planners share this envelope, so the field must default rather than 500.
from models.inference import DiffusionDownloadPlanResponse
assert DiffusionDownloadPlanResponse(entries = [], total_bytes = 0).incompatible_reason is None
def test_a_compatible_plan_reports_nothing(monkeypatch, tmp_path):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
monkeypatch.setattr(
"core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_4B_BASE
)
monkeypatch.setattr(
DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
)
monkeypatch.setattr(
DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
)
monkeypatch.setattr(
"core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
)
plan = DiffusionBackend().download_plan(KLEIN_4B_GGUF, gguf_filename = KLEIN_4B_FILE)
assert plan["incompatible_reason"] is None
def test_the_pre_eviction_preflight_refuses_the_mismatch(monkeypatch, tmp_path):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
monkeypatch.setattr(
"core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
)
monkeypatch.setattr(
"core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
)
with pytest.raises(ValueError, match = "klein"):
DiffusionBackend().preflight_base_access(
KLEIN_4B_GGUF,
FLUX2_FAMILY,
gguf_filename = KLEIN_4B_FILE,
model_kind = "gguf",
)
def test_the_load_refuses_before_prefetching_or_unloading_anything(monkeypatch, tmp_path):
_stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
monkeypatch.setattr(
"core.inference.diffusion._resolve_base_repo", lambda *a, **k: KLEIN_9B_BASE
)
monkeypatch.setattr(
"core.inference.diffusion._assert_base_repo_accessible", lambda *a, **k: None
)
monkeypatch.setattr(
DiffusionBackend, "_te_prequant_plan_files", staticmethod(lambda *a, **k: {})
)
monkeypatch.setattr(
DiffusionBackend, "_estimate_download_bytes", staticmethod(lambda *a, **k: (0, []))
)
monkeypatch.setattr(
DiffusionBackend,
"_prefetch_files",
lambda self, *a, **k: pytest.fail("a rejected pick must not stage a single byte"),
)
monkeypatch.setattr(
DiffusionBackend,
"load_pipeline",
lambda self, **k: pytest.fail("a rejected pick must not reach the load"),
)
backend = DiffusionBackend()
monkeypatch.setattr(
backend,
"_unload_locked",
lambda: pytest.fail("a rejected pick must not free the resident pipeline"),
)
resident = object()
backend._state = resident
backend._load_token = 7
backend._loading = _LoadingState(repo_id = KLEIN_4B_GGUF, base_repo = "")
backend._run_load(
repo_id = KLEIN_4B_GGUF,
gguf_filename = KLEIN_4B_FILE,
model_kind = "gguf",
_load_token = 7,
)
progress = backend.load_progress()
assert progress["phase"] == "error"
assert KLEIN_9B_BASE in progress["error"]
assert backend._state is resident
# ── the sibling hole: the native text-encoder pick ─────────────────────────────
from core.inference.diffusion_families import _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS # noqa: E402
def test_the_native_encoder_follows_the_header_over_the_filename():
fam = detect_family("unsloth/FLUX.2-klein-4B-GGUF")
assert fam is not None and fam.name == "flux.2-klein"
by_name = sd_cpp_text_encoders_for(fam, "unsloth/FLUX.2-klein-4B-GGUF", "my-checkpoint.gguf")
by_header = sd_cpp_text_encoders_for(
fam, "unsloth/FLUX.2-klein-4B-GGUF", "my-checkpoint.gguf", inner_dim = 4096
)
assert by_name == fam.sd_cpp_text_encoders
assert by_header != by_name
# The 9B checkpoint reads Qwen3-8B.
assert by_header == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS
def test_the_header_also_overrides_a_misleading_9b_filename():
fam = detect_family("unsloth/FLUX.2-klein-9B-GGUF")
assert fam is not None
picked = sd_cpp_text_encoders_for(
fam, "unsloth/FLUX.2-klein-9B-GGUF", "flux-2-klein-9b-Q4_K_M.gguf", inner_dim = 3072
)
assert picked == fam.sd_cpp_text_encoders
def test_an_unmapped_or_absent_inner_dim_keeps_the_filename_rule():
fam = detect_family("unsloth/FLUX.2-klein-9B-GGUF")
assert fam is not None
nine_b = sd_cpp_text_encoders_for(fam, "unsloth/FLUX.2-klein-9B-GGUF", "klein-9b.gguf")
for inner_dim in (None, 1234):
assert (
sd_cpp_text_encoders_for(
fam, "unsloth/FLUX.2-klein-9B-GGUF", "klein-9b.gguf", inner_dim = inner_dim
)
== nine_b
)
assert nine_b == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS
def test_a_stalled_response_header_cannot_hold_the_picker_open(monkeypatch):
"""requests' timeout is inactivity only, so the header call must run on an abandonable worker."""
import threading
import types
released = threading.Event()
def _never_returns(*_args, **_kwargs):
released.wait(30)
raise AssertionError("the request should have been abandoned, not awaited")
monkeypatch.setattr(diffusion_compat, "_HEADER_TIMEOUT_SECONDS", 0.5)
monkeypatch.setattr(
"huggingface_hub.utils.get_session",
lambda: types.SimpleNamespace(get = _never_returns),
)
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
out: list[bytes] = []
caller = threading.Thread(
target = lambda: out.append(
diffusion_compat._read_gguf_header(KLEIN_4B_GGUF, KLEIN_4B_FILE, None)
),
daemon = True,
)
caller.start()
caller.join(8)
released.set()
assert not caller.is_alive(), "the caller waited on a request that never returned headers"
assert out == [b""]
def test_the_offline_caller_still_gets_a_memoised_remote_answer(monkeypatch, tmp_path):
"""Offline begin_load must reuse a memoised remote answer, not fall back to the filename heuristic."""
monkeypatch.setattr(diffusion_compat, "_INNER_DIM_CACHE", {})
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
monkeypatch.setattr(
diffusion_compat,
"_read_gguf_header",
lambda *a, **k: _gguf_header(4096, tmp_path),
)
online = diffusion_compat.flux2_inner_dim_for_pick(KLEIN_4B_GGUF, "renamed-4b.gguf")
assert online == 4096
monkeypatch.setattr(
diffusion_compat,
"_read_gguf_header",
lambda *a, **k: pytest.fail("the offline caller made a range request"),
)
assert (
diffusion_compat.flux2_inner_dim_for_pick(
KLEIN_4B_GGUF, "renamed-4b.gguf", allow_network = False
)
== 4096
)
def _cached_snapshot(
tmp_path,
sha,
body,
filename = KLEIN_4B_FILE,
):
"""A file where huggingface_hub puts it: ``models--org--repo/snapshots/<sha>/<file>``."""
path = tmp_path / f"models--{KLEIN_4B_GGUF.replace('/', '--')}" / "snapshots" / sha / filename
path.parent.mkdir(parents = True, exist_ok = True)
path.write_bytes(body)
return path
def _stub_revision(monkeypatch, sha):
def _meta(*_args, **_kwargs):
if sha is None:
raise OSError("offline")
return types.SimpleNamespace(commit_hash = sha, etag = sha)
monkeypatch.setattr("huggingface_hub.get_hf_file_metadata", _meta)
def test_a_republished_checkpoint_is_not_refused_from_the_stale_cache(monkeypatch, tmp_path):
"""try_to_load_from_cache resolves the LOCAL refs/main, so a 4B file republished at the same
name as a 9B one would refuse a pick the loader's own hf_hub_download refreshes and loads."""
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
_stub_revision(monkeypatch, "newcommit")
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
assert reason is None, "a stale cached header refused a pick the loader would have loaded"
assert requests, "the live header was never read"
def test_a_cached_checkpoint_at_the_current_revision_is_still_refused(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
_stub_revision(monkeypatch, "oldcommit")
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
assert reason is not None and "klein-9B" in reason
assert requests == []
def test_a_revision_check_that_cannot_run_keeps_the_cached_refusal(monkeypatch, tmp_path):
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(4096, tmp_path)})
cached = _cached_snapshot(tmp_path, "oldcommit", _gguf_header(3072, tmp_path))
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: str(cached))
_stub_revision(monkeypatch, None)
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_9B_BASE
)
assert reason is not None and "klein-9B" in reason
assert requests == []
def test_an_on_device_checkpoint_is_never_revalidated(monkeypatch, tmp_path):
local = tmp_path / "on-device"
local.mkdir()
(local / KLEIN_4B_FILE).write_bytes(_gguf_header(3072, tmp_path))
requests = _stub_range_reads(monkeypatch, {})
monkeypatch.setattr(
diffusion_compat,
"_hub_revision",
lambda *a, **k: pytest.fail("an On Device pick asked the Hub for a revision"),
)
reason = diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, str(local), KLEIN_4B_FILE, KLEIN_9B_BASE
)
assert reason is not None and "klein-9B" in reason
assert requests == []
# Undownloaded speech quants stay listed, and detect_family_for_pick reads the folder name.
CSM_REPO = "someone/mixed-media-GGUF"
CSM_FILE = "csm-1b-Q4_0.gguf"
DENOISER_FILE = "flux1-dev-Q4_K_M.gguf"
def _arch_header(architecture: str) -> bytes:
"""Minimal GGUF prefix with only general.architecture, read by hand to match the listing-side gate."""
import struct
def string(value: str) -> bytes:
data = value.encode()
return struct.pack("<Q", len(data)) + data
return (
struct.pack("<IIQQ", 0x46554747, 3, 0, 1)
+ string("general.architecture")
+ struct.pack("<I", 8)
+ string(architecture)
)
def test_an_undownloaded_speech_pick_is_refused_before_any_download(monkeypatch):
"""The whole point: the refusal lands off one range request, so the checkpoint is never
pulled and the resident pipeline never torn down for a file that cannot decode."""
requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
with pytest.raises(ValueError) as excinfo:
diffusion_compat.assert_pick_is_not_speech(CSM_REPO, CSM_FILE)
detail = str(excinfo.value)
assert CSM_FILE in detail and "llama-csm" in detail
assert len(requests) == 1
url, byte_range = requests[0]
assert url.endswith(f"{CSM_REPO}/resolve/main/{CSM_FILE}")
assert byte_range == f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}"
def test_a_runnable_media_pick_in_the_same_repo_still_loads(monkeypatch):
"""A runnable media sibling in the repo must still load: catching it too would hide it."""
_stub_range_reads(monkeypatch, {DENOISER_FILE: _arch_header("flux")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, DENOISER_FILE) is None
diffusion_compat.assert_pick_is_not_speech(CSM_REPO, DENOISER_FILE)
TE_REPO = "ponpoke/flux2-klein-9b-uncensored-text-encoder"
TE_FILE = "flux2-klein-9b-uncensored-q4_k_m.gguf"
def test_an_undownloaded_text_encoder_pick_is_refused_before_any_download(monkeypatch):
"""#9875: the repo name matches flux.2-klein, so without this the Qwen3 encoder loads as the denoiser and dies
with "Cannot copy out of meta tensor" after the download and the teardown."""
requests = _stub_range_reads(monkeypatch, {TE_FILE: _arch_header("qwen3")})
with pytest.raises(ValueError) as excinfo:
diffusion_compat.assert_pick_is_not_speech(TE_REPO, TE_FILE)
detail = str(excinfo.value)
assert TE_FILE in detail and "text encoder (qwen3 GGUF)" in detail
assert len(requests) == 1
def test_an_unreadable_speech_header_fails_open(monkeypatch):
"""Fail-open throughout: refusing a pick that works is worse than the download this saves."""
_stub_range_reads(monkeypatch, {}, status = 200)
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
diffusion_compat.assert_pick_is_not_speech(CSM_REPO, CSM_FILE)
def test_a_pick_with_no_gguf_filename_is_not_probed(monkeypatch):
"""A pipeline or single_file pick names no GGUF, so there is no header to ask."""
requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, None) is None
assert requests == []
def test_the_speech_verdict_is_memoised_per_pick(monkeypatch):
"""Expanding and re-picking a row must not re-spend the range request."""
requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(requests) == 1
def test_a_failed_probe_is_not_reused_for_a_retry_with_a_working_token(monkeypatch):
"""A probe that failed on an expired credential memoises "no verdict". Keyed without the
token, the retry with a working one reads that back and the speech file reaches the download
this preflight exists to stop."""
bodies = {CSM_FILE: _arch_header("llama-csm")}
requests: list = []
class _Session:
def get(
self,
url,
headers = None,
timeout = None,
stream = False,
):
header_map = headers or {}
requests.append(header_map.get("authorization") or header_map.get("Authorization"))
if not any("good" in str(v) for v in header_map.values()):
return _FakeResponse(401)
body = next((b for name, b in bodies.items() if url.endswith(name)), None)
return _FakeResponse(206, body) if body is not None else _FakeResponse(404)
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: _Session())
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, "expired") is None
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, "good-token") is not None
assert len(requests) == 2
def test_a_checkpoint_that_lands_after_a_miss_is_probed_again(monkeypatch, tmp_path):
"""A file replaced under the same name is a different checkpoint; keyed without its identity
the verdict never revisits it."""
_stub_range_reads(monkeypatch, {})
landed = tmp_path / CSM_FILE
seen: dict = {"path": None}
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: seen["path"])
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
landed.write_bytes(_arch_header("llama-csm"))
seen["path"] = str(landed)
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
def _cache_entry(tmp_path, revision, arch):
"""A GGUF sitting in an HF cache snapshot dir, so ``_snapshot_revision`` can read its commit."""
snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / revision
snapshot.mkdir(parents = True, exist_ok = True)
path = snapshot / CSM_FILE
path.write_bytes(_arch_header(arch))
return str(path)
def test_a_republished_gguf_is_not_refused_from_the_stale_cached_copy(monkeypatch, tmp_path):
"""``try_to_load_from_cache`` resolves the LOCAL refs/main, so a republished filename would
be refused off the csm bytes still on disk while ``hf_hub_download`` refreshes and loads the
new ones."""
cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("flux")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
def test_a_cached_gguf_at_the_current_revision_is_still_refused(monkeypatch, tmp_path):
"""The revalidation must not become an escape hatch: same commit, same verdict."""
cached = _cache_entry(tmp_path, "samesha", "llama-csm")
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "samesha")
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
def test_a_revision_check_that_cannot_run_keeps_the_refusal(monkeypatch, tmp_path):
"""An offline or erroring host leaves today's verdict alone rather than opening the gate."""
cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: None)
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
def test_an_on_device_speech_checkpoint_is_never_revalidated(monkeypatch, tmp_path):
"""An On Device file is the one the loader opens, so there is no revision to be behind."""
on_device = tmp_path / CSM_FILE
on_device.write_bytes(_arch_header("llama-csm"))
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))
asked: list = []
def _never(*a, **k):
asked.append(a)
return "newsha"
monkeypatch.setattr(diffusion_compat, "_hub_revision", _never)
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert asked == []
def test_a_pick_that_names_the_checkpoint_outright_is_probed_like_the_loader_opens_it(tmp_path):
"""A file-valued repo_id is accepted by the video loader, so the preflight must probe it as a file."""
direct = tmp_path / "wan-models" / CSM_FILE
direct.parent.mkdir(parents = True)
direct.write_bytes(_arch_header("llama-csm"))
reason = diffusion_compat.speech_pick_refusal(str(direct), CSM_FILE, None, False)
assert reason is not None and "llama-csm" in reason
assert diffusion_compat._local_gguf_path(str(direct), CSM_FILE) == str(direct)
denoiser = direct.parent / DENOISER_FILE
denoiser.write_bytes(_arch_header("flux"))
assert diffusion_compat.speech_pick_refusal(str(denoiser), DENOISER_FILE, None, False) is None
assert diffusion_compat._local_gguf_path(str(direct.parent), CSM_FILE) == str(direct)
# Pages stage and download BEFORE load; Video and sd.cpp do not share DiffusionBackend's preflight.
def test_the_shared_refusal_is_wired_into_every_plan_and_load_path():
"""Structural, deliberately: the tests above pin the verdict, but what keeps regressing is
where it is CALLED, and exercising each engine's plan/load needs a live backend and a Hub."""
import inspect
from core.inference import diffusion, sd_cpp_backend, video
plan = inspect.getsource(diffusion.DiffusionBackend.download_plan)
assert "speech_pick_refusal" in plan
assert "_assert_pick_is_not_speech" in inspect.getsource(video.VideoBackend.download_plan)
assert "_assert_pick_is_not_speech" in inspect.getsource(video.VideoBackend._run_load)
# sd.cpp: plan and worker. NOT begin_load, which is offline-only and cannot afford the bound.
sd_plan = inspect.getsource(sd_cpp_backend.SdCppDiffusionBackend.download_plan)
assert "_assert_pick_is_not_speech" in sd_plan
assert "_assert_pick_is_not_speech" not in inspect.getsource(
sd_cpp_backend.SdCppDiffusionBackend.begin_load
)
def test_the_video_and_sd_cpp_helpers_delegate_to_the_one_verdict(monkeypatch):
"""Three engines, one refusal. A second copy of the speech arch set is how they drift."""
from core.inference import sd_cpp_backend, video
seen: list = []
monkeypatch.setattr(
diffusion_compat,
"assert_pick_is_not_speech",
lambda *a, **k: seen.append(a),
)
video._assert_pick_is_not_speech(CSM_REPO, CSM_FILE, "tok", allow_network = False)
sd_cpp_backend._assert_pick_is_not_speech(CSM_REPO, CSM_FILE, "tok", allow_network = False)
assert seen == [(CSM_REPO, CSM_FILE, "tok", False), (CSM_REPO, CSM_FILE, "tok", False)]
def test_a_media_gguf_republished_as_speech_is_refused(monkeypatch, tmp_path):
"""A stale refusal only costs a pick, but a stale ALLOW hands csm bytes to a media loader, so
revalidation cannot be the cheap side of the asymmetry."""
snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "oldsha"
snapshot.mkdir(parents = True)
cached = snapshot / CSM_FILE
cached.write_bytes(_arch_header("flux"))
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
def test_an_uncached_pick_never_spends_a_revision_head(monkeypatch):
"""No cached copy, no revision to be behind: uncached picks must not spend a Hub HEAD."""
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
asked: list = []
monkeypatch.setattr(
diffusion_compat, "_hub_revision", lambda *a, **k: asked.append(a) or "newsha"
)
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert asked == []
def test_a_cache_only_load_never_range_reads_an_uncached_pick(monkeypatch):
"""An automatic load sets local_files_only, and that contract covers the metadata probes too:
an uncached pick gives up rather than spend the range request and its 15s bound."""
requests = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is None
assert requests == []
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(requests) == 1
def test_a_cache_only_load_still_reads_a_checkpoint_already_on_disk(monkeypatch, tmp_path):
"""Offline does not mean blind: a copy already on disk answers with no request at all."""
on_device = tmp_path / CSM_FILE
on_device.write_bytes(_arch_header("llama-csm"))
requests = _stub_range_reads(monkeypatch, {})
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is not None
assert requests == []
def test_a_cache_only_probe_does_not_memoise_a_skipped_revision_check(monkeypatch, tmp_path):
"""A cached copy read WITHOUT its revision check is half an answer; memoising it would let
the network-allowed caller behind it read that back and never revalidate."""
snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "oldsha"
snapshot.mkdir(parents = True)
cached = snapshot / CSM_FILE
cached.write_bytes(_arch_header("flux"))
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))
heads: list = []
monkeypatch.setattr(
diffusion_compat, "_hub_revision", lambda *a, **k: heads.append(a) or "newsha"
)
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE, allow_network = False) is None
assert heads == []
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(heads) == 1
def test_an_uncached_remote_verdict_is_not_memoised_forever(monkeypatch):
"""An uncached remote pick keys on a None identity, so a republish under the same filename
changes nothing; without a TTL the verdict would outlive the process."""
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: None)
bodies = {CSM_FILE: _arch_header("llama-csm")}
_stub_range_reads(monkeypatch, bodies)
# Driven, not real: the entry expires relative to whatever monotonic said when it was written.
clock = [1000.0]
monkeypatch.setattr(diffusion_compat.time, "monotonic", lambda: clock[0])
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
bodies[CSM_FILE] = _arch_header("flux")
clock[0] += diffusion_compat._SPEECH_REMOTE_TTL_SECONDS + 1.0
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
def test_a_snapshot_backed_verdict_keeps_its_entry_across_the_window(monkeypatch, tmp_path):
"""A cached entry needs no TTL: its key carries the file identity and the revision check asks
the Hub. Expiring it too would spend a range read per pick for nothing."""
snapshot = tmp_path / "models--someone--mixed-media-GGUF" / "snapshots" / "samesha"
snapshot.mkdir(parents = True)
cached = snapshot / CSM_FILE
cached.write_bytes(_arch_header("llama-csm"))
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(cached))
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "samesha")
requests = _stub_range_reads(monkeypatch, {})
clock = [1000.0]
monkeypatch.setattr(diffusion_compat.time, "monotonic", lambda: clock[0])
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
clock[0] += diffusion_compat._SPEECH_REMOTE_TTL_SECONDS * 10
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert requests == []
def test_both_media_routes_refuse_a_speech_pick_before_taking_the_gpu():
"""Media routes refuse a speech pick before the GPU arbiter, or the resident model is evicted first."""
import inspect
from routes import inference as inference_route
from routes import video as video_route
for source, acquire, label in (
(
inspect.getsource(video_route.load_video_model_gated),
r"acquire_for_request\(\s*VIDEO\b",
"video",
),
(
inspect.getsource(inference_route.load_diffusion_model_gated),
r"acquire_for_request\(\s*DIFFUSION\b",
"images",
),
):
assert "assert_pick_is_not_speech" in source, label
# The call may wrap its arguments over several lines (e.g. with policy_kwargs).
call = re.search(acquire, source)
assert call is not None, label
assert source.index("assert_pick_is_not_speech") < call.start(), label
def test_an_automatic_image_load_keeps_the_pre_eviction_preflight_offline():
"""Automatic image loads keep the pre-eviction preflight offline, so no revision HEAD hits the Hub."""
import inspect
from core.inference import diffusion, sd_cpp_backend
from routes import inference as inference_route
preflight = inspect.getsource(diffusion.DiffusionBackend.preflight_base_access)
assert "assert_pick_is_not_speech(repo_id, gguf_filename, hf_token, allow_network)" in preflight
route = inspect.getsource(inference_route.load_diffusion_model_gated)
assert "allow_network = user_initiated" in route
for backend in (diffusion.DiffusionBackend, sd_cpp_backend.SdCppDiffusionBackend):
assert "allow_network" in inspect.signature(backend.preflight_base_access).parameters
# The Mimi vocoder in ggml-org/sesame-csm-1b-GGUF writes a sentence as its architecture id.
_VOCODER_ARCH = "this model cannot be used as LLM, use it via --model-vocoder in TTS examples"
class _HttpxLikeClient:
"""Fake httpx.Client surface matching get_session on huggingface_hub 1.x, not a requests mock."""
def __init__(self, body):
self.body = body
self.calls: list[tuple[str, str]] = []
def get(
self,
url,
params = None,
headers = None,
timeout = None,
**kwargs,
):
if "stream" in kwargs:
raise TypeError("Client.get() got an unexpected keyword argument 'stream'")
raise AssertionError("a ranged header read must use the streaming API")
def stream(
self,
method,
url,
headers = None,
timeout = None,
follow_redirects = False,
):
self.calls.append((method, (headers or {}).get("Range", "")))
assert follow_redirects, "the Hub answers a resolve URL with a 302 to the CDN"
return _HttpxLikeStream(self.body)
class _HttpxLikeStream:
def __init__(self, body):
self.body = body
def __enter__(self):
return self
def __exit__(self, *exc):
return False
@property
def status_code(self):
return 206
def iter_bytes(self, chunk_size = 65536):
for start in range(0, len(self.body), chunk_size):
yield self.body[start : start + chunk_size]
def close(self):
pass
def test_the_ranged_read_works_on_the_httpx_client_hub_1_x_returns(monkeypatch):
"""huggingface_hub 1.0 moved to httpx, which has no stream = True keyword; the TypeError was
swallowed by a blanket except, so every uncached remote pick failed open."""
client = _HttpxLikeClient(_arch_header("llama-csm"))
monkeypatch.setattr("huggingface_hub.utils.get_session", lambda: client)
monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", lambda *a, **k: None)
diffusion_compat._reset_inner_dim_cache()
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert client.calls == [("GET", f"bytes=0-{diffusion_compat._GGUF_HEADER_BYTES - 1}")]
def test_the_ranged_read_still_works_on_the_requests_session_hub_0_x_returns(monkeypatch):
"""The other half of the floor: python < 3.10 pins 0.36, whose session is requests'."""
requests_log = _stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("llama-csm")})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(requests_log) == 1
def test_a_requests_session_is_not_mistaken_for_an_httpx_client(monkeypatch):
"""``requests.Session.stream`` is a plain bool attribute and ``httpx.Client.stream`` is a
method, so the branch has to test for a CALLABLE. Testing for the name alone sends a requests
session down the httpx path and breaks the client that works today."""
import requests
assert hasattr(requests.Session(), "stream")
assert not callable(getattr(requests.Session(), "stream", None))
def test_a_cached_snapshot_verdict_does_not_outlive_its_revision_check(monkeypatch, tmp_path):
"""A snapshot-backed entry memoises a revision check; holding it forever meant the Hub was asked
once per file per process, so a republished checkpoint kept its stale verdict."""
cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
heads: list = []
def _head(*a, **k):
heads.append(a)
return "oldsha"
monkeypatch.setattr(diffusion_compat, "_hub_revision", _head)
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(heads) == 1
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(heads) == 1
monkeypatch.setattr(
diffusion_compat.time,
"monotonic",
lambda: 1e9 + diffusion_compat._SPEECH_REMOTE_TTL_SECONDS,
)
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
assert len(heads) == 2
def test_an_on_device_verdict_is_still_cached_permanently(monkeypatch, tmp_path):
"""On Device files have no revision to lag, so the identity-keyed verdict never expires."""
on_device = tmp_path / CSM_FILE
on_device.write_bytes(_arch_header("llama-csm"))
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: str(on_device))
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
key = next(iter(diffusion_compat._SPEECH_ARCH_CACHE))
assert diffusion_compat._SPEECH_ARCH_CACHE[key][1] is None
def test_a_failed_refresh_keeps_the_verdict_it_already_had(monkeypatch, tmp_path):
"""A new-revision HEAD followed by a failed re-read must keep a known llama-csm verdict, not
replace it with None; failing open is for UNKNOWN picks only."""
cached = _cache_entry(tmp_path, "oldsha", "llama-csm")
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
_stub_range_reads(monkeypatch, {})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None
diffusion_compat._reset_inner_dim_cache()
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header("flux")})
monkeypatch.setattr(diffusion_compat, "_local_gguf_path", lambda *a, **k: cached)
monkeypatch.setattr(diffusion_compat, "_hub_revision", lambda *a, **k: "newsha")
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is None
def test_every_published_csm_spelling_is_refused_by_the_media_preflight(monkeypatch):
"""A bundle's vocoder reaches media loaders too, so every CSM spelling must be refused."""
for arch in ("llama-csm", "csm", "csm-tts", "mimi"):
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header(arch)})
assert diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE) is not None, arch
_stub_range_reads(monkeypatch, {CSM_FILE: _arch_header(_VOCODER_ARCH)})
reason = diffusion_compat.speech_pick_refusal(CSM_REPO, CSM_FILE)
assert reason is not None and "--model-vocoder" not in reason
def test_one_pick_range_reads_the_header_once_for_both_probes(monkeypatch, tmp_path):
"""Size pairing and the speech verdict must share one range read of the same GGUF prefix."""
requests = _stub_range_reads(monkeypatch, {KLEIN_4B_FILE: _gguf_header(3072, tmp_path)})
assert (
diffusion_compat.flux2_pick_mismatch(
FLUX2_FAMILY, KLEIN_4B_GGUF, KLEIN_4B_FILE, KLEIN_4B_BASE
)
is None
), "the fixture pairs correctly, so the speech probe behind it really does run"
assert diffusion_compat.speech_pick_refusal(KLEIN_4B_GGUF, KLEIN_4B_FILE) is None
assert len(requests) == 1, f"one pick, one header read; got {len(requests)}"
def test_a_revalidation_still_re_reads_rather_than_answering_from_the_shared_prefix(
monkeypatch, tmp_path
):
"""Revalidation must re-read the header, never answer from the shared prefix memo."""
source = inspect.getsource(diffusion_compat)
for fn in ("_revalidated_inner_dim", "_revalidated_speech_arch"):
body = source.split(f"def {fn}(", 1)[1].split("\ndef ", 1)[0]
assert "_shared_gguf_header" not in body, f"{fn} must re-read, not consult the memo"
assert "_read_gguf_header" in body
def test_the_chat_backend_does_not_import_pyyaml_to_learn_the_speech_verdict():
"""llama_cpp must not import the models package, or PyYAML becomes a hard chat-backend dependency."""
import importlib
import subprocess
import sys
from pathlib import Path
backend = Path(diffusion_compat.__file__).resolve().parents[2]
probe = (
"import sys\n"
"class Blocker:\n"
" def find_spec(self, name, path=None, target=None):\n"
" if name == 'yaml' or name.startswith('yaml.'):\n"
" raise ModuleNotFoundError(\"No module named 'yaml'\")\n"
" return None\n"
"sys.meta_path.insert(0, Blocker())\n"
f"sys.path.insert(0, {str(backend)!r})\n"
"import core.inference.llama_cpp as m\n"
"from utils.gguf_archs import SPEECH_GGUF_ARCHS\n"
"assert m.LlamaCppBackend._SPEECH_ARCHES is SPEECH_GGUF_ARCHS\n"
"print('ok')\n"
)
# Subprocess: yaml is already imported here, and meta_path blockers cannot un-import it.
result = subprocess.run(
[sys.executable, "-c", probe], capture_output = True, text = True, timeout = 300
)
assert result.returncode == 0, f"stderr: {result.stderr}"
# No re-export from the heavy package; scripts/verify_import_hoist.py blocks those anyway.
gguf_metadata = importlib.import_module("utils.models.gguf_metadata")
for name in ("SPEECH_GGUF_ARCHS", "is_speech_gguf_architecture"):
assert not hasattr(
gguf_metadata, name
), f"{name} must be imported from utils.gguf_archs, not through utils.models"
def test_qwen_image_2_1_takes_the_dynamic_4bit_text_encoder():
"""Pin the Qwen-Image-2.1 encoder filename exactly; a missing name 404s mid-load, after staging."""
from core.inference.diffusion_families import detect_family
fam = detect_family("Qwen/Qwen-Image-2.1")
assert fam.sd_cpp_text_encoders == (
(
"unsloth/Qwen3-VL-8B-Instruct-GGUF",
"Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf",
"llm",
),
("unsloth/Qwen3-VL-8B-Instruct-GGUF", "mmproj-F16.gguf", "llm_vision"),
)