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: opt-in MLX image engine for Apple Silicon (Z-Image) (#13379)
Daniel Han10bddef22e71
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex 70f6cb8708e..545d0fa49bb 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -3385,7 +3385,7 @@ class DiffusionBackend:# same predicate. Imported here, not at module import, because the router imports this module's siblings.from .diffusion_engine_router import family_buildable_here- if not family_buildable_here(fam, model_kind = kind):+ if not family_buildable_here(fam, model_kind = kind, gguf_filename = gguf_filename):assert_pipeline_class_available(fam.pipeline_class, fam.name)# Whole-pipeline families take a GGUF only when it is whole too (stable-diffusion.cpp ``convert``).if (@@ -4819,6 +4819,7 @@ class DiffusionBackend:text_encoder_quant: Optional[str] = None,allow_device_probe: bool = True,memory_verdict: bool = True,+ discover_text_encoders: bool = True,**load_kwargs: Any,) -> dict[str, Any]:"""The repos + exact files this pick needs, so the Hub download manager can fetch them with the@@ -4837,6 +4838,7 @@ class DiffusionBackend:verdict while training owns the GPU. It is not free: the pre-cast encoder and the DiTprequant need a target to resolve, so clearing it also changes WHICH FILES the plan counts.``memory_verdict=False`` suppresses only the oversized-unified-memory refusal.+ ``discover_text_encoders=False`` keeps the base repo's encoder for an engine that never opens a single-file one."""fam = detect_family_for_pick(repo_id, gguf_filename, family_override)kind = resolve_model_kind(gguf_filename, model_kind)@@ -4859,7 +4861,11 @@ class DiffusionBackend:fam, repo_id, gguf_filename, base, hf_token) or speech_pick_refusal(repo_id, gguf_filename, hf_token)component_overrides = None- if not load_kwargs.get("text_encoder_files") and not load_kwargs.get("vae_file"):+ if (+ discover_text_encoders+ and not load_kwargs.get("text_encoder_files")+ and not load_kwargs.get("vae_file")+ ):# The same pick the load makes, so the plan stages no encoder the load will not open.load_kwargs["text_encoder_files"] = (self._comfy_text_encoders(diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.pyindex 46fdfea80d2..8b8d8c8c3d9 100644--- a/studio/backend/core/inference/diffusion_engine_router.py+++ b/studio/backend/core/inference/diffusion_engine_router.py@@ -17,12 +17,22 @@ Env knobs:UNSLOTH_DIFFUSION_SD_CPP_MPS=0|1 allow native on Apple MPS (default off)UNSLOTH_DIFFUSION_SD_CPP_INSTALL=auto|0|1 allow lazy binary install (in sd_cpp_backend)UNSLOTH_DIFFUSION_SD_CPP_DEVICE=nvidia[:N] run native on a card torch cannot see+ UNSLOTH_DIFFUSION_MLX=0|1|auto opt in to the Apple Silicon MLX engine (default 0; auto+ behaves like 0 until a real-Mac A/B against diffusers MPS+ and sd.cpp Metal settles the default)++The MLX engine (``mlx_diffusion_backend``) is considered only when UNSLOTH_DIFFUSION_MLX=1, on macOS 14+ on+Apple Silicon, for a GGUF of a family that declares ``mlx_model_config`` in a quant the converter handles+(Q4_0 / Q4_1 / Q8_0 / BF16 / F16), with ``mlx`` and ``mflux`` installed. Every refusal is recorded+(``mlx_fallback_reason`` in the status) and falls through to the choice this module makes without it."""from __future__ import annotationsimport functools+import importlib.utilimport os+import platformimport sysimport threadingfrom dataclasses import dataclass@@ -31,6 +41,7 @@ from typing import Any, Callable, Optionalfrom core.inference.diffusion_device import resolve_diffusion_device_targetfrom core.inference.diffusion_families import (DiffusionFamily,+ family_mlx_supported,family_pipeline_available,family_sd_cpp_supported,pipeline_available_family_names,@@ -50,6 +61,7 @@ from core.inference.sd_cpp_backend import ()from core.inference.sd_cpp_engine import (ENGINE_DIFFUSERS,+ ENGINE_MLX,ENGINE_SD_CPP,SdCppEngine,select_diffusion_engine,@@ -162,6 +174,110 @@ _lock = threading.Lock()_transition_lock = threading.Lock()_active_engine_name: str = ENGINE_DIFFUSERS_fallback_reason: Optional[str] = None+_mlx_fallback_reason: Optional[str] = None++_MLX_MIN_MACOS = (14, 0)+++def _mlx_requested() -> bool:+ """``auto`` means off for now."""+ return os.environ.get("UNSLOTH_DIFFUSION_MLX", "0").strip().lower() in _ENABLE_TOKENS+++def _mlx_host_refusal() -> Optional[str]:+ if sys.platform != "darwin":+ return "the MLX engine runs on macOS only"+ if platform.machine().lower() not in ("arm64", "aarch64"):+ return "the MLX engine needs Apple Silicon"+ release = platform.mac_ver()[0]+ try:+ version = tuple(int(part) for part in release.split(".")[:2])+ except ValueError:+ version = ()+ if not version or version < _MLX_MIN_MACOS:+ return f"the MLX engine needs macOS 14 or newer (found {release or 'unknown'})"+ return None+++# mflux's own darwin mlx range plus the light deps install_python_stack.py installs beside it (mflux goes in --no-deps).+_MLX_RUNTIME_REQUIREMENTS: tuple[str, ...] = (+ "mlx>=0.32.0,<0.33.0",+ "piexif>=1.1.3,<2",+ "platformdirs>=4,<5",+ "toml>=0.10.2,<1",+)+++def _installed_version(name: str) -> Optional[str]:+ try:+ from importlib.metadata import PackageNotFoundError, version+ return version(name)+ except (PackageNotFoundError, ValueError):+ return None+++def _mlx_runtime_refusal() -> Optional[str]:+ """find_spec and distribution metadata only: never import mlx / mflux here."""+ missing = [name for name in ("mlx", "mflux") if importlib.util.find_spec(name) is None]+ if missing:+ return f"{' and '.join(missing)} not installed"+ from core.inference.mlx_diffusion_convert import MFLUX_VERSION++ try:+ from packaging.requirements import Requirement+ for spec in (f"mflux=={MFLUX_VERSION}", *_MLX_RUNTIME_REQUIREMENTS):+ requirement = Requirement(spec)+ installed = _installed_version(requirement.name)+ if installed is None or not requirement.specifier.contains(installed, prereleases = True):+ return f"the MLX engine needs {spec} (found {installed or 'none'})"+ except Exception as exc: # noqa: BLE001 -- no packaging, or a version it cannot parse+ return f"could not verify the MLX runtime versions ({exc})"+ return None+++def mlx_selection(+ fam: Optional[DiffusionFamily],+ *,+ model_kind: Optional[str],+ gguf_filename: Optional[str],+ backend: Optional[str] = None,+) -> tuple[bool, Optional[str]]:+ """``(use_mlx, refusal)``. Shared by selection and ``predict_engine`` so the download plan and the load+ cannot disagree about MLX."""+ if not _mlx_requested():+ return False, None+ forced = os.environ.get("UNSLOTH_DIFFUSION_ENGINE", "auto").strip().lower()+ if forced in (ENGINE_DIFFUSERS, ENGINE_SD_CPP):+ return False, f"UNSLOTH_DIFFUSION_ENGINE={forced} overrides UNSLOTH_DIFFUSION_MLX"+ if model_kind and model_kind != "gguf":+ return False, f"the MLX engine loads GGUF picks only (got {model_kind})"+ if fam is None or not family_mlx_supported(fam):+ name = getattr(fam, "name", None) or "unknown"+ return False, f"family '{name}' has no MLX implementation"+ from core.inference.mlx_diffusion_convert import quant_convertible++ convertible, why = quant_convertible(gguf_filename)+ if not convertible:+ return False, why or "GGUF quant not convertible to MLX"+ host = _mlx_host_refusal()+ if host:+ return False, host+ if backend is None:+ backend = resolve_diffusion_device_target().backend+ if backend not in ("mps", "cpu"):+ return False, f"device backend '{backend}' is not Apple MPS"+ runtime = _mlx_runtime_refusal()+ if runtime:+ return False, runtime+ return True, None+++def _note_mlx_refusal(reason: Optional[str]) -> None:+ global _mlx_fallback_reason+ with _lock:+ _mlx_fallback_reason = reason+ if reason:+ logger.warning("UNSLOTH_DIFFUSION_MLX=1 but the MLX engine is not used: %s", reason)def _engine_config() -> tuple[str, str, bool]:@@ -177,6 +293,9 @@ def engine_for(name: str) -> Any:if name == ENGINE_SD_CPP:from core.inference.sd_cpp_backend import get_sd_cpp_backendreturn get_sd_cpp_backend()+ if name == ENGINE_MLX:+ from core.inference.mlx_diffusion_backend import get_mlx_diffusion_backend+ return get_mlx_diffusion_backend()from core.inference.diffusion import get_diffusion_backendreturn get_diffusion_backend()@@ -187,16 +306,21 @@ def get_active_diffusion_engine() -> Any:return engine_for(_active_engine_name)+# (module, singleton attribute) of every image engine, read from sys.modules only.+_ENGINE_SINGLETONS = (+ ("core.inference.diffusion", "_diffusion_backend"),+ ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),+ ("core.inference.mlx_diffusion_backend", "_mlx_diffusion_backend"),+)++def cancel_generation_for_account(account_id: str) -> bool:"""Stop an in-flight image generation owned by ``account_id``; True when one was signalled.- Engines come from ``sys.modules`` (no import, no construction); both are checked because a+ Engines come from ``sys.modules`` (no import, no construction); all are checked because adeselected engine can still be draining."""cancelled = False- for module_name, attribute in (- ("core.inference.diffusion", "_diffusion_backend"),- ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),- ):+ for module_name, attribute in _ENGINE_SINGLETONS:module = sys.modules.get(module_name)engine = getattr(module, attribute, None) if module is not None else Noneif engine is None or engine._active_generate_account != account_id:@@ -212,10 +336,7 @@ def retire_load_for_account(account_id: str) -> bool:from hub.services.models.account_access import retire_media_loadretired = False- for module_name, attribute in (- ("core.inference.diffusion", "_diffusion_backend"),- ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),- ):+ for module_name, attribute in _ENGINE_SINGLETONS:module = sys.modules.get(module_name)engine = getattr(module, attribute, None) if module is not None else Noneif retire_media_load("diffusion", account_id, engine):@@ -263,6 +384,8 @@ def _activate(name: str, reason: Optional[str]) -> Any:_fallback_reason = reason if name == ENGINE_DIFFUSERS else Noneif name == ENGINE_SD_CPP:logger.info("diffusion engine: sd_cpp")+ elif name == ENGINE_MLX:+ logger.info("diffusion engine: mlx")else:logger.info("diffusion engine: diffusers (%s)", reason or "selected")return get_active_diffusion_engine()@@ -305,6 +428,7 @@ def select_and_activate_engine(model_kind: Optional[str] = None,gpu_ordinal: Optional[int] = None,before_fallback: Optional[Callable[[], None]] = None,+ gguf_filename: Optional[str] = None,) -> Any:"""Pick + activate the engine for loading ``fam`` on this host; return the engine.``before_fallback`` may raise to refuse a diffusers fallback before it unloads the resident model.@@ -312,7 +436,14 @@ def select_and_activate_engine(Falls back to diffusers (recording a reason) when the native route is disabled, the device hasa usable GPU, MPS is not enabled, the family has no native asset, or the binary is unavailable-- always BEFORE the slow load, so a fallback never strands a half-native load.++ With UNSLOTH_DIFFUSION_MLX=1 the MLX engine is tried first (``mlx_selection``, which needs+ ``gguf_filename`` to judge the quant); a refusal is recorded and the choice below runs unchanged."""+ use_mlx, mlx_refusal = mlx_selection(fam, model_kind = model_kind, gguf_filename = gguf_filename)+ _note_mlx_refusal(mlx_refusal)+ if use_mlx:+ return _activate(ENGINE_MLX, None)if model_kind and model_kind != "gguf":return _activate(ENGINE_DIFFUSERS, f"non-GGUF load ({model_kind}) requires diffusers")@@ -499,6 +630,7 @@ def predict_engine(*,model_kind: Optional[str] = None,gpu_ordinal: Optional[int] = None,+ gguf_filename: Optional[str] = None,) -> str:"""The engine a load of ``fam`` would select on this host, WITHOUT any side effect.@@ -514,6 +646,8 @@ def predict_engine(diffusers for the very first native load, when no binary is on disk yet) would mispredict thecommon case: a fresh CPU host."""+ if mlx_selection(fam, model_kind = model_kind, gguf_filename = gguf_filename)[0]:+ return ENGINE_MLXif model_kind and model_kind != "gguf":return ENGINE_DIFFUSERS@@ -545,7 +679,12 @@ def predict_engine()-def family_buildable_here(fam: Optional[DiffusionFamily], *, model_kind: Optional[str]) -> bool:+def family_buildable_here(+ fam: Optional[DiffusionFamily],+ *,+ model_kind: Optional[str],+ gguf_filename: Optional[str] = None,+) -> bool:"""True when THIS host can actually build ``fam`` for a ``model_kind`` load, by either engine.The two engines need different things. diffusers instantiates ``fam.pipeline_class``, which the@@ -566,6 +705,12 @@ def family_buildable_here(fam: Optional[DiffusionFamily], *, model_kind: Optionareturn Falseif family_pipeline_available(fam):return True+ if model_kind == "gguf" and gguf_filename and family_mlx_supported(fam):+ try:+ if predict_engine(fam, model_kind = "gguf", gguf_filename = gguf_filename) == ENGINE_MLX:+ return True+ except Exception: # noqa: BLE001 -- a probe failure must not hide/refuse a usable model+ pass# only a GGUF can go native, and only for a family with the single-file assets sd.cpp needsif model_kind != "gguf" or not family_sd_cpp_supported(fam):return False@@ -585,6 +730,7 @@ def annotate_status(status: dict[str, Any]) -> dict[str, Any]:out = dict(status)out["engine"] = _active_engine_nameout["fallback_reason"] = _fallback_reason+ out["mlx_fallback_reason"] = _mlx_fallback_reasonout["supported_families"] = list(_supported_family_capabilities())return outdiff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.pyindex 09d897f4444..92b8c5afd81 100644--- a/studio/backend/core/inference/diffusion_families.py+++ b/studio/backend/core/inference/diffusion_families.py@@ -188,6 +188,9 @@ class DiffusionFamily:# VAE latent-format override for sd-cli (--vae-format): "flux2" for FLUX.2, None otherwisesd_cpp_vae_format: Optional[str] = Nonesd_cpp_text_encoders: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)+ # mflux ModelConfig name (None = no MLX); ``_by_base`` maps a lowercase base repo to another config.+ mlx_model_config: Optional[str] = None+ mlx_model_config_by_base: tuple[tuple[str, str], ...] = field(default_factory = tuple)# Family-specific sd-cli sampler settings so native output matches the model's supported invocation. None leaves# sd-cli defaults.sd_cpp_sampling_method: Optional[str] = None@@ -660,6 +663,8 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (fp16_incompatible = True,# The attention / FFN branches overflow float16 before their post-norm.fp16_guard = "rescale_post_norm",+ mlx_model_config = "z-image-turbo",+ mlx_model_config_by_base = (("Tongyi-MAI/Z-Image", "z-image"),),# Byte-identical mirror of Comfy-Org/z_image_turbo (AE + Qwen3-4B).sd_cpp_vae = ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"),sd_cpp_text_encoders = (@@ -2153,6 +2158,20 @@ def family_gguf_loadable(fam: DiffusionFamily) -> bool:return not fam.single_file_is_pipeline and not fam.pipeline_only+def family_mlx_supported(fam: Optional[DiffusionFamily]) -> bool:+ return fam is not None and bool(getattr(fam, "mlx_model_config", None))+++def mlx_model_config_for(fam: DiffusionFamily, base_repo: Optional[str]) -> Optional[str]:+ if not family_mlx_supported(fam):+ return None+ key = (base_repo or "").strip().lower()+ for base, name in getattr(fam, "mlx_model_config_by_base", ()) or ():+ if key == base.lower():+ return name+ return fam.mlx_model_config++def family_sd_cpp_supported(fam: DiffusionFamily) -> bool:"""True when the family has the single-file VAE + text-encoder mapping sd.cpp needs; without itthe no-GPU route falls back to diffusers.diff --git a/studio/backend/core/inference/media_locality.py b/studio/backend/core/inference/media_locality.pyindex 9d58b581e6b..e186ed209a3 100644--- a/studio/backend/core/inference/media_locality.py+++ b/studio/backend/core/inference/media_locality.py@@ -246,7 +246,7 @@ def planners_for(owner: str, pick: MediaModelPick) -> list:if fam is None:return [backend_for(owner)]kind = resolve_model_kind(pick.gguf_filename, pick.model_kind)- predicted = predict_engine(fam, model_kind = kind)+ predicted = predict_engine(fam, model_kind = kind, gguf_filename = pick.gguf_filename)names = [predicted]if predicted == ENGINE_SD_CPP and not native_binary_installed():names.append(ENGINE_DIFFUSERS)diff --git a/studio/backend/core/inference/mlx_diffusion_backend.py b/studio/backend/core/inference/mlx_diffusion_backend.pynew file mode 100644index 00000000000..7e229a5a610--- /dev/null+++ b/studio/backend/core/inference/mlx_diffusion_backend.py@@ -0,0 +1,1356 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Opt-in MLX (mflux) image engine for Apple Silicon (``UNSLOTH_DIFFUSION_MLX=1``) on Studio's GGUF.++Same duck-typed surface as the other image engines; selected only by ``diffusion_engine_router``.+"""++from __future__ import annotations++import gc+import json+import os+import random+import subprocess+import threading+import time+from collections import OrderedDict+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any, Callable, Optional, Union++from core.inference.diffusion_families import (+ DIFFUSION_CANCELLED_MSG,+ DIFFUSION_NOT_LOADED_MSG,+ DiffusionFamily,+ DiffusionModelReplacedError,+ LoadIdentity,+ _is_local_path,+ canonical_base,+ detect_family_for_pick,+ family_mlx_supported,+ load_identity,+ mirror_repo,+ mlx_model_config_for,+ named_variant_base,+ prefer_ungated_mirror,+ resolve_base_repo,+ resolve_local_gguf_child,+ supported_family_names,+)+from core.inference import mlx_diffusion_convert as convert+from core.inference.diffusion_batched import SEED_MASK+from loggers import get_logger+from utils.account_context import account_thread, current_account_id+from utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memory++logger = get_logger(__name__)++ENGINE_NAME = "mlx"++BASE_ALLOW_PATTERNS = (+ "text_encoder/*.safetensors",+ "text_encoder/*.json",+ "tokenizer/*",+ "vae/*.safetensors",+ "vae/*.json",+)+_LINKED_SUBDIRS = ("text_encoder", "tokenizer", "vae")+_TE_GROUP_SIZE = 64+_ENCODING_CACHE_SIZE = 8+_LOW_RAM_BYTES = 16 * 1024**3+++class MlxCancelled(Exception):+ """Raised in the mflux step callback to stop at the next step."""+++def clear_exception_locals(exc: Optional[BaseException]) -> None:+ """Drop the locals of every finished frame in an exception chain, keeping the traceback text."""+ import traceback++ seen: set[int] = set()+ while exc is not None and id(exc) not in seen:+ seen.add(id(exc))+ if exc.__traceback__ is not None:+ traceback.clear_frames(exc.__traceback__)+ exc = exc.__cause__ or exc.__context__+++def drop_exception_frames(exc: Optional[BaseException]) -> None:+ """Clear frame locals along an exception chain: a retained traceback otherwise keeps the model alive."""+ import traceback++ seen: set[int] = set()+ while exc is not None and id(exc) not in seen:+ seen.add(id(exc))+ if exc.__traceback__ is not None:+ traceback.clear_frames(exc.__traceback__)+ exc.__traceback__ = None+ nxt = exc.__cause__ or exc.__context__+ exc.__cause__ = None+ exc.__context__ = None+ exc = nxt+++def _total_ram_bytes() -> int:+ try:+ return int(os.sysconf("SC_PAGE_SIZE")) * int(os.sysconf("SC_PHYS_PAGES"))+ except (AttributeError, ValueError, OSError):+ return 0+++def _env_int(name: str, allowed: tuple[int, ...]) -> Optional[int]:+ raw = os.environ.get(name, "").strip()+ if not raw:+ return None+ try:+ value = int(raw)+ except ValueError:+ logger.warning("%s=%r is not an integer; ignoring it", name, raw)+ return None+ if value not in allowed:+ logger.warning("%s=%s is not one of %s; ignoring it", name, value, allowed)+ return None+ return value+++def text_encoder_bits(ram_bytes: Optional[int] = None) -> Optional[int]:+ forced = _env_int("UNSLOTH_DIFFUSION_MLX_TE_BITS", (4, 8, 16))+ if forced is not None:+ return None if forced == 16 else forced+ ram = _total_ram_bytes() if ram_bytes is None else ram_bytes+ return 4 if 0 < ram <= _LOW_RAM_BYTES else 8+++def dense_bits(ram_bytes: Optional[int] = None) -> int:+ forced = _env_int("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", (0, 4, 8))+ if forced is not None:+ return forced+ ram = _total_ram_bytes() if ram_bytes is None else ram_bytes+ return 4 if 0 < ram <= _LOW_RAM_BYTES else 0+++def _chip_name() -> str:+ try:+ out = subprocess.run(+ ["sysctl", "-n", "machdep.cpu.brand_string"],+ capture_output = True,+ text = True,+ timeout = 5,+ )+ return (out.stdout or "").strip()+ except Exception: # noqa: BLE001+ return ""+++def compute_precision_name(chip: Optional[str] = None) -> str:+ """M1 / M2 lack native bf16, so fp16 there."""+ raw = os.environ.get("UNSLOTH_DIFFUSION_MLX_PRECISION", "auto").strip().lower()+ if raw in ("fp16", "float16", "half"):+ return "float16"+ if raw in ("bf16", "bfloat16"):+ return "bfloat16"+ name = (chip if chip is not None else _chip_name()).lower()+ return "float16" if ("apple m1" in name or "apple m2" in name) else "bfloat16"+++class MfluxRuntime:+ """The only code that imports mlx / mflux. Tests replace it with a fake (``backend.runtime_factory``)."""++ def build(+ self, model_path: str, *, model_config: str, precision: str, te_bits: Optional[int]+ ) -> Any:+ import mlx.core as mx+ import mlx.nn as nn+ from mflux.models.common.config.model_config import ModelConfig+ from mflux.models.z_image import ZImage++ config = getattr(ModelConfig, model_config.replace("-", "_"))()+ model = ZImage(+ model_config = config,+ model_path = model_path,+ quantize = None,+ compute_precision = mx.float16 if precision == "float16" else None,+ )+ if te_bits:++ def _quantizable(_path, module):+ weight = getattr(module, "weight", None)+ return (+ hasattr(module, "to_quantized")+ and weight is not None+ and weight.shape[-1] % _TE_GROUP_SIZE == 0+ )++ nn.quantize(+ model.text_encoder,+ group_size = _TE_GROUP_SIZE,+ bits = te_bits,+ class_predicate = _quantizable,+ )+ # Materialize in slices so peak memory stays near the quantized size, not the bf16 checkpoint.+ from mlx.utils import tree_flatten++ for component in (model.transformer, model.vae, model.text_encoder):+ arrays = [a for _name, a in tree_flatten(component.parameters())]+ for start in range(0, len(arrays), 32):+ mx.eval(arrays[start : start + 32])+ mx.eval(model.parameters())+ return model++ def generate(+ self,+ model: Any,+ *,+ prompt: str,+ negative_prompt: Optional[str],+ seed: int,+ steps: int,+ width: int,+ height: int,+ guidance: Optional[float],+ on_step: Callable[[int], None],+ ) -> Any:+ import mlx.core as mx+ from mflux.utils.exceptions import StopImageGenerationException++ class _StepCallback:+ def call_in_loop(self, t, seed, prompt, latents, config, time_steps): # noqa: ARG002+ mx.eval(latents)+ try:+ on_step(int(t) + 1)+ except MlxCancelled as exc:+ raise StopImageGenerationException(str(exc)) from exc++ callback = _StepCallback()+ model.callbacks.register(callback)+ cancelled = False+ try:+ result = model.generate_image(+ seed = int(seed),+ prompt = prompt,+ negative_prompt = negative_prompt,+ num_inference_steps = int(steps),+ width = int(width),+ height = int(height),+ guidance = guidance,+ )+ except StopImageGenerationException as exc:+ # The unwound mflux frames hold the model; uncleared, it survives unload().+ drop_exception_frames(exc)+ cancelled = True+ except BaseException as exc:+ # Same for a real failure, but keep the traceback for the caller's log.+ clear_exception_locals(exc)+ raise+ finally:+ try:+ model.callbacks.in_loop.remove(callback)+ except (AttributeError, ValueError):+ pass+ if cancelled:+ raise MlxCancelled("cancelled")+ return result.image++ def cache_text_encodings(+ self,+ model: Any,+ size: int = _ENCODING_CACHE_SIZE,+ ) -> None:+ original = model._encode_prompts+ cache: OrderedDict = OrderedDict()++ def _cached(*, prompt, negative_prompt, guidance):+ cfg = float(guidance or 0.0) > 1.0+ key = (prompt, negative_prompt if cfg else None, cfg)+ if key in cache:+ cache.move_to_end(key)+ return cache[key]+ value = original(prompt = prompt, negative_prompt = negative_prompt, guidance = guidance)+ cache[key] = value+ while len(cache) > size:+ cache.popitem(last = False)+ return value++ model._encode_prompts = _cached++ def free(self) -> None:+ gc.collect()+ try:+ import mlx.core as mx+ mx.clear_cache()+ except Exception: # noqa: BLE001+ pass++ def supports_guidance(self, model: Any) -> bool:+ return bool(getattr(getattr(model, "model_config", None), "supports_guidance", False))+++@dataclass+class _MlxState:+ repo_id: str+ display_repo_id: Optional[str]+ gguf_filename: str+ base_repo: str+ family: DiffusionFamily+ model: Any+ model_config: str+ precision: str+ te_bits: Optional[int]+ dense_bits: int+ convert_dir: str+ timings: dict = field(default_factory = dict)+++@dataclass+class _MlxLoading:+ repo_id: str+ base_repo: str+ fetch_repo: Optional[str] = None+ phase: str = "downloading"+ downloaded_bytes: int = 0+ expected_bytes: int = 0+ fraction: float = 0.0+ error: Optional[str] = None+++@dataclass+class _MlxGen:+ total_steps: int+ step: int = 0+ first_step_at: float = 0.0+ eta_seconds: Optional[float] = None+++def _snapshot_revision(path: str) -> Optional[str]:+ parts = Path(path).parts+ if "snapshots" in parts:+ index = parts.index("snapshots")+ if index + 1 < len(parts):+ return parts[index + 1]+ return None+++def fetch_gguf(+ repo_id: str,+ gguf_filename: str,+ hf_token: Optional[str],+ *,+ cancel_event: threading.Event,+ local_files_only: bool,+) -> str:+ local_root = Path(repo_id).expanduser()+ if local_root.exists():+ return str(resolve_local_gguf_child(local_root, gguf_filename))+ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback++ return hf_hub_download_with_xet_fallback(+ repo_id,+ gguf_filename,+ hf_token,+ cancel_event = cancel_event,+ reuse_other_cache_root = True,+ local_files_only = local_files_only,+ )+++def _holds_base_components(snapshot: str) -> bool:+ root = Path(snapshot)+ if not all((root / sub).is_dir() for sub in _LINKED_SUBDIRS):+ return False+ if not all((root / "tokenizer" / f).is_file() for f in ("tokenizer.json", "tokenizer_config.json")):+ return False+ for sub in ("text_encoder", "vae"):+ folder = root / sub+ shards: set[str] = set()+ for index in folder.glob("*.safetensors.index.json"):+ try:+ shards.update(json.loads(index.read_text(encoding = "utf-8"))["weight_map"].values())+ except (OSError, ValueError, KeyError, AttributeError):+ return False+ if shards:+ if not all((folder / shard).is_file() for shard in shards):+ return False+ elif not any(folder.glob("*.safetensors")):+ return False+ return True+++def fetch_base_snapshot(+ base_repo: str,+ hf_token: Optional[str],+ *,+ local_files_only: bool,+ cancel_event: Optional[threading.Event] = None,+) -> str:+ """The base repo's text encoder / tokenizer / VAE snapshot dir. Online, each file goes through the+ same cancellable downloader as the GGUF, so an unload stops the transfer between and within files."""+ local_root = Path(base_repo).expanduser()+ if local_root.is_dir():+ return str(local_root)+ from huggingface_hub import snapshot_download++ if local_files_only:+ from huggingface_hub import constants+ from huggingface_hub.errors import LocalEntryNotFoundError+ from utils.hf_cache_settings import active_hf_hub_cache++ missing: Optional[Exception] = None+ incomplete: Optional[Exception] = None+ # The plan may have staged the mirror even when the upstream holds some weights: try both.+ repos = [prefer_ungated_mirror(base_repo, hf_token), base_repo]+ if not os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip():+ repos.append(mirror_repo(base_repo))+ for repo in dict.fromkeys(r for r in repos if r):+ for cache_dir in dict.fromkeys((active_hf_hub_cache(), constants.HF_HUB_CACHE)):+ try:+ snapshot = snapshot_download(+ repo,+ allow_patterns = list(BASE_ALLOW_PATTERNS),+ token = hf_token,+ local_files_only = True,+ cache_dir = cache_dir,+ )+ except LocalEntryNotFoundError as exc:+ missing = exc+ continue+ if _holds_base_components(snapshot):+ return snapshot+ incomplete = incomplete or LocalEntryNotFoundError(+ f"'{repo}' is cached without a complete text_encoder / tokenizer / vae"+ )+ raise incomplete or missing+ import fnmatch++ from huggingface_hub import HfApi+ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback++ def _listing(repo: str) -> tuple[Any, list[str]]:+ info = HfApi().model_info(repo, token = hf_token, files_metadata = False)+ return info, [+ s.rfilename+ for s in info.siblings or ()+ if any(fnmatch.fnmatch(s.rfilename, pattern) for pattern in BASE_ALLOW_PATTERNS)+ ]++ info, wanted = _listing(base_repo)+ # The repo the delegated download plan staged from: the ungated mirror unless the upstream is cached.+ fetch_repo = prefer_ungated_mirror(base_repo, hf_token, files = wanted) if wanted else base_repo+ if fetch_repo != base_repo:+ info, wanted = _listing(fetch_repo)+ if not wanted:+ raise FileNotFoundError(f"'{fetch_repo}' has no text_encoder / tokenizer / vae files")+ from huggingface_hub import constants, try_to_load_from_cache+ from utils.hf_cache_settings import active_hf_hub_cache++ def _holds_all(root: str) -> bool:+ return all(+ isinstance(+ try_to_load_from_cache(fetch_repo, f, revision = info.sha, cache_dir = root), str+ )+ for f in wanted+ )++ # One root for every file: mflux reads the three directories out of a single snapshot.+ cache_dir = active_hf_hub_cache()+ if not _holds_all(cache_dir) and _holds_all(constants.HF_HUB_CACHE):+ cache_dir = constants.HF_HUB_CACHE+ snapshot_dir: Optional[str] = None+ for filename in wanted:+ if cancel_event is not None and cancel_event.is_set():+ raise MlxCancelled("load cancelled")+ path = hf_hub_download_with_xet_fallback(+ fetch_repo,+ filename,+ hf_token,+ cancel_event = cancel_event,+ revision = info.sha,+ cache_dir = cache_dir,+ )+ if snapshot_dir is None:+ snapshot_dir = str(Path(path).parents[len(Path(filename).parts) - 1])+ return snapshot_dir+++def resolve_variant_base(+ repo_id: str,+ fam: DiffusionFamily,+ hf_token: Optional[str],+ gguf_filename: Optional[str],+ *,+ fallback: str,+ local_files_only: bool = False,+) -> str:+ """The diffusers loader's base resolution (trusted ``base_model`` card tag, then a named variant,+ then the family default), so both engines read the same base for one pick. Cache-only reads no+ card: the base an earlier online load recorded for this repo, else the name, else the default."""+ if local_files_only:+ return _cached_variant_base(repo_id, fam, gguf_filename, fallback)+ if Path(repo_id).expanduser().exists():+ named = _named_mlx_base(fam, repo_id, gguf_filename)+ if named:+ return named+ try:+ from core.inference.diffusion import _hf_base_model, _resolve_base_repo+ except Exception as exc: # noqa: BLE001 -- no diffusers stack: the family default stands+ logger.debug("mlx_diffusion.base_resolver_unavailable: %s", exc)+ return fallback+ named = _named_mlx_base(fam, repo_id, gguf_filename)+ try:+ # No card tag (none set, or the Hub read failed): the named variant decides, as offline.+ explicit = named if named and _hf_base_model(repo_id, hf_token) is None else None+ return _resolve_base_repo(repo_id, explicit, fam, hf_token, gguf_filename)+ except Exception as exc: # noqa: BLE001 -- a metadata failure keeps the named variant or default+ logger.debug("mlx_diffusion.base_resolve_failed: %s", exc)+ return named or fallback+++def _cached_variant_base(+ repo_id: str, fam: DiffusionFamily, gguf_filename: Optional[str], fallback: str+) -> str:+ candidates = {+ b.lower()+ for b in (+ fam.base_repo,+ *(getattr(fam, "named_variant_bases", ()) or ()),+ *(b for b, _name in getattr(fam, "mlx_model_config_by_base", ()) or ()),+ )+ if b+ }+ try:+ from hub.utils.companion_assets import read_companion_links+ recorded = read_companion_links().get(repo_id.strip().lower(), ())+ except Exception as exc: # noqa: BLE001 -- no record: the name decides+ logger.debug("mlx_diffusion.companion_links_unreadable: %s", exc)+ recorded = ()+ named = _named_mlx_base(fam, repo_id, gguf_filename)+ for base in reversed(recorded):+ upstream = canonical_base(base)+ # A recorded family default may be an earlier offline fallback, so it cannot overrule a name.+ if upstream.lower() in candidates and not (+ named and upstream.lower() == fam.base_repo.lower()+ ):+ return upstream+ return named or named_variant_base(fam, repo_id, gguf_filename) or fallback+++def _named_mlx_base(fam: DiffusionFamily, *names: Optional[str]) -> Optional[str]:+ """The ``mlx_model_config_by_base`` base the names spell, or None. Per name the longest spelling wins, so a Turbo+ name (which also spells the undistilled ``Z-Image``) keeps the family default, and any name spelling the family+ default (a Turbo repo holding a short file name) keeps it too."""++ def fold(text: str) -> str:+ return "".join(c for c in text.lower() if c.isalnum())++ keyed = [+ (b, fold(b.rsplit("/", 1)[-1]))+ for b in (+ fam.base_repo,+ *(b for b, _name in getattr(fam, "mlx_model_config_by_base", ()) or ()),+ )+ if b+ ]+ found = None+ for name in reversed([n for n in names if n]):+ identity = fold(name.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1])+ hits = [(len(key), b) for b, key in keyed if key and key in identity]+ if hits:+ best = max(hits)[1]+ if best == fam.base_repo:+ return None+ found = found or best+ return found+++def _companion_mirror(base: str) -> Optional[str]:+ if os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip():+ return None+ return mirror_repo(base)+++def _link_base_components(model_dir: Path, base_dir: str) -> None:+ """Relinked every load: a new revision moves the snapshot."""+ for sub in _LINKED_SUBDIRS:+ source = Path(base_dir) / sub+ if not source.is_dir():+ raise FileNotFoundError(f"base repo snapshot has no {sub}/ directory")+ link = model_dir / sub+ if link.is_symlink() or link.is_file():+ link.unlink()+ elif link.is_dir():+ import shutil+ shutil.rmtree(link)+ os.symlink(str(source.resolve()), str(link), target_is_directory = True)+++def _eta(total: int, step: int, first_at: float, now: float) -> Optional[float]:+ if step <= 1 or first_at <= 0 or total <= step:+ return 0.0 if total and step >= total else None+ per_step = (now - first_at) / (step - 1)+ return max(0.0, per_step * (total - step))+++def _round16(value: Optional[int], default: int) -> int:+ v = int(value or default)+ return max(64, (v // 16) * 16)+++class MlxDiffusionBackend:+ runs_off_torch_device = False++ def __init__(self, runtime_factory: Optional[Callable[[], Any]] = None) -> None:+ self._lock = threading.Lock()+ self._generate_lock = threading.Lock()+ self.runtime_factory = runtime_factory or MfluxRuntime+ self._runtime: Any = None+ self._state: Optional[_MlxState] = None+ self._loading: Optional[_MlxLoading] = None+ self._load_token = 0+ self._cancel_event = threading.Event()+ self._active_generate_cancel: Optional[threading.Event] = None+ self._active_generate_account: Optional[str] = None+ self._gen: Optional[_MlxGen] = None+ self._load_thread: Optional[threading.Thread] = None+ self._unloading = 0+ self._teardown_lock = threading.Lock()+ self._free_pending = False+ # Repos a cancelled load may still be reading until its worker is joined; see draining_repo_ids().+ self._draining_repos: dict[int, tuple[str, ...]] = {}+ self.last_timings: dict[str, Any] = {}++ def _rt(self) -> Any:+ if self._runtime is None:+ self._runtime = self.runtime_factory()+ return self._runtime++ @property+ def is_loaded(self) -> bool:+ return self._state is not None++ # ── Load ─────────────────────────────────────────────────────────────────++ def begin_load(+ self,+ repo_id: str,+ *,+ local_files_only: bool = False,+ display_repo_id: Optional[str] = None,+ gguf_filename: Optional[str] = None,+ base_repo: Optional[str] = None,+ family_override: Optional[str] = None,+ hf_token: Optional[Union[str, bool]] = None,+ # Accepted and ignored: uniform route call.+ cpu_offload: bool = False,+ memory_mode: Optional[str] = None,+ speed_mode: Optional[str] = None,+ text_encoder_quant: Optional[str] = None,+ transformer_quant: Optional[str] = None,+ transformer_quant_fast_accum: Optional[bool] = None,+ transformer_prequant_path: Optional[str] = None,+ attention_backend: Optional[str] = None,+ transformer_cache: Optional[str] = None,+ transformer_cache_threshold: Optional[float] = None,+ model_kind: Optional[str] = None,+ loras: Optional[list[tuple[str, float]]] = None,+ gpu_ids: Optional[list[int]] = None,+ gpu_ordinal: Optional[int] = None,+ **_ignored: Any,+ ) -> dict[str, Any]:+ if isinstance(hf_token, str):+ hf_token = hf_token.strip() or None+ if not gguf_filename:+ raise ValueError(+ "gguf_filename is required: the MLX engine loads GGUF checkpoints only."+ )+ if model_kind and model_kind != "gguf":+ raise ValueError("The MLX engine loads GGUF checkpoints only.")+ fam = detect_family_for_pick(repo_id, gguf_filename, family_override)+ if fam is None:+ raise ValueError(+ f"'{repo_id}' is not a supported diffusion image model. Supported families: "+ f"{', '.join(supported_family_names())}."+ )+ if not family_mlx_supported(fam):+ raise ValueError(f"Family '{fam.name}' has no MLX implementation.")+ convertible, why = convert.quant_convertible(gguf_filename)+ if not convertible:+ raise ValueError(why or "This GGUF quant is not convertible to MLX.")+ if loras:+ raise ValueError("LoRA adapters are not supported on the MLX engine yet.")+ base = resolve_base_repo(fam, base_repo)+ named = _named_mlx_base(fam, base) if _is_local_path(base) else None+ model_config = mlx_model_config_for(fam, named or base)+ with self._lock:+ if self._loading is not None and self._loading.error is None:+ raise RuntimeError("A diffusion load is already in progress.")+ if self._unloading:+ raise RuntimeError("A diffusion unload is in progress.")+ if self._active_generate_cancel is not None:+ self._active_generate_cancel.set()+ self._load_token += 1+ token = self._load_token+ cancel_event = threading.Event()+ self._cancel_event = cancel_event+ self._loading = _MlxLoading(+ repo_id = repo_id, base_repo = base, fetch_repo = _companion_mirror(base)+ )+ worker = account_thread(+ target = self._run_load,+ kwargs = dict(+ repo_id = repo_id,+ display_repo_id = display_repo_id,+ gguf_filename = gguf_filename,+ base = base,+ fam = fam,+ model_config = model_config,+ hf_token = hf_token,+ local_files_only = local_files_only,+ _load_token = token,+ _cancel_event = cancel_event,+ explicit_base = bool((base_repo or "").strip()),+ ),+ daemon = True,+ )+ self._load_thread = worker+ worker.start()+ return self.status()++ def _set_phase(+ self,+ token: int,+ phase: str,+ fraction: float = 0.0,+ ) -> None:+ with self._lock:+ if self._load_token == token and self._loading is not None:+ self._loading.phase = phase+ self._loading.fraction = fraction++ @_invalidates_gpu_memory("mlx diffusion load")+ def _run_load(+ self,+ *,+ repo_id: str,+ display_repo_id: Optional[str],+ gguf_filename: str,+ base: str,+ fam: DiffusionFamily,+ model_config: str,+ hf_token: Optional[str],+ local_files_only: bool,+ _load_token: int,+ _cancel_event: threading.Event,+ explicit_base: bool = True,+ ) -> None:+ timings: dict[str, Any] = {}+ model = state = displaced = None+ building = published = False+ try:+ if not explicit_base:+ # The repo's base_model card tag can name the undistilled base: resolve it the way the+ # diffusers loader and the delegated download plan do, before picking the mflux config.+ base = resolve_variant_base(+ repo_id,+ fam,+ hf_token,+ gguf_filename,+ fallback = base,+ local_files_only = local_files_only,+ )+ model_config = mlx_model_config_for(fam, base)+ with self._lock:+ if self._load_token == _load_token and self._loading is not None:+ self._loading.base_repo = base+ self._loading.fetch_repo = _companion_mirror(base)+ t0 = time.perf_counter()+ gguf_path = fetch_gguf(+ repo_id,+ gguf_filename,+ hf_token,+ cancel_event = _cancel_event,+ local_files_only = local_files_only,+ )+ base_dir = fetch_base_snapshot(+ base,+ hf_token,+ local_files_only = local_files_only,+ cancel_event = _cancel_event,+ )+ timings["fetch_s"] = round(time.perf_counter() - t0, 3)+ if _cancel_event.is_set():+ return+ bits = dense_bits()+ revision = _snapshot_revision(gguf_path)+ if revision is None:+ st = os.stat(gguf_path)+ revision = f"local-{st.st_size}-{int(st.st_mtime)}"+ out_dir = convert.cache_dir_for(repo_id, revision, gguf_filename, dense_bits = bits)+ self._set_phase(_load_token, "finalizing", 0.0)+ t1 = time.perf_counter()+ if convert.conversion_complete(out_dir, source_path = gguf_path):+ timings["convert_cached"] = True+ else:+ out_dir.mkdir(parents = True, exist_ok = True)++ def _progress(done: int, total: int) -> None:+ self._set_phase(_load_token, "finalizing", (done / total) if total else 0.0)++ summary = convert.convert_gguf_to_mflux(+ gguf_path,+ out_dir,+ dense_bits = bits,+ cancel_event = _cancel_event,+ progress = _progress,+ )+ timings["convert_cached"] = False+ timings["convert_summary"] = {+ k: v+ for k, v in (summary or {}).items()+ if isinstance(v, (int, float, str, dict))+ }+ timings["convert_s"] = round(time.perf_counter() - t1, 3)+ _link_base_components(Path(out_dir), base_dir)+ if _cancel_event.is_set():+ return+ precision = compute_precision_name()+ te_bits = text_encoder_bits()+ t2 = time.perf_counter()+ runtime = self._rt()+ # Free the replaced model first: two resident DiTs do not fit a small Mac.+ with self._lock:+ displaced = self._state if self._load_token == _load_token else None+ if displaced is not None:+ self._state = None+ if displaced is not None:+ del displaced+ with self._generate_lock:+ pass+ runtime.free()+ if _cancel_event.is_set():+ return+ building = True+ model = runtime.build(+ str(out_dir),+ model_config = model_config,+ precision = precision,+ te_bits = te_bits,+ )+ runtime.cache_text_encodings(model)+ timings["build_s"] = round(time.perf_counter() - t2, 3)+ state = _MlxState(+ repo_id = repo_id,+ display_repo_id = display_repo_id,+ gguf_filename = gguf_filename,+ base_repo = base,+ family = fam,+ model = model,+ model_config = model_config,+ precision = precision,+ te_bits = te_bits,+ dense_bits = bits,+ convert_dir = str(out_dir),+ timings = timings,+ )+ with self._lock:+ if self._load_token != _load_token:+ superseded = True+ else:+ superseded = False+ self._state = state+ self._loading = None+ published = True+ if superseded:+ del state, model+ runtime.free()+ return+ logger.info(+ "mlx_diffusion.loaded: repo=%s gguf=%s config=%s precision=%s te_bits=%s dense_bits=%s "+ "timings=%s",+ repo_id,+ gguf_filename,+ model_config,+ precision,+ te_bits,+ bits,+ timings,+ )+ except Exception as exc: # noqa: BLE001 -- surfaced via load_progress+ clear_exception_locals(exc)+ if self._load_token != _load_token or _cancel_event.is_set():+ return+ logger.error("mlx_diffusion.load_failed: %s", exc, exc_info = True)+ if self._state is not None:+ from .gpu_arbiter import DIFFUSION, restore_owner_account+ from hub.services.models.account_access import restore_resident_metadata++ restore_owner_account(DIFFUSION)+ restore_resident_metadata("diffusion")+ from utils.native_path_leases import redact_native_paths++ with self._lock:+ if self._load_token == _load_token and self._loading is not None:+ self._loading.error = redact_native_paths(str(exc))+ finally:+ # A cached exception below (Hub helpers memoize import failures) can retain this frame;+ # a model left in its locals would then survive unload().+ model = state = displaced = None+ if building and not published and self._runtime is not None:+ self._runtime.free()++ def download_plan(self, repo_id: str, **kwargs: Any) -> dict[str, Any]:+ """The diffusers GGUF plan stages exactly the files this engine opens; its memory verdict does not apply."""+ from core.inference.diffusion import get_diffusion_backend++ kwargs["memory_verdict"] = False+ if not (kwargs.get("base_repo") or "").strip():+ gguf_filename = kwargs.get("gguf_filename")+ fam = detect_family_for_pick(repo_id, gguf_filename, kwargs.get("family_override"))+ if fam is not None and gguf_filename and family_mlx_supported(fam):+ kwargs["base_repo"] = resolve_variant_base(+ repo_id,+ fam,+ kwargs.get("hf_token"),+ gguf_filename,+ fallback = fam.base_repo,+ local_files_only = bool(kwargs.get("local_files_only")),+ )+ # The loader always opens the base repo's text_encoder/ and vae/, never a single-file component.+ kwargs.pop("text_encoder_files", None)+ kwargs.pop("vae_file", None)+ return get_diffusion_backend().download_plan(+ repo_id, discover_text_encoders = False, **kwargs+ )++ def preflight_base_access(+ self, repo_id: str, fam: Optional[DiffusionFamily], **kwargs: Any+ ) -> None:+ from core.inference.diffusion import get_diffusion_backend+ get_diffusion_backend().preflight_base_access(repo_id, fam, **kwargs)++ def load_progress(self) -> dict[str, Any]:+ loading = self._loading+ if loading is not None and loading.error:+ return _progress("error", error = loading.error)+ if loading is None:+ return _progress("ready" if self._state is not None else None)+ return _progress(+ loading.phase,+ loading.downloaded_bytes,+ loading.expected_bytes,+ loading.fraction,+ )++ def loading_repo_ids(self) -> tuple[str, ...]:+ with self._lock:+ loading = self._loading+ if loading is None or loading.error is not None:+ return ()+ return tuple(+ dict.fromkeys(+ r for r in (loading.repo_id, loading.base_repo, loading.fetch_repo) if r+ )+ )++ def draining_repo_ids(self) -> tuple[str, ...]:+ """Repos a cancelled load is still reading until unload() has joined its worker, for the cache-deletion guards+ only (``loading_repo_ids()`` reads as ownership elsewhere)."""+ with self._lock:+ return tuple(dict.fromkeys(r for repos in self._draining_repos.values() for r in repos))++ def loaded_repo_ids(self) -> tuple[str, ...]:+ with self._lock:+ state = self._state+ if state is None:+ return ()+ return tuple(dict.fromkeys((state.repo_id, state.base_repo)))++ # ── Generate ─────────────────────────────────────────────────────────────++ def generate(+ self,+ *,+ prompt: str,+ negative_prompt: Optional[str] = None,+ width: Optional[int] = 1024,+ height: Optional[int] = 1024,+ steps: int = 9,+ guidance: float = 0.0,+ seed: Optional[int] = None,+ batch_size: int = 1,+ prompts: Optional[list[str]] = None,+ seeds: Optional[list[int]] = None,+ init_image: Optional[str] = None,+ mask_image: Optional[str] = None,+ strength: Optional[float] = None,+ upscale: Optional[float] = None,+ reference_images: Optional[list[str]] = None,+ workflow: Optional[str] = None,+ reference_resolution: Optional[int] = None,+ localized_edit: Any = None,+ loras: Optional[list[tuple[str, float]]] = None,+ controlnet: Optional[tuple[str, str, str, float, float, float]] = None,+ expected_load: Optional[LoadIdentity] = None,+ allow_oversized: bool = False,+ ) -> dict[str, Any]:+ if (+ init_image is not None+ or mask_image is not None+ or reference_images+ or workflow not in (None, "txt2img")+ or reference_resolution is not None+ or localized_edit is not None+ or (upscale is not None and upscale > 1)+ ):+ raise ValueError(+ "The MLX engine runs text-to-image only; unset UNSLOTH_DIFFUSION_MLX for "+ "img2img / inpaint / edit / reference / upscale."+ )+ if prompts is not None or seeds is not None:+ raise ValueError(+ "Batched prompt/seed lists are not supported on the MLX engine; use batch_size."+ )+ if controlnet is not None and controlnet[3] not in (None, 0, 0.0):+ raise ValueError("ControlNet is not supported on the MLX engine.")+ if loras:+ raise ValueError("LoRA adapters are not supported on the MLX engine yet.")+ steps = int(steps)+ if steps < 1:+ raise ValueError("steps must be at least 1")+ batch = max(1, int(batch_size or 1))+ base_seed = int(seed) if seed is not None else random.randint(0, 2**31 - 1)+ w = _round16(width, 1024)+ h = _round16(height, 1024)+ family = getattr(self._state, "family", None)+ if family is not None:+ from core.inference.diffusion_conditioning import check_output_size+ check_output_size(family, w, h)++ cancel = threading.Event()+ from hub.services.models.account_access import media_generation_slot++ with self._generate_lock, media_generation_slot("diffusion"):+ with self._lock:+ state = self._state+ if state is None:+ raise RuntimeError(DIFFUSION_NOT_LOADED_MSG)+ loaded_id = load_identity(state.repo_id, state.base_repo, state.family.name)+ if expected_load is not None and expected_load != loaded_id:+ raise DiffusionModelReplacedError(expected_load, loaded_id)+ self._active_generate_cancel = cancel+ self._active_generate_account = current_account_id()+ self._gen = _MlxGen(total_steps = steps * batch)+ try:+ runtime = self._rt()+ cfg = float(guidance or 0.0) if runtime.supports_guidance(state.model) else None+ images = []+ seeds_out = []+ per_image: list[dict[str, float]] = []+ for index in range(batch):+ image_seed = (base_seed + index) & SEED_MASK+ offset = index * steps+ started = time.perf_counter()+ marks: list[float] = []++ def _on_step(+ done: int,+ offset = offset,+ marks = marks,+ ) -> None:+ marks.append(time.perf_counter())+ gen = self._gen+ if gen is not None:+ now = time.time()+ gen.step = min(offset + done, gen.total_steps)+ if gen.first_step_at == 0.0:+ gen.first_step_at = now+ gen.eta_seconds = _eta(+ gen.total_steps, gen.step, gen.first_step_at, now+ )+ if cancel.is_set():+ raise MlxCancelled("cancelled")++ if cancel.is_set():+ raise MlxCancelled("cancelled")+ image = runtime.generate(+ state.model,+ prompt = prompt,+ negative_prompt = negative_prompt,+ seed = image_seed,+ steps = steps,+ width = w,+ height = h,+ guidance = cfg,+ on_step = _on_step,+ )+ total = time.perf_counter() - started+ timing = {"total_s": round(total, 3)}+ if len(marks) >= 2:+ # Exclude the first step: it includes prompt encoding.+ timing["s_per_step"] = round((marks[-1] - marks[0]) / (len(marks) - 1), 4)+ timing["first_step_s"] = round(marks[0] - started, 3)+ timing["decode_s"] = round(time.perf_counter() - marks[-1], 3)+ per_image.append(timing)+ images.append(image)+ seeds_out.append(image_seed)+ with self._lock:+ if cancel.is_set():+ raise RuntimeError(DIFFUSION_CANCELLED_MSG)+ if self._active_generate_cancel is cancel:+ self._active_generate_cancel = None+ self._active_generate_account = None+ self.last_timings = {"width": w, "height": h, "steps": steps, "images": per_image}+ logger.info(+ "mlx_diffusion.generated: %dx%d steps=%d batch=%d timings=%s",+ w,+ h,+ steps,+ batch,+ per_image,+ )+ return {+ "images": images,+ "seed": base_seed,+ "seeds": seeds_out,+ "negative_prompt": (negative_prompt or None) if cfg and cfg > 1.0 else None,+ "repo_id": state.display_repo_id or state.repo_id,+ "model_kind": "gguf",+ "gguf_filename": state.gguf_filename,+ # The MLX build on top of the GGUF: on-load quantization varies with RAM and env.+ "transformer_quant": _dense_quant_name(state.dense_bits),+ "text_encoder_quant": _te_quant_name(state.te_bits),+ "memory_mode": None,+ "offload_policy": "none",+ "speed_mode": None,+ "cpu_offload": False,+ "workflow": "txt2img",+ "reference_resolution": None,+ "localized_edit": None,+ }+ except MlxCancelled as exc:+ drop_exception_frames(exc)+ raise RuntimeError(DIFFUSION_CANCELLED_MSG) from None+ except BaseException as exc:+ clear_exception_locals(exc)+ raise+ finally:+ state = runtime = None+ self._gen = None+ with self._lock:+ if self._active_generate_cancel is cancel:+ self._active_generate_cancel = None+ self._active_generate_account = None++ def generate_progress(self) -> dict[str, Any]:+ gen = self._gen+ if gen is None or gen.total_steps <= 0:+ return {+ "active": False,+ "step": 0,+ "total_steps": 0,+ "fraction": 0.0,+ "eta_seconds": None,+ }+ return {+ "active": True,+ "step": gen.step,+ "total_steps": gen.total_steps,+ "fraction": min(gen.step / gen.total_steps, 1.0),+ "eta_seconds": gen.eta_seconds,+ }++ def cancel_generate(self, expected_account: Optional[str] = None) -> bool:+ with self._lock:+ cancel = self._active_generate_cancel+ if cancel is None:+ return False+ if expected_account is not None and self._active_generate_account not in (+ None,+ expected_account,+ ):+ return False+ cancel.set()+ return True++ # ── Unload / status ──────────────────────────────────────────────────────++ @_invalidates_gpu_memory("mlx diffusion unload")+ def unload(self, *, expected_account: Optional[str] = None) -> dict[str, Any]:+ with self._lock:+ if expected_account is not None:+ from .gpu_arbiter import DIFFUSION, GpuBusyForAnotherAccountError+ from hub.services.models.account_access import require_resident_control++ if (+ self._active_generate_cancel is not None+ and self._active_generate_account != expected_account+ ):+ raise GpuBusyForAnotherAccountError(DIFFUSION, 1)+ require_resident_control(+ DIFFUSION, self._state.repo_id if self._state is not None else None+ )+ self._cancel_event.set()+ if self._active_generate_cancel is not None:+ self._active_generate_cancel.set()+ if self._state is not None:+ self._free_pending = True+ self._state = None+ self._load_token += 1+ # Left visible until joined: a concurrent unload must wait for the same worker.+ worker = self._load_thread+ if self._loading is not None and worker is not None:+ self._draining_repos[id(worker)] = tuple(+ dict.fromkeys(+ r+ for r in (+ self._loading.repo_id,+ self._loading.base_repo,+ self._loading.fetch_repo,+ )+ if r+ )+ )+ self._loading = None+ # Held until the join and free below: a load started meanwhile would build beside the superseded one.+ self._unloading += 1+ try:+ # Serialized so every unload returns only after the whole teardown, whichever caller runs it.+ with self._teardown_lock:+ # Barrier: on return the cancelled generation has released the model.+ with self._generate_lock:+ pass+ # And a superseded load has stopped: a build in progress cannot be interrupted, and the+ # caller treats this return as "memory is free" before activating another engine or load.+ if worker is not None and worker is not threading.current_thread():+ worker.join()+ with self._lock:+ if self._load_thread is worker:+ self._load_thread = None+ if worker is not None:+ self._draining_repos.pop(id(worker), None)+ free, self._free_pending = self._free_pending, False+ if free and self._runtime is not None:+ self._runtime.free()+ finally:+ with self._lock:+ self._unloading -= 1+ return self.status()++ def status(self) -> dict[str, Any]:+ state = self._state+ if state is None:+ return {+ "loaded": False,+ "repo_id": None,+ "display_repo_id": None,+ "family": None,+ "base_repo": None,+ "device": None,+ "dtype": None,+ "gguf_variant": None,+ "cpu_offload": False,+ "offload_policy": None,+ "vae_tiling": False,+ "memory_mode": None,+ "speed_mode": None,+ "speed_optims": [],+ "text_encoder_quant": None,+ "transformer_quant": None,+ "attention_backend": None,+ "transformer_cache": None,+ "resolved": None,+ "engine": ENGINE_NAME,+ "native_mode": None,+ "supports_lora": False,+ "supports_controlnet": False,+ "workflows": [],+ "conditioning": None,+ }+ from core.inference.diffusion_conditioning import conditioning_capabilities+ from hub.utils.gguf import extract_quant_token++ conditioning = conditioning_capabilities(state.family, ["txt2img"])+ conditioning["reference_resolutions"] = []+ conditioning["notes"] = []+ try:+ negative = bool(self._rt().supports_guidance(state.model))+ except Exception: # noqa: BLE001+ negative = False+ return {+ "loaded": True,+ "repo_id": state.repo_id,+ "display_repo_id": state.display_repo_id,+ "family": state.family.name,+ "base_repo": state.base_repo,+ "device": "mps",+ "dtype": state.precision,+ "model_kind": "gguf",+ "gguf_filename": state.gguf_filename,+ "gguf_variant": extract_quant_token(state.gguf_filename),+ "cpu_offload": False,+ "offload_policy": "none",+ "vae_tiling": False,+ "memory_mode": None,+ "speed_mode": None,+ "speed_optims": [],+ "text_encoder_quant": _te_quant_name(state.te_bits),+ "transformer_quant": _dense_quant_name(state.dense_bits),+ "attention_backend": None,+ "transformer_cache": None,+ "resolved": None,+ "engine": ENGINE_NAME,+ "native_mode": None,+ "mlx": {+ "model_config": state.model_config,+ "precision": state.precision,+ "text_encoder_bits": state.te_bits,+ "dense_bits": state.dense_bits,+ "timings": dict(state.timings),+ },+ "supports_lora": False,+ "supports_controlnet": False,+ "supports_negative_prompt": negative,+ "workflows": ["txt2img"],+ "conditioning": conditioning,+ }+++def _dense_quant_name(bits: Optional[int]) -> Optional[str]:+ return f"mlx_int{bits}_dense" if bits else None+++def _te_quant_name(bits: Optional[int]) -> Optional[str]:+ return f"mlx_int{bits}" if bits else None+++def _progress(+ phase: Optional[str],+ bytes_downloaded: int = 0,+ bytes_total: int = 0,+ fraction: float = 0.0,+ *,+ error: Optional[str] = None,+) -> dict[str, Any]:+ return {+ "phase": phase,+ "bytes_downloaded": bytes_downloaded,+ "bytes_total": bytes_total,+ "fraction": fraction,+ "error": error,+ }+++_mlx_diffusion_backend: Optional[MlxDiffusionBackend] = None+++def get_mlx_diffusion_backend() -> MlxDiffusionBackend:+ global _mlx_diffusion_backend+ if _mlx_diffusion_backend is None:+ _mlx_diffusion_backend = MlxDiffusionBackend()+ return _mlx_diffusion_backend+++def generation_in_flight() -> bool:+ backend = _mlx_diffusion_backend+ return backend is not None and backend._gen is not Nonediff --git a/studio/backend/core/inference/mlx_diffusion_convert.py b/studio/backend/core/inference/mlx_diffusion_convert.pynew file mode 100644index 00000000000..a95097f8907--- /dev/null+++ b/studio/backend/core/inference/mlx_diffusion_convert.py@@ -0,0 +1,560 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Diffusion GGUF -> mflux pre-quantized transformer layout (numpy + gguf only, streamed per tensor).++Q4_0 / Q4_1 / Q8_0 map exactly onto MLX affine group-32 (dequant = q * scale + bias):+ Q4_0: scale d, bias -8d; Q4_1: scale d, bias m; Q8_0: q = qs + 128, scale d, bias -128d.+K-quants are refused (not converted yet): their per-sub-block scale products do not round-trip exactly through MLX's 16-bit group scales, and Q6_K uses 16-element groups.+"""++from __future__ import annotations++import json+import os+import re+import struct+import time+from pathlib import Path+from typing import Any, Callable, Optional++import numpy as np++CONVERTER_VERSION = "1"+MFLUX_VERSION = "0.22.0"+GROUP_SIZE = 32+OUTPUT_FILENAME = "0.safetensors"+MARKER_FILENAME = "unsloth_mlx_convert.json"++CONVERTIBLE_TYPES = frozenset({"Q4_0", "Q4_1", "Q8_0", "BF16", "F16", "F32"})+CONVERTIBLE_QUANT_TOKENS = frozenset({"Q4_0", "Q4_1", "Q8_0", "BF16", "F16", "F32"})++_BLOCK_BYTES = {"Q4_0": 18, "Q4_1": 20, "Q8_0": 34}+_BLOCK_BITS = {"Q4_0": 4, "Q4_1": 4, "Q8_0": 8}+_DENSE_TYPES = frozenset({"BF16", "F16", "F32"})+_PAD_TOKENS = ("cap_pad_token", "x_pad_token")+_QKV_PARTS = ("to_q", "to_k", "to_v")+++class UnsupportedGGUFError(ValueError):+ """The GGUF holds a tensor type this converter cannot map onto MLX affine weights."""+++# ── Filename-level verdict (router) ─────────────────────────────────────────────────────────────++_QUANT_RE = re.compile(+ r"(?:^|[-_.])((?:UD-)?(?:I?Q\d+_[A-Z0-9_]+|Q\d+|BF16|F16|F32|MXFP4|TQ\d_\d))(?:\.gguf)?$",+ re.IGNORECASE,+)+++def _quant_token(gguf_filename: str) -> Optional[str]:+ try:+ from hub.utils.gguf import extract_quant_token+ return extract_quant_token(gguf_filename)+ except Exception: # noqa: BLE001 -- the regex below answers when the hub helper cannot+ match = _QUANT_RE.search(Path(gguf_filename).name)+ return match.group(1) if match else None+++def quant_convertible(gguf_filename: Optional[str]) -> tuple[bool, Optional[str]]:+ """Filename verdict only; conversion re-checks every tensor."""+ if not gguf_filename:+ return (+ False,+ "GGUF quant unknown (no GGUF filename); the MLX engine needs Q4_0/Q4_1/Q8_0/BF16",+ )+ token = _quant_token(str(gguf_filename))+ if not token:+ return False, (+ f"GGUF quant unknown for {Path(str(gguf_filename)).name!r}; the MLX engine needs "+ "Q4_0/Q4_1/Q8_0/BF16"+ )+ upper = str(token).upper()+ if upper in CONVERTIBLE_QUANT_TOKENS:+ return True, None+ return False, (f"GGUF quant {token} is not convertible to MLX yet (only Q4_0/Q4_1/Q8_0/BF16)")+++# ── Block math ──────────────────────────────────────────────────────────────────────────────────+++def _pack(q: np.ndarray, bits: int) -> np.ndarray:+ """(R, C) integers in [0, 2**bits) -> (R, C * bits / 32) uint32, element i at bits*(i % per_word)."""+ per_word = 32 // bits+ rows, cols = q.shape+ if cols % per_word:+ raise ValueError(f"{cols} columns do not pack into {bits}-bit words")+ q = q.reshape(rows, cols // per_word, per_word).astype(np.uint32)+ shifts = (bits * np.arange(per_word, dtype = np.uint32)).astype(np.uint32)+ return np.bitwise_or.reduce(q << shifts, axis = -1).astype(np.uint32)+++def _unpack(packed: np.ndarray, bits: int) -> np.ndarray:+ per_word = 32 // bits+ rows, words = packed.shape+ shifts = (bits * np.arange(per_word, dtype = np.uint32)).astype(np.uint32)+ mask = np.uint32((1 << bits) - 1)+ q = (packed.astype(np.uint32)[..., None] >> shifts) & mask+ return q.reshape(rows, words * per_word)+++def _f16_field(blocks: np.ndarray, start: int) -> np.ndarray:+ return blocks[..., start : start + 2].copy().view(np.float16)[..., 0].astype(np.float32)+++def affine_from_ggml(+ kind: str, raw: np.ndarray, rows: int, cols: int+) -> tuple[np.ndarray, np.ndarray, np.ndarray, int]:+ """Q4_0 / Q4_1 / Q8_0 block bytes -> (packed uint32, scales f32, biases f32, bits), MLX affine g32."""+ kind = str(kind).upper()+ if kind not in _BLOCK_BYTES:+ raise UnsupportedGGUFError(f"{kind} blocks have no exact MLX affine mapping")+ if cols % GROUP_SIZE:+ raise ValueError(f"{cols} columns are not a whole number of {GROUP_SIZE}-wide blocks")+ nb = cols // GROUP_SIZE+ raw = np.ascontiguousarray(np.asarray(raw)).view(np.uint8).reshape(-1)+ expected = rows * nb * _BLOCK_BYTES[kind]+ if raw.size != expected:+ raise ValueError(f"{kind}: {raw.size} bytes for {rows}x{cols}, expected {expected}")+ blocks = raw.reshape(rows, nb, _BLOCK_BYTES[kind])+ if kind == "Q4_0":+ d = _f16_field(blocks, 0)+ qs = blocks[..., 2:]+ q = np.concatenate([qs & 0xF, qs >> 4], axis = -1).reshape(rows, cols)+ return _pack(q, 4), d, -8.0 * d, 4+ if kind == "Q4_1":+ d = _f16_field(blocks, 0)+ m = _f16_field(blocks, 2)+ qs = blocks[..., 4:]+ q = np.concatenate([qs & 0xF, qs >> 4], axis = -1).reshape(rows, cols)+ return _pack(q, 4), d, m, 4+ d = _f16_field(blocks, 0)+ qs = blocks[..., 2:].copy().view(np.int8).astype(np.int16) + 128+ return _pack(qs.astype(np.uint8).reshape(rows, cols), 8), d, -128.0 * d, 8+++def _f32_to_bf16_bits(a: np.ndarray) -> np.ndarray:+ """float32 -> bf16 bit patterns (uint16), round to nearest even; NaN stays NaN."""+ a = np.ascontiguousarray(a, dtype = np.float32)+ u = a.view(np.uint32)+ rounded = ((u + (np.uint32(0x7FFF) + ((u >> 16) & np.uint32(1)))) >> 16).astype(np.uint16)+ nan = np.isnan(a)+ if nan.any():+ rounded = np.where(nan, ((u >> 16) | np.uint32(0x40)).astype(np.uint16), rounded)+ return rounded+++def _bf16_bits_to_f32(b: np.ndarray) -> np.ndarray:+ return (np.asarray(b, dtype = np.uint16).astype(np.uint32) << 16).view(np.float32)+++def round_to_bf16(a: np.ndarray) -> np.ndarray:+ """float32 values as they read back after a bf16 store."""+ return _bf16_bits_to_f32(_f32_to_bf16_bits(a))+++def quantize_dense_affine(+ w: np.ndarray,+ bits: int,+ group_size: int = GROUP_SIZE,+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:+ """Min/max affine quantization of a dense (R, C) weight; scale / bias already bf16-rounded."""+ if bits not in (4, 8):+ raise ValueError(f"dense quantization supports 4 or 8 bits, not {bits}")+ w = np.asarray(w, dtype = np.float32)+ rows, cols = w.shape+ if cols % group_size:+ raise ValueError(f"{cols} columns are not a whole number of {group_size}-wide groups")+ g = w.reshape(rows, cols // group_size, group_size)+ lo = g.min(axis = -1)+ hi = g.max(axis = -1)+ levels = float((1 << bits) - 1)+ bias = round_to_bf16(lo)+ scale = round_to_bf16((hi - bias) / levels)+ flat = scale == 0+ safe_scale = np.where(flat, np.float32(1.0), scale).astype(np.float32)+ q = np.rint((g - bias[..., None]) / safe_scale[..., None])+ q = np.where(flat[..., None], 0.0, q)+ q = np.clip(q, 0, levels).astype(np.uint8).reshape(rows, cols)+ return _pack(q, bits), scale.astype(np.float32), bias.astype(np.float32)+++def dequantize_affine(+ packed: np.ndarray,+ scales: np.ndarray,+ biases: np.ndarray,+ bits: int,+ group_size: int = GROUP_SIZE,+) -> np.ndarray:+ q = _unpack(np.asarray(packed), bits).astype(np.float32)+ rows, cols = q.shape+ q = q.reshape(rows, cols // group_size, group_size)+ s = np.asarray(scales, dtype = np.float32)[..., None]+ b = np.asarray(biases, dtype = np.float32)[..., None]+ return (q * s + b).reshape(rows, cols)+++# ── Names ───────────────────────────────────────────────────────────────────────────────────────+++def zimage_rename(name: str) -> str:+ """Single-file Z-Image tensor name -> mflux's (the qkv split happens in the converter)."""+ k = re.sub(r"^final_layer\.", "all_final_layer.2-1.", name)+ k = re.sub(r"^x_embedder\.", "all_x_embedder.2-1.", k)+ k = k.replace(+ "all_final_layer.2-1.adaLN_modulation.1.", "all_final_layer.2-1.adaLN_modulation.0."+ )+ k = k.replace("t_embedder.mlp.0.", "t_embedder.linear1.").replace(+ "t_embedder.mlp.2.", "t_embedder.linear2."+ )+ k = k.replace(".attention.out.", ".attention.to_out.0.")+ k = k.replace(".attention.q_norm.", ".attention.norm_q.").replace(+ ".attention.k_norm.", ".attention.norm_k."+ )+ return k+++# ── Planning ────────────────────────────────────────────────────────────────────────────────────++_ST_DTYPE_BYTES = {"U32": 4, "BF16": 2, "F16": 2}+++def _type_name(tensor: Any) -> str:+ return str(tensor.tensor_type.name).upper()+++def _gguf_dims(tensor: Any) -> list[int]:+ """numpy-order shape (outermost first); GGUF stores the innermost dimension first."""+ return [int(x) for x in reversed([int(v) for v in tensor.shape])]+++def _dense_f32(tensor: Any) -> np.ndarray:+ kind = _type_name(tensor)+ raw = np.asarray(tensor.data)+ shape = _gguf_dims(tensor)+ if kind == "BF16":+ return _bf16_bits_to_f32(np.ascontiguousarray(raw).view(np.uint16)).reshape(shape)+ if kind == "F16":+ return np.ascontiguousarray(raw).view(np.float16).astype(np.float32).reshape(shape)+ return np.ascontiguousarray(raw).view(np.float32).reshape(shape)+++def _dense_bf16_bits(tensor: Any) -> np.ndarray:+ """Dense tensor as bf16 bit patterns; a BF16 source is copied bit for bit."""+ if _type_name(tensor) == "BF16":+ return (+ np.ascontiguousarray(np.asarray(tensor.data))+ .view(np.uint16)+ .reshape(_gguf_dims(tensor))+ )+ return _f32_to_bf16_bits(_dense_f32(tensor))+++class _Job:+ """One source tensor -> its output tensors, planned from shapes alone and produced on demand."""++ def __init__(self, tensor: Any, outputs: list[tuple[str, str, list[int]]], produce: Callable):+ self.tensor = tensor+ self.outputs = outputs+ self.produce = produce+++def _scale_store(a: np.ndarray, scale_dtype: str) -> np.ndarray:+ if scale_dtype == "f16":+ return np.ascontiguousarray(a, dtype = np.float32).astype(np.float16)+ return _f32_to_bf16_bits(a)+++def _plan(reader: Any, *, dense_bits: int, scale_dtype: str) -> tuple[list[_Job], dict]:+ sdt = "F16" if scale_dtype == "f16" else "BF16"+ jobs: list[_Job] = []+ bits_count = {4: 0, 8: 0}+ for tensor in reader.tensors:+ kind = _type_name(tensor)+ name = zimage_rename(str(tensor.name))+ dims = _gguf_dims(tensor)+ if kind in _BLOCK_BYTES:+ if not name.endswith(".weight"):+ raise UnsupportedGGUFError(f"quantized tensor {tensor.name} is not a .weight")+ cols = dims[-1]+ rows = int(np.prod(dims[:-1])) if len(dims) > 1 else 1+ bits = _BLOCK_BITS[kind]+ bits_count[bits] += 1+ base = name[: -len(".weight")]+ parts = [(base, 0, rows)]+ if base.endswith(".attention.qkv"):+ if rows % 3:+ raise UnsupportedGGUFError(+ f"{tensor.name}: {rows} rows do not split into q/k/v"+ )+ n = rows // 3+ stem = base[: -len("qkv")]+ parts = [(stem + p, i * n, (i + 1) * n) for i, p in enumerate(_QKV_PARTS)]+ outputs = []+ for nm, a, b in parts:+ r = b - a+ outputs += [+ (nm + ".weight", "U32", [r, cols * bits // 32]),+ (nm + ".scales", sdt, [r, cols // GROUP_SIZE]),+ (nm + ".biases", sdt, [r, cols // GROUP_SIZE]),+ ]++ def produce(+ tensor = tensor,+ kind = kind,+ rows = rows,+ cols = cols,+ parts = parts,+ ):+ w, s, b, _bits = affine_from_ggml(kind, tensor.data, rows, cols)+ for _nm, lo, hi in parts:+ yield np.ascontiguousarray(w[lo:hi])+ yield _scale_store(s[lo:hi], scale_dtype)+ yield _scale_store(b[lo:hi], scale_dtype)++ jobs.append(_Job(tensor, outputs, produce))+ continue+ if name in _PAD_TOKENS:+ dims = [1, int(np.prod(dims))]+ quantize = (+ dense_bits+ and len(dims) == 2+ and name.endswith(".weight")+ and dims[-1] % GROUP_SIZE == 0+ and name not in _PAD_TOKENS+ )+ if name.endswith(".attention.qkv.weight"):+ if dims[0] % 3:+ raise UnsupportedGGUFError(f"{tensor.name}: {dims[0]} rows do not split into q/k/v")+ n = dims[0] // 3+ stem = name[: -len("qkv.weight")]+ parts = [(stem + p, i * n, (i + 1) * n) for i, p in enumerate(_QKV_PARTS)]+ else:+ parts = [(name[: -len(".weight")] if quantize else name, 0, dims[0] if dims else 1)]+ outputs = []+ for nm, a, b in parts:+ r = b - a+ if quantize:+ bits_count[dense_bits] += 1+ outputs += [+ (nm + ".weight", "U32", [r, dims[-1] * dense_bits // 32]),+ (nm + ".scales", sdt, [r, dims[-1] // GROUP_SIZE]),+ (nm + ".biases", sdt, [r, dims[-1] // GROUP_SIZE]),+ ]+ elif len(parts) > 1:+ outputs.append((nm + ".weight", "BF16", [r, *dims[1:]]))+ else:+ outputs.append((nm, "BF16", list(dims)))++ def produce_dense(+ tensor = tensor,+ dims = dims,+ parts = parts,+ quantize = quantize,+ ):+ if quantize:+ full = _dense_f32(tensor).reshape(dims)+ for _nm, lo, hi in parts:+ w, s, b = quantize_dense_affine(round_to_bf16(full[lo:hi]), dense_bits)+ yield w+ yield _scale_store(s, scale_dtype)+ yield _scale_store(b, scale_dtype)+ return+ bits16 = _dense_bf16_bits(tensor).reshape(dims)+ for _nm, lo, hi in parts:+ yield np.ascontiguousarray(bits16[lo:hi] if len(parts) > 1 else bits16)++ jobs.append(_Job(tensor, outputs, produce_dense))+ return jobs, bits_count+++def _check_types(reader: Any) -> dict[str, int]:+ counts: dict[str, int] = {}+ for tensor in reader.tensors:+ kind = _type_name(tensor)+ counts[kind] = counts.get(kind, 0) + 1+ bad = {k: v for k, v in counts.items() if k not in CONVERTIBLE_TYPES}+ if bad:+ listed = ", ".join(f"{v} x {k}" for k, v in sorted(bad.items()))+ raise UnsupportedGGUFError(+ f"GGUF holds tensor types MLX conversion does not support yet: {listed} "+ "(supported: Q4_0, Q4_1, Q8_0, BF16, F16, F32)"+ )+ return counts+++# ── Writer ──────────────────────────────────────────────────────────────────────────────────────+++def _nbytes(dtype: str, shape: list[int]) -> int:+ return int(np.prod(shape)) * _ST_DTYPE_BYTES[dtype] if shape else _ST_DTYPE_BYTES[dtype]+++def _header_bytes(entries: list[tuple[str, str, list[int]]], metadata: dict[str, str]) -> bytes:+ header: dict[str, Any] = {"__metadata__": metadata}+ offset = 0+ for name, dtype, shape in entries:+ size = _nbytes(dtype, shape)+ header[name] = {"dtype": dtype, "shape": shape, "data_offsets": [offset, offset + size]}+ offset += size+ blob = json.dumps(header, separators = (",", ":")).encode("utf-8")+ blob += b" " * ((-len(blob)) % 8)+ return blob+++def convert_gguf_to_mflux(+ gguf_path: os.PathLike | str,+ out_dir: os.PathLike | str,+ *,+ dense_bits: int = 0,+ scale_dtype: str = "bf16",+ cancel_event: Any = None,+ progress: Optional[Callable[[int, int], None]] = None,+) -> dict[str, Any]:+ """Refuses unsupported types before writing; lands the file atomically, marker last."""+ from gguf import GGUFReader++ if dense_bits not in (0, 4, 8):+ raise ValueError(f"dense_bits must be 0, 4 or 8, not {dense_bits}")+ if scale_dtype not in ("bf16", "f16"):+ raise ValueError(f"scale_dtype must be 'bf16' or 'f16', not {scale_dtype!r}")+ started = time.perf_counter()+ gguf_path = Path(gguf_path)+ reader = GGUFReader(str(gguf_path))+ counts = _check_types(reader)+ jobs, bits_count = _plan(reader, dense_bits = dense_bits, scale_dtype = scale_dtype)+ entries = [entry for job in jobs for entry in job.outputs]+ names = [e[0] for e in entries]+ if len(set(names)) != len(names):+ raise UnsupportedGGUFError("tensor names collide after the mflux rename")+ if bits_count[4] or bits_count[8]:+ level = "8" if bits_count[8] > bits_count[4] else "4"+ else:+ level = "None"+ metadata = {+ "quantization_level": level,+ "mflux_version": MFLUX_VERSION,+ "source_gguf": gguf_path.name,+ "unsloth_converter": CONVERTER_VERSION,+ }+ header = _header_bytes(entries, metadata)++ target_dir = Path(out_dir) / "transformer"+ target_dir.mkdir(parents = True, exist_ok = True)+ final = target_dir / OUTPUT_FILENAME+ marker = target_dir / MARKER_FILENAME+ # A stale marker must not vouch for the file this run is about to replace.+ with _suppress_missing():+ marker.unlink()+ tmp = target_dir / f".{OUTPUT_FILENAME}.{os.getpid()}.tmp"+ total = len(jobs)+ written = 0+ try:+ with open(tmp, "wb") as fh:+ fh.write(struct.pack("<Q", len(header)))+ fh.write(header)+ for index, job in enumerate(jobs):+ if cancel_event is not None and cancel_event.is_set():+ raise RuntimeError("cancelled")+ produced = list(job.produce())+ if len(produced) != len(job.outputs):+ raise RuntimeError(f"{job.tensor.name}: produced {len(produced)} tensors")+ for (name, dtype, shape), array in zip(job.outputs, produced):+ data = np.ascontiguousarray(array)+ if list(data.shape) != list(shape) or data.nbytes != _nbytes(dtype, shape):+ raise RuntimeError(+ f"{name}: produced {data.dtype}{list(data.shape)}, planned {dtype}{shape}"+ )+ fh.write(data.tobytes())+ written += data.nbytes+ if progress is not None:+ progress(index + 1, total)+ os.replace(tmp, final)+ except BaseException:+ with _suppress_missing():+ tmp.unlink()+ raise+ out_bytes = final.stat().st_size+ stat = gguf_path.stat()+ summary = {+ "converter_version": CONVERTER_VERSION,+ "source_gguf": gguf_path.name,+ "source_size": int(stat.st_size),+ "source_mtime": float(stat.st_mtime),+ "counts": counts,+ "dense_bits": dense_bits,+ "scale_dtype": scale_dtype,+ "quantization_level": level,+ "n_out_tensors": len(entries),+ "output_bytes": int(out_bytes),+ "bytes": int(written),+ "seconds": round(time.perf_counter() - started, 3),+ }+ marker_tmp = target_dir / f".{MARKER_FILENAME}.{os.getpid()}.tmp"+ marker_tmp.write_text(json.dumps(summary, indent = 1), encoding = "utf-8")+ os.replace(marker_tmp, marker)+ return summary+++class _suppress_missing:+ def __enter__(self):+ return self++ def __exit__(self, exc_type, exc, tb):+ return exc_type is not None and issubclass(exc_type, FileNotFoundError)+++# ── Cache layout ────────────────────────────────────────────────────────────────────────────────+++def _safe(text: str) -> str:+ out = re.sub(r"[^A-Za-z0-9._@-]+", "_", str(text).replace("\\", "/").replace("/", "--"))+ return "_" if out in ("", ".", "..") else out+++def cache_dir_for(+ repo_id: str,+ revision: Optional[str],+ gguf_filename: str,+ *,+ dense_bits: int,+ scale_dtype: str = "bf16",+) -> Path:+ """``<studio cache>/mlx_diffusion/<repo>@<revision>/<gguf stem>-d<bits>-<scale dtype>``."""+ from utils.paths.storage_roots import cache_root++ stem = str(gguf_filename)+ if stem.lower().endswith(".gguf"):+ stem = stem[: -len(".gguf")]+ return (+ cache_root()+ / "mlx_diffusion"+ / f"{_safe(repo_id)}@{_safe(revision or 'local')}"+ / f"{_safe(stem)}-d{int(dense_bits)}-{_safe(scale_dtype)}"+ )+++def conversion_complete(+ out_dir: os.PathLike | str, *, source_path: Optional[os.PathLike | str] = None+) -> bool:+ target_dir = Path(out_dir) / "transformer"+ try:+ marker = json.loads((target_dir / MARKER_FILENAME).read_text(encoding = "utf-8"))+ size = (target_dir / OUTPUT_FILENAME).stat().st_size+ except (OSError, ValueError):+ return False+ if not isinstance(marker, dict) or marker.get("converter_version") != CONVERTER_VERSION:+ return False+ if int(marker.get("output_bytes", -1)) != size:+ return False+ if source_path is not None:+ try:+ stat = Path(source_path).stat()+ except OSError:+ return False+ if int(marker.get("source_size", -1)) != int(stat.st_size):+ return False+ if abs(float(marker.get("source_mtime", -1.0)) - float(stat.st_mtime)) > 1e-3:+ return False+ return Truediff --git a/studio/backend/core/inference/sd_cpp_engine.py b/studio/backend/core/inference/sd_cpp_engine.pyindex fbf501003e9..fb46434fb72 100644--- a/studio/backend/core/inference/sd_cpp_engine.py+++ b/studio/backend/core/inference/sd_cpp_engine.py@@ -972,6 +972,8 @@ class SdCppEngine:ENGINE_DIFFUSERS = "diffusers"ENGINE_SD_CPP = "sd_cpp"+# Opt-in Apple Silicon MLX engine (core.inference.mlx_diffusion_backend), chosen only by the router, never here.+ENGINE_MLX = "mlx"# Backends diffusers serves well with GPU acceleration; everything else is native-engine territory._GPU_BACKENDS = frozenset({"cuda", "rocm", "xpu"})diff --git a/studio/backend/main.py b/studio/backend/main.pyindex cff05fccf0b..834e25e99d6 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -2012,6 +2012,7 @@ _MEDIA_BACKEND_MODULES = ("core.inference.video","core.inference.diffusion","core.inference.sd_cpp_backend",+ "core.inference.mlx_diffusion_backend","routes.inference",)diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex dd4efddca6f..a9a8878791e 100644--- a/studio/backend/models/inference.py+++ b/studio/backend/models/inference.py@@ -5245,7 +5245,10 @@ class DiffusionStatusResponse(BaseModel):"max_output_side, max_output_pixels, reference_resolutions and localized_edit_modes. ""Null when nothing is loaded.",)- engine: Optional[str] = Field(None, description = "Active diffusion engine: diffusers | sd_cpp")+ engine: Optional[str] = Field(+ None,+ description = "Active diffusion engine: diffusers | sd_cpp | mlx (opt-in, Apple Silicon)",+ )native_mode: Optional[str] = Field(None,description = "Native sd.cpp execution mode: server (resident sd-server) | oneshot "@@ -5255,6 +5258,11 @@ class DiffusionStatusResponse(BaseModel):None,description = "Why diffusers was chosen over the native sd.cpp engine (null when none)",)+ mlx_fallback_reason: Optional[str] = Field(+ None,+ description = "Why UNSLOTH_DIFFUSION_MLX=1 did not get the MLX engine on the last load (null when "+ "MLX was not requested or is in use)",+ )supports_lora: bool = Field(False,description = "Whether the loaded model + quantisation can apply LoRA adapters (drives the "diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex d92fd4a5362..4e30efe9ef0 100644--- a/studio/backend/routes/inference.py+++ b/studio/backend/routes/inference.py@@ -46236,6 +46236,14 @@ def _refuse_native_component_files(request: DiffusionLoadRequest) -> None:)+def _refuse_mlx_loras(request: DiffusionLoadRequest) -> None:+ if request.loras:+ raise HTTPException(+ status_code = 400,+ detail = "LoRA adapters are not supported on the MLX engine yet.",+ )++@studio_router.post("/images/download-plan", response_model = DiffusionDownloadPlanResponse)async def diffusion_download_plan(request: DiffusionLoadRequest, current_subject: str = Depends(get_current_subject)@@ -46265,7 +46273,7 @@ async def diffusion_download_plan(resolve_model_kind,)from core.inference.diffusion_engine_router import predict_engine- from core.inference.sd_cpp_engine import ENGINE_SD_CPP+ from core.inference.sd_cpp_engine import ENGINE_MLX, ENGINE_SD_CPPfrom utils.native_path_leases import redact_native_pathsbackend = get_diffusion_backend()@@ -46317,13 +46325,27 @@ async def diffusion_download_plan(gpu_ordinal = await _selected_gpu_ordinal(request.gpu_ids, allow_ranking = not training)# Plan for the engine /images/load will pick: a GGUF on a GPU-less host routes to native# sd.cpp, which reads different files. Card-scoped, since the failure records are per card.- if (- fam is not None- and predict_engine(fam, model_kind = kind, gpu_ordinal = gpu_ordinal) == ENGINE_SD_CPP- ):+ predicted = (+ predict_engine(+ fam,+ model_kind = kind,+ gpu_ordinal = gpu_ordinal,+ gguf_filename = request.gguf_filename,+ )+ if fam is not None+ else None+ )+ if predicted == ENGINE_SD_CPP:_refuse_native_component_files(request)from core.inference.sd_cpp_backend import get_sd_cpp_backendplanner = get_sd_cpp_backend()+ elif predicted == ENGINE_MLX:+ # Opt-in MLX engine (UNSLOTH_DIFFUSION_MLX=1): same single-GGUF contract as native.+ _refuse_native_component_files(request)+ _refuse_mlx_loras(request)+ from core.inference.mlx_diffusion_backend import get_mlx_diffusion_backend++ planner = get_mlx_diffusion_backend()if fam is not None and not training:if planner is backend:await asyncio.to_thread(@@ -46526,7 +46548,7 @@ async def load_diffusion_model_gated(from core.inference.media_keepwarm import note_load_origin as note_media_load_originfrom hub.utils.gguf import extract_quant_tokenfrom core.inference.sd_cpp_args import forces_cpu_backend- from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_SD_CPP+ from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_MLX, ENGINE_SD_CPPfrom utils.native_path_leases import redact_native_pathsbackend = get_diffusion_backend()@@ -46592,12 +46614,20 @@ async def load_diffusion_model_gated(try:# Card-scoped like the activation below, or the wrong engine's preflight runs.pending_name = (- predict_engine(fam, model_kind = kind, gpu_ordinal = gpu_ordinal)+ predict_engine(+ fam,+ model_kind = kind,+ gpu_ordinal = gpu_ordinal,+ gguf_filename = request.gguf_filename,+ )if fam is not Noneelse None)except Exception: # noqa: BLE001 -- a probe failure must not refuse a loadable pickpending_name = None+ # MLX drives the Apple GPU itself even where torch resolved "cpu": take the arbiter.+ if pending_name == ENGINE_MLX:+ needs_gpu = True# Before selection: switching to diffusers would unload the resident off-torch model, then refuse.if off_torch is not None and pending_name != ENGINE_SD_CPP:_guard_diffusion_load_against_training()@@ -46621,8 +46651,11 @@ async def load_diffusion_model_gated(repo_id = request.model_path,base_repo = request.base_repo,)- elif fam is not None and pending_name == ENGINE_SD_CPP:+ elif fam is not None and pending_name in (ENGINE_SD_CPP, ENGINE_MLX):+ # The opt-in MLX engine shares the native contract: one GGUF, no dense-quant knobs._refuse_native_component_files(request)+ if pending_name == ENGINE_MLX:+ _refuse_mlx_loras(request)# The native engine accepts both knobs for interface parity and ignores them. It was# excluded from the gate above so as not to refuse loads that work today, but the# loads it "works" for are precisely the silent mismatch this whole change exists to@@ -46668,6 +46701,8 @@ async def load_diffusion_model_gated(before_fallback = (_guard_diffusion_load_against_training if off_torch is not None else None),+ # Only the opt-in MLX engine reads it (to judge the GGUF quant).+ gguf_filename = request.gguf_filename,))# predict_engine is selection's read-only twin: it never installs, so a host whose sd-cli@@ -46684,8 +46719,10 @@ async def load_diffusion_model_gated(# only when the prediction was inconclusive or wrong; a correct one already paid it.activated = active_engine_name()if fam is not None and activated != pending_name:- if activated == ENGINE_SD_CPP:+ if activated in (ENGINE_SD_CPP, ENGINE_MLX):_refuse_native_component_files(request)+ if activated == ENGINE_MLX:+ _refuse_mlx_loras(request)_assert_native_precision_unset(transformer_quant = request.transformer_quant,text_encoder_quant = request.text_encoder_quant,@@ -46709,6 +46746,8 @@ async def load_diffusion_model_gated(needs_gpu = Falseelse:_guard_diffusion_load_against_training()+ if activated == ENGINE_MLX:+ needs_gpu = True# sd.cpp runs a paravirtual Mac GPU on the CPU backend, so it takes no DIFFUSION claim.if (activated == ENGINE_SD_CPPdiff --git a/studio/backend/tests/test_comfy_auto_text_encoders.py b/studio/backend/tests/test_comfy_auto_text_encoders.pyindex 3b5093bdc41..faf52f299fe 100644--- a/studio/backend/tests/test_comfy_auto_text_encoders.py+++ b/studio/backend/tests/test_comfy_auto_text_encoders.py@@ -240,3 +240,40 @@ def test_download_plan_drops_the_base_encoder_a_comfy_file_replaces(tmp_path, momemory_verdict = False,)assert "text_encoder" in seen["skip_te_components"]+++def test_the_mlx_plan_keeps_the_base_encoder_it_always_opens(tmp_path, monkeypatch):+ """The MLX loader reads the base repo's text_encoder/, so its plan never trades it for a single file."""+ from core.inference import diffusion+ from core.inference import mlx_diffusion_backend as mb++ models = tmp_path / "ComfyUI" / "models"+ for name in ("diffusion_models", "text_encoders", "vae", "loras"):+ (models / name).mkdir(parents = True, exist_ok = True)+ (models / "diffusion_models" / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"x")+ te = _encoder_file(models / "text_encoders" / "qwen_3_4b.safetensors")+ base = _base(tmp_path)+ seen = []++ def _estimate(*args, **kwargs):+ seen.append(tuple(kwargs["skip_te_components"]))+ return 0, []++ monkeypatch.setattr(+ diffusion.DiffusionBackend, "_estimate_download_bytes", staticmethod(_estimate)+ )+ monkeypatch.setattr(diffusion, "_resolve_base_repo", lambda *a, **k: base)+ backend = diffusion.DiffusionBackend.__new__(diffusion.DiffusionBackend)+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: backend)+ pick = dict(+ gguf_filename = "z-image-turbo-Q4_K_M.gguf",+ model_kind = "gguf",+ allow_device_probe = False,+ )+ backend.download_plan(str(models / "diffusion_models"), memory_verdict = False, **pick)+ mb.MlxDiffusionBackend().download_plan(str(models / "diffusion_models"), **pick)+ mb.MlxDiffusionBackend().download_plan(+ str(models / "diffusion_models"), text_encoder_files = [te], **pick+ )+ assert "text_encoder" in seen[0]+ assert all("text_encoder" not in skip for skip in seen[1:])diff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.pynew file mode 100644index 00000000000..0e6258bfe25--- /dev/null+++ b/studio/backend/tests/test_diffusion_mlx_engine_router.py@@ -0,0 +1,433 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Router matrix for the opt-in MLX image engine: defaults unchanged, refusals fall back, predict == select."""++from __future__ import annotations++import sys+from types import SimpleNamespace++import pytest++from core.inference import diffusion_engine_router as r+from core.inference.diffusion_families import detect_family+from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_MLX, ENGINE_SD_CPP++_ENVS = (+ "UNSLOTH_DIFFUSION_ENGINE",+ "UNSLOTH_DIFFUSION_SD_CPP",+ "UNSLOTH_DIFFUSION_SD_CPP_MPS",+ "UNSLOTH_DIFFUSION_SD_CPP_INSTALL",+ "UNSLOTH_DIFFUSION_MLX",+)+_Q4 = "z-image-turbo-Q4_0.gguf"++[email protected](autouse = True)+def _clean(monkeypatch):+ r._supported_family_capabilities.cache_clear()+ for e in _ENVS:+ monkeypatch.delenv(e, raising = False)+ monkeypatch.setattr(+ r,+ "get_active_diffusion_engine",+ lambda: SimpleNamespace(+ status = lambda: {"loaded": False, "repo_id": None}, unload = lambda: None+ ),+ )+ # No sd.cpp binary anywhere and no install: today's MPS / CPU choice is then diffusers, never a real exec.+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_INSTALL", "0")+ monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: None)+ monkeypatch.setattr(r, "_server_binary_runnable", lambda *_a, **_k: False)+ saved = (r._active_engine_name, r._fallback_reason, r._mlx_fallback_reason)+ try:+ yield+ finally:+ r._active_engine_name, r._fallback_reason, r._mlx_fallback_reason = saved+ r._supported_family_capabilities.cache_clear()+++def _device(monkeypatch, backend):+ monkeypatch.setattr(+ r,+ "resolve_diffusion_device_target",+ lambda: SimpleNamespace(backend = backend, device = backend),+ )+++def _host(+ monkeypatch,+ *,+ system = "darwin",+ machine = "arm64",+ macos = "15.1",+):+ monkeypatch.setattr(r, "sys", SimpleNamespace(platform = system, modules = sys.modules))+ monkeypatch.setattr(+ r,+ "platform",+ SimpleNamespace(machine = lambda: machine, mac_ver = lambda: (macos, ("", "", ""), "")),+ )+++_GOOD_VERSIONS = {+ "mflux": "0.22.0",+ "mlx": "0.32.3",+ "piexif": "1.1.3",+ "platformdirs": "4.3.8",+ "toml": "0.10.2",+}+++def _runtime(+ monkeypatch,+ *,+ mlx = True,+ mflux = True,+ versions = None,+):+ present = {"mlx": mlx, "mflux": mflux}+ versions = {**_GOOD_VERSIONS, **(versions or {})}+ monkeypatch.setattr(r, "_installed_version", versions.get)+ real_find_spec = r.importlib.util.find_spec+ monkeypatch.setattr(+ r,+ "importlib",+ SimpleNamespace(+ util = SimpleNamespace(+ find_spec = lambda name, *a, **k: (+ (object() if present[name] else None)+ if name in present+ else real_find_spec(name, *a, **k)+ )+ )+ ),+ )+++def _apple(monkeypatch, backend = "mps"):+ _host(monkeypatch)+ _device(monkeypatch, backend)+ _runtime(monkeypatch)+++def _select(+ fam = "z-image",+ gguf = _Q4,+ kind = "gguf",+):+ r.select_and_activate_engine(detect_family(fam), model_kind = kind, gguf_filename = gguf)+ return r.active_engine_name()+++def _predict(+ fam = "z-image",+ gguf = _Q4,+ kind = "gguf",+):+ return r.predict_engine(detect_family(fam), model_kind = kind, gguf_filename = gguf)+++# ── opt-in on a capable Mac picks MLX ────────────────────────────────────────++[email protected]("value", ["1", "on", "true", "yes"])+ "gguf",+ [+ _Q4,+ "z-image-turbo-Q4_1.gguf",+ "z-image-turbo-Q8_0.gguf",+ "z-image-turbo-BF16.gguf",+ ],+)+def test_opt_in_on_apple_silicon_picks_mlx(monkeypatch, value, gguf):+ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)+ assert _predict(gguf = gguf) == ENGINE_MLX+ assert _select(gguf = gguf) == ENGINE_MLX+ status = r.annotate_status({"loaded": False})+ assert status["engine"] == ENGINE_MLX+ assert status["mlx_fallback_reason"] is None+ assert status["fallback_reason"] is None+++def test_opt_in_on_the_mps_less_cpu_backend_still_picks_mlx(monkeypatch):+ # A Mac whose torch has no MPS resolves "cpu"; MLX drives the GPU itself.+ _apple(monkeypatch, backend = "cpu")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() == _select() == ENGINE_MLX+++# ── default unchanged: unset / 0 / auto never consult MLX ────────────────────++[email protected]("value", [None, "0", "off", "auto", "AUTO", "garbage"])+def test_default_and_auto_keep_todays_engine(monkeypatch, value):+ _apple(monkeypatch)+ if value is not None:+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)++ def _no_probe(*_a, **_k):+ raise AssertionError("MLX must not be probed when it was not asked for")++ monkeypatch.setattr(r, "_mlx_runtime_refusal", _no_probe)+ monkeypatch.setattr(r, "_mlx_host_refusal", _no_probe)+ assert _predict() == ENGINE_DIFFUSERS+ assert _select() == ENGINE_DIFFUSERS+ status = r.annotate_status({})+ assert status["mlx_fallback_reason"] is None+ # Today's reason, untouched.+ assert status["fallback_reason"] == "GPU backend 'mps' uses diffusers"+++def test_default_keeps_sd_cpp_where_sd_cpp_is_chosen_today(monkeypatch):+ _host(monkeypatch)+ _device(monkeypatch, "mps")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MPS", "1")+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: "/usr/bin/sd-cli")+ monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: "v0"))+ assert _predict() == ENGINE_SD_CPP+ assert _select() == ENGINE_SD_CPP+++# ── refusals fall back to today's engine and say why ─────────────────────────+++ "fam, gguf, kind, needle",+ [+ ("sdxl", "sdxl-Q4_0.gguf", "gguf", "no MLX implementation"),+ ("qwen-image", "qwen-image-Q4_0.gguf", "gguf", "no MLX implementation"),+ ("z-image", "z-image-turbo-Q4_K_M.gguf", "gguf", "Q4_K_M"),+ ("z-image", "z-image-turbo-Q6_K.gguf", "gguf", "Q6_K"),+ ("z-image", "z-image-turbo-UD-Q4_K_XL.gguf", "gguf", "not convertible"),+ ("z-image", None, "gguf", "unknown"),+ ("z-image", None, "pipeline", "GGUF picks only"),+ ("z-image", "model.safetensors", "single_file", "GGUF picks only"),+ ],+)+def test_unsupported_family_quant_or_kind_falls_back_with_reason(+ monkeypatch, fam, gguf, kind, needle+):+ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ predicted = _predict(fam, gguf, kind)+ chosen = _select(fam, gguf, kind)+ assert predicted == chosen == ENGINE_DIFFUSERS+ reason = r.annotate_status({})["mlx_fallback_reason"] or ""+ assert needle in reason+++ "host, needle",+ [+ ({"system": "linux", "machine": "x86_64"}, "macOS only"),+ ({"system": "linux", "machine": "aarch64"}, "macOS only"),+ ({"system": "win32", "machine": "AMD64"}, "macOS only"),+ ({"system": "darwin", "machine": "x86_64"}, "Apple Silicon"),+ ({"system": "darwin", "machine": "arm64", "macos": "13.6"}, "macOS 14"),+ ({"system": "darwin", "machine": "arm64", "macos": ""}, "macOS 14"),+ ],+)+def test_non_apple_silicon_hosts_never_get_mlx(monkeypatch, host, needle):+ _host(monkeypatch, **host)+ _device(monkeypatch, "cpu")+ _runtime(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() == _select() == ENGINE_DIFFUSERS+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")++[email protected]("gpu", ["cuda", "rocm", "xpu"])+def test_gpu_backends_never_get_mlx(monkeypatch, gpu):+ _host(monkeypatch)+ _device(monkeypatch, gpu)+ _runtime(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() == _select() == ENGINE_DIFFUSERS+ assert "not Apple MPS" in (r.annotate_status({})["mlx_fallback_reason"] or "")+++def test_real_linux_host_never_gets_mlx(monkeypatch):+ # No host stubs at all: this suite runs on Linux CI.+ if sys.platform == "darwin":+ pytest.skip("checks the real non-macOS host")+ _device(monkeypatch, "cpu")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() != ENGINE_MLX+ assert _select() != ENGINE_MLX+ assert "macOS only" in (r.annotate_status({})["mlx_fallback_reason"] or "")+++ "mlx, mflux, needle",+ [+ (False, True, "mlx not installed"),+ (True, False, "mflux not installed"),+ (False, False, "mlx and mflux"),+ ],+)+def test_missing_runtime_falls_back(monkeypatch, mlx, mflux, needle):+ _host(monkeypatch)+ _device(monkeypatch, "mps")+ _runtime(monkeypatch, mlx = mlx, mflux = mflux)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() == _select() == ENGINE_DIFFUSERS+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")+++ "versions, needle",+ [+ ({"mflux": "0.17.0"}, "mflux==0.22.0 (found 0.17.0)"),+ ({"mlx": "0.29.1"}, "mlx>=0.32.0,<0.33.0 (found 0.29.1)"),+ ({"mlx": None}, "mlx>=0.32.0,<0.33.0 (found none)"),+ ({"toml": None}, "toml>=0.10.2,<1 (found none)"),+ ({"platformdirs": "5.0.0"}, "platformdirs>=4,<5 (found 5.0.0)"),+ ],+)+def test_an_incompatible_installed_runtime_falls_back(monkeypatch, versions, needle):+ # An older mflux left behind by a failed upgrade still imports; selection must read the installed versions.+ _host(monkeypatch)+ _device(monkeypatch, "mps")+ _runtime(monkeypatch, versions = versions)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ assert _predict() == _select() == ENGINE_DIFFUSERS+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")++[email protected]("forced", ["diffusers", "sd_cpp"])+def test_forced_engine_overrides_the_opt_in(monkeypatch, forced):+ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", forced)+ assert _predict() != ENGINE_MLX+ assert _select() != ENGINE_MLX+ assert "overrides" in (r.annotate_status({})["mlx_fallback_reason"] or "")+++def test_refusal_falls_through_to_sd_cpp_when_that_is_todays_choice(monkeypatch):+ # A K-quant on a CPU-backend Mac with a runnable sd-cli stays on sd.cpp, exactly as without the opt-in.+ _apple(monkeypatch, backend = "cpu")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: "/usr/bin/sd-cli")+ monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: "v0"))+ gguf = "z-image-turbo-Q4_K_M.gguf"+ assert _predict(gguf = gguf) == _select(gguf = gguf) == ENGINE_SD_CPP+ assert "Q4_K_M" in (r.annotate_status({})["mlx_fallback_reason"] or "")+++def test_a_later_default_selection_clears_the_mlx_reason(monkeypatch):+ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ _select(gguf = "z-image-turbo-Q4_K_M.gguf")+ assert r.annotate_status({})["mlx_fallback_reason"]+ monkeypatch.delenv("UNSLOTH_DIFFUSION_MLX")+ _select()+ assert r.annotate_status({})["mlx_fallback_reason"] is None+++# ── predict == select on the whole matrix ────────────────────────────────────++[email protected]("env", [None, "0", "auto", "1"])[email protected]("backend", ["mps", "cpu", "cuda"])[email protected]("gguf", [_Q4, "z-image-turbo-Q4_K_M.gguf", None])[email protected]("fam", ["z-image", "flux.1"])+def test_predict_matches_selection(monkeypatch, env, backend, gguf, fam):+ _host(monkeypatch)+ _device(monkeypatch, backend)+ _runtime(monkeypatch)+ if env is not None:+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", env)+ predicted = _predict(fam, gguf)+ r._active_engine_name = ENGINE_DIFFUSERS+ assert _select(fam, gguf) == predicted+ expect_mlx = env == "1" and backend != "cuda" and gguf == _Q4 and fam == "z-image"+ assert (predicted == ENGINE_MLX) is expect_mlx+++# ── engine plumbing ──────────────────────────────────────────────────────────+++def test_engine_for_mlx_is_the_mlx_singleton():+ from core.inference import mlx_diffusion_backend as mb++ engine = r.engine_for(ENGINE_MLX)+ assert isinstance(engine, mb.MlxDiffusionBackend)+ assert engine is mb.get_mlx_diffusion_backend()+++def test_cancel_and_retire_scan_the_mlx_singleton(monkeypatch):+ from core.inference import mlx_diffusion_backend as mb++ calls = []+ fake = SimpleNamespace(+ _active_generate_account = "acct",+ cancel_generate = lambda expected_account = None: calls.append(expected_account) or True,+ )+ monkeypatch.setattr(mb, "_mlx_diffusion_backend", fake)+ assert (+ "core.inference.mlx_diffusion_backend",+ "_mlx_diffusion_backend",+ ) in r._ENGINE_SINGLETONS+ assert r.cancel_generation_for_account("acct") is True+ assert calls == ["acct"]+++def test_switching_away_from_mlx_unloads_it(monkeypatch):+ unloaded = []+ monkeypatch.setattr(+ r,+ "get_active_diffusion_engine",+ lambda: SimpleNamespace(status = lambda: {}, unload = lambda: unloaded.append(True)),+ )+ r._active_engine_name = ENGINE_MLX+ _host(monkeypatch)+ _device(monkeypatch, "mps")+ assert _select() == ENGINE_DIFFUSERS+ assert unloaded == [True]+++def test_family_buildable_here_counts_mlx_only_with_a_convertible_gguf(monkeypatch):+ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ fam = detect_family("z-image")+ monkeypatch.setattr(r, "family_pipeline_available", lambda _f: False)+ assert r.family_buildable_here(fam, model_kind = "gguf", gguf_filename = _Q4) is True+ assert r.family_buildable_here(fam, model_kind = "gguf") is False+ monkeypatch.delenv("UNSLOTH_DIFFUSION_MLX")+ assert r.family_buildable_here(fam, model_kind = "gguf", gguf_filename = _Q4) is False+++def test_runtime_requirements_match_the_installer():+ import ast+ from pathlib import Path++ from core.inference.mlx_diffusion_convert import MFLUX_VERSION++ source = (Path(__file__).resolve().parents[2] / "install_python_stack.py").read_text()+ literals = {+ node.targets[0].id if isinstance(node, ast.Assign) else node.target.id: node.value+ for node in ast.parse(source).body+ if isinstance(node, (ast.Assign, ast.AnnAssign))+ and isinstance(node.targets[0] if isinstance(node, ast.Assign) else node.target, ast.Name)+ }+ assert ast.literal_eval(literals["_MLX_DIFFUSION_PINS"]) == (f"mflux=={MFLUX_VERSION}",)+ deps = set(ast.literal_eval(literals["_MLX_DIFFUSION_DEPS"]))+ assert deps == {s for s in r._MLX_RUNTIME_REQUIREMENTS if not s.startswith("mlx")}+++def test_auto_switch_planner_judges_mlx_with_the_picks_gguf(monkeypatch):+ from core.inference import media_locality+ from core.inference.gpu_arbiter import DIFFUSION+ from core.inference.media_model_index import MediaModelPick++ _apple(monkeypatch)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")+ monkeypatch.setattr(r, "engine_for", lambda name: name)+ pick = MediaModelPick("unsloth/Z-Image-Turbo-GGUF", "unsloth/Z-Image-Turbo-GGUF", _Q4, "gguf")+ assert media_locality.planners_for(DIFFUSION, pick) == [ENGINE_MLX]diff --git a/studio/backend/tests/test_liveness_reports_inference_active.py b/studio/backend/tests/test_liveness_reports_inference_active.pyindex 409181aed05..1607d80554c 100644--- a/studio/backend/tests/test_liveness_reports_inference_active.py+++ b/studio/backend/tests/test_liveness_reports_inference_active.py@@ -113,6 +113,7 @@ media_modules = ("core.inference.video","core.inference.diffusion","core.inference.sd_cpp_backend",+ "core.inference.mlx_diffusion_backend","routes.inference",)# routes.inference is imported at startup regardless, so the ML-stack question is onlydiff --git a/studio/backend/tests/test_media_auto_switch.py b/studio/backend/tests/test_media_auto_switch.pyindex 41aeaeed4ce..a3b7df0e901 100644--- a/studio/backend/tests/test_media_auto_switch.py+++ b/studio/backend/tests/test_media_auto_switch.py@@ -966,7 +966,7 @@ def test_the_native_fallback_is_only_verified_when_a_binary_must_be_installed(morouter = __import__("core.inference.diffusion_engine_router", fromlist = ["x"])families = __import__("core.inference.diffusion_families", fromlist = ["x"])monkeypatch.setattr(families, "detect_family_for_pick", lambda *a, **k: object())- monkeypatch.setattr(router, "predict_engine", lambda fam, model_kind = None: ENGINE_SD_CPP)+ monkeypatch.setattr(router, "predict_engine", lambda fam, model_kind = None, **_k: ENGINE_SD_CPP)monkeypatch.setattr(router, "engine_for", lambda name: name)monkeypatch.setattr(router, "native_binary_installed", lambda: True)diff --git a/studio/backend/tests/test_mlx_diffusion_backend.py b/studio/backend/tests/test_mlx_diffusion_backend.pynew file mode 100644index 00000000000..bdfcad51c89--- /dev/null+++ b/studio/backend/tests/test_mlx_diffusion_backend.py@@ -0,0 +1,1406 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Engine-surface tests for the MLX image engine with mlx / mflux stubbed out."""++from __future__ import annotations++import json+import threading+import time+from pathlib import Path++import pytest++from core.inference import mlx_diffusion_backend as mb+from core.inference.diffusion_families import (+ DIFFUSION_CANCELLED_MSG,+ DIFFUSION_NOT_LOADED_MSG,+ _FAMILIES,+ DiffusionModelReplacedError,+ load_identity,+)++ZIMAGE = next(f for f in _FAMILIES if f.name == "z-image")++REPO = "unsloth/Z-Image-Turbo-GGUF"+GGUF = "z-image-turbo-Q4_0.gguf"+_REAL_RESOLVE_VARIANT_BASE = getattr(mb, "resolve_variant_base", None)+BASE = "Tongyi-MAI/Z-Image-Turbo"+++class FakeRuntime:+ def __init__(self):+ self.builds = []+ self.generates = []+ self.freed = 0+ self.step_gate: threading.Event | None = None+ self.in_step = threading.Event()++ def build(self, model_path, *, model_config, precision, te_bits):+ self.builds.append(+ dict(+ model_path = model_path,+ model_config = model_config,+ precision = precision,+ te_bits = te_bits,+ )+ )+ return {"model": model_config}++ def cache_text_encodings(self, model):+ model["cached"] = True++ def supports_guidance(self, model):+ return model["model"] == "z-image"++ def generate(+ self, model, *, prompt, negative_prompt, seed, steps, width, height, guidance, on_step+ ):+ from PIL import Image++ self.generates.append(+ dict(+ prompt = prompt, seed = seed, steps = steps, width = width, height = height, guidance = guidance+ )+ )+ for t in range(steps):+ if self.step_gate is not None:+ self.in_step.set()+ self.step_gate.wait(5)+ on_step(t + 1)+ return Image.new("RGB", (width, height), (seed % 255, 0, 0))++ def free(self):+ self.freed += 1+++def env(monkeypatch, tmp_path):+ """A backend whose fetch / convert / runtime are fakes; returns (backend, runtime, calls)."""+ gguf_path = tmp_path / "hub" / "snapshots" / "abc123" / GGUF+ gguf_path.parent.mkdir(parents = True)+ gguf_path.write_bytes(b"GGUF" + b"\0" * 64)+ base_dir = tmp_path / "base"+ for sub in ("text_encoder", "tokenizer", "vae"):+ (base_dir / sub).mkdir(parents = True)+ calls = {"convert": 0, "fetch_gguf": [], "fetch_base": []}++ def _fetch_gguf(repo_id, gguf_filename, hf_token, *, cancel_event, local_files_only):+ calls["fetch_gguf"].append((repo_id, gguf_filename, local_files_only))+ return str(gguf_path)++ def _fetch_base(+ base_repo,+ hf_token,+ *,+ local_files_only,+ cancel_event = None,+ ):+ calls["fetch_base"].append((base_repo, local_files_only))+ return str(base_dir)++ def _convert(+ gguf,+ out_dir,+ *,+ dense_bits,+ cancel_event = None,+ progress = None,+ **_,+ ):+ calls["convert"] += 1+ calls["dense_bits"] = dense_bits+ out = Path(out_dir) / "transformer"+ out.mkdir(parents = True, exist_ok = True)+ (out / "0.safetensors").write_bytes(b"x" * 8)+ (out / "unsloth_mlx_convert.json").write_text(+ json.dumps({"source": {"size": Path(gguf).stat().st_size}, "bytes": 8})+ )+ if progress:+ progress(1, 1)+ return {"n_out_tensors": 1}++ monkeypatch.setattr(mb, "fetch_gguf", _fetch_gguf)+ monkeypatch.setattr(mb, "fetch_base_snapshot", _fetch_base)+ # No card lookup in unit tests: the family default stands unless a test says otherwise.+ monkeypatch.setattr(+ mb, "resolve_variant_base", lambda *a, fallback, **k: fallback, raising = False+ )+ monkeypatch.setattr(mb.convert, "convert_gguf_to_mflux", _convert)+ monkeypatch.setattr(+ mb.convert,+ "conversion_complete",+ lambda d, **_k: (Path(d) / "transformer" / "0.safetensors").exists(),+ )+ monkeypatch.setattr(+ mb.convert,+ "cache_dir_for",+ lambda repo, rev, fn, *, dense_bits, **_: tmp_path / "cache" / f"{rev}-{fn}-d{dense_bits}",+ )+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_PRECISION", "fp16")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_TE_BITS", "4")+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", "4")+ runtime = FakeRuntime()+ backend = mb.MlxDiffusionBackend(runtime_factory = lambda: runtime)+ return backend, runtime, calls+++def _wait_loaded(backend, timeout = 10.0):+ deadline = time.time() + timeout+ while time.time() < deadline:+ progress = backend.load_progress()+ if progress["phase"] in ("ready", "error"):+ return progress+ time.sleep(0.01)+ raise AssertionError(f"load did not finish: {backend.load_progress()}")+++def _load(backend, **kw):+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf", **kw)+ return _wait_loaded(backend)+++def test_surface_matches_the_other_engines():+ from core.inference.sd_cpp_backend import SdCppDiffusionBackend++ shared = {+ "begin_load",+ "generate",+ "cancel_generate",+ "unload",+ "status",+ "load_progress",+ "generate_progress",+ "loading_repo_ids",+ "loaded_repo_ids",+ "download_plan",+ "preflight_base_access",+ "is_loaded",+ }+ for name in shared:+ assert hasattr(SdCppDiffusionBackend, name)+ assert hasattr(mb.MlxDiffusionBackend, name), name+ import inspect++ sd_params = set(inspect.signature(SdCppDiffusionBackend.begin_load).parameters)+ mlx_params = inspect.signature(mb.MlxDiffusionBackend.begin_load).parameters+ # Every keyword the route passes to sd.cpp is accepted, and the route's extra component kwargs land in **_ignored.+ assert sd_params <= set(mlx_params)+ assert any(p.kind is p.VAR_KEYWORD for p in mlx_params.values())+ assert set(inspect.signature(SdCppDiffusionBackend.generate).parameters) <= set(+ inspect.signature(mb.MlxDiffusionBackend.generate).parameters+ )+++def test_load_then_status_and_guards(env):+ backend, runtime, calls = env+ assert backend.status()["loaded"] is False+ assert backend.status()["engine"] == "mlx"+ assert _load(backend)["phase"] == "ready"+ status = backend.status()+ assert status["loaded"] and status["engine"] == "mlx"+ assert (+ status["repo_id"] == REPO and status["base_repo"] == BASE and status["family"] == "z-image"+ )+ assert status["gguf_filename"] == GGUF and status["model_kind"] == "gguf"+ assert status["workflows"] == ["txt2img"]+ assert status["mlx"]["precision"] == "float16" and status["mlx"]["text_encoder_bits"] == 4+ assert runtime.builds[0]["model_config"] == "z-image-turbo"+ model_dir = Path(runtime.builds[0]["model_path"])+ for sub in ("text_encoder", "tokenizer", "vae"):+ assert (model_dir / sub).is_symlink()+ assert backend.loaded_repo_ids() == (REPO, BASE)+ assert backend.loading_repo_ids() == ()+ assert calls["dense_bits"] == 4+++def test_conversion_is_cached_across_loads(env):+ backend, runtime, calls = env+ _load(backend)+ backend.unload()+ _load(backend)+ assert calls["convert"] == 1+ assert backend.status()["mlx"]["timings"]["convert_cached"] is True+++def test_local_files_only_reaches_every_fetch(env):+ backend, _rt, calls = env+ _load(backend, local_files_only = True)+ assert calls["fetch_gguf"][-1][2] is True+ assert calls["fetch_base"][-1] == (BASE, True)+++ "kwargs, needle",+ [+ ({"gguf_filename": None}, "gguf_filename is required"),+ ({"gguf_filename": "z-image-turbo-Q4_K_M.gguf"}, "Q4_K_M"),+ ({"gguf_filename": GGUF, "model_kind": "pipeline"}, "GGUF"),+ ({"gguf_filename": "sdxl-Q4_0.gguf", "family_override": "sdxl"}, "no MLX implementation"),+ ({"gguf_filename": GGUF, "loras": [("a/b", 1.0)]}, "LoRA"),+ ],+)+def test_begin_load_refuses_what_it_cannot_run(env, kwargs, needle):+ backend, _rt, _calls = env+ repo = "unsloth/SDXL-GGUF" if "sdxl" in str(kwargs.get("gguf_filename")) else REPO+ with pytest.raises(ValueError, match = needle):+ backend.begin_load(repo, **kwargs)+ assert backend.loading_repo_ids() == ()+++def test_load_failure_surfaces_in_load_progress(env, monkeypatch):+ backend, _rt, _calls = env++ def _boom(*_a, **_k):+ raise RuntimeError("converter exploded")++ monkeypatch.setattr(mb.convert, "convert_gguf_to_mflux", _boom)+ progress = _load(backend)+ assert progress["phase"] == "error" and "converter exploded" in progress["error"]+ assert backend.status()["loaded"] is False+++def test_generate_batch_seeds_and_progress(env):+ backend, runtime, _calls = env+ _load(backend)+ seen = []+ runtime_generate = runtime.generate++ def _spy(*a, **k):+ inner = k["on_step"]++ def _on_step(n):+ inner(n)+ seen.append(backend.generate_progress())++ k["on_step"] = _on_step+ return runtime_generate(*a, **k)++ runtime.generate = _spy+ result = backend.generate(prompt = "a fox", width = 280, height = 270, steps = 3, seed = 7, batch_size = 2)+ assert result["seeds"] == [7, 8] and result["seed"] == 7+ assert len(result["images"]) == 2+ assert result["images"][0].size == (272, 256) # rounded down to multiples of 16+ assert (+ result["model_kind"] == "gguf"+ and result["gguf_filename"] == GGUF+ and result["workflow"] == "txt2img"+ )+ assert [p["step"] for p in seen] == [1, 2, 3, 4, 5, 6]+ assert all(p["active"] and p["total_steps"] == 6 for p in seen)+ assert backend.generate_progress()["active"] is False+ # Turbo has no CFG, so guidance is not forwarded and the negative prompt is not recorded.+ assert runtime.generates[0]["guidance"] is None+ assert backend.last_timings["images"][0]["s_per_step"] >= 0+ assert mb.generation_in_flight() is False+++ "kwargs",+ [+ {"init_image": "data:"},+ {"mask_image": "data:"},+ {"reference_images": ["data:"]},+ {"workflow": "edit"},+ {"upscale": 2.0},+ {"prompts": ["a", "b"]},+ {"seeds": [1, 2]},+ {"loras": [("x/y", 1.0)]},+ {"controlnet": ("c", "img", "canny", 1.0, 0.0, 1.0)},+ ],+)+def test_generate_refuses_unsupported_workflows(env, kwargs):+ backend, _rt, _calls = env+ _load(backend)+ with pytest.raises(ValueError):+ backend.generate(prompt = "x", steps = 1, **kwargs)+++def test_generate_without_a_model_and_with_a_replaced_model(env):+ backend, _rt, _calls = env+ with pytest.raises(RuntimeError, match = DIFFUSION_NOT_LOADED_MSG):+ backend.generate(prompt = "x", steps = 1)+ _load(backend)+ stale = load_identity("someone/else", BASE, "z-image")+ with pytest.raises(DiffusionModelReplacedError):+ backend.generate(prompt = "x", steps = 1, expected_load = stale)+ ok = load_identity(REPO, BASE, "z-image")+ assert backend.generate(prompt = "x", steps = 1, seed = 1, width = 256, height = 256, expected_load = ok)[+ "images"+ ]+++def test_cancel_stops_at_the_next_step(env):+ backend, runtime, _calls = env+ _load(backend)+ assert backend.cancel_generate() is False+ runtime.step_gate = threading.Event()+ errors = []++ def _run():+ try:+ backend.generate(prompt = "x", steps = 4, seed = 1, width = 256, height = 256)+ except RuntimeError as exc:+ errors.append(str(exc))++ worker = threading.Thread(target = _run)+ worker.start()+ assert runtime.in_step.wait(5)+ assert mb.generation_in_flight() is False # the module singleton is not this instance+ assert backend.generate_progress()["active"] is True+ assert backend.cancel_generate() is True+ runtime.step_gate.set()+ worker.join(5)+ assert errors == [DIFFUSION_CANCELLED_MSG]+ assert backend.generate_progress()["active"] is False+ assert backend.cancel_generate() is False+++def test_unload_frees_and_cancels(env):+ backend, runtime, _calls = env+ _load(backend)+ status = backend.unload()+ assert status["loaded"] is False and status["engine"] == "mlx"+ assert runtime.freed == 1+ assert backend.loaded_repo_ids() == ()+ with pytest.raises(RuntimeError, match = DIFFUSION_NOT_LOADED_MSG):+ backend.generate(prompt = "x", steps = 1)+++def test_unload_during_load_waits_for_the_build_and_discards_it(env, monkeypatch):+ # A build cannot be interrupted, and the router treats unload()'s return as "memory is free"+ # before it activates another engine, so unload must wait for the superseded worker.+ backend, runtime, _calls = env+ gate = threading.Event()+ started = threading.Event()+ real_build = runtime.build++ def _slow_build(*a, **k):+ started.set()+ gate.wait(10)+ return real_build(*a, **k)++ runtime.build = _slow_build+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert started.wait(5)+ assert backend.loading_repo_ids() == (REPO, BASE, "unsloth/Z-Image-Turbo")+ with pytest.raises(RuntimeError, match = "already in progress"):+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ done = threading.Event()+ unloader = threading.Thread(target = lambda: (backend.unload(), done.set()))+ unloader.start()+ assert not done.wait(0.5), "unload() returned while the superseded build was still running"+ freed_before = runtime.freed+ gate.set()+ assert done.wait(5)+ unloader.join(5)+ assert runtime.freed == freed_before + 1 # the superseded worker freed what it built+ assert backend.status()["loaded"] is False+ assert backend.load_progress()["phase"] is None+++def test_a_load_racing_unload_waits_until_the_superseded_build_is_gone(env):+ backend, runtime, _calls = env+ gate = threading.Event()+ started = threading.Event()+ real_build = runtime.build++ def _slow_build(*a, **k):+ started.set()+ gate.wait(10)+ return real_build(*a, **k)++ runtime.build = _slow_build+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert started.wait(5)+ unloader = threading.Thread(target = backend.unload)+ unloader.start()+ deadline = time.time() + 5+ while backend.loading_repo_ids() and time.time() < deadline:+ time.sleep(0.01)+ try:+ with pytest.raises(RuntimeError, match = "unload is in progress"):+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert len(runtime.builds) == 0+ finally:+ gate.set()+ unloader.join(5)+ assert len(runtime.builds) == 1 # the superseded build, discarded+ runtime.build = real_build+ assert _load(backend)["phase"] == "ready"+ assert len(runtime.builds) == 2+++def test_a_cache_only_load_resolves_the_variant_without_the_hub(env, monkeypatch):+ import core.inference.diffusion as diffusion+ import hub.utils.companion_assets as companion++ backend, runtime, calls = env+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)++ def _no_hub(*_a, **_k):+ raise AssertionError("a cache-only load read the model card")++ monkeypatch.setattr(diffusion, "_hf_base_model", _no_hub)+ links = {REPO.lower(): ["Tongyi-MAI/Z-Image-Turbo", "Tongyi-MAI/Z-Image", "Qwen/Qwen3-4B"]}+ monkeypatch.setattr(companion, "read_companion_links", lambda: links)+ _load(backend, local_files_only = True)+ assert calls["fetch_base"][-1] == ("Tongyi-MAI/Z-Image", True)+ assert runtime.builds[-1]["model_config"] == "z-image"+ backend.unload()+ links.clear()+ _load(backend, local_files_only = True)+ assert calls["fetch_base"][-1] == (BASE, True)+++def test_a_cache_only_undistilled_pick_with_no_record_builds_the_base_config(env, monkeypatch):+ import hub.utils.companion_assets as companion++ backend, runtime, calls = env+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)+ monkeypatch.setattr(companion, "read_companion_links", lambda: {})+ backend.begin_load(+ "unsloth/Z-Image-GGUF",+ gguf_filename = "z-image-Q4_0.gguf",+ model_kind = "gguf",+ local_files_only = True,+ )+ assert _wait_loaded(backend)["phase"] == "ready"+ assert calls["fetch_base"][-1] == ("Tongyi-MAI/Z-Image", True)+ assert runtime.builds[-1]["model_config"] == "z-image"+++ "repo_id, gguf_filename, expected",+ [+ ("unsloth/Z-Image-GGUF", "z-image-Q4_K_M.gguf", "Tongyi-MAI/Z-Image"),+ ("unsloth/Z-Image-GGUF", "z-image-BF16.gguf", "Tongyi-MAI/Z-Image"),+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", BASE),+ ("unsloth/Z-Image-GGUF", "z-image-turbo-Q4_0.gguf", BASE),+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-Q4_0.gguf", BASE),+ ("leejet/Z-Image-Turbo-GGUF", "z_image_turbo-Q4_K.gguf", BASE),+ ("someone/my-gguf-models", "model-Q4_K_M.gguf", BASE),+ ("someone/Z-Image-GGUF", "model-Q4_K_M.gguf", "Tongyi-MAI/Z-Image"),+ ("someone/z-image-turbo", "model-Q4_K_M.gguf", BASE),+ ],+)+def test_the_name_resolves_the_z_image_variant_offline(+ monkeypatch, repo_id, gguf_filename, expected+):+ import hub.utils.companion_assets as companion++ fam = ZIMAGE+ monkeypatch.setattr(companion, "read_companion_links", lambda: {})+ assert mb._cached_variant_base(repo_id, fam, gguf_filename, BASE) == expected+ assert mb.mlx_model_config_for(fam, expected) == (+ "z-image" if expected != BASE else "z-image-turbo"+ )+++def test_a_recorded_default_does_not_overrule_an_undistilled_name(monkeypatch):+ import hub.utils.companion_assets as companion++ fam = ZIMAGE+ links = {"unsloth/z-image-gguf": [BASE]}+ monkeypatch.setattr(companion, "read_companion_links", lambda: links)+ assert mb._cached_variant_base("unsloth/Z-Image-GGUF", fam, "z-image-Q4_K_M.gguf", BASE) == (+ "Tongyi-MAI/Z-Image"+ )+ links["unsloth/z-image-turbo-gguf"] = ["Tongyi-MAI/Z-Image"]+ assert (+ mb._cached_variant_base("unsloth/Z-Image-Turbo-GGUF", fam, "z-image-turbo-Q4_0.gguf", BASE)+ == "Tongyi-MAI/Z-Image"+ )+++def test_a_local_undistilled_gguf_resolves_without_the_hub(tmp_path, monkeypatch):+ import core.inference.diffusion as diffusion++ fam = ZIMAGE+ monkeypatch.setattr(diffusion, "_remember_companion_base", lambda *a: None)+ (tmp_path / "z-image-Q4_K_M.gguf").write_bytes(b"x")+ (tmp_path / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"x")+ resolve = _REAL_RESOLVE_VARIANT_BASE+ assert resolve(str(tmp_path), fam, None, "z-image-Q4_K_M.gguf", fallback = BASE) == (+ "Tongyi-MAI/Z-Image"+ )+ assert resolve(str(tmp_path), fam, None, "z-image-turbo-Q4_K_M.gguf", fallback = BASE) == BASE+++def test_policy_helpers(monkeypatch):+ for name in (+ "UNSLOTH_DIFFUSION_MLX_TE_BITS",+ "UNSLOTH_DIFFUSION_MLX_DENSE_BITS",+ "UNSLOTH_DIFFUSION_MLX_PRECISION",+ ):+ monkeypatch.delenv(name, raising = False)+ gib = 1024**3+ assert mb.text_encoder_bits(8 * gib) == 4 and mb.text_encoder_bits(16 * gib) == 4+ assert mb.text_encoder_bits(32 * gib) == 8+ assert mb.dense_bits(7 * gib) == 4 and mb.dense_bits(64 * gib) == 0+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_TE_BITS", "16")+ assert mb.text_encoder_bits(8 * gib) is None+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", "3") # not allowed: ignored+ assert mb.dense_bits(64 * gib) == 0+ assert mb.compute_precision_name("Apple M1 (Virtual)") == "float16"+ assert mb.compute_precision_name("Apple M2 Max") == "float16"+ assert mb.compute_precision_name("Apple M3 Pro") == "bfloat16"+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_PRECISION", "bf16")+ assert mb.compute_precision_name("Apple M1") == "bfloat16"+++def test_importing_the_engine_does_not_import_mlx():+ import subprocess+ import sys++ code = (+ "import sys; import core.inference.mlx_diffusion_backend as m; "+ "print(any(k == 'mlx' or k.startswith(('mlx.', 'mflux')) for k in sys.modules))"+ )+ backend_root = Path(__file__).resolve().parent.parent+ out = subprocess.run(+ [sys.executable, "-c", code], cwd = backend_root, capture_output = True, text = True, timeout = 300+ )+ assert out.returncode == 0, out.stderr[-2000:]+ assert out.stdout.strip().splitlines()[-1] == "False"+++def test_a_replacing_load_frees_the_old_model_first(env):+ backend, runtime, _calls = env+ _load(backend)+ freed_before = runtime.freed+ seen = []+ real_build = runtime.build++ def _build(*a, **k):+ seen.append(backend.status()["loaded"])+ return real_build(*a, **k)++ runtime.build = _build+ _load(backend)+ assert seen == [False]+ assert runtime.freed == freed_before + 1+ assert backend.status()["loaded"] is True+++def test_a_cancelled_run_releases_its_frames():+ # A cancel unwinds through the model's own frames; clearing them is what lets unload() free the model.+ import gc+ import weakref++ class Model:+ pass++ def _inner(model):+ raise mb.MlxCancelled("stop")++ model = Model()+ ref = weakref.ref(model)+ try:+ _inner(model)+ except mb.MlxCancelled as exc:+ kept = exc+ mb.drop_exception_frames(exc)+ del model+ gc.collect()+ assert ref() is None+ assert kept.__traceback__ is None+++def test_a_cached_exception_below_the_load_does_not_pin_the_model(env, monkeypatch):+ # The Hub helpers memoize import failures, and a memoized traceback keeps every frame up the+ # stack, the load worker's included. The worker must not leave the model in its locals.+ import gc+ import weakref++ backend, runtime, _calls = env+ cache = {}+ real_fetch = mb.fetch_gguf++ def _fetch(*a, **k):+ try:+ raise ModuleNotFoundError("No module named 'unsloth_zoo'")+ except ModuleNotFoundError as exc:+ cache["error"] = exc # what hf_xet_fallback._load_shared does+ return real_fetch(*a, **k)++ class Model(dict):+ pass++ monkeypatch.setattr(mb, "fetch_gguf", _fetch)+ real_build = runtime.build+ runtime.build = lambda *a, **k: Model(real_build(*a, **k))+ _load(backend)+ ref = weakref.ref(backend._state.model)+ backend.unload()+ gc.collect()+ assert "error" in cache+ assert ref() is None+++def test_generate_rejects_sizes_beyond_the_family_limits(env):+ backend, runtime, _calls = env+ _load(backend)+ with pytest.raises(ValueError):+ backend.generate(prompt = "x", steps = 1, width = 4096, height = 4096)+ assert runtime.generates == []+++def test_a_failed_generation_does_not_pin_the_model(env):+ # Any error raised inside the render holds the model in its frames; a caller or logger that+ # keeps the exception must not keep the model alive past unload().+ import gc+ import weakref++ backend, runtime, _calls = env++ class Model(dict):+ pass++ real_build = runtime.build+ runtime.build = lambda *a, **k: Model(real_build(*a, **k))++ def _boom(model, **_k):+ raise RuntimeError("metal failure")++ runtime.generate = _boom+ _load(backend)+ ref = weakref.ref(backend._state.model)+ with pytest.raises(RuntimeError, match = "metal failure") as info:+ backend.generate(prompt = "x", steps = 1, width = 256, height = 256)+ kept = info.value # what an error handler or log record would hold+ backend.unload()+ gc.collect()+ assert ref() is None+ assert kept.__traceback__ is not None # the traceback text survives for the log+++def test_generated_images_record_the_mlx_build(env):+ backend, _rt, _calls = env+ _load(backend)+ result = backend.generate(prompt = "x", steps = 1, width = 256, height = 256, seed = 1)+ assert result["text_encoder_quant"] == "mlx_int4"+ assert result["transformer_quant"] == "mlx_int4_dense"+++def test_an_undistilled_base_tag_selects_the_base_config_and_companions(env, monkeypatch):+ # No explicit base_repo, as for a normal Hub pick: the repo's base_model card tag decides.+ import core.inference.diffusion as diffusion++ backend, runtime, calls = env+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)+ monkeypatch.setattr(diffusion, "_hf_base_model", lambda repo_id, token: "Tongyi-MAI/Z-Image")+ _load(backend)+ assert calls["fetch_base"][-1][0] == "Tongyi-MAI/Z-Image"+ assert runtime.builds[-1]["model_config"] == "z-image"+ assert backend.status()["base_repo"] == "Tongyi-MAI/Z-Image"+++ "card_tag, expected_base, expected_config",+ [+ (None, "Tongyi-MAI/Z-Image", "z-image"),+ ("Tongyi-MAI/Z-Image-Turbo", BASE, "z-image-turbo"),+ ],+)+def test_an_online_undistilled_pick_without_a_card_tag_keeps_the_named_variant(+ env, monkeypatch, card_tag, expected_base, expected_config+):+ # A failed card read returns no tag: the name still decides, a real tag still wins.+ import core.inference.diffusion as diffusion++ backend, runtime, calls = env+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)+ monkeypatch.setattr(diffusion, "_hf_base_model", lambda repo_id, token: card_tag)+ monkeypatch.setattr(diffusion, "_remember_companion_base", lambda *a: None)+ backend.begin_load("unsloth/Z-Image-GGUF", gguf_filename = "z-image-Q4_0.gguf", model_kind = "gguf")+ assert _wait_loaded(backend)["phase"] == "ready"+ assert calls["fetch_base"][-1] == (expected_base, False)+ assert runtime.builds[-1]["model_config"] == expected_config+++def test_a_resolver_error_keeps_the_named_variant(monkeypatch):+ import core.inference.diffusion as diffusion++ def _boom(*_a, **_k):+ raise RuntimeError("hub down")++ monkeypatch.setattr(diffusion, "_hf_base_model", _boom)+ out = mb.resolve_variant_base(+ "unsloth/Z-Image-GGUF", ZIMAGE, None, "z-image-Q4_0.gguf", fallback = BASE+ )+ assert out == "Tongyi-MAI/Z-Image"+++ "folder, expected", [("Z-Image", "z-image"), ("Z-Image-Turbo", "z-image-turbo")]+)+def test_an_explicit_local_base_selects_the_config_its_name_spells(env, tmp_path, folder, expected):+ backend, runtime, calls = env+ local_base = tmp_path / "models" / folder+ local_base.mkdir(parents = True)+ _load(backend, base_repo = str(local_base))+ assert calls["fetch_base"][-1][0] == str(local_base)+ assert runtime.builds[-1]["model_config"] == expected+ assert backend.status()["base_repo"] == str(local_base)+++def test_base_fetch_is_cancellable_between_files(monkeypatch):+ import huggingface_hub+ import utils.hf_xet_fallback as xet++ files = [+ "text_encoder/a.safetensors",+ "text_encoder/b.safetensors",+ "vae/c.safetensors",+ "README.md",+ ]+ info = type(+ "Info", (), {"sha": "abc", "siblings": [type("S", (), {"rfilename": f}) for f in files]}+ )+ monkeypatch.setattr(huggingface_hub.HfApi, "model_info", lambda self, *a, **k: info)+ cancel = threading.Event()+ fetched = []++ def _download(+ repo,+ filename,+ token,+ *,+ cancel_event = None,+ **_k,+ ):+ assert cancel_event is cancel+ fetched.append(filename)+ cancel.set() # an unload lands during the first file+ return f"/hub/models--x/snapshots/abc/{filename}"++ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)+ with pytest.raises(mb.MlxCancelled):+ mb.fetch_base_snapshot(+ "Tongyi-MAI/Z-Image-Turbo", None, local_files_only = False, cancel_event = cancel+ )+ assert fetched == ["text_encoder/a.safetensors"]+ cancel.clear()+ fetched.clear()+ monkeypatch.setattr(+ xet,+ "hf_hub_download_with_xet_fallback",+ lambda repo, fn, tok, **k: fetched.append(fn) or f"/hub/snapshots/abc/{fn}",+ )+ out = mb.fetch_base_snapshot(+ "Tongyi-MAI/Z-Image-Turbo", None, local_files_only = False, cancel_event = cancel+ )+ assert out == "/hub/snapshots/abc"+ assert fetched == files[:3] # README is outside the allow patterns++[email protected]("predicted", ["mlx", None])+def test_the_load_route_takes_the_gpu_arbiter_for_mlx_on_a_cpu_torch_host(monkeypatch, predicted):+ # torch can resolve "cpu" on an Apple-Silicon Mac, but MLX still drives the Apple GPU: the route+ # must evict / own the GPU through the arbiter instead of releasing it. Also when the prediction+ # failed and only the activation says MLX.+ import asyncio+ import types+ from unittest.mock import create_autospec++ import core.inference.diffusion_device as device_module+ import core.inference.diffusion_engine_router as router_module+ import core.inference.gpu_arbiter as arbiter+ from models.inference import DiffusionLoadRequest+ from routes.inference import load_diffusion_model_gated++ engine = create_autospec(mb.MlxDiffusionBackend, instance = True)+ engine.begin_load.return_value = {"loaded": False, "repo_id": None}+ engine.preflight_base_access.return_value = None++ def _predict(*a, **k):+ if predicted is None:+ raise RuntimeError("probe failed")+ return predicted++ monkeypatch.setattr(router_module, "predict_engine", _predict)+ monkeypatch.setattr(router_module, "active_engine_name", lambda: "mlx")+ monkeypatch.setattr(router_module, "engine_for", lambda name: engine)+ monkeypatch.setattr(router_module, "select_and_activate_engine", lambda *a, **k: engine)+ monkeypatch.setattr(router_module, "begin_load_on", lambda _engine, start: start())+ monkeypatch.setattr(router_module, "annotate_status", lambda status: status)+ monkeypatch.setattr(+ device_module,+ "resolve_diffusion_device_target",+ lambda: types.SimpleNamespace(device = "cpu"),+ )+ monkeypatch.setattr("routes.inference._guard_diffusion_load_against_training", lambda: None)++ async def _no_ordinal(_gpu_ids):+ return None++ monkeypatch.setattr("routes.inference._selected_gpu_ordinal", _no_ordinal)+ calls = []+ monkeypatch.setattr(+ arbiter, "acquire_for_request", lambda owner, fn: calls.append("acquire") or fn()+ )+ monkeypatch.setattr(arbiter, "release", lambda owner: calls.append("release"))+ asyncio.run(+ load_diffusion_model_gated(+ DiffusionLoadRequest(model_path = REPO, gguf_filename = GGUF),+ "test-user",+ user_initiated = False,+ )+ )+ engine.begin_load.assert_called_once()+ assert calls == ["acquire"]+++def test_the_anonymous_token_sentinel_reaches_every_fetch(env, monkeypatch):+ backend, _rt, _calls = env+ seen = []+ real_fetch_gguf, real_fetch_base = mb.fetch_gguf, mb.fetch_base_snapshot+ monkeypatch.setattr(+ mb,+ "fetch_gguf",+ lambda r, f, tok, **k: (seen.append(tok), real_fetch_gguf(r, f, tok, **k))[1],+ )+ monkeypatch.setattr(+ mb,+ "fetch_base_snapshot",+ lambda b, tok, **k: (seen.append(tok), real_fetch_base(b, tok, **k))[1],+ )+ monkeypatch.setattr(+ mb,+ "resolve_variant_base",+ lambda r, f, tok, *a, fallback, **k: (seen.append(tok), fallback)[1],+ )+ assert _load(backend, hf_token = False)["phase"] == "ready"+ assert seen == [False, False, False]+ seen.clear()+ backend.unload()+ assert _load(backend, hf_token = " hf_x ")["phase"] == "ready"+ assert seen == ["hf_x", "hf_x", "hf_x"]+ seen.clear()+ backend.unload()+ assert _load(backend, hf_token = " ")["phase"] == "ready"+ assert seen == [None, None, None]+++def test_unload_racing_begin_load_never_joins_an_unstarted_worker(env, monkeypatch):+ backend, _rt, _calls = env+ started = []+ real_thread = mb.account_thread++ def _thread(**kw):+ worker = real_thread(**kw)+ real_start = worker.start++ def _start():+ # Publication and start share one critical section, so unload() never sees an unstarted worker.+ held = not backend._lock.acquire(blocking = False)+ if not held:+ backend._lock.release()+ assert held+ started.append(worker)+ real_start()++ worker.start = _start+ return worker++ monkeypatch.setattr(mb, "account_thread", _thread)+ _load(backend)+ assert len(started) == 1+++def test_a_load_cancelled_while_waiting_on_generation_skips_the_build(env):+ backend, runtime, _calls = env+ _load(backend)+ runtime.step_gate = threading.Event()+ errors = []+ gen = threading.Thread(+ target = lambda: _swallow(errors, lambda: backend.generate(prompt = "x", steps = 1))+ )+ gen.start()+ assert runtime.in_step.wait(5)+ builds_before = len(runtime.builds)+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ deadline = time.time() + 5+ while backend._state is not None and time.time() < deadline:+ time.sleep(0.01)+ backend._cancel_event.set()+ runtime.step_gate.set()+ gen.join(5)+ backend._load_thread.join(5)+ assert len(runtime.builds) == builds_before+ assert backend.status()["loaded"] is False+++def _swallow(errors, fn):+ try:+ fn()+ except Exception as exc: # noqa: BLE001+ errors.append(exc)++[email protected]("stage", ["build", "cache_text_encodings"])+def test_a_failed_build_frees_the_runtime(env, stage):+ backend, runtime, _calls = env++ def _boom(*_a, **_k):+ raise MemoryError("[metal::malloc] out of memory")++ setattr(runtime, stage, _boom)+ progress = _load(backend)+ assert progress["phase"] == "error" and "out of memory" in progress["error"]+ assert runtime.freed == 1+ assert backend.status()["loaded"] is False+++def test_status_reports_the_engaged_mlx_quantization(env):+ backend, _rt, _calls = env+ _load(backend)+ status = backend.status()+ assert status["text_encoder_quant"] == "mlx_int4"+ assert status["transformer_quant"] == "mlx_int4_dense"+++def test_derived_batch_seeds_stay_json_safe(env):+ backend, runtime, _calls = env+ _load(backend)+ result = backend.generate(+ prompt = "x", steps = 1, width = 256, height = 256, seed = 2**53 - 1, batch_size = 2+ )+ assert result["seeds"] == [2**53 - 1, 0]+ assert [g["seed"] for g in runtime.generates] == [2**53 - 1, 0]+++def test_a_failed_replacement_hands_the_resident_model_back_to_its_owner(env, monkeypatch):+ import core.inference.gpu_arbiter as arbiter+ import hub.services.models.account_access as account_access++ backend, _rt, _calls = env+ restored = []+ monkeypatch.setattr(+ arbiter, "restore_owner_account", lambda owner, *a, **k: restored.append(owner)+ )+ monkeypatch.setattr(+ account_access, "restore_resident_metadata", lambda kind: restored.append(kind)+ )+ real_fetch_gguf = mb.fetch_gguf+ failing = [True]++ def _fetch(*a, **k):+ if failing[0]:+ raise OSError("fetch failed")+ return real_fetch_gguf(*a, **k)++ monkeypatch.setattr(mb, "fetch_gguf", _fetch)+ assert _load(backend)["phase"] == "error"+ assert restored == [] # nothing resident to hand back+ failing[0] = False+ assert _load(backend)["phase"] == "ready"+ failing[0] = True+ assert _load(backend)["phase"] == "error"+ assert backend.is_loaded+ assert restored == [arbiter.DIFFUSION, "diffusion"]+++def _hub_listing(monkeypatch, files):+ import huggingface_hub++ listed = []+ info = type(+ "Info", (), {"sha": "abc", "siblings": [type("S", (), {"rfilename": f}) for f in files]}+ )+ monkeypatch.setattr(+ huggingface_hub.HfApi,+ "model_info",+ lambda self, repo, *a, **k: listed.append(repo) or info,+ )+ return listed+++def test_base_companions_come_from_the_repo_the_plan_staged(monkeypatch):+ import utils.hf_xet_fallback as xet++ files = ["text_encoder/a.safetensors", "vae/c.safetensors"]+ listed = _hub_listing(monkeypatch, files)+ judged = []+ monkeypatch.setattr(+ mb,+ "prefer_ungated_mirror",+ lambda base, tok = None, *, files = None: judged.append(files) or "unsloth/Z-Image-Turbo",+ raising = False,+ )+ fetched = []+ monkeypatch.setattr(+ xet,+ "hf_hub_download_with_xet_fallback",+ lambda repo, fn, tok, **k: fetched.append((repo, fn, k.get("revision")))+ or f"/hub/snapshots/abc/{fn}",+ )+ mb.fetch_base_snapshot(BASE, None, local_files_only = False)+ assert judged == [files]+ assert listed == [BASE, "unsloth/Z-Image-Turbo"]+ assert fetched == [("unsloth/Z-Image-Turbo", f, "abc") for f in files]+++def _companion_snapshot(root, complete = True, tokenizer_config = True):+ root.mkdir(parents = True, exist_ok = True)+ for sub in ("text_encoder", "tokenizer", "vae"):+ (root / sub).mkdir(exist_ok = True)+ (root / "tokenizer" / "tokenizer.json").write_text("{}")+ if tokenizer_config:+ (root / "tokenizer" / "tokenizer_config.json").write_text("{}")+ (root / "vae" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")+ shards = ["model-00001-of-00002.safetensors", "model-00002-of-00002.safetensors"]+ (root / "text_encoder" / "model.safetensors.index.json").write_text(+ json.dumps({"weight_map": {"a": shards[0], "b": shards[1]}})+ )+ for shard in shards if complete else shards[:1]:+ (root / "text_encoder" / shard).write_bytes(b"x")+ return str(root)+++def test_cache_only_companions_read_the_mirror_and_the_live_cache_root(monkeypatch, tmp_path):+ import huggingface_hub+ from huggingface_hub.errors import LocalEntryNotFoundError++ import utils.hf_cache_settings as cache_settings++ live = str(tmp_path / "live")+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)+ monkeypatch.setattr(+ mb,+ "prefer_ungated_mirror",+ lambda base, tok = None, **k: "unsloth/Z-Image-Turbo",+ raising = False,+ )+ mirror_snapshot = _companion_snapshot(tmp_path / "live" / "mirror-snap")+ asked = []++ def _snapshot(+ repo,+ *,+ cache_dir = None,+ local_files_only = False,+ **_k,+ ):+ assert local_files_only+ asked.append((repo, cache_dir))+ if (repo, cache_dir) == ("unsloth/Z-Image-Turbo", live):+ return mirror_snapshot+ raise LocalEntryNotFoundError("not cached")++ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)+ out = mb.fetch_base_snapshot(BASE, None, local_files_only = True)+ assert out == mirror_snapshot+ assert asked == [("unsloth/Z-Image-Turbo", live)]+ asked.clear()+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_NO_MIRROR", "1")+ with pytest.raises(LocalEntryNotFoundError):+ mb.fetch_base_snapshot(BASE, None, local_files_only = True)+ assert asked and all(repo == BASE for repo, _ in asked)+ assert asked[0] == (BASE, live)+++def test_cache_only_companions_skip_an_incomplete_upstream_for_the_staged_mirror(+ monkeypatch, tmp_path+):+ # The upstream holds some weights, so the fetch-repo choice keeps it, but the plan staged the mirror.+ import huggingface_hub+ from huggingface_hub.errors import LocalEntryNotFoundError++ import utils.hf_cache_settings as cache_settings++ live = str(tmp_path / "live")+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)+ snapshots = {+ BASE: _companion_snapshot(tmp_path / "upstream", complete = False),+ "unsloth/Z-Image-Turbo": _companion_snapshot(tmp_path / "mirror"),+ }++ def _snapshot(repo, *, cache_dir = None, local_files_only = False, **_k):+ assert local_files_only+ if cache_dir != live or repo not in snapshots:+ raise LocalEntryNotFoundError("not cached")+ return snapshots[repo]++ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)+ assert mb.fetch_base_snapshot(BASE, None, local_files_only = True) == snapshots["unsloth/Z-Image-Turbo"]+ del snapshots["unsloth/Z-Image-Turbo"]+ with pytest.raises(LocalEntryNotFoundError, match = "complete"):+ mb.fetch_base_snapshot(BASE, None, local_files_only = True)+++def _mlx_route_stubs(monkeypatch, *, predicted = "mlx"):+ import core.inference.diffusion_engine_router as router_module+ import core.inference.gpu_arbiter as arbiter++ touched = []+ monkeypatch.setattr(router_module, "predict_engine", lambda *a, **k: predicted)+ monkeypatch.setattr(router_module, "active_engine_name", lambda: "diffusers")+ monkeypatch.setattr(+ router_module, "engine_for", lambda name: touched.append(("engine_for", name))+ )+ monkeypatch.setattr(+ router_module,+ "select_and_activate_engine",+ lambda *a, **k: touched.append("select"),+ )+ monkeypatch.setattr(arbiter, "acquire_for_request", lambda *a, **k: touched.append("acquire"))+ monkeypatch.setattr("routes.inference._guard_diffusion_load_against_training", lambda: None)+ monkeypatch.setattr("routes.inference._training_is_active", lambda: False)++ async def _no_ordinal(_gpu_ids, **_k):+ return None++ monkeypatch.setattr("routes.inference._selected_gpu_ordinal", _no_ordinal)+ return touched+++def test_the_load_route_refuses_mlx_loras_before_activation_or_eviction(monkeypatch):+ import asyncio++ from fastapi import HTTPException++ from models.inference import DiffusionLoadRequest+ from routes.inference import load_diffusion_model_gated++ touched = _mlx_route_stubs(monkeypatch)+ request = DiffusionLoadRequest(+ model_path = REPO, gguf_filename = GGUF, loras = [{"id": "a/b", "weight": 1.0}]+ )+ with pytest.raises(HTTPException) as err:+ asyncio.run(load_diffusion_model_gated(request, "test-user", user_initiated = False))+ assert err.value.status_code == 400+ assert "LoRA" in err.value.detail+ assert touched == []+++def test_the_download_plan_refuses_mlx_loras_before_planning(monkeypatch):+ import asyncio++ from fastapi import HTTPException++ from models.inference import DiffusionLoadRequest+ from routes import inference as routes++ touched = _mlx_route_stubs(monkeypatch)+ monkeypatch.setattr(+ mb.MlxDiffusionBackend,+ "download_plan",+ lambda self, *a, **k: touched.append("plan") or {},+ )+ request = DiffusionLoadRequest(+ model_path = REPO, gguf_filename = GGUF, loras = [{"id": "a/b", "weight": 1.0}]+ )+ with pytest.raises(HTTPException) as err:+ asyncio.run(routes.diffusion_download_plan(request, current_subject = "u"))+ assert err.value.status_code == 400+ assert "LoRA" in err.value.detail+ assert "plan" not in touched+++def test_a_concurrent_unload_waits_for_the_active_teardown(env):+ backend, runtime, _calls = env+ gate = threading.Event()+ started = threading.Event()+ real_build = runtime.build++ def _slow_build(*a, **k):+ started.set()+ gate.wait(10)+ return real_build(*a, **k)++ runtime.build = _slow_build+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert started.wait(5)+ first = threading.Thread(target = backend.unload)+ first.start()+ deadline = time.time() + 5+ while not backend._unloading and time.time() < deadline:+ time.sleep(0.01)+ done = threading.Event()+ second = threading.Thread(target = lambda: (backend.unload(), done.set()))+ second.start()+ try:+ assert not done.wait(+ 0.5+ ), "a second unload returned while the first was still joining the build"+ finally:+ gate.set()+ first.join(5)+ second.join(5)+ assert done.is_set()+ assert runtime.freed == 1+++def test_a_cancelled_load_keeps_its_repos_draining_until_the_worker_is_joined(env, monkeypatch):+ import core.inference.diffusion_engine_router as router+ from hub.services.models import deletion++ backend, runtime, _calls = env+ monkeypatch.setattr(router, "get_active_diffusion_engine", lambda: backend)+ gate = threading.Event()+ started = threading.Event()+ real_build = runtime.build++ def _slow_build(*a, **k):+ started.set()+ gate.wait(10)+ return real_build(*a, **k)++ runtime.build = _slow_build+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert started.wait(5)+ unloader = threading.Thread(target = backend.unload)+ unloader.start()+ deadline = time.time() + 5+ while not backend._unloading and time.time() < deadline:+ time.sleep(0.01)+ try:+ assert backend.loading_repo_ids() == ()+ assert REPO in backend.draining_repo_ids()+ assert "still releasing" in (deletion._diffusion_blocks_delete(REPO) or "")+ finally:+ gate.set()+ unloader.join(5)+ assert backend.draining_repo_ids() == ()+++def test_online_companions_land_under_one_cache_root(monkeypatch, tmp_path):+ import huggingface_hub+ from huggingface_hub import constants++ import utils.hf_cache_settings as cache_settings+ import utils.hf_xet_fallback as xet++ files = ["text_encoder/a.safetensors", "tokenizer/b.json", "vae/c.safetensors"]+ _hub_listing(monkeypatch, files)+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)+ live, old = str(tmp_path / "live"), str(tmp_path / "old")+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)+ monkeypatch.setattr(constants, "HF_HUB_CACHE", old)+ # Only the first file survives under the import-time root; the rest are cached nowhere.+ monkeypatch.setattr(+ huggingface_hub,+ "try_to_load_from_cache",+ lambda repo, fn, *, cache_dir = None, **k: (+ f"{old}/snapshots/abc/{fn}" if cache_dir in (None, old) and fn == files[0] else None+ ),+ )+ roots = []++ def _download(+ repo,+ fn,+ tok,+ *,+ cache_dir = None,+ reuse_other_cache_root = False,+ **k,+ ):+ root = old if reuse_other_cache_root and fn == files[0] else (cache_dir or live)+ roots.append(root)+ return f"{root}/snapshots/abc/{fn}"++ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)+ out = mb.fetch_base_snapshot(BASE, None, local_files_only = False)+ assert roots == [live] * len(files)+ assert out == f"{live}/snapshots/abc"+++def test_cache_only_companions_skip_a_snapshot_without_tokenizer_config(monkeypatch, tmp_path):+ # AutoTokenizer cannot resolve the tokenizer class without tokenizer_config.json.+ import huggingface_hub+ from huggingface_hub.errors import LocalEntryNotFoundError++ import utils.hf_cache_settings as cache_settings++ live = str(tmp_path / "live")+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)+ snapshots = {+ BASE: _companion_snapshot(tmp_path / "upstream", tokenizer_config = False),+ "unsloth/Z-Image-Turbo": _companion_snapshot(tmp_path / "mirror"),+ }++ def _snapshot(repo, *, cache_dir = None, local_files_only = False, **_k):+ if cache_dir != live or repo not in snapshots:+ raise LocalEntryNotFoundError("not cached")+ return snapshots[repo]++ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)+ assert mb.fetch_base_snapshot(BASE, None, local_files_only = True) == snapshots["unsloth/Z-Image-Turbo"]+++def test_a_cancelled_load_keeps_the_companion_mirror_guarded(env, monkeypatch):+ import core.inference.diffusion_engine_router as router+ from hub.services.models import deletion++ backend, runtime, _calls = env+ monkeypatch.setattr(router, "get_active_diffusion_engine", lambda: backend)+ gate = threading.Event()+ started = threading.Event()+ real_build = runtime.build++ def _slow_build(*a, **k):+ started.set()+ gate.wait(10)+ return real_build(*a, **k)++ runtime.build = _slow_build+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")+ assert started.wait(5)+ assert "unsloth/Z-Image-Turbo" in backend.loading_repo_ids()+ assert "using this repo" in (deletion._diffusion_blocks_delete("unsloth/Z-Image-Turbo") or "")+ unloader = threading.Thread(target = backend.unload)+ unloader.start()+ deadline = time.time() + 5+ while not backend._unloading and time.time() < deadline:+ time.sleep(0.01)+ try:+ assert "unsloth/Z-Image-Turbo" in backend.draining_repo_ids()+ assert "still releasing" in (deletion._diffusion_blocks_delete("unsloth/Z-Image-Turbo") or "")+ finally:+ gate.set()+ unloader.join(5)+ assert backend.draining_repo_ids() == ()+++class _PlanRecorder:+ def __init__(self):+ self.calls = []++ def download_plan(self, repo_id, **kwargs):+ self.calls.append(kwargs)+ return {"entries": [], "total_bytes": 0}+++def test_the_mlx_plan_forces_off_the_memory_verdict(monkeypatch):+ import core.inference.diffusion as diffusion++ recorder = _PlanRecorder()+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: recorder)+ mb.MlxDiffusionBackend().download_plan(+ REPO, gguf_filename = GGUF, base_repo = BASE, memory_verdict = True+ )+ assert recorder.calls[-1]["memory_verdict"] is False+++def test_the_mlx_plan_names_the_base_the_load_will_read(monkeypatch, tmp_path):+ import core.inference.diffusion as diffusion++ recorder = _PlanRecorder()+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: recorder)+ local = tmp_path / "picks"+ local.mkdir()+ gguf = "z-image-Q4_0.gguf"+ (local / gguf).write_bytes(b"GGUF")+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = gguf)+ assert recorder.calls[-1]["base_repo"] == "Tongyi-MAI/Z-Image"+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = "z-image-turbo-Q4_0.gguf")+ assert recorder.calls[-1]["base_repo"] == BASE+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = gguf, base_repo = BASE)+ assert recorder.calls[-1]["base_repo"] == BASEdiff --git a/studio/backend/tests/test_mlx_diffusion_convert.py b/studio/backend/tests/test_mlx_diffusion_convert.pynew file mode 100644index 00000000000..1bc8319dd94--- /dev/null+++ b/studio/backend/tests/test_mlx_diffusion_convert.py@@ -0,0 +1,365 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""GGUF -> MLX affine converter for the opt-in MLX image engine: numpy + gguf only, runs on Linux."""++import json+import struct+import threading++import numpy as np+import pytest++gguf = pytest.importorskip("gguf")+from gguf import GGMLQuantizationType as T # noqa: E402+from gguf import quants # noqa: E402++from core.inference import mlx_diffusion_convert as conv # noqa: E402+++def _rng(seed = 0):+ return np.random.default_rng(seed)+++def _blocks(+ kind,+ rows,+ cols,+ seed = 0,+):+ x = (_rng(seed).standard_normal((rows, cols)) * 0.05).astype(np.float32)+ return quants.quantize(x, kind)++[email protected]("kind", [T.Q4_0, T.Q4_1, T.Q8_0])[email protected]("cols", [64, 96])+def test_affine_matches_gguf_dequantize_exactly(kind, cols):+ raw = _blocks(kind, 6, cols, seed = cols)+ reference = quants.dequantize(raw, kind).astype(np.float32)+ w, s, b, bits = conv.affine_from_ggml(kind.name, raw, 6, cols)+ assert bits == (8 if kind == T.Q8_0 else 4)+ assert w.dtype == np.uint32 and w.shape == (6, cols * bits // 32)+ assert s.shape == b.shape == (6, cols // 32)+ got = conv.dequantize_affine(w, s, b, bits)+ assert np.array_equal(got, reference)+ # fp16 scales are lossless: d, m, -8d and -128d are all fp16 values+ s16 = s.astype(np.float16).astype(np.float32)+ b16 = b.astype(np.float16).astype(np.float32)+ assert np.array_equal(s16, s) and np.array_equal(b16, b)+ assert np.array_equal(conv.dequantize_affine(w, s16, b16, bits), reference)++[email protected]("kind", [T.Q4_0, T.Q4_1, T.Q8_0])+def test_affine_bf16_scales_within_rounding_bound(kind):+ raw = _blocks(kind, 8, 128, seed = 3)+ reference = quants.dequantize(raw, kind).astype(np.float32)+ w, s, b, bits = conv.affine_from_ggml(kind.name, raw, 8, 128)+ sb, bb = conv.round_to_bf16(s), conv.round_to_bf16(b)+ got = conv.dequantize_affine(w, sb, bb, bits)+ q = conv._unpack(w, bits).astype(np.float32).reshape(8, 4, 32)+ bound = (q * np.abs(sb - s)[..., None] + np.abs(bb - b)[..., None]).reshape(8, 128)+ assert np.all(np.abs(got - reference) <= bound * 1.0001 + 1e-12)+ # and bf16 keeps ~8 bits: never worse than 2^-8 relative on the scale+ assert np.all(np.abs(sb - s) <= np.abs(s) * 2.0**-8)+++def test_affine_rejects_kquant_and_bad_sizes():+ with pytest.raises(conv.UnsupportedGGUFError):+ conv.affine_from_ggml("Q4_K", np.zeros(144, np.uint8), 1, 256)+ with pytest.raises(ValueError):+ conv.affine_from_ggml("Q4_0", np.zeros(17, np.uint8), 1, 32)++[email protected]("bits", [4, 8])+def test_quantize_dense_roundtrip(bits):+ w = (_rng(1).standard_normal((5, 64)) * 0.1).astype(np.float32)+ packed, s, b = conv.quantize_dense_affine(w, bits)+ assert packed.shape == (5, 64 * bits // 32) and s.shape == b.shape == (5, 2)+ assert np.array_equal(conv.round_to_bf16(s), s) and np.array_equal(conv.round_to_bf16(b), b)+ got = conv.dequantize_affine(packed, s, b, bits)+ err = np.abs(got - w).reshape(5, 2, 32)+ # half a step from rounding, plus the top edge the bf16 rounding of scale may shave off+ slack = (s * 2.0**-8 * ((1 << bits) - 1) + np.abs(b) * 2.0**-8)[..., None]+ assert np.all(err <= s[..., None] / 2 + slack + 1e-7)+++def test_quantize_dense_constant_group():+ w = np.full((2, 32), 0.25, np.float32)+ w[1] = -3.0+ packed, s, b = conv.quantize_dense_affine(w, 4)+ assert np.all(s == 0)+ assert np.array_equal(conv.dequantize_affine(packed, s, b, 4), w)+++ "src, dst",+ [+ ("final_layer.adaLN_modulation.1.weight", "all_final_layer.2-1.adaLN_modulation.0.weight"),+ ("final_layer.linear.weight", "all_final_layer.2-1.linear.weight"),+ ("x_embedder.weight", "all_x_embedder.2-1.weight"),+ ("t_embedder.mlp.0.weight", "t_embedder.linear1.weight"),+ ("t_embedder.mlp.2.bias", "t_embedder.linear2.bias"),+ ("layers.3.attention.out.weight", "layers.3.attention.to_out.0.weight"),+ ("layers.3.attention.q_norm.weight", "layers.3.attention.norm_q.weight"),+ ("layers.3.attention.k_norm.weight", "layers.3.attention.norm_k.weight"),+ ("layers.3.attention.qkv.weight", "layers.3.attention.qkv.weight"),+ ("layers.3.feed_forward.w1.weight", "layers.3.feed_forward.w1.weight"),+ ],+)+def test_zimage_rename(src, dst):+ assert conv.zimage_rename(src) == dst+++ "name, ok",+ [+ ("z-image-turbo-Q4_0.gguf", True),+ ("z-image-turbo-Q4_1.gguf", True),+ ("z-image-turbo-Q8_0.gguf", True),+ ("z-image-turbo-BF16.gguf", True),+ ("z-image-turbo-F16.gguf", True),+ ("z_image_turbo-Q4_K_M.gguf", False),+ ("z-image-turbo-UD-Q4_K_XL.gguf", False),+ ("z-image-turbo-Q6_K.gguf", False),+ ("z-image-turbo-Q5_0.gguf", False),+ ("z-image-turbo-IQ4_XS.gguf", False),+ ("z-image-turbo-MXFP4.gguf", False),+ ("z-image-turbo.gguf", False),+ (None, False),+ ],+)+def test_quant_convertible(name, ok):+ verdict, reason = conv.quant_convertible(name)+ assert verdict is ok+ assert (reason is None) is ok+ if not ok:+ assert "MLX" in reason+++def test_quant_convertible_names_the_kquant():+ _ok, reason = conv.quant_convertible("z_image_turbo-Q4_K_M.gguf")+ assert "Q4_K_M" in reason and "not convertible" in reason+++# ── End to end on a tiny synthetic GGUF ─────────────────────────────────────────────────────────+++def _read_safetensors(path):+ data = path.read_bytes()+ (n,) = struct.unpack("<Q", data[:8])+ header = json.loads(data[8 : 8 + n])+ body = data[8 + n :]+ meta = header.pop("__metadata__")+ np_dtype = {"U32": np.uint32, "BF16": np.uint16, "F16": np.float16}+ tensors = {}+ end = 0+ for name, info in sorted(header.items(), key = lambda kv: kv[1]["data_offsets"][0]):+ a, b = info["data_offsets"]+ assert a == end, "offsets must be contiguous"+ end = b+ tensors[name] = (+ info["dtype"],+ np.frombuffer(body[a:b], dtype = np_dtype[info["dtype"]]).reshape(info["shape"]),+ )+ assert end == len(body)+ return meta, tensors+++def _bf16(bits16):+ return conv._bf16_bits_to_f32(bits16)+++def _write_gguf(path, extra = None):+ rng = _rng(7)+ sources = {}+ w = gguf.GGUFWriter(str(path), "z-image")++ def add_q(name, kind, rows, cols):+ x = (rng.standard_normal((rows, cols)) * 0.05).astype(np.float32)+ raw = quants.quantize(x, kind)+ sources[name] = (kind, raw)+ w.add_tensor(name, raw, raw_dtype = kind)++ add_q("layers.0.attention.qkv.weight", T.Q4_0, 3 * 64, 64)+ add_q("layers.0.feed_forward.w1.weight", T.Q8_0, 96, 64)+ add_q("layers.0.attention.out.weight", T.Q4_1, 64, 64)+ dense = (rng.standard_normal((32, 64)) * 0.05).astype(np.float32)+ sources["context_refiner.0.feed_forward.w2.weight"] = (T.BF16, dense)+ w.add_tensor(+ "context_refiner.0.feed_forward.w2.weight",+ quants.quantize(dense, T.BF16),+ raw_dtype = T.BF16,+ )+ norm = rng.standard_normal(64).astype(np.float32)+ sources["layers.0.attention.q_norm.weight"] = (T.F32, norm)+ w.add_tensor("layers.0.attention.q_norm.weight", norm)+ pad = rng.standard_normal(64).astype(np.float32)+ sources["cap_pad_token"] = (T.F32, pad)+ w.add_tensor("cap_pad_token", pad)+ if extra:+ extra(w)+ w.write_header_to_file()+ w.write_kv_data_to_file()+ w.write_tensors_to_file()+ w.close()+ return sources+++def test_convert_end_to_end(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ sources = _write_gguf(src)+ seen = []+ summary = conv.convert_gguf_to_mflux(+ src, tmp_path / "out", progress = lambda d, t: seen.append((d, t))+ )+ assert summary["counts"] == {"Q4_0": 1, "Q8_0": 1, "Q4_1": 1, "BF16": 1, "F32": 2}+ assert seen[-1] == (6, 6)+ out = tmp_path / "out" / "transformer" / "0.safetensors"+ meta, tensors = _read_safetensors(out)+ assert meta["quantization_level"] == "4"+ assert meta["mflux_version"] and meta["source_gguf"] == src.name+ assert meta["unsloth_converter"] == conv.CONVERTER_VERSION+ names = set(tensors)+ for p in ("to_q", "to_k", "to_v"):+ for suffix in ("weight", "scales", "biases"):+ assert f"layers.0.attention.{p}.{suffix}" in names+ assert not any(".qkv." in n for n in names)+ assert "layers.0.attention.to_out.0.scales" in names+ assert "layers.0.attention.norm_q.weight" in names+ kind, raw = sources["layers.0.attention.qkv.weight"]+ ref = quants.dequantize(raw, kind).astype(np.float32)+ for i, p in enumerate(("to_q", "to_k", "to_v")):+ dt, packed = tensors[f"layers.0.attention.{p}.weight"]+ assert dt == "U32" and packed.shape == (64, 8)+ s = _bf16(tensors[f"layers.0.attention.{p}.scales"][1])+ b = _bf16(tensors[f"layers.0.attention.{p}.biases"][1])+ got = conv.dequantize_affine(packed, s, b, 4)+ np.testing.assert_allclose(got, ref[i * 64 : (i + 1) * 64], atol = 2e-3, rtol = 0)+ # Q8_0 packs 4 per word+ assert tensors["layers.0.feed_forward.w1.weight"][1].shape == (96, 16)+ # dense BF16 stays bit-identical; F32 is rounded to bf16; pad token is (1, -1)+ dt, bits16 = tensors["context_refiner.0.feed_forward.w2.weight"]+ assert dt == "BF16" and bits16.shape == (32, 64)+ np.testing.assert_array_equal(+ _bf16(bits16), conv.round_to_bf16(sources["context_refiner.0.feed_forward.w2.weight"][1])+ )+ assert tensors["cap_pad_token"][1].shape == (1, 64)+ np.testing.assert_array_equal(+ _bf16(tensors["layers.0.attention.norm_q.weight"][1]),+ conv.round_to_bf16(sources["layers.0.attention.q_norm.weight"][1]),+ )+ marker = json.loads((out.parent / conv.MARKER_FILENAME).read_text())+ assert marker["output_bytes"] == out.stat().st_size and marker["dense_bits"] == 0+ assert conv.conversion_complete(tmp_path / "out")+ assert conv.conversion_complete(tmp_path / "out", source_path = src)+ assert not list(out.parent.glob(".*tmp"))+++def test_convert_f16_scales_are_exact(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ sources = _write_gguf(src)+ conv.convert_gguf_to_mflux(src, tmp_path / "out", scale_dtype = "f16")+ _meta, tensors = _read_safetensors(tmp_path / "out" / "transformer" / "0.safetensors")+ kind, raw = sources["layers.0.attention.out.weight"]+ dt, packed = tensors["layers.0.attention.to_out.0.weight"]+ s = tensors["layers.0.attention.to_out.0.scales"]+ b = tensors["layers.0.attention.to_out.0.biases"]+ assert s[0] == b[0] == "F16"+ got = conv.dequantize_affine(packed, s[1].astype(np.float32), b[1].astype(np.float32), 4)+ assert np.array_equal(got, quants.dequantize(raw, kind).astype(np.float32))+++def test_convert_dense_bits_quantizes_dense_linears(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ sources = _write_gguf(src)+ summary = conv.convert_gguf_to_mflux(src, tmp_path / "out", dense_bits = 4)+ assert summary["dense_bits"] == 4+ _meta, tensors = _read_safetensors(tmp_path / "out" / "transformer" / "0.safetensors")+ base = "context_refiner.0.feed_forward.w2"+ assert tensors[base + ".weight"][0] == "U32"+ got = conv.dequantize_affine(+ tensors[base + ".weight"][1],+ _bf16(tensors[base + ".scales"][1]),+ _bf16(tensors[base + ".biases"][1]),+ 4,+ )+ dense = sources[base + ".weight"][1]+ assert np.max(np.abs(got - dense)) < 0.05+ # norms (1-D) and pad tokens stay dense+ assert tensors["layers.0.attention.norm_q.weight"][0] == "BF16"+ assert tensors["cap_pad_token"][0] == "BF16"+++def test_convert_refuses_kquant_before_writing(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_K_M.gguf"++ def extra(w):+ raw = _rng(2).integers(0, 255, size = (4, 144), dtype = np.uint8)+ w.add_tensor("layers.0.feed_forward.w2.weight", raw, raw_dtype = T.Q4_K)++ _write_gguf(src, extra = extra)+ with pytest.raises(conv.UnsupportedGGUFError, match = "Q4_K"):+ conv.convert_gguf_to_mflux(src, tmp_path / "out")+ assert not (tmp_path / "out" / "transformer" / "0.safetensors").exists()+ assert not conv.conversion_complete(tmp_path / "out")+++def test_convert_cancel_leaves_no_file(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ _write_gguf(src)+ cancel = threading.Event()+ cancel.set()+ with pytest.raises(RuntimeError, match = "cancelled"):+ conv.convert_gguf_to_mflux(src, tmp_path / "out", cancel_event = cancel)+ target = tmp_path / "out" / "transformer"+ assert not (target / "0.safetensors").exists()+ assert not list(target.glob(".*"))+++def test_conversion_complete_detects_truncation_and_source_change(tmp_path):+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ _write_gguf(src)+ conv.convert_gguf_to_mflux(src, tmp_path / "out")+ out = tmp_path / "out" / "transformer" / "0.safetensors"+ with open(out, "ab") as fh:+ fh.write(b"x")+ assert not conv.conversion_complete(tmp_path / "out")+ conv.convert_gguf_to_mflux(src, tmp_path / "out")+ assert conv.conversion_complete(tmp_path / "out", source_path = src)+ with open(src, "ab") as fh:+ fh.write(b"\0" * 32)+ assert not conv.conversion_complete(tmp_path / "out", source_path = src)+++def test_cache_dir_for(tmp_path, monkeypatch):+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))+ d = conv.cache_dir_for(+ "unsloth/Z-Image-Turbo-GGUF", "abc123", "z-image-turbo-Q4_0.gguf", dense_bits = 4+ )+ assert d.parent.name == "unsloth--Z-Image-Turbo-GGUF@abc123"+ assert d.name == "z-image-turbo-Q4_0-d4-bf16"+ assert d.parent.parent.name == "mlx_diffusion"+ assert str(d).startswith(str(tmp_path.resolve())) or str(d).startswith(str(tmp_path))+ local = conv.cache_dir_for("../x", None, "sub/../m.gguf", dense_bits = 0)+ assert ".." not in local.parts and local.parent.name.endswith("@local")+++def test_mlx_loads_the_output_when_available(tmp_path):+ mx = pytest.importorskip("mlx.core")+ src = tmp_path / "z-image-turbo-Q4_0.gguf"+ sources = _write_gguf(src)+ conv.convert_gguf_to_mflux(src, tmp_path / "out")+ loaded, meta = mx.load(+ str(tmp_path / "out" / "transformer" / "0.safetensors"), return_metadata = True+ )+ assert meta["quantization_level"] == "4"+ name = "layers.0.attention.to_out.0"+ got = mx.dequantize(+ loaded[name + ".weight"],+ loaded[name + ".scales"],+ loaded[name + ".biases"],+ group_size = 32,+ bits = 4,+ ).astype(mx.float32)+ kind, raw = sources["layers.0.attention.out.weight"]+ np.testing.assert_allclose(np.array(got), quants.dequantize(raw, kind), atol = 2e-3, rtol = 0)diff --git a/studio/install_python_stack.py b/studio/install_python_stack.pyindex 9553e32d93a..e63cafbc2f9 100644--- a/studio/install_python_stack.py+++ b/studio/install_python_stack.py@@ -10514,6 +10514,49 @@ _MLX_VLM_SPEC = "mlx-vlm>=0.4.4,<=0.7.4"# Exact: llguidance.mlx / llguidance.hf are the API grammar_constraint.py binds to._LLGUIDANCE_PIN = "llguidance==1.8.0"_MLX_NAMES: tuple[str, ...] = tuple(spec.partition("==")[0] for spec in _MLX_PINS) + ("mlx-vlm",)+# mflux goes in --no-deps: its declared torch / transformers floors would move the MLX pins, and Z-Image+# needs only the deps below. Best-effort: a failure must never mark the MLX stack broken.+_MLX_DIFFUSION_PINS: tuple[str, ...] = ("mflux==0.22.0",)+_MLX_DIFFUSION_DEPS: tuple[str, ...] = (+ "piexif>=1.1.3,<2",+ "platformdirs>=4,<5",+ "toml>=0.10.2,<1",+)+++def _mlx_diffusion_engine_is_current() -> bool:+ """Whether mflux is at its pin and its light runtime deps are inside their ranges."""+ if not all(_exact_distribution_spec_is_installed(spec) for spec in _MLX_DIFFUSION_PINS):+ return False+ try:+ from packaging.requirements import Requirement+ for spec in _MLX_DIFFUSION_DEPS:+ requirement = Requirement(spec)+ installed = _installed_distribution_version(requirement.name)+ if installed is None or not requirement.specifier.contains(installed, prereleases = True):+ return False+ except Exception: # noqa: BLE001 - no packaging, or a version it cannot parse+ return False+ return True+++def _install_mlx_diffusion_engine() -> None:+ """Install the opt-in MLX image engine; a failure is noted, never fatal."""+ if not _full_deps_requested() and _mlx_diffusion_engine_is_current():+ return+ try:+ pip_install(+ "Installing the MLX image engine (mflux)",+ "--no-cache-dir",+ "--no-deps",+ *_MLX_DIFFUSION_PINS,+ *_MLX_DIFFUSION_DEPS,+ )+ except SystemExit:+ _note(+ f"{_MLX_DIFFUSION_PINS[0]} failed to install; image generation keeps its "+ "current engine (UNSLOTH_DIFFUSION_MLX has no effect)"+ )def _mlx_vlm_spec_for_installed_zoo() -> str:@@ -12402,6 +12445,9 @@ def install_python_stack() -> int:*_MLX_PINS,_mlx_vlm_spec_for_installed_zoo(),)+ # Inside the MLX slot, after the pins it runs on; its own check, so a satisfied+ # stack still gets a missing engine.+ _install_mlx_diffusion_engine()_mlx_vlm_spec_used = _mlx_vlm_spec_for_installed_zoo()else:_progress("MLX stack (skipped, no wheel for this macOS or Python)")diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.pyindex 0e50067fdcd..50782ea7e77 100644--- a/tests/studio/install/test_mlx_install.py+++ b/tests/studio/install/test_mlx_install.py@@ -30,6 +30,7 @@ def _run_to_extras(shared_base = False,mlx_error = None,mlx_installable = True,+ engine_error = None,):monkeypatch.setenv("SKIP_STUDIO_BASE", "1" if skip_base else "0")for name in ("STUDIO_LOCAL_REPO", "STUDIO_PACKAGE_NAME", "UNSLOTH_CI_SOURCE_OVERLAY"):@@ -66,6 +67,8 @@ def _run_to_extras(def record_install(label, *args, **kwargs):if label.startswith("Installing MLX") and mlx_error is not None:raise mlx_error+ if label.startswith("Installing the MLX image engine") and engine_error is not None:+ raise engine_errorinstall = Mock(side_effect = record_install)monkeypatch.setattr(stack, "pip_install", install)@@ -84,6 +87,11 @@ def _run_to_extras(stack.install_python_stack()# Labels reached before the stop, for callers asserting on the step not the install._run_to_extras.steps = steps+ _run_to_extras.engine_calls = [+ call+ for call in install.call_args_list+ if call.args[0].startswith("Installing the MLX image engine")+ ]return [call for call in install.call_args_list if call.args[0].startswith("Installing MLX")]@@ -446,3 +454,85 @@ def test_an_unchanged_zoo_does_not_re_resolve_mlx(monkeypatch):calls = _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False)assert len(calls) == 1assert "MLX stack (zoo unchanged, skipped)" in _run_to_extras.steps+++# ── Opt-in MLX image engine (mflux) ──────────────────────────────────────────+++def test_mlx_image_engine_pins_leave_the_mlx_stack_alone():+ assert stack._MLX_PINS == ("mlx==0.32.3", "mlx-metal==0.32.3", "mlx-lm==0.31.3")+ names = {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_PINS}+ names |= {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_DEPS}+ assert names == {"mflux", "piexif", "platformdirs", "toml"}+ # The heavy declared deps of mflux stay out: --no-deps plus this list is the whole install.+ assert not names & {+ "opencv-python",+ "opencv-python-headless",+ "matplotlib",+ "torch",+ "transformers",+ "mlx",+ "mlx-metal",+ "mlx-lm",+ }+ (pin,) = stack._MLX_DIFFUSION_PINS+ assert pin.startswith("mflux==0.22.")++[email protected]("platform", ["macos_arm", "macos_intel", "linux", "windows"])[email protected]("no_torch", [False, True], ids = ["training", "gguf_only"])+def test_mlx_image_engine_installs_no_deps_only_where_the_mlx_stack_does(+ monkeypatch, platform, no_torch+):+ monkeypatch.setattr(stack, "_mlx_vlm_spec_for_installed_zoo", lambda: stack._MLX_VLM_SPEC)+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)+ _run_to_extras(monkeypatch, platform = platform, skip_base = True, no_torch = no_torch)+ calls = _run_to_extras.engine_calls+ assert len(calls) == int(platform == "macos_arm" and not no_torch)+ if calls:+ args = list(calls[0].args[1:])+ assert "--no-deps" in args+ specs = [arg for arg in args if not arg.startswith("-")]+ assert specs == [*stack._MLX_DIFFUSION_PINS, *stack._MLX_DIFFUSION_DEPS]+ assert not any("opencv" in arg or "matplotlib" in arg for arg in args)+++def test_mlx_image_engine_skipped_off_the_wheel_floor(monkeypatch):+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)+ _run_to_extras(+ monkeypatch, platform = "macos_arm", skip_base = True, no_torch = False, mlx_installable = False+ )+ assert _run_to_extras.engine_calls == []+++def test_satisfied_mlx_image_engine_is_not_reinstalled(monkeypatch):+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: True)+ monkeypatch.setattr(stack, "_full_deps_requested", lambda: False)+ _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = True, no_torch = False)+ assert _run_to_extras.engine_calls == []++[email protected]("skip_base", [True, False], ids = ["fresh", "update"])+def test_failed_mlx_image_engine_install_is_not_fatal(monkeypatch, skip_base):+ # The MLX stack still installs, and the pass carries on to the extras step.+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)+ noted = Mock()+ monkeypatch.setattr(stack, "_note", noted)+ calls = _run_to_extras(+ monkeypatch,+ platform = "macos_arm",+ skip_base = skip_base,+ no_torch = False,+ engine_error = SystemExit(1),+ )+ assert calls and len(_run_to_extras.engine_calls) == 1+ assert any("mflux" in str(call.args[0]) for call in noted.call_args_list)+++def test_mlx_image_engine_is_not_part_of_the_mlx_gate():+ # The self-heal and the chat-only gate judge mlx / mlx-lm / mlx-vlm only.+ assert "mflux" not in _repair_specs()+ source = (Path(stack.SCRIPT_DIR) / "backend" / "utils" / "mlx_repair.py").read_text(+ encoding = "utf-8"+ )+ assert "mflux" not in source