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
Studio: faster MiniMax-H3 GGUF renders (resident under memory auto, sd.cpp pin upgrade, speed_mode=max kernels) (#12405)
Daniel Hanc85ee3700c8a
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.pyindex 35d27b7ced4..b25261c2204 100644--- a/studio/backend/core/inference/sd_cpp_backend.py+++ b/studio/backend/core/inference/sd_cpp_backend.py@@ -343,6 +343,14 @@ def sd_cpp_supports_graph_cut(binary: Optional[str]) -> bool:return all(marker in text for marker in _GRAPH_CUT_HELP_MARKERS)+def sd_cpp_supports_sage_attn(binary: Optional[str]) -> bool:+ """Fails closed: sd-cli exits non-zero on an unknown option (u13b9d92 predates --sage-attn)."""+ if not binary:+ return False+ text = _sd_cpp_probe_output(binary, "--help")+ return text is not None and "--sage-attn" in text++def sd_cpp_lists_accelerator_device(binary: Optional[str]) -> bool:"""True unless ``binary`` demonstrably enumerates the CPU ggml device and nothing else.@@ -804,6 +812,48 @@ def _installer_module():_failed_accelerator_upgrades: set[str] = set()+# (pin, accelerator class) upgrades that failed this process: keep the old bundle instead of retrying every load.+_failed_pin_upgrades: set[tuple[str, str]] = set()+_PIN_UPGRADE_ENV = "UNSLOTH_SD_CPP_AUTO_UPGRADE"+++def _pin_upgrade_disabled() -> bool:+ return os.environ.get(_PIN_UPGRADE_ENV, "").strip().lower() in ("0", "false", "no", "off")+++def _pin_moved(binary: str, accelerator: str) -> bool:+ """True when ``binary`` is a managed install made for an older pin. Unknown answers False."""+ if _pin_upgrade_disabled():+ return False+ root = owning_managed_root(binary)+ if root is None:+ return False+ if _managed_tree_in_use():+ return False+ try:+ mod = _installer_module()+ want = mod._pinned_tag()+ if not want or (want, mod.accelerator_class(accelerator)) in _failed_pin_upgrades:+ return False+ return bool(mod.install_is_stale(root))+ except Exception: # noqa: BLE001 -- cannot tell -> keep the existing binary+ return False+++def _note_failed_pin_upgrade(accelerator: str) -> None:+ try:+ mod = _installer_module()+ want = mod._pinned_tag()+ if want:+ _failed_pin_upgrades.add((want, mod.accelerator_class(accelerator)))+ except Exception: # noqa: BLE001+ pass+++def _needs_reinstall(binary: str, accelerator: str) -> bool:+ return _accelerator_changed(binary, accelerator) or _pin_moved(binary, accelerator)++def _note_failed_upgrade(accelerator: str) -> None:"""Stop retrying an accelerator upgrade that just failed while a usable binary is kept."""try:@@ -1590,7 +1640,15 @@ def _superseded_legacy_server(binary: Optional[str], accelerator: str) -> bool:try:mod = _installer_module()want = mod.accelerator_class(accelerator)- if not _record_mismatch(mod, root, want) or _record_mismatch(mod, current, want):+ # Superseded = built for another accelerator, or (with the pin upgrade on) for an older pin.+ legacy_stale = _record_mismatch(mod, root, want) or (+ not _pin_upgrade_disabled() and mod.install_is_stale(root)+ )+ if (+ not legacy_stale+ or _record_mismatch(mod, current, want)+ or mod.install_is_stale(current)+ ):return Falsereturn mod.installed_ships_server(current) is Falseexcept Exception: # noqa: BLE001 -- cannot tell@@ -1827,14 +1885,14 @@ def ensure_sd_cpp_binary(*, allow_install: bool = True, accelerator: str = "cpu"diffusers."""found = find_sd_cpp_binary()usable = bool(found) and _usable_or_discard_managed(found)- if usable and not _accelerator_changed(found, accelerator):+ if usable and not _needs_reinstall(found, accelerator):return foundif not allow_install:return foundwith _install_lock:found = find_sd_cpp_binary()usable = bool(found) and _usable_or_discard_managed(found)- if usable and not _accelerator_changed(found, accelerator):+ if usable and not _needs_reinstall(found, accelerator):return found# A usable binary of the wrong accelerator is still better than none, so an install that cannot deliver the# right one (no such asset for this host, no network) keeps it.@@ -1867,6 +1925,7 @@ def ensure_sd_cpp_binary(*, allow_install: bool = True, accelerator: str = "cpu"return refound if refound and _usable_or_discard_managed(refound) else Noneif fallback is not None:_note_failed_upgrade(accelerator)+ _note_failed_pin_upgrade(accelerator)return fallback@@ -1886,7 +1945,7 @@ def ensure_sd_server_binary(# not downloaded again on every later load.if usable and _superseded_legacy_server(found, accelerator):return None- if usable and not _accelerator_changed(found, accelerator):+ if usable and not _needs_reinstall(found, accelerator):return foundif not allow_install:return found@@ -1895,7 +1954,7 @@ def ensure_sd_server_binary(usable = bool(found) and _usable_or_discard_managed(found)if usable and _superseded_legacy_server(found, accelerator):return None- if usable and not _accelerator_changed(found, accelerator):+ if usable and not _needs_reinstall(found, accelerator):return found# Keep a usable wrong-accelerator server if the matching one cannot be fetchedfallback = found if usable else None@@ -1921,6 +1980,7 @@ def ensure_sd_server_binary(return refound if refound and _usable_or_discard_managed(refound) else Noneif fallback is not None or find_sd_cpp_binary() is not None:_note_failed_upgrade(accelerator)+ _note_failed_pin_upgrade(accelerator)return fallbackinstalled = find_sd_server_binary()# The finder also probes the tree an older build left beside the Unsloth home, so when the bundle just@@ -1928,7 +1988,7 @@ def ensure_sd_server_binary(# None, not the fallback: an install just completed, so the router's next step resolves the sd-cli it landed,# and a one-shot run on the right build beats a resident server on the wrong one. The fallback stays for the# failure path above, where no matching binary was fetched at all.- if installed and _accelerator_changed(installed, accelerator):+ if installed and _needs_reinstall(installed, accelerator):return Nonereturn installed or fallbackdiff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex e5f690ef4aa..b5660f9f983 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -1268,6 +1268,29 @@ def _h3_free_device_bytes(device: str) -> Optional[int]:return None+def _h3_card_free_bytes(device: Optional[str], ordinal: Optional[int]) -> Optional[int]:+ """Live free VRAM via nvidia-smi / amd-smi (no CUDA context here), or None. No pin = sd.cpp's ordinal 0."""+ if device != "cuda":+ return None+ try:+ from utils.hardware import get_visible_gpu_utilization, gpu_query++ with gpu_query.fresh_reads():+ devices = get_visible_gpu_utilization().get("devices", [])+ want = 0 if ordinal is None else int(ordinal)+ for entry in devices:+ if entry.get("visible_ordinal") != want:+ continue+ total = entry.get("vram_total_gb")+ used = entry.get("vram_used_gb")+ if total is None or used is None:+ return None+ return max(0, int((float(total) - float(used)) * 1024**3))+ except Exception: # noqa: BLE001 -- an unreadable card decides nothing+ return None+ return None++def _h3_device_capacity_bytes(device: str) -> Optional[int]:"""TOTAL VRAM on the card, or None when it cannot be read.@@ -3018,6 +3041,7 @@ class VideoBackend:gpu_ordinal: Optional[int] = None,# NAMED so a static step-skip ask can be recorded as declined: sd.cpp runs every step itself.transformer_cache: Optional[str] = None,+ speed_mode: Optional[str] = None,# NAMED, not left to the ``**_`` swallow below: an API-initiated load hands this in through _run_load's kwargs,# and swallowed it meant the four-file bundle, the sizing metadata and the sd-cli install were all fetched by a# load that promised no downloads.@@ -3053,6 +3077,7 @@ class VideoBackend:sd_cpp_accelerator_device_verdict,sd_cpp_device_name_for_ordinal,sd_cpp_supports_graph_cut,+ sd_cpp_supports_sage_attn,)from .sd_cpp_engine import SdCppEnginefrom .video_minimax_h3 import (@@ -3335,6 +3360,14 @@ class VideoBackend:# Under the claim like every other probe here; None on the CPU fallback, which has no card to choose# between.supports_graph_cut = native_device != "cpu" and sd_cpp_supports_graph_cut(binary)+ # Lossy (INT8 QK^T), so only on an explicit speed_mode="max".+ h3_sage = (+ native_device != "cpu"+ and str(speed_mode or "").strip().lower() == "max"+ and os.environ.get("UNSLOTH_H3_SAGE_ATTN", "").strip().lower()+ not in ("0", "false", "no", "off")+ and sd_cpp_supports_sage_attn(binary)+ )# Dropped with the accelerator: the CPU fallback runs on no card, so a recorded ordinal would outlive the# decision and be committed against a runtime that never used it.native_ordinal = None if native_device == "cpu" else gpu_ordinal@@ -3382,6 +3415,13 @@ class VideoBackend:native_offload += GRAPH_CUT_VRAM_FLAGSif "--offload-to-cpu" in native_offload:native_offload += GRAPH_CUT_STREAM_FLAGS+ native_env: tuple[tuple[str, str], ...] = ()+ if h3_sage:+ native_offload += ("--sage-attn",)+ # Same opt-in takes the fork's BF16 cuBLAS path; a user-exported value (0 included) wins.+ from .video_minimax_h3 import H3_QUANT_CUBLAS_ENV, H3_QUANT_CUBLAS_MIN_BATCH+ if H3_QUANT_CUBLAS_ENV not in os.environ:+ native_env += ((H3_QUANT_CUBLAS_ENV, H3_QUANT_CUBLAS_MIN_BATCH),)# After the policy, so the pin can see which modules it left on the CPU; without it sd.cpp uses ordinal 0# whatever was selected.native_offload += tuple(device_backend_flags(native_device_name, list(native_offload)))@@ -3400,6 +3440,7 @@ class VideoBackend:audio_vae = str(resolved[3]),),offload_flags = native_offload,+ env = native_env,)with self._lock:@@ -3433,15 +3474,25 @@ class VideoBackend:offload_policy = policy,vae_tiling = False,memory_mode = requested_mode,- attention_backend = "flash",+ attention_backend = "sage" if h3_sage else "flash",+ speed_mode = SPEED_MAX if h3_sage else SPEED_OFF,resolved = build_resolved_record({"family_override": _family_override_resolved(family_override, fam),"memory_mode": (memory_mode, policy, "native model offload"),+ "speed_mode": (+ speed_mode,+ SPEED_MAX if h3_sage else SPEED_OFF,+ "sd.cpp SageAttention + BF16 cuBLAS"+ if h3_sage+ else "sd.cpp exact kernels",+ ),"attention_backend": (None,- "flash",- "sd.cpp diffusion flash attention",+ "sage" if h3_sage else "flash",+ "sd.cpp SageAttention (speed_mode=max)"+ if h3_sage+ else "sd.cpp diffusion flash attention",),**({@@ -5159,6 +5210,7 @@ class VideoBackend:# would let an offline load fetch the four-file bundle.local_files_only = local_files_only,transformer_cache = transformer_cache,+ speed_mode = speed_mode,)return self.status()@@ -8528,12 +8580,33 @@ class VideoBackend:from .sd_cpp_args import SdCppVideoGenParamsfrom .sd_cpp_engine import SdCppCancelledfrom .video_minimax_h3 import (+ h3_native_render_flags,+ h3_native_resident_bytes,inspect_video,stage_h3_references,transcode_video_to_mp4,)runtime = state.pipe+ render_flags = list(runtime.offload_flags)+ render_resident = False+ if "--offload-to-cpu" in render_flags and state.memory_mode in (None, "auto"):+ try:+ files = runtime.files+ file_bytes = sum(+ os.path.getsize(p)+ for p in (files.diffusion_model, files.llm, files.vae, files.audio_vae)+ if p+ )+ need = h3_native_resident_bytes(file_bytes, width, height, frames)+ except Exception: # noqa: BLE001 -- unknown size keeps the committed offload+ need = None+ render_flags, render_resident = h3_native_render_flags(+ runtime.offload_flags,+ memory_mode = state.memory_mode,+ free_bytes = _h3_card_free_bytes(state.device, state.gpu_ordinal) if need else None,+ need_bytes = need,+ )if seed is None:seed = random.SystemRandom().randrange(0, 2**53)started = time.monotonic()@@ -8644,7 +8717,8 @@ class VideoBackend:flow_shift = flow_shift,),output_path = str(output_path),- offload = list(runtime.offload_flags),+ offload = render_flags,+ env = dict(runtime.env) or None,on_log = on_log,cancel_event = cancel,)@@ -8692,7 +8766,7 @@ class VideoBackend:"transformer_quant": state.transformer_quant,"text_encoder_quant": state.text_encoder_quant,"memory_mode": state.memory_mode,- "offload_policy": state.offload_policy,+ "offload_policy": "none" if render_resident else state.offload_policy,}finally:output_path.unlink(missing_ok = True)diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.pyindex 20f8e802d8c..f559b8f6be6 100644--- a/studio/backend/core/inference/video_minimax_h3.py+++ b/studio/backend/core/inference/video_minimax_h3.py@@ -6,6 +6,7 @@from __future__ import annotationsimport math+import osimport tempfilefrom dataclasses import dataclassfrom pathlib import Path@@ -1102,6 +1103,48 @@ def h3_component_metadata_repo(repo_id: str) -> str:return H3_COMPONENT_REPO if repo_id == H3_LEGACY_COMPONENT_REPO else repo_id+# Resident peak is the four files plus ~1 GiB (sd.cpp frees the text encoder before the denoiser's compute buffer);+# the estimate still adds that buffer on top of every file, plus a margin.+H3_NATIVE_RESIDENT_ENV = "UNSLOTH_H3_NATIVE_RESIDENT"+# Unsloth sd.cpp fork: quantized matmuls with >= this many rows run BF16 cuBLAS instead of int8 MMQ. Unset/0 = MMQ.+H3_QUANT_CUBLAS_ENV = "GGML_CUDA_QUANT_CUBLAS_MIN_BATCH"+H3_QUANT_CUBLAS_MIN_BATCH = "1024"+# Denoiser compute buffer at 960x544x124, from sd-cli's log; scaled by pixel volume.+H3_NATIVE_DIT_COMPUTE_BYTES_H1 = int(5.4 * 1024**3)+H3_NATIVE_H1_PIXEL_VOLUME = 960 * 544 * 124+H3_NATIVE_RESIDENT_MARGIN_BYTES = 2 * 1024**3+_H3_STREAM_ONLY_FLAGS = ("--offload-to-cpu", "--stream-layers")+++def h3_native_resident_bytes(file_bytes: int, width: int, height: int, frames: int) -> int:+ volume = max(1, int(width)) * max(1, int(height)) * max(1, int(frames))+ compute = math.ceil(+ H3_NATIVE_DIT_COMPUTE_BYTES_H1 * max(1.0, volume / H3_NATIVE_H1_PIXEL_VOLUME)+ )+ return int(file_bytes) + compute + H3_NATIVE_RESIDENT_MARGIN_BYTES+++def h3_native_render_flags(+ offload_flags: "tuple[str, ...] | list[str]",+ *,+ memory_mode: Optional[str],+ free_bytes: Optional[int],+ need_bytes: Optional[int],+ env: Optional[dict] = None,+) -> tuple[list[str], bool]:+ """Flags for one render and whether it runs resident: only memory auto, only when the live free VRAM covers+ the estimate; anything unknown keeps the committed flags."""+ flags = list(offload_flags)+ environ = env if env is not None else os.environ+ if str(environ.get(H3_NATIVE_RESIDENT_ENV, "")).strip().lower() in ("0", "false", "no", "off"):+ return flags, False+ if (memory_mode or "auto") != "auto" or "--offload-to-cpu" not in flags:+ return flags, False+ if free_bytes is None or need_bytes is None or int(free_bytes) < int(need_bytes):+ return flags, False+ return [f for f in flags if f not in _H3_STREAM_ONLY_FLAGS], True++def h3_native_hub_files(transformer_filename: str) -> tuple[tuple[str, str], ...]:validate_h3_transformer_filename(transformer_filename)return (@@ -1125,6 +1168,7 @@ class MiniMaxH3NativeRuntime:binary_identity: Optional[tuple[int, int]] = None# The card the load resolved, kept for failure records: re-resolving at failure time can read None.selected_card: Optional[str] = None+ env: tuple[tuple[str, str], ...] = ()def transcode_video_to_mp4(source: Path, *, fps: int) -> bytes:diff --git a/studio/backend/tests/test_h3_native_resident.py b/studio/backend/tests/test_h3_native_resident.pynew file mode 100644index 00000000000..e7bc41dd07d--- /dev/null+++ b/studio/backend/tests/test_h3_native_resident.py@@ -0,0 +1,203 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Memory auto runs a MiniMax-H3 sd-cli render resident when the card holds the whole bundle.++The native runtime commits --offload-to-cpu for memory auto, so a 96 GB card still pinned the 17 GB text+encoder in host RAM and paged every weight in on each render (Colab G4: peak 16.5 GiB used of 96). The+per-render check below drops only the streaming flags, only for memory auto, and only when the live free+VRAM covers a conservative resident estimate.+"""++from __future__ import annotations++import os+import sys+from pathlib import Path+from types import SimpleNamespace++import pytest++_BACKEND = Path(__file__).resolve().parents[1]+if str(_BACKEND) not in sys.path:+ sys.path.insert(0, str(_BACKEND))++from core.inference import video_minimax_h3 as h3 # noqa: E402++GIB = 1024**3+AUTO_FLAGS = (+ "--offload-to-cpu",+ "--diffusion-fa",+ "--max-vram",+ "-1",+ "--stream-layers",+ "--backend",+ "diffusion=CUDA0,te=CUDA0,vae=CUDA0",+)+# The four Hub files of the UD-Q3_K_XL and Q8_0 bundles (bytes on disk).+Q3_FILES = int((8.90 + 16.97 + 4.85 + 0.56) * GIB)+Q8_FILES = int((19.97 + 16.97 + 4.85 + 0.56) * GIB)+++def test_auto_runs_resident_when_the_card_holds_the_bundle():+ need = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)+ flags, resident = h3.h3_native_render_flags(+ AUTO_FLAGS, memory_mode = "auto", free_bytes = need, need_bytes = need, env = {}+ )+ assert resident is True+ assert "--offload-to-cpu" not in flags and "--stream-layers" not in flags+ # Everything else the load committed is kept, in order: flash attention, the graph-cut budget, the device pin.+ assert flags == [+ "--diffusion-fa",+ "--max-vram",+ "-1",+ "--backend",+ "diffusion=CUDA0,te=CUDA0,vae=CUDA0",+ ]+++def test_auto_keeps_offload_when_the_card_is_one_byte_short():+ need = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)+ flags, resident = h3.h3_native_render_flags(+ AUTO_FLAGS, memory_mode = "auto", free_bytes = need - 1, need_bytes = need, env = {}+ )+ assert resident is False and flags == list(AUTO_FLAGS)++[email protected]("free, need", [(None, 10 * GIB), (90 * GIB, None), (None, None)])+def test_an_unreadable_card_or_size_keeps_offload(free, need):+ flags, resident = h3.h3_native_render_flags(+ AUTO_FLAGS, memory_mode = "auto", free_bytes = free, need_bytes = need, env = {}+ )+ assert resident is False and flags == list(AUTO_FLAGS)++[email protected]("mode", ["balanced", "low_vram"])+def test_an_explicit_offload_mode_is_left_as_asked(mode):+ flags, resident = h3.h3_native_render_flags(+ AUTO_FLAGS, memory_mode = mode, free_bytes = 500 * GIB, need_bytes = GIB, env = {}+ )+ assert resident is False and flags == list(AUTO_FLAGS)+++def test_flags_that_do_not_offload_are_untouched():+ fast = ("--diffusion-fa",)+ flags, resident = h3.h3_native_render_flags(+ fast, memory_mode = "auto", free_bytes = 500 * GIB, need_bytes = GIB, env = {}+ )+ assert resident is False and flags == ["--diffusion-fa"]++[email protected]("value", ["0", "false", "off", "no"])+def test_kill_switch(value):+ flags, resident = h3.h3_native_render_flags(+ AUTO_FLAGS,+ memory_mode = "auto",+ free_bytes = 500 * GIB,+ need_bytes = GIB,+ env = {h3.H3_NATIVE_RESIDENT_ENV: value},+ )+ assert resident is False and flags == list(AUTO_FLAGS)+++def test_estimate_covers_the_measured_resident_peaks():+ # Resident peaks measured with nvidia-smi on a B200, 960x544x124, pinned u1d02858: 33030 MiB (q3), 44318 MiB (q8).+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) > 33030 * 1024**2+ assert h3.h3_native_resident_bytes(Q8_FILES, 960, 544, 124) > 44318 * 1024**2+ # A 48 GB card (the RTX 6000 Ada this was reported on) holds the q3 bundle resident; a 24 GB card does not.+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) < 47 * GIB+ assert h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124) > 23 * GIB+++def test_estimate_grows_with_the_clip_and_never_shrinks_below_h1():+ h1 = h3.h3_native_resident_bytes(Q3_FILES, 960, 544, 124)+ assert h3.h3_native_resident_bytes(Q3_FILES, 1280, 720, 241) > h1+ assert h3.h3_native_resident_bytes(Q3_FILES, 640, 384, 25) == h1+++def _video_backend_tests():+ # The H3 generate fixture lives there; loaded by path because `tests` can resolve to the repo-root package.+ import importlib.util++ name = "_studio_test_video_backend"+ if name not in sys.modules:+ spec = importlib.util.spec_from_file_location(+ name, Path(__file__).with_name("test_video_backend.py")+ )+ module = importlib.util.module_from_spec(spec)+ sys.modules[name] = module+ spec.loader.exec_module(module)+ return sys.modules[name]+++def _backend_with_files(monkeypatch, tmp_path, calls, *, memory_mode, flags):+ backend = _video_backend_tests()._h3_native_backend(monkeypatch, calls)+ paths = {}+ sizes = {}+ for name, size in (("diffusion_model", 9), ("llm", 17), ("vae", 5), ("audio_vae", 1)):+ p = tmp_path / f"{name}.bin"+ p.write_bytes(b"")+ paths[name] = str(p)+ sizes[str(p)] = size * GIB+ # Not truncate(): NTFS allocates the full 32 GiB per test, which fills a Windows runner's disk.+ real_getsize = os.path.getsize+ monkeypatch.setattr(os.path, "getsize", lambda p: sizes.get(str(p)) or real_getsize(p))+ import dataclasses++ state = backend._state+ backend._state = dataclasses.replace(+ state,+ pipe = h3.MiniMaxH3NativeRuntime(+ engine = state.pipe.engine, files = SimpleNamespace(**paths), offload_flags = tuple(flags)+ ),+ memory_mode = memory_mode,+ offload_policy = "group",+ )+ return backend+++def test_generate_drops_offload_on_a_card_that_fits(monkeypatch, tmp_path):+ import core.inference.video as video++ calls: list = []+ backend = _backend_with_files(+ monkeypatch, tmp_path, calls, memory_mode = "auto", flags = AUTO_FLAGS+ )+ seen = []+ monkeypatch.setattr(+ video,+ "_h3_card_free_bytes",+ lambda device, ordinal: seen.append((device, ordinal)) or 90 * GIB,+ )+ result = backend.generate(prompt = "a fox", width = 960, height = 544)+ assert seen == [("cuda", None)]+ assert "--offload-to-cpu" not in calls[0]["offload"] and "--diffusion-fa" in calls[0]["offload"]+ assert result["offload_policy"] == "none"+ assert result["memory_mode"] == "auto"+++def test_generate_keeps_offload_on_a_card_that_does_not(monkeypatch, tmp_path):+ import core.inference.video as video++ calls: list = []+ backend = _backend_with_files(+ monkeypatch, tmp_path, calls, memory_mode = "auto", flags = AUTO_FLAGS+ )+ monkeypatch.setattr(video, "_h3_card_free_bytes", lambda device, ordinal: 20 * GIB)+ result = backend.generate(prompt = "a fox", width = 960, height = 544)+ assert calls[0]["offload"] == list(AUTO_FLAGS)+ assert result["offload_policy"] == "group"+++def test_generate_does_not_probe_the_card_for_balanced(monkeypatch, tmp_path):+ import core.inference.video as video++ calls: list = []+ backend = _backend_with_files(+ monkeypatch, tmp_path, calls, memory_mode = "balanced", flags = AUTO_FLAGS+ )+ monkeypatch.setattr(+ video, "_h3_card_free_bytes", lambda *_a: (_ for _ in ()).throw(AssertionError("probed"))+ )+ backend.generate(prompt = "a fox", width = 960, height = 544)+ assert calls[0]["offload"] == list(AUTO_FLAGS)diff --git a/studio/backend/tests/test_sd_cpp_install.py b/studio/backend/tests/test_sd_cpp_install.pyindex 8ec69bda239..202e6e12860 100644--- a/studio/backend/tests/test_sd_cpp_install.py+++ b/studio/backend/tests/test_sd_cpp_install.py@@ -3112,6 +3112,45 @@ def test_a_serverless_install_is_not_downloaded_again_on_every_later_load(tmp_paassert installs == []+def test_an_old_pin_legacy_server_is_not_reinstalled_over_a_serverless_current_pin(+ tmp_path, monkeypatch+):+ """A legacy server for the RIGHT accelerator but an older pin is superseded once the current root holds the+ current pin's serverless bundle: not handed back after the upgrade, and not reinstalled on every later load."""+ bk, home, legacy = _shared_setup_3(monkeypatch, tmp_path)+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)+ monkeypatch.delenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", raising = False)+ old_server = legacy / "sd-bin" / _SERVER+ old_server.write_bytes(b"old-pin-build")+ (legacy / sdmod.INSTALL_RECORD).write_text(+ json.dumps({"accelerator": "cuda", "repo": "r", "tag": "master-1-0000000-u0000000"}),+ encoding = "utf-8",+ )+ current = home / "stable-diffusion.cpp"+ current.mkdir()+ (current / ".unsloth-studio-owned").touch()+ sdmod._INSTALLED_ACCELERATOR_MEMO.clear()+ sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()++ installs: list[dict] = []++ def _install(**kw):+ installs.append(kw)+ sdmod._write_install_record(+ current, accelerator = "cuda", repo = "r", tag = "t", ships_server = False+ )++ monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(old_server))+ monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)+ monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())+ monkeypatch.setattr(bk, "_failed_pin_upgrades", set())+ monkeypatch.setattr(sdmod, "install", _install)++ assert bk.ensure_sd_server_binary(accelerator = "cuda") is None+ assert bk.ensure_sd_server_binary(accelerator = "cuda") is None+ assert len(installs) == 1++def test_a_matching_legacy_server_is_still_preferred_over_the_one_shot_cli(tmp_path, monkeypatch):"""The serverless guard must fire only on a MISMATCHED legacy server. One built for theaccelerator being asked for is a working resident server, and dropping to the one-shot CLIdiff --git a/studio/backend/tests/test_sd_cpp_pin_upgrade.py b/studio/backend/tests/test_sd_cpp_pin_upgrade.pynew file mode 100644index 00000000000..da8c6270813--- /dev/null+++ b/studio/backend/tests/test_sd_cpp_pin_upgrade.py@@ -0,0 +1,283 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A managed sd.cpp install made for an older pin is upgraded to the pin this Studio ships.++Before this, ensure_sd_cpp_binary / ensure_sd_server_binary reinstalled only a missing, unrunnable or+wrong-accelerator binary, so moving DEFAULT_TAG reached new installs only: a host that installed the+2026-08-09 u13b9d92 bundle kept running it after the pin moved to u1d02858 (observed on a benchmark+host whose Studio pinned u1d02858 while ~/.unsloth/stable-diffusion.cpp still held u13b9d92).+"""++from __future__ import annotations++import json+import sys+from pathlib import Path++import pytest++_STUDIO = Path(__file__).resolve().parents[2]+if str(_STUDIO) not in sys.path:+ sys.path.insert(0, str(_STUDIO))++import install_sd_cpp_prebuilt as sdmod # noqa: E402++_CLI = "sd-cli.exe" if sys.platform == "win32" else "sd-cli"+_SERVER = "sd-server.exe" if sys.platform == "win32" else "sd-server"+++def _tree(tmp_path, monkeypatch, record):+ import core.inference.sd_cpp_backend as bk++ root = tmp_path / "sd-home" / "stable-diffusion.cpp"+ (root / "sd-bin").mkdir(parents = True)+ (root / ".unsloth-studio-owned").touch()+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)+ monkeypatch.delenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", raising = False)+ if record is not None:+ (root / sdmod.INSTALL_RECORD).write_text(json.dumps(record), encoding = "utf-8")+ sdmod._INSTALLED_ACCELERATOR_MEMO.clear()+ sdmod._INSTALLED_SHIPS_SERVER_MEMO.clear()+ cli = root / "sd-bin" / _CLI+ cli.write_bytes(b"old-build")+ server = root / "sd-bin" / _SERVER+ server.write_bytes(b"old-build")+ monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: str(cli))+ monkeypatch.setattr(bk, "find_sd_server_binary", lambda: str(server))+ monkeypatch.setattr(bk, "_usable_or_discard_managed", lambda *_a, **_k: True)+ monkeypatch.setattr(bk, "_server_binary_runnable", lambda *_a, **_k: True)+ monkeypatch.setattr(bk, "_failed_accelerator_upgrades", set())+ monkeypatch.setattr(bk, "_failed_pin_upgrades", set())+ return bk, root, cli, server+++def _recording_install(root, cli, server, installs):+ def _install(**kwargs):+ installs.append(kwargs)+ cli.write_bytes(b"new-build")+ server.write_bytes(b"new-build")+ sdmod._write_install_record(+ root, accelerator = kwargs["accelerator"], repo = "r", tag = sdmod.DEFAULT_TAG+ )+ return cli++ return _install+++OLD = "master-813-bfbef5b-u13b9d92"+++def test_an_install_for_an_older_pin_is_upgraded_once(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ assert OLD != sdmod.DEFAULT_TAG+ installs: list = []+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))++ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert [k["accelerator"] for k in installs] == ["cuda"]+ assert cli.read_bytes() == b"new-build"+ # The record now names the shipped pin: the next load reuses it.+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+ assert len(installs) == 1+++def test_an_unwritable_record_does_not_redownload_on_every_load(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ import builtins++ def _open(+ path,+ mode = "r",+ *args,+ **kwargs,+ ):+ if "w" in mode and Path(path).name == sdmod.INSTALL_RECORD:+ raise PermissionError("record held by another writer")+ return builtins.open(path, mode, *args, **kwargs)++ monkeypatch.setattr(sdmod, "open", _open, raising = False)+ installs: list = []+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))+ for _ in range(3):+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+ assert len(installs) == 1+ assert OLD in (root / sdmod.INSTALL_RECORD).read_text(encoding = "utf-8")+++def test_the_server_resolver_upgrades_an_old_pin_too(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ installs: list = []+ monkeypatch.setattr(sdmod, "install", _recording_install(root, cli, server, installs))+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+ assert server.read_bytes() == b"new-build"+ assert len(installs) == 1+++def test_the_current_pin_is_never_reinstalled(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(tmp_path, monkeypatch, None)+ sdmod._write_install_record(root, accelerator = "cuda", repo = "r", tag = sdmod.DEFAULT_TAG)++ def _install(**_kwargs):+ raise AssertionError("the shipped pin must not be reinstalled")++ monkeypatch.setattr(sdmod, "install", _install)+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+++ "record",+ [+ None, # predates the record+ {"accelerator": "cuda", "repo": "r"}, # no tag+ {"accelerator": "cuda", "repo": "r", "tag": ""},+ ],+)+def test_an_install_that_cannot_say_its_pin_is_left_alone(tmp_path, monkeypatch, record):+ bk, root, cli, server = _tree(tmp_path, monkeypatch, record)++ def _install(**_kwargs):+ raise AssertionError("unknown is not stale")++ monkeypatch.setattr(sdmod, "install", _install)+ # cpu: an unrecorded install is not an accelerator mismatch either, so only the pin check could fire.+ assert bk.ensure_sd_cpp_binary(accelerator = "cpu") == str(cli)+++def test_a_fallback_install_for_the_current_pin_is_not_redownloaded(tmp_path, monkeypatch):+ """A host the mirror does not build gets the upstream release (or latest), whose tag can never equal the pin.+ requested_tag records what the install was FOR, so it is not re-fetched on every load."""+ bk, root, cli, server = _tree(+ tmp_path,+ monkeypatch,+ {+ "accelerator": "vulkan",+ "repo": "leejet/stable-diffusion.cpp",+ "tag": "master-999-abcdef0",+ "requested_tag": sdmod.DEFAULT_TAG,+ },+ )++ def _install(**_kwargs):+ raise AssertionError("a fallback install for the current pin is current")++ monkeypatch.setattr(sdmod, "install", _install)+ assert bk.ensure_sd_cpp_binary(accelerator = "vulkan") == str(cli)+++def test_an_old_record_holding_the_upstream_form_of_the_pin_is_current(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path,+ monkeypatch,+ {"accelerator": "vulkan", "repo": "r", "tag": sdmod.upstream_tag_for(sdmod.DEFAULT_TAG)},+ )+ monkeypatch.setattr(+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("current"))+ )+ assert bk.ensure_sd_cpp_binary(accelerator = "vulkan") == str(cli)+++def test_kill_switch_keeps_the_installed_bundle(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ monkeypatch.setenv("UNSLOTH_SD_CPP_AUTO_UPGRADE", "0")+ monkeypatch.setattr(+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("kill switch"))+ )+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+++def test_tracking_latest_never_counts_as_a_moved_pin(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "")+ monkeypatch.setattr(+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("latest"))+ )+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+++def test_a_failed_pin_upgrade_keeps_the_old_binary_and_stops_retrying(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ attempts: list = []++ def _install(**kwargs):+ attempts.append(kwargs)+ raise RuntimeError("offline")++ monkeypatch.setattr(sdmod, "install", _install)+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert bk.ensure_sd_server_binary(accelerator = "cuda") == str(server)+ assert len(attempts) == 1, "a hopeless upgrade is attempted once per process, not once per load"+ assert cli.read_bytes() == b"old-build"+++def test_a_failed_upgrade_for_one_accelerator_still_lets_another_upgrade_the_pin(+ tmp_path, monkeypatch+):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cpu", "repo": "r", "tag": OLD}+ )+ installs: list = []+ ok = _recording_install(root, cli, server, installs)++ def _install(**kwargs):+ if kwargs["accelerator"] == "cuda":+ installs.append(kwargs)+ raise RuntimeError("no CUDA asset for this host")+ return ok(**kwargs)++ monkeypatch.setattr(sdmod, "install", _install)+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+ assert cli.read_bytes() == b"old-build"+ assert bk.ensure_sd_cpp_binary(accelerator = "cpu") == str(cli)+ assert [k["accelerator"] for k in installs] == ["cuda", "cpu"]+ assert cli.read_bytes() == b"new-build"+++def test_no_upgrade_while_the_managed_tree_is_in_use(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ monkeypatch.setattr(bk, "_managed_tree_in_use", lambda: True)+ monkeypatch.setattr(+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("in use"))+ )+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+++def test_a_user_supplied_binary_is_never_upgraded(tmp_path, monkeypatch):+ bk, root, cli, server = _tree(+ tmp_path, monkeypatch, {"accelerator": "cuda", "repo": "r", "tag": OLD}+ )+ (root / ".unsloth-studio-owned").unlink()+ monkeypatch.setattr(+ sdmod, "install", lambda **_k: (_ for _ in ()).throw(AssertionError("not ours"))+ )+ assert bk.ensure_sd_cpp_binary(accelerator = "cuda") == str(cli)+++def test_new_records_carry_the_pin_they_were_made_for(tmp_path, monkeypatch):+ monkeypatch.delenv("UNSLOTH_SD_CPP_TAG", raising = False)+ sdmod._write_install_record(tmp_path, accelerator = "cuda", repo = "r", tag = "whatever-it-got")+ rec = sdmod.read_install_record(tmp_path)+ assert rec["requested_tag"] == sdmod.DEFAULT_TAG+ assert sdmod.install_is_stale(tmp_path) is False+ monkeypatch.setenv("UNSLOTH_SD_CPP_TAG", "master-999-0000000-u0000000")+ assert sdmod.install_is_stale(tmp_path) is Truediff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.pyindex 75319e82518..ac7a2b69c9c 100644--- a/studio/backend/tests/test_video_backend.py+++ b/studio/backend/tests/test_video_backend.py@@ -3649,6 +3649,21 @@ def test_direct_h3_native_load_uses_sd_cpp_path(monkeypatch):assert calls[0]["gguf_filename"] == "minimax_h3_fl2va-Q4_K_M.gguf"+def test_direct_h3_native_load_hands_speed_mode_to_the_sd_cpp_path(monkeypatch):+ backend = VideoBackend()+ calls = []+ monkeypatch.setattr("core.inference.video._ensure_mp4_encoder_available", lambda: None)+ monkeypatch.setattr(backend, "_run_load_h3_native", lambda **kwargs: calls.append(kwargs))+ backend.load_pipeline(+ "leejet/MiniMax-H3-GGUF",+ gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",+ family_override = "minimax-h3",+ model_kind = "gguf",+ speed_mode = "max",+ )+ assert calls and calls[0]["speed_mode"] == "max"++def test_h3_native_load_claims_the_companion_repos_before_the_preflight(monkeypatch, tmp_path):# asset_repos stops the delete-cached guard dropping the H3 companion repos mid-load, and the# preflight can spend minutes installing the sd-cli prebuilt. A delete admitted in that window@@ -4017,6 +4032,7 @@ def _load_h3_native_offload(help_text,accelerator = True,memory_mode = None,+ speed_mode = None,):"""Run the native H3 load against a stubbed sd-cli and hand back its committed offload flags.@@ -4074,6 +4090,7 @@ def _load_h3_native_offload(repo_id = "leejet/MiniMax-H3-GGUF",gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",memory_mode = memory_mode,+ speed_mode = speed_mode,)assert backend._state is not Nonereturn backend._state, list(backend._state.pipe.offload_flags)@@ -4117,6 +4134,97 @@ def test_h3_native_drops_stream_layers_without_cpu_offload(monkeypatch, tmp_pathassert "--stream-layers" not in offload+_SAGE_HELP = _GRAPH_CUT_HELP + " --sage-attn use native CUDA SageAttention\n"+++def test_h3_native_sage_attention_only_on_speed_max(monkeypatch, tmp_path):+ """SageAttention is lossy (INT8 QK^T), so it rides only on an explicit speed_mode="max"."""+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)+ state, offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"+ )+ assert offload[-1] == "--sage-attn"+ assert state.attention_backend == "sage"+ assert state.speed_mode == "max" and state.resolved["speed_mode"]["value"] == "max"+ for mode in (None, "default", "off"):+ state, offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode+ )+ assert "--sage-attn" not in offload, mode+ assert state.attention_backend == "flash"+ assert state.speed_mode == "off"+++def test_h3_native_sage_attention_needs_the_flag_and_honours_the_veto(monkeypatch, tmp_path):+ """An older prebuilt (u13b9d92) has no --sage-attn, and sd-cli exits on an unknown option."""+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)+ _state, offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, speed_mode = "max"+ )+ assert "--sage-attn" not in offload+ monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")+ _state, offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"+ )+ assert "--sage-attn" not in offload+++def test_h3_native_speed_max_takes_the_bf16_cublas_path(monkeypatch, tmp_path):+ """speed_mode=max also hands sd-cli GGML_CUDA_QUANT_CUBLAS_MIN_BATCH; every other mode launches with no extra env."""+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)+ monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)+ state, _offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"+ )+ assert dict(state.pipe.env) == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}+ for mode in (None, "default", "off"):+ state, _offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode+ )+ assert state.pipe.env == (), mode+ # The veto that drops sage drops this too, and a value the user exported (0 included) is never overridden.+ monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")+ state, _offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"+ )+ assert state.pipe.env == ()+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)+ monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")+ state, _offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"+ )+ assert state.pipe.env == ()+++def test_h3_native_generate_hands_the_runtime_env_to_sd_cli(monkeypatch):+ import dataclasses++ calls: list = []+ backend = _h3_native_backend(monkeypatch, calls)+ backend._state = dataclasses.replace(+ backend._state,+ pipe = dataclasses.replace(+ backend._state.pipe, env = (("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "1024"),)+ ),+ )+ backend.generate(prompt = "a fox", width = 960, height = 544)+ assert calls[0]["env"] == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}+ calls.clear()+ backend._state = dataclasses.replace(+ backend._state, pipe = dataclasses.replace(backend._state.pipe, env = ())+ )+ backend.generate(prompt = "a fox", width = 960, height = 544)+ assert calls[0]["env"] is None+++def test_h3_native_sage_attention_never_on_the_cpu_build(monkeypatch, tmp_path):+ monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)+ _state, offload = _load_h3_native_offload(+ monkeypatch, tmp_path, help_text = _SAGE_HELP, accelerator = False, speed_mode = "max"+ )+ assert "--sage-attn" not in offload++def test_h3_native_skips_the_graph_cut_flags_on_an_older_build(monkeypatch, tmp_path):"""sd-cli exits non-zero on an option it does not know, so emitting these unconditionallywould break every generation on a build that predates the executor."""diff --git a/studio/install_sd_cpp_prebuilt.py b/studio/install_sd_cpp_prebuilt.pyindex 0a2a99369be..7ab25ecaf29 100644--- a/studio/install_sd_cpp_prebuilt.py+++ b/studio/install_sd_cpp_prebuilt.py@@ -100,6 +100,8 @@ def _raw_install_record(root: Path) -> Optional[str]:# The same, for the bundle's sd-server capability. Memoised alongside the accelerator or not at all: with only half of it remembered, an unwritable record leaves a serverless install looking server-capable, and the load that finds a mismatched legacy server keeps reinstalling._INSTALLED_SHIPS_SERVER_MEMO: dict[str, bool] = {}+# The same for the pin: an unwritable record still names the old one, which re-downloads on every load.+_INSTALLED_PIN_MEMO: dict[str, tuple[Optional[str], Optional[str]]] = {}def installed_ships_server(root: Path) -> Optional[bool]:@@ -119,7 +121,8 @@ def _write_install_record() -> None:"""Record what this install is, so a later ensure_* can tell a CPU bundle from a GPU one. The write itself stays best-effort (a metadata failure must not throw away binaries that extracted correctly) but the answer is memoised either way, so this process never re-installs what it just installed."""klass = accelerator_class(accelerator)- rec: dict = {"accelerator": klass, "repo": repo, "tag": tag}+ # The pin this install was FOR: a fallback (upstream / latest) tag never equals it.+ rec: dict = {"accelerator": klass, "repo": repo, "tag": tag, "requested_tag": _pinned_tag()}if ships_server is not None:rec["ships_server"] = ships_server_INSTALLED_SHIPS_SERVER_MEMO[str(root)] = ships_server@@ -130,7 +133,9 @@ def _write_install_record(with open(root / INSTALL_RECORD, "w", encoding = "utf-8") as f:json.dump(rec, f)except OSError as exc:- _INSTALLED_ACCELERATOR_MEMO[str(root)] = (klass, _raw_install_record(root))+ snapshot = _raw_install_record(root)+ _INSTALLED_ACCELERATOR_MEMO[str(root)] = (klass, snapshot)+ _INSTALLED_PIN_MEMO[str(root)] = (rec["requested_tag"], snapshot)print(f"sd-cli: WARNING could not write the install record in {root}: {exc}; "f"remembering {klass} for this process only",@@ -138,6 +143,7 @@ def _write_install_record()else:_INSTALLED_ACCELERATOR_MEMO.pop(str(root), None)+ _INSTALLED_PIN_MEMO.pop(str(root), None)def _repo() -> str:@@ -150,6 +156,28 @@ def _pinned_tag() -> Optional[str]:return val or None+def install_is_stale(root: Path) -> bool:+ """True when ``root`` was installed for another pin. Unknown (no record / tag, tracking latest) is not stale."""+ want = _pinned_tag()+ if not want:+ return False+ memo = _INSTALLED_PIN_MEMO.get(str(root))+ if memo is not None:+ raw = _raw_install_record(root)+ if raw is None or raw == memo[1]:+ return memo[0] != want+ _INSTALLED_PIN_MEMO.pop(str(root), None)+ rec = read_install_record(root)+ requested = rec.get("requested_tag")+ if isinstance(requested, str) and requested:+ return requested != want+ have = rec.get("tag")+ if not isinstance(have, str) or not have:+ return False+ # Pre-requested_tag records: the mirror tag, or its upstream release on hosts the mirror does not build.+ return have not in (want, upstream_tag_for(want))++def is_mirror_only_tag(tag: Optional[str]) -> bool:"""True for a ``<upstream tag>-u<id>`` tag, which only the Unsloth mirror can serve: the mirror publishes such a tag when it builds the upstream tree plus the patch set in its ``patches/`` directory, so by construction upstream has no release under that name."""return bool(tag) and bool(_MIRROR_ONLY_TAG_RE.match(tag))