Skip to content

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

45.1 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""CPU-only base_precision tests for config validation, auto policy and the fp8 filter; no model load."""

from __future__ import annotations

import pytest
import torch.nn as nn

import core.training.diffusion_train_common as common
from core.training import diffusion_dit_trainer as dit
from core.training.diffusion_train_common import (
    DiffusionLoraConfig,
    _config_from_dict,
    repo_is_prequantized,
    train_precision_modes,
)
from models.training import DiffusionTrainingStartRequest

_FLUX_DENSE = "black-forest-labs/FLUX.1-dev"
_Z_PREQUANT = "unsloth/Z-Image-Turbo-unsloth-bnb-4bit"
_SDXL_PREQUANT_NAME = "some/sdxl-model-bnb-4bit"
_QWEN_DENSE = "Qwen/Qwen-Image"


def _cfg(base_model = _FLUX_DENSE, **kw) -> DiffusionLoraConfig:
    return DiffusionLoraConfig(base_model = base_model, data_dir = "d", output_dir = "o", **kw)


@pytest.fixture(autouse = True)
def _not_rocm(monkeypatch):
    """Pin the ROCm gate off: these cases simulate NVIDIA tiers, which an AMD host would leak."""
    for _mod in (common, dit):
        monkeypatch.setattr(_mod, "torch_is_rocm", lambda: False)


def test_base_precision_validation():
    assert _cfg().normalized().base_precision == "nf4"

    with pytest.raises(ValueError, match = "base_precision"):
        _cfg(base_precision = "banana").normalized()

    norm = _cfg(base_precision = " FP8 ", mixed_precision = "bf16").normalized()
    assert norm.base_precision == "fp8"

    with pytest.raises(ValueError, match = "dense base repo"):
        _cfg(base_model = _Z_PREQUANT, base_precision = "bf16").normalized()

    with pytest.raises(ValueError, match = "bf16 compute"):
        _cfg(base_precision = "int8", mixed_precision = "fp16").normalized()

    assert _cfg(base_model = _Z_PREQUANT, base_precision = "auto").normalized().base_precision == "auto"


def test_normalized_config_keeps_the_canonical_base_and_pins_its_fetch_mirror(monkeypatch):
    from core.inference import diffusion_families

    upstream = "black-forest-labs/FLUX.2-klein-base-9B"
    mirror = "unsloth/FLUX.2-klein-base-9B"
    seen = []

    def _prefer(base, token = None):
        seen.append((base, token))
        return mirror

    monkeypatch.setattr(diffusion_families, "prefer_ungated_mirror", _prefer)
    norm = _cfg(base_model = upstream, hf_token = " token ").normalized()

    assert norm.base_model == upstream
    assert norm.fetch_base_model == mirror
    assert norm.hf_token == "token"
    assert seen == [(upstream, "token")]

    sdxl = _cfg(base_model = "stabilityai/stable-diffusion-xl-base-1.0").normalized()
    assert sdxl.fetch_base_model == sdxl.base_model
    assert seen == [(upstream, "token")]


def test_base_precision_denies_fp8_for_corrupted_family():
    with pytest.raises(ValueError, match = "fp8"):
        _cfg(base_model = _QWEN_DENSE, base_precision = "fp8", mixed_precision = "bf16").normalized()

    for mode in ("nf4", "bf16", "int8", "auto"):
        norm = _cfg(
            base_model = _QWEN_DENSE, base_precision = mode, mixed_precision = "bf16"
        ).normalized()
        assert norm.resolved_family == "qwen-image"
        assert norm.base_precision == mode

    flux = _cfg(base_model = _FLUX_DENSE, base_precision = "fp8", mixed_precision = "bf16").normalized()
    assert flux.resolved_family == "flux.1"
    assert flux.base_precision == "fp8"


def test_family_train_infos_drops_denied_fp8_for_qwen(monkeypatch, dit_train_host):
    monkeypatch.setattr(
        common, "train_precision_modes", lambda: (["nf4", "bf16", "int8", "fp8", "auto"], "auto")
    )
    monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: None)
    infos = {i["name"]: i for i in common.family_train_infos()}
    assert "fp8" not in infos["qwen-image"]["precision_modes"]
    assert "int8" in infos["qwen-image"]["precision_modes"]
    assert "fp8" in infos["flux.1"]["precision_modes"]


def test_resolve_base_precision_explicit_int8_gates_on_torchao(monkeypatch):
    spec = dit._SPECS["flux.1"]
    cfg = _cfg(base_precision = "int8")

    monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
    with pytest.raises(ValueError, match = "torchao"):
        dit._resolve_base_precision(cfg, spec, "cuda")

    monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"

    # The gate is int8-specific: explicit bf16/fp8 pass through regardless of torchao (fp8 on an sm89 GPU).
    import torch

    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 9))
    monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
    assert dit._resolve_base_precision(_cfg(base_precision = "bf16"), spec, "cuda") == "bf16"
    assert dit._resolve_base_precision(_cfg(base_precision = "fp8"), spec, "cuda") == "fp8"


def test_bf16_unsupported_reason(monkeypatch):
    import torch

    from core.training.diffusion_train_common import bf16_unsupported_reason

    assert bf16_unsupported_reason("sdxl") is None
    assert bf16_unsupported_reason("") is None

    # Pre-Ampere cards emulate bf16 and report is_bf16_supported() True, so the gate is SM >= 8.
    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
    assert "bfloat16" in (bf16_unsupported_reason("flux.1") or "")

    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 0))
    assert bf16_unsupported_reason("qwen-image") is None

    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    assert bf16_unsupported_reason("z-image") is None


def test_native_bf16_supported_gates_on_capability(monkeypatch):
    import torch

    from core.training.diffusion_train_common import native_bf16_supported

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
    assert native_bf16_supported() is False
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 0))
    assert native_bf16_supported() is True
    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    assert native_bf16_supported() is False


def test_training_precision_preflight_error(monkeypatch):
    import torch

    from core.training.diffusion_train_common import training_precision_preflight_error

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda *a, **k: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 6))

    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (7, 5))
    assert "bfloat16" in (training_precision_preflight_error("flux.1", "int8") or "")
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (8, 6))

    monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
    reason = training_precision_preflight_error("qwen-image", "int8")
    assert reason is not None and "int8" in reason and "torchao" in reason

    monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
    assert training_precision_preflight_error("qwen-image", "int8") is None

    monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
    assert training_precision_preflight_error("flux.1", "nf4") is None
    assert training_precision_preflight_error("flux.1", "auto") is None
    assert training_precision_preflight_error("sdxl", "int8") is None
    assert training_precision_preflight_error("", "int8") is None

    monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    monkeypatch.setattr(torch.xpu, "is_available", lambda: False)
    monkeypatch.setattr(torch.mps, "is_available", lambda: False)
    for dense in ("bf16", "int8", "fp8", "mxfp8"):
        reason = training_precision_preflight_error("flux.1", dense)
        assert reason is not None and "CUDA" in reason
    for mode in ("nf4", "auto"):
        reason = training_precision_preflight_error("flux.1", mode)
        assert reason is not None and "GPU" in reason
    assert training_precision_preflight_error("sdxl", "bf16") is None

    monkeypatch.setattr(torch.xpu, "is_available", lambda: True)
    assert training_precision_preflight_error("flux.1", "nf4") is None
    assert training_precision_preflight_error("flux.1", "auto") is None
    assert training_precision_preflight_error("flux.1", "bf16") is not None
    monkeypatch.setattr(torch.xpu, "is_available", lambda: False)

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (9, 0))
    reason = training_precision_preflight_error("flux.1", "mxfp8")
    assert reason is not None and "Blackwell" in reason
    assert training_precision_preflight_error("flux.1", "bf16") is None
    assert training_precision_preflight_error("flux.1", "fp8") is None

    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda *a, **k: (10, 0))
    assert training_precision_preflight_error("flux.1", "mxfp8") is None
    assert training_precision_preflight_error("sdxl", "mxfp8") is None


def test_family_train_infos_empties_dit_modes_on_non_bf16(monkeypatch):
    from core.training.diffusion_train_common import _DIT_TRAIN_FAMILIES, family_train_infos

    monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: "no bfloat16 on this GPU")

    infos = {info["name"]: info for info in family_train_infos()}
    dit_seen = False
    for name, info in infos.items():
        if name in _DIT_TRAIN_FAMILIES:
            dit_seen = True
            assert info["precision_modes"] == []
            assert info["vram_note"] == "no bfloat16 on this GPU"
            assert info["recommended_precision"] == "nf4"
            assert info["supports_compile"] is False
    assert dit_seen


def test_family_train_infos_drops_base_specs_on_a_dit_block(monkeypatch, dit_train_host):
    # FamilyFacts renders vram_note only with no chips, so per-base chips must be cleared too.
    from core.training.diffusion_train_common import _DIT_TRAIN_FAMILIES, family_train_infos

    unblocked = {info["name"]: info for info in family_train_infos()}
    assert any(unblocked[n]["base_specs"] for n in _DIT_TRAIN_FAMILIES if n in unblocked)

    monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: "no bfloat16 on this GPU")
    for name, info in (
        (n, i)
        for n, i in ((i["name"], i) for i in family_train_infos())
        if n in _DIT_TRAIN_FAMILIES
    ):
        assert info["base_specs"] == {}, name
        assert info["vram_note"] == "no bfloat16 on this GPU", name


def test_base_precision_gates_skip_sdxl():
    norm = _cfg(base_model = _SDXL_PREQUANT_NAME, base_precision = "bf16").normalized()
    assert norm.resolved_family == "sdxl"
    assert norm.base_precision == "bf16"

    norm2 = _cfg(
        base_model = "stabilityai/stable-diffusion-xl-base-1.0",
        base_precision = "int8",
        mixed_precision = "fp16",
    ).normalized()
    assert norm2.resolved_family == "sdxl"

    with pytest.raises(ValueError, match = "base_precision"):
        _cfg(base_model = _SDXL_PREQUANT_NAME, base_precision = "banana").normalized()

    with pytest.raises(ValueError, match = "dense base repo"):
        _cfg(base_model = _Z_PREQUANT, base_precision = "bf16").normalized()


@pytest.mark.parametrize(
    "repo, expected",
    [
        ("unsloth/Qwen-Image-2512-unsloth-bnb-4bit", True),
        ("some/model-4bit", True),
        ("some/model-int4", True),
        ("some/model-nf4", True),
        ("black-forest-labs/FLUX.1-dev", False),
        ("Tongyi-MAI/Z-Image-Turbo", False),
    ],
)
def test_repo_is_prequantized_cases(repo, expected):
    assert repo_is_prequantized(repo) is expected


def test_repo_is_prequantized_alias_is_same_object():
    assert dit._repo_is_prequantized is repo_is_prequantized


def test_pick_auto_precision_policy_table():
    p = dit._pick_auto_precision

    assert p(True, "cuda", 140, 23.8, (10, 0), True) == "nf4"
    assert p(False, "cpu", 140, 23.8, (10, 0), True) == "nf4"
    assert p(False, "cuda", None, 23.8, (10, 0), True) == "nf4"

    # Compiled bf16 measured faster than torchao float8 at LoRA shapes.
    assert p(False, "cuda", 140, 23.8, (10, 0), True) == "bf16"
    assert p(False, "cuda", 140, 23.8, (8, 0), True) == "bf16"
    assert p(False, "cuda", 140, 23.8, (10, 0), False) == "bf16"

    # 30 > 23.8 * 1.15 (int8 band) but not > 23.8 * 1.5 (bf16 band).
    assert p(False, "cuda", 30, 23.8, (10, 0), True) == "int8"
    assert p(False, "cuda", 30, 23.8, (10, 0), True, False) == "nf4"
    assert p(False, "cuda", 140, 23.8, (10, 0), True, False) == "bf16"
    assert p(False, "cuda", 25, 23.8, (10, 0), True) == "nf4"
    assert p(False, "cuda", 10, 23.8, (10, 0), True) == "nf4"


def test_resolve_base_precision_passes_explicit_through():
    spec = dit._SPECS["flux.1"]
    cfg = _cfg(base_precision = "bf16")
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "bf16"

    with pytest.raises(ValueError, match = "CUDA"):
        dit._resolve_base_precision(cfg, spec, "cpu")
    assert dit._resolve_base_precision(_cfg(base_precision = "nf4"), spec, "cpu") == "nf4"


def test_resolve_auto_requires_bf16_compute():
    spec = dit._SPECS["flux.1"]
    cfg = _cfg(base_precision = "auto", mixed_precision = "fp16")
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"


def test_resolve_auto_int8_band_gates_on_torchao(monkeypatch):
    import torch

    spec = dit._SPECS["flux.1"]
    cfg = _cfg(base_precision = "auto", mixed_precision = "bf16")

    class _FakeCuda:
        @staticmethod
        def mem_get_info():
            return (int(30 * 1e9), int(80 * 1e9))

        @staticmethod
        def get_device_capability():
            return (10, 0)

    monkeypatch.setattr(torch, "cuda", _FakeCuda)

    monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"

    monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"


def test_resolve_auto_uses_klein_variant_size(monkeypatch):
    import torch

    spec = dit._SPECS["flux.2-klein"]

    class _FakeCuda:
        @staticmethod
        def mem_get_info():
            return (int(20 * 1e9), int(24 * 1e9))

        @staticmethod
        def get_device_capability():
            return (10, 0)

    monkeypatch.setattr(torch, "cuda", _FakeCuda)
    monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)

    four_b = _cfg(
        base_model = "black-forest-labs/FLUX.2-klein-base-4B",
        base_precision = "auto",
        mixed_precision = "bf16",
    )
    nine_b = _cfg(
        base_model = "unsloth/FLUX.2-klein-base-9B",
        base_precision = "auto",
        mixed_precision = "bf16",
    )

    assert dit._resolve_base_precision(four_b, spec, "cuda") == "bf16"
    assert dit._resolve_base_precision(nine_b, spec, "cuda") == "nf4"


def test_resolve_auto_int8_band_treats_stub_as_absent(monkeypatch):
    # Windows-ROCm torchao stub (find_spec ok, quantize_ no-op): the int8 band must fall to nf4.
    import torch

    spec = dit._SPECS["flux.1"]
    cfg = _cfg(base_precision = "auto", mixed_precision = "bf16")

    class _FakeCuda:
        @staticmethod
        def mem_get_info():
            return (int(30 * 1e9), int(80 * 1e9))

        @staticmethod
        def get_device_capability():
            return (10, 0)

    monkeypatch.setattr(torch, "cuda", _FakeCuda)
    monkeypatch.setattr(dit, "has_functional_torchao", lambda: False)
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"


def _fake_cuda_with_free_gb(monkeypatch, free_gb: float):
    """Point torch.cuda at a GPU reporting ``free_gb`` free, so the auto pick is deterministic."""
    import torch

    class _FakeCuda:
        @staticmethod
        def mem_get_info():
            return (int(free_gb * 1e9), int(80 * 1e9))

        @staticmethod
        def get_device_capability():
            return (10, 0)

    monkeypatch.setattr(torch, "cuda", _FakeCuda)
    monkeypatch.setattr(dit, "has_functional_torchao", lambda: True)


@pytest.mark.parametrize(
    "base_model",
    [
        "black-forest-labs/FLUX.2-klein-9B",
        "black-forest-labs/FLUX.2-klein-base-9B",
        "unsloth/FLUX.2-klein-9B",
        "unsloth/FLUX.2-klein-base-9B",
    ],
)
def test_auto_sizes_flux2_klein_9b_off_its_own_weights(monkeypatch, base_model):
    # Family dense_bf16_gb (8.1) is the 4B; 9B dense is 18.2 GB, so 20 GB free must pick nf4.
    spec = dit._SPECS["flux.2-klein"]
    _fake_cuda_with_free_gb(monkeypatch, 20.0)
    cfg = _cfg(base_model = base_model, base_precision = "auto", mixed_precision = "bf16")
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "nf4"
    assert dit._dense_bf16_gb(spec, base_model) > 2 * spec.dense_bf16_gb


def test_auto_still_picks_bf16_for_the_klein_4b_default(monkeypatch):
    spec = dit._SPECS["flux.2-klein"]
    _fake_cuda_with_free_gb(monkeypatch, 20.0)
    cfg = _cfg(
        base_model = "black-forest-labs/FLUX.2-klein-4B",
        base_precision = "auto",
        mixed_precision = "bf16",
    )
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "bf16"


def test_the_klein_4b_bf16_band_edge_does_not_move(monkeypatch):
    # Band edge is dense_gb * 1.5: 8.1 -> 12.15 keeps int8; 7.8 -> 11.70 would flip to bf16.
    spec = dit._SPECS["flux.2-klein"]
    _fake_cuda_with_free_gb(monkeypatch, 12.0)
    cfg = _cfg(
        base_model = "black-forest-labs/FLUX.2-klein-4B",
        base_precision = "auto",
        mixed_precision = "bf16",
    )
    assert dit._resolve_base_precision(cfg, spec, "cuda") == "int8"


def test_dense_bf16_gb_keeps_every_base_without_an_override_exactly_where_it_was():
    # Only klein 9B is overridden; the shared family table differs (7.8 vs 8.1), never read through.
    for name in ("flux.1", "qwen-image", "z-image", "krea-2", "flux.2-dev", "flux.2-klein"):
        spec = dit._SPECS[name]
        for base in ("some/unknown-base", spec.family, ""):
            assert dit._dense_bf16_gb(spec, base) == spec.dense_bf16_gb
    klein = dit._SPECS["flux.2-klein"]
    for base in (
        "black-forest-labs/FLUX.2-klein-4B",
        "black-forest-labs/FLUX.2-klein-base-4B",
        "unsloth/FLUX.2-klein-4B",
    ):
        assert dit._dense_bf16_gb(klein, base) == klein.dense_bf16_gb


def test_dense_bf16_gb_survives_a_broken_lookup(monkeypatch):
    import core.inference.diffusion_auto_policy as ap

    def _boom(*_a, **_kw):
        raise RuntimeError("table unavailable")

    monkeypatch.setattr(ap, "base_repo_bf16_components_gb", _boom)
    spec = dit._SPECS["flux.2-klein"]
    assert dit._dense_bf16_gb(spec, "unsloth/FLUX.2-klein-base-9B") == pytest.approx(
        spec.dense_bf16_gb
    )


def test_has_functional_torchao_rejects_stub(monkeypatch):
    import importlib
    import types

    from core._torchao_stub import _STUB_SENTINEL

    real_import_module = importlib.import_module

    stub_quant = types.ModuleType("torchao.quantization")
    stub_quant._unsloth_stub = _STUB_SENTINEL

    def _fake_import(name, *args, **kwargs):
        if name == "torchao.quantization":
            return stub_quant
        return real_import_module(name, *args, **kwargs)

    monkeypatch.setattr(importlib, "import_module", _fake_import)
    assert common.has_functional_torchao() is False

    real_like = types.ModuleType("torchao.quantization")
    real_like.Int8WeightOnlyConfig = object
    real_like.quantize_ = lambda *a, **k: None

    def _fake_import_real(name, *args, **kwargs):
        if name == "torchao.quantization":
            return real_like
        return real_import_module(name, *args, **kwargs)

    monkeypatch.setattr(importlib, "import_module", _fake_import_real)
    assert common.has_functional_torchao() is True


def test_fp8_module_filter():
    lin = nn.Linear(64, 64)
    assert dit._fp8_module_filter(lin, "transformer_blocks.0.ff.net.0") is True
    assert dit._fp8_module_filter(lin, "transformer_blocks.0.attn.to_q.lora_A.default") is False
    assert dit._fp8_module_filter(lin, "proj_out") is False
    assert dit._fp8_module_filter(nn.Linear(30, 64), "transformer_blocks.0.ff.net.0") is False
    assert dit._fp8_module_filter(nn.LayerNorm(64), "transformer_blocks.0.norm") is False


def _real_cuda():
    import torch

    # Other suites in a worker can leave torch.cuda.is_available() spoofed True; the C call asks the driver.
    return torch.cuda.is_available() and getattr(torch._C, "_cuda_getDeviceCount", lambda: 0)() > 0


def _block_model(bias = False):
    import torch

    class Block(nn.Module):
        def __init__(self):
            super().__init__()
            self.ff = nn.Linear(64, 64, bias = bias)
            self.norm1 = nn.Module()
            self.norm1.linear = nn.Linear(64, 64 * 6, bias = True)  # AdaLN: M = batch rows

    class Model(nn.Module):
        _repeated_blocks = ["Block"]

        def __init__(self):
            super().__init__()
            self.time_mod_proj = nn.Linear(64, 64 * 6, bias = False)
            self.blocks = nn.ModuleList([Block(), Block()])
            self.final_layer = nn.Module()
            self.final_layer.linear = nn.Linear(64, 64)

    return Model().to(torch.bfloat16)


def test_float8_filters_stay_inside_the_repeated_blocks():
    m = _block_model()
    for base in (dit._fp8_module_filter, dit._mx_module_filter):
        f = dit._in_repeated_blocks(m, base)
        assert f(m.blocks[1].ff, "blocks.1.ff") is True
        assert f(m.time_mod_proj, "time_mod_proj") is False
        assert f(m.blocks[0].ff, "blocks.0.ff.lora_A.default") is False
    assert (
        dit._in_repeated_blocks(nn.Linear(64, 64), dit._fp8_module_filter) is dit._fp8_module_filter
    )


@pytest.mark.parametrize(
    "family, fqn, kept",
    [
        ("flux.1", "transformer_blocks.0.attn.to_q", True),
        ("flux.1", "transformer_blocks.0.ff.net.0.proj", True),
        ("flux.1", "transformer_blocks.0.norm1.linear", False),
        ("flux.1", "transformer_blocks.0.norm1_context.linear", False),
        ("flux.1", "single_transformer_blocks.0.norm.linear", False),
        ("flux.1", "single_transformer_blocks.0.proj_mlp", True),
        ("flux.2-klein", "single_transformer_blocks.0.attn.to_qkv_mlp_proj", True),
        ("flux.2-klein", "double_stream_modulation_img.linear", False),
        ("z-image", "layers.0.feed_forward.w1", True),
        ("z-image", "layers.0.adaLN_modulation.0", False),
        ("z-image", "noise_refiner.0.adaLN_modulation.0", False),
        ("krea-2", "transformer_blocks.0.ff.gate", True),
        ("krea-2", "time_mod_proj", False),
        ("krea-2", "final_layer.linear", False),
        ("ltx-2", "transformer_blocks.0.attn1.to_q", True),
        ("ltx-2", "transformer_blocks.0.audio_attn1.to_q", False),
        ("ltx-2", "transformer_blocks.0.audio_ff.net.0.proj", False),
        ("ltx-2", "transformer_blocks.0.video_to_audio_attn.to_k", False),
    ],
)
def test_lowp_filters_skip_small_m_linears(family, fqn, kept):
    import torch

    lin = nn.Linear(3072, 3072, bias = True).to(torch.bfloat16)
    tokens = dit._lowp_exclude_tokens(family)
    assert dit._fp8_module_filter(lin, fqn, tokens) is kept
    assert dit._mx_module_filter(lin, fqn, tokens) is kept


def test_lowp_exclusions_extend_the_int8_small_m_list():
    from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme

    for family in (None, "flux.1", "ltx-2", "krea-2"):
        tokens = dit._lowp_exclude_tokens(family)
        assert set(exclude_tokens_for_scheme("int8", family)) <= set(tokens)
        assert "final_layer" in tokens
    assert "audio" in dit._lowp_exclude_tokens("ltx-2")
    assert "audio" not in dit._lowp_exclude_tokens("flux.1")


def test_mx_input_hook_mirrors_autocast():
    import torch

    x = torch.ones(2, 4)
    assert dit._autocast_mx_input(None, (x,)) is None  # CPU / no autocast: untouched
    if not _real_cuda():
        pytest.skip("needs CUDA autocast")
    xc = x.cuda()
    assert dit._autocast_mx_input(None, (xc,)) is None
    with torch.autocast("cuda", dtype = torch.bfloat16):
        (out,) = dit._autocast_mx_input(None, (xc,))
        assert out.dtype == torch.bfloat16
        assert dit._autocast_mx_input(None, (xc.bfloat16(),)) is None


@pytest.mark.parametrize("mode", ["mxfp8"])
def test_lowp_apply_without_torchao_is_a_noop_with_warning(monkeypatch, mode):
    import sys

    for name in (
        "torchao",
        "torchao.float8",
        "torchao.quantization",
        "torchao.prototype.mx_formats",
        "torchao.prototype.moe_training.config",
    ):
        monkeypatch.setitem(sys.modules, name, None)
    m = _block_model()
    before = [type(x) for x in m.modules()]
    events = []
    apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
    assert apply(m, events.append, "flux.1") is False
    assert [type(x) for x in m.modules()] == before
    assert [e["type"] for e in events] == ["warning"] and mode in events[0]["message"]


def _fake_mx_backend(monkeypatch, *, with_linear_cls = True):
    """A torchao 0.18-shaped MX API without the GPU: records the swaps."""
    import sys
    from types import SimpleNamespace

    class _Op:
        wgrad_with_hp = True
        kernel_preference = "auto"
        scale_calculation_mode = "rceil"

    class _Recipe:
        MXFP8_RCEIL_WGRAD_WITH_HP = "hp"

    class MXFP8Linear(nn.Linear):
        pass

    quantized = []
    monkeypatch.setitem(sys.modules, "torchao.prototype.mx_formats", None)
    cfg_mod = SimpleNamespace(
        MXFP8TrainingOpConfig = SimpleNamespace(from_recipe = lambda r: _Op()),
        MXFP8TrainingRecipe = _Recipe,
    )
    monkeypatch.setitem(sys.modules, "torchao.prototype.moe_training.config", cfg_mod)
    monkeypatch.setitem(
        sys.modules,
        "torchao.prototype.moe_training.mxfp8_linear",
        SimpleNamespace(MXFP8Linear = MXFP8Linear) if with_linear_cls else None,
    )

    def quantize_(model, config, filter_fn):
        for fqn, mod in model.named_modules():
            if filter_fn(mod, fqn):
                quantized.append(fqn)

    monkeypatch.setitem(sys.modules, "torchao.quantization", SimpleNamespace(quantize_ = quantize_))
    return MXFP8Linear, quantized


def test_mxfp8_swaps_biased_and_unbiased_block_linears_once(monkeypatch):
    linear_cls, quantized = _fake_mx_backend(monkeypatch)
    m = _block_model(bias = True)
    params = [id(p) for p in m.parameters()]
    assert dit._apply_mxfp8_training(m, None, "flux.1") is True
    swapped = sorted(n for n, x in m.named_modules() if type(x) is linear_cls)
    # Biased block linears included; AdaLN (norm1.linear), top-level and final_layer stay bf16.
    assert swapped == ["blocks.0.ff", "blocks.1.ff"]
    assert m.blocks[0].ff.wgrad_with_hp is True and quantized == []
    assert [id(p) for p in m.parameters()] == params  # the Parameters stay
    hooks = len(m.blocks[0].ff._forward_pre_hooks)
    assert dit._apply_mxfp8_training(m, None, "flux.1") is True
    assert len(m.blocks[0].ff._forward_pre_hooks) == hooks == 1


def test_mxfp8_torchao_0_17_keeps_biased_linears_dense(monkeypatch):
    # Without MXFP8Linear the quantize_ weight wrapper is the only path, and it drops F.linear's bias (pytorch/ao#4846).
    _, quantized = _fake_mx_backend(monkeypatch, with_linear_cls = False)
    m = _block_model(bias = True)
    events = []
    assert dit._apply_mxfp8_training(m, events.append, "flux.1") is False
    assert quantized == [] and "no eligible linear layers" in events[0]["message"]
    m2 = _block_model(bias = False)
    assert dit._apply_mxfp8_training(m2, None, "flux.1") is True
    assert quantized == ["blocks.0.ff", "blocks.1.ff"]


def test_fp8_quantizes_each_frozen_base_weight_once():
    import torch

    from core.training.diffusion_frozen_fp8 import FrozenFp8Linear

    m = _block_model(bias = True).requires_grad_(False)
    ref = {
        fqn: mod.weight.float().clone()
        for fqn, mod in m.named_modules()
        if isinstance(mod, nn.Linear)
    }
    assert dit._convert_fp8(m, "flux.1") is True
    swapped = {fqn: mod for fqn, mod in m.named_modules() if isinstance(mod, FrozenFp8Linear)}
    # Only the repeated blocks' big linears; the AdaLN rows stay bf16 like the int8 / MX paths.
    assert sorted(swapped) == ["blocks.0.ff", "blocks.1.ff"]
    for fqn, mod in swapped.items():
        assert mod.weight.dtype == torch.float8_e4m3fn and not isinstance(mod.weight, nn.Parameter)
        assert mod._studio_lowp == "fp8" and mod.bias is not None and not mod.bias.requires_grad
        deq = mod.weight.float() * mod.weight_scale.t()
        assert ((deq - ref[fqn]).norm() / ref[fqn].norm()).item() < 0.04
    # The bf16 weight is gone: no frozen base Parameter left on a converted path, so its memory is freed.
    assert not any(n.endswith("ff.weight") for n, _ in m.named_parameters())


def test_fp8_layer_that_fails_stays_bf16_and_the_rest_convert(monkeypatch):
    import core.training.diffusion_frozen_fp8 as ff

    real = ff._quantize_weight
    calls = []

    def flaky(w, rows = 2048):
        calls.append(1)
        if len(calls) == 1:
            raise RuntimeError("CUDA out of memory")
        return real(w, rows)

    monkeypatch.setattr(ff, "_quantize_weight", flaky)
    m = _block_model().requires_grad_(False)
    events = []
    assert dit._apply_fp8_training(m, events.append, "flux.1") is True
    kinds = sorted(type(b.ff).__name__ for b in m.blocks)
    assert kinds == ["FrozenFp8Linear", "Linear"]
    assert any("1 layer(s)" in e.get("message", "") for e in events)


def test_fp8_chunked_quantization_matches_one_shot():
    import torch

    from core.training.diffusion_frozen_fp8 import _quantize_weight, _rowwise_quant

    w = (
        torch.randn(300, 64, dtype = torch.bfloat16)
        * torch.logspace(-3, 3, 300).unsqueeze(1).bfloat16()
    )
    q1, s1 = _rowwise_quant(w)
    q2, s2 = _quantize_weight(w, rows = 64)
    assert torch.equal(q1.view(torch.uint8), q2.view(torch.uint8)) and torch.equal(s1, s2)


def test_fp8_conversion_needs_no_torchao(monkeypatch):
    import sys

    for name in ("torchao", "torchao.float8", "torchao.quantization"):
        monkeypatch.setitem(sys.modules, name, None)
    m = _block_model().requires_grad_(False)
    assert dit._apply_fp8_training(m, lambda e: None, "flux.1") is True


def _lowp_gpu_ready(mode):
    import torch

    if not _real_cuda():
        return False
    need = (8, 9) if mode == "fp8" else (10, 0)
    return torch.cuda.get_device_capability() >= need


@pytest.mark.parametrize("mode", ["fp8", "mxfp8"])
@pytest.mark.parametrize("compiled", [False, True])
def test_lowp_backward_on_odd_token_counts(mode, compiled):
    """Token counts not divisible by 16 / 32 (LTX-2 192x320 = 60) raised in the frozen grad_weight GEMM."""
    import torch

    if not _lowp_gpu_ready(mode):
        pytest.skip(f"{mode} needs a capable CUDA GPU")
    pytest.importorskip("torchao")

    class Block(nn.Module):
        def __init__(self):
            super().__init__()
            self.ff = nn.Linear(256, 512, bias = True)

        def forward(self, x):
            return self.ff(x)

    class Model(nn.Module):
        _repeated_blocks = ["Block"]

        def __init__(self):
            super().__init__()
            self.blocks = nn.ModuleList([Block()])

        def forward(self, x):
            return self.blocks[0](x)

    torch.manual_seed(0)
    ref = Model().to("cuda", torch.bfloat16).requires_grad_(False)
    m = Model().to("cuda", torch.bfloat16).requires_grad_(False)
    m.load_state_dict(ref.state_dict())
    apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
    events = []
    applied = apply(m, events.append, "flux.1")
    # torchao 0.17 on torch 2.11 (the installer's pairing) refuses MX training on any GPU; the fallback is the test.
    if not applied and mode == "mxfp8" and any("unavailable" in str(e) for e in events):
        pytest.skip(f"this torch / torchao cannot run mxfp8 training: {events}")
    assert applied is True, events
    assert type(m.blocks[0].ff) is not nn.Linear
    run = torch.compile(m, fullgraph = True, dynamic = True) if compiled else m
    for tokens in (60, 240, 1008, 1024):
        x = torch.randn(1, tokens, 256, device = "cuda", requires_grad = True)
        xr = x.detach().clone().requires_grad_(True)
        with torch.autocast("cuda", dtype = torch.bfloat16):
            y = run(x)
            yr = ref(xr)
        g = torch.randn_like(yr)
        y.backward(g)
        yr.backward(g)
        rel = lambda a, b: float((a.float() - b.float()).norm() / b.float().norm())  # noqa: E731
        assert rel(y, yr) < 0.1 and rel(x.grad, xr.grad) < 0.1, (
            tokens,
            rel(y, yr),
            rel(x.grad, xr.grad),
        )
        assert m.blocks[0].ff.weight.grad is None


# ── _should_compile fp8 branch ────────────────────────────────────────────────
def test_should_compile_fp8_branch():
    cfg = _cfg(compile_transformer = "auto")
    assert dit._should_compile(cfg, False, "cuda", "fp8") is True
    assert dit._should_compile(cfg, True, "cuda", "fp8") is True
    assert dit._should_compile(_cfg(compile_transformer = "off"), False, "cuda", "fp8") is False


def test_train_precision_modes_no_cuda(monkeypatch):
    import torch
    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    assert train_precision_modes() == (["nf4"], "nf4")


def test_train_precision_modes_gates_int8_fp8_on_torchao(monkeypatch):
    # int8/mxfp8 are only advertised when torchao is FUNCTIONAL: their explicit paths import it with no fallback.
    # fp8 runs on torch's own _scaled_mm, so only the GPU decides.
    import torch

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda: True)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda: (10, 0))

    monkeypatch.setattr(common, "has_functional_torchao", lambda: False)
    modes, recommended = train_precision_modes()
    assert modes == ["nf4", "bf16", "fp8", "auto"]
    assert recommended == "auto"

    monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
    modes2, _ = train_precision_modes()
    assert modes2 == ["nf4", "bf16", "int8", "fp8", "mxfp8", "auto"]


def test_train_precision_modes_gates_dense_on_bf16_support(monkeypatch):
    import torch

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda: False)
    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda: (7, 5))
    monkeypatch.setattr(common, "has_functional_torchao", lambda: True)
    modes, recommended = train_precision_modes()
    assert modes == ["nf4"]
    assert recommended == "nf4"


def test_family_train_infos_carries_precision_fields(monkeypatch, dit_train_host):
    monkeypatch.setattr(common, "train_precision_modes", lambda: (["nf4", "bf16"], "auto"))
    monkeypatch.setattr(common, "bf16_unsupported_reason", lambda name: None)
    infos = {i["name"]: i for i in common.family_train_infos()}

    flux = infos["flux.1"]
    assert flux["precision_modes"] == ["nf4", "bf16"]
    assert flux["recommended_precision"] == "auto"
    assert flux["supports_compile"] is True

    sdxl = infos["sdxl"]
    assert sdxl["precision_modes"] == []
    assert sdxl["recommended_precision"] == "nf4"
    assert sdxl["supports_compile"] is True


def test_request_model_base_precision():
    req = DiffusionTrainingStartRequest(base_model = "x", data_dir = "d", output_dir = "o")
    assert req.base_precision == "nf4"

    assert (
        DiffusionTrainingStartRequest(
            base_model = "x", data_dir = "d", output_dir = "o", base_precision = "fp8"
        ).base_precision
        == "fp8"
    )

    with pytest.raises(Exception):
        DiffusionTrainingStartRequest(
            base_model = "x", data_dir = "d", output_dir = "o", base_precision = "int4"
        )

    cfg = _config_from_dict(
        {
            "base_model": _FLUX_DENSE,
            "data_dir": "d",
            "output_dir": "o",
            "base_precision": "bf16",
        }
    )
    assert cfg.base_precision == "bf16"


def test_assert_trusted_base_model_rejects_local_non_pipeline(tmp_path):
    bad = tmp_path / "bare-base"
    bad.mkdir()
    with pytest.raises(ValueError, match = "model_index.json"):
        common._assert_trusted_base_model(str(bad))
    manifest = (
        '{"_class_name":"DiffusionPipeline","transformer":["diffusers","Transformer2DModel"]}'
    )
    (bad / "model_index.json").write_text(manifest)
    (bad / "transformer").mkdir()
    (bad / "transformer" / "config.json").write_text("{}")
    (bad / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
    common._assert_trusted_base_model(str(bad))
    with pytest.raises(ValueError, match = "untrusted"):
        common._assert_trusted_base_model("evil/base")


def test_quoted_local_base_is_unquoted_before_the_trust_gate(tmp_path):
    # #9605: Windows "Copy as path" quotes the folder.
    base = tmp_path / "my sdxl"
    base.mkdir()
    (base / "model_index.json").write_text(
        '{"_class_name":"DiffusionPipeline","transformer":["diffusers","Transformer2DModel"]}'
    )
    (base / "transformer").mkdir()
    (base / "transformer" / "config.json").write_text("{}")
    (base / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
    for pasted in (f'"{base}"', f"'{base}'", f'  "{base}" '):
        req = DiffusionTrainingStartRequest(base_model = pasted, data_dir = "d", output_dir = "o")
        assert req.base_model == str(base)
        common._assert_trusted_base_model(req.base_model)  # no raise
    for written in ("unsloth/sdxl-base", str(base), '"half', 'a"b"', "\"x'"):
        req = DiffusionTrainingStartRequest(base_model = written, data_dir = "d", output_dir = "o")
        assert req.base_model == written


def test_single_file_training_base_names_the_checkpoint(tmp_path):
    # #9605: still refused, but the refusal says why, echoing only the caller's own path.
    models = tmp_path / "stable-diffusion"
    models.mkdir()
    ckpt = models / "sd_xl_base_1.0.safetensors"
    ckpt.write_bytes(b"x")
    for base, what in (
        (models, "holds single-file checkpoints"),
        (ckpt, "is a single-file checkpoint"),
    ):
        with pytest.raises(ValueError, match = what) as err:
            common._assert_trusted_base_model(str(base))
        assert f"'{base}' {what}" in str(err.value)
    with pytest.raises(ValueError) as err:
        common._assert_trusted_base_model(str(models))
    assert ckpt.name not in str(err.value)
    # A macOS AppleDouble sidecar is not a checkpoint.
    sidecar = tmp_path / "sidecar-only"
    sidecar.mkdir()
    (sidecar / "._sd_xl.safetensors").write_bytes(b"\x00\x05\x16\x07" + b"\x00" * 28)
    # Only the wrapper goes: a name that really ends in a space keeps it.
    req = DiffusionTrainingStartRequest(base_model = f'"{models} "', data_dir = "d", output_dir = "o")
    assert req.base_model == f"{models} "
    # The SDXL repo ships a root checkpoint beside model_index.json.
    component = tmp_path / "unet"
    component.mkdir()
    (component / "config.json").write_text("{}")
    (component / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
    partial = tmp_path / "partial-sdxl"
    partial.mkdir()
    (partial / "model_index.json").write_text(
        '{"_class_name":"StableDiffusionXLPipeline","unet":["diffusers","UNet2DConditionModel"]}'
    )
    (partial / "sd_xl_base_1.0.safetensors").write_bytes(b"x")
    lora = tmp_path / "my_lora"
    lora.mkdir()
    (lora / "pytorch_lora_weights.safetensors").write_bytes(b"x")
    for base in (component, partial, lora, sidecar, tmp_path / "empty"):
        base.mkdir(exist_ok = True)
        with pytest.raises(ValueError, match = "not a diffusers pipeline directory"):
            common._assert_trusted_base_model(str(base))


def test_dit_accelerator_missing_reason_and_info_hide_train_without_a_gpu(monkeypatch):
    import torch

    from core.training.diffusion_train_common import (
        _DIT_TRAIN_FAMILIES,
        dit_accelerator_missing_reason,
        family_train_infos,
    )

    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    monkeypatch.setattr(torch.xpu, "is_available", lambda: False)
    monkeypatch.setattr(torch.backends.mps, "is_available", lambda: False)
    assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")
    assert dit_accelerator_missing_reason("sdxl") is None
    assert dit_accelerator_missing_reason("") is None

    infos = {info["name"]: info for info in family_train_infos()}
    for name, info in infos.items():
        if name in _DIT_TRAIN_FAMILIES:
            assert info["precision_modes"] == []
            assert "GPU" in info["vram_note"]
            assert info["supports_compile"] is False
        else:
            assert info["precision_modes"] != [] or name not in _DIT_TRAIN_FAMILIES

    # MPS alone does not clear it: the trainer would run on the CPU, where the 4-bit load refuses.
    monkeypatch.setattr(torch.backends.mps, "is_available", lambda: True)
    assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")
    monkeypatch.setattr(torch.xpu, "is_available", lambda: True)
    assert dit_accelerator_missing_reason("flux.1") is None


def test_dit_accelerator_gate_survives_a_torch_without_every_probe(monkeypatch):
    """torch.mps.is_available() is absent before torch 2.5 but the floor is 2.4; a shared try/except
    would turn that AttributeError into no block, letting CPU-only hosts pass."""
    import torch

    from core.training.diffusion_train_common import dit_accelerator_missing_reason

    class _Missing:
        """A torch.mps that predates is_available()."""

    class _Raising:
        @staticmethod
        def is_available():
            raise RuntimeError("driver not initialised")

    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
    monkeypatch.setattr(torch, "xpu", _Raising)
    monkeypatch.setattr(torch.backends, "mps", _Missing)
    assert "GPU" in (dit_accelerator_missing_reason("flux.1") or "")

    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
    assert dit_accelerator_missing_reason("flux.1") is None


@pytest.mark.parametrize("mode", ["fp8", "mxfp8"])
def test_lowp_probe_failure_falls_back_before_touching_the_model(monkeypatch, mode):
    # An arch whose float8 / MX GEMM fails (unverified sm89 / sm120 paths) must fall back to bf16 at load, not mid-run.
    def broken_probe(convert, transformer):
        raise RuntimeError("CUBLAS_STATUS_NOT_SUPPORTED")

    monkeypatch.setattr(dit, "_probe_lowp", broken_probe)
    m = _block_model()
    before = [type(x) for x in m.modules()]
    events = []
    apply = dit._apply_fp8_training if mode == "fp8" else dit._apply_mxfp8_training
    assert apply(m, events.append, "flux.1") is False
    assert [type(x) for x in m.modules()] == before
    assert not any(getattr(x, "_studio_lowp", None) for x in m.modules())
    assert "CUBLAS_STATUS_NOT_SUPPORTED" in events[0]["message"] and mode in events[0]["message"]


def test_lowp_probe_skips_off_cuda_and_raises_on_a_failing_gemm():
    import torch

    calls = []
    dit._probe_lowp(lambda probe: calls.append(probe), _block_model())  # CPU model: no probe
    assert calls == []
    if not _real_cuda():
        pytest.skip("needs CUDA")

    def failing_convert(probe):
        probe.ff.forward = lambda x: (_ for _ in ()).throw(RuntimeError("scaled_mm unsupported"))

    with pytest.raises(RuntimeError, match = "scaled_mm unsupported"):
        dit._probe_lowp(failing_convert, _block_model().cuda())
    model = _block_model().cuda()
    cpu_state, cuda_state = torch.get_rng_state(), torch.cuda.get_rng_state()
    dit._probe_lowp(lambda probe: None, model)  # a working GEMM passes
    # The seed is set before conversion: the probe must not move the training draws.
    assert torch.equal(torch.get_rng_state(), cpu_state)
    assert torch.equal(torch.cuda.get_rng_state(), cuda_state)


@pytest.mark.parametrize(
    "vendor",
    [
        "black-forest-labs/FLUX.1-dev",
        "black-forest-labs/FLUX.2-dev",
        "black-forest-labs/FLUX.2-klein-base-9B",
    ],
)
def test_training_access_facts_follow_no_token_mirror_with_cached_vendor_shard(
    monkeypatch, tmp_path, vendor
):
    from core.inference import diffusion_families as families
    from utils import hf_cache_settings

    monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
    snapshot = (
        tmp_path / ("models--" + vendor.replace("/", "--")) / "snapshots" / "rev" / "transformer"
    )
    snapshot.mkdir(parents = True)
    (snapshot / "diffusion_pytorch_model-00001-of-00003.safetensors").write_bytes(b"x")
    monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(tmp_path))
    assert families._upstream_is_cached(vendor)

    mirror = families.mirror_repo(vendor)
    facts = common._training_mirror_access_specs(vendor)[vendor]
    fetched = _cfg(base_model = vendor, hf_token = "").normalized().fetch_base_model
    assert fetched == mirror
    assert facts["gated"] is False
    assert mirror in facts["note"]