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.

27.0 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

"""Text-encoder quantisation tests, hermetic: torch and the casters are stubbed in sys.modules."""

from __future__ import annotations

import sys
import types

import pytest

import core.inference.diffusion_precision as dp
from core.inference.diffusion_precision import (
    _cast_fp8_dynamic,
    TE_QUANT_FP8,
    TE_QUANT_FP8_DYNAMIC,
    TE_QUANT_INT8,
    TE_QUANT_MODES,
    TE_QUANT_NVFP4,
    _cast_int8_selective,
    _cast_nvfp4,
    _keep_bf16_block_fqns,
    effective_te_quant,
    normalize_te_quant,
    resolve_te_quant_request,
    te_quant_is_auto,
    quantize_text_encoders,
    te_quant_supported,
    te_quant_unsupported_reason,
)


def _target(
    *,
    device = "cuda",
    dtype = "bfloat16",
    cc = (10, 0),
):
    return types.SimpleNamespace(device = device, dtype = dtype, _cc = cc)


def _stub_torch(
    monkeypatch,
    *,
    with_fp8 = True,
    cc = (10, 0),
    nvfp4_config = True,
):
    monkeypatch.setattr(dp, "nvfp4_weight_only_importable", lambda: nvfp4_config)
    torch = types.ModuleType("torch")
    torch.bfloat16 = "bfloat16"
    torch.float16 = "float16"
    if with_fp8:
        torch.float8_e4m3fn = "float8_e4m3fn"
    # _cast_fp8 skips nn.Embedding and _keep_bf16_block_fqns walks nn.ModuleList, so stub both
    torch.nn = types.SimpleNamespace(
        Embedding = type("Embedding", (), {}),
        ModuleList = type("ModuleList", (list,), {}),
    )
    torch.cuda = types.SimpleNamespace(get_device_capability = lambda *a: cc)
    monkeypatch.setitem(sys.modules, "torch", torch)
    return torch


def _stub_casters(monkeypatch, recorder):
    hooks = types.ModuleType("diffusers.hooks")
    casting = types.ModuleType("diffusers.hooks.layerwise_casting")
    casting.DEFAULT_SKIP_MODULES_PATTERN = ("norm",)
    hooks.apply_layerwise_casting = lambda module, **kw: recorder.append(("fp8", module))
    monkeypatch.setitem(sys.modules, "diffusers.hooks", hooks)
    monkeypatch.setitem(sys.modules, "diffusers.hooks.layerwise_casting", casting)
    # nvfp4 quantize_ receives a filter_fn; accept and ignore it
    tq = types.ModuleType("torchao.quantization")
    tq.quantize_ = lambda module, config, filter_fn = None: recorder.append(("nvfp4", module))
    mx = types.ModuleType("torchao.prototype.mx_formats")
    mx.NVFP4WeightOnlyConfig = lambda: "nvfp4cfg"
    monkeypatch.setitem(sys.modules, "torchao.quantization", tq)
    monkeypatch.setitem(sys.modules, "torchao.prototype.mx_formats", mx)
    dtq = types.ModuleType("core.inference.diffusion_transformer_quant")
    dtq.DEFAULT_MIN_LINEAR_FEATURES = 512
    dtq.make_filter_fn = lambda min_features, exclude = (), *, require_bf16 = False: (
        lambda module, fqn = "": True
    )
    dtq._quiet_config = lambda cls, **kw: cls(**kw)
    monkeypatch.setitem(sys.modules, "core.inference.diffusion_transformer_quant", dtq)


def test_normalize_te_quant():
    assert normalize_te_quant(None) is None
    assert normalize_te_quant("") is None
    assert normalize_te_quant("none") is None
    assert normalize_te_quant("FP8") == TE_QUANT_FP8
    assert normalize_te_quant("NVFP4") == TE_QUANT_NVFP4
    assert normalize_te_quant("int8") == TE_QUANT_INT8
    assert normalize_te_quant("FP8-Dynamic") == TE_QUANT_FP8_DYNAMIC
    with pytest.raises(ValueError):
        normalize_te_quant("int2")


def test_fp8_supported_requires_cuda_bf16_and_fp8(monkeypatch):
    _stub_torch(monkeypatch, with_fp8 = True)
    assert te_quant_supported(_target(), TE_QUANT_FP8) is True
    assert te_quant_supported(_target(device = "cpu"), TE_QUANT_FP8) is False
    assert te_quant_supported(_target(dtype = "float16"), TE_QUANT_FP8) is False


@pytest.mark.parametrize("cc", [(8, 0), (8, 6), (8, 9), (9, 0), (10, 0), (12, 0)])
def test_nvfp4_supported_without_fp4_cores(monkeypatch, cc):
    _stub_torch(monkeypatch, cc = cc)
    assert te_quant_supported(_target(cc = cc), TE_QUANT_NVFP4) is True


def test_nvfp4_supported_requires_cuda_bf16_and_fp8_dtype(monkeypatch):
    _stub_torch(monkeypatch, cc = (8, 6))
    assert te_quant_supported(_target(device = "cpu"), TE_QUANT_NVFP4) is False
    # pre-Ampere resolves float16, which torchao's nvfp4 quantizer rejects
    assert te_quant_supported(_target(dtype = "float16"), TE_QUANT_NVFP4) is False
    _stub_torch(monkeypatch, with_fp8 = False, cc = (8, 6))
    assert te_quant_supported(_target(), TE_QUANT_NVFP4) is False


def test_nvfp4_unsupported_when_torchao_lacks_the_weight_only_config(monkeypatch):
    # older Studio installs keep torchao 0.14 with torch <= 2.8, which lacks NVFP4WeightOnlyConfig
    _stub_torch(monkeypatch, cc = (8, 6), nvfp4_config = False)
    assert te_quant_supported(_target(cc = (8, 6)), TE_QUANT_NVFP4) is False
    assert te_quant_supported(_target(cc = (8, 6)), TE_QUANT_INT8) is True


def test_int8_supported_requires_sm80(monkeypatch):
    # int8 tensor cores (torch._int_mm) need sm_80+
    _stub_torch(monkeypatch, cc = (8, 0))
    assert te_quant_supported(_target(), TE_QUANT_INT8) is True
    _stub_torch(monkeypatch, cc = (7, 5))
    assert te_quant_supported(_target(), TE_QUANT_INT8) is False
    # all modes also require CUDA and bf16
    _stub_torch(monkeypatch, cc = (8, 0))
    assert te_quant_supported(_target(device = "cpu"), TE_QUANT_INT8) is False


def test_fp8_dynamic_supported_requires_sm89_and_fp8(monkeypatch):
    # fp8 GEMM (torch._scaled_mm) needs sm_89+
    _stub_torch(monkeypatch, cc = (8, 9))
    assert te_quant_supported(_target(), TE_QUANT_FP8_DYNAMIC) is True
    _stub_torch(monkeypatch, cc = (9, 0))
    assert te_quant_supported(_target(), TE_QUANT_FP8_DYNAMIC) is True
    _stub_torch(monkeypatch, cc = (8, 0))
    assert te_quant_supported(_target(), TE_QUANT_FP8_DYNAMIC) is False
    _stub_torch(monkeypatch, with_fp8 = False, cc = (9, 0))
    assert te_quant_supported(_target(), TE_QUANT_FP8_DYNAMIC) is False


def test_quantize_disabled_returns_none(monkeypatch):
    _stub_torch(monkeypatch)
    pipe = types.SimpleNamespace(text_encoder = object())
    assert quantize_text_encoders(pipe, _target(), mode = None).mode is None
    assert quantize_text_encoders(pipe, _target(), mode = "none").mode is None


def test_quantize_fp8_casts_all_encoders(monkeypatch):
    _stub_torch(monkeypatch)
    recorder: list = []
    _stub_casters(monkeypatch, recorder)
    te1, te3 = object(), object()
    pipe = types.SimpleNamespace(text_encoder = te1, text_encoder_2 = None, text_encoder_3 = te3)
    outcome = quantize_text_encoders(pipe, _target(), mode = "fp8")
    assert outcome.mode == TE_QUANT_FP8
    assert outcome.status == "applied"
    assert recorder == [("fp8", te1), ("fp8", te3)]


def test_quantize_nvfp4_uses_torchao(monkeypatch):
    _stub_torch(monkeypatch, cc = (10, 0))
    recorder: list = []
    _stub_casters(monkeypatch, recorder)
    te = object()
    pipe = types.SimpleNamespace(text_encoder = te)
    outcome = quantize_text_encoders(pipe, _target(), mode = "nvfp4")
    assert outcome.mode == TE_QUANT_NVFP4
    assert recorder == [("nvfp4", te)]


def test_quantize_nvfp4_engages_on_ampere(monkeypatch):
    _stub_torch(monkeypatch, cc = (8, 6))
    recorder: list = []
    _stub_casters(monkeypatch, recorder)
    te = object()
    pipe = types.SimpleNamespace(text_encoder = te)
    outcome = quantize_text_encoders(pipe, _target(cc = (8, 6)), mode = "nvfp4")
    assert outcome.mode == TE_QUANT_NVFP4 and outcome.status == "applied"
    assert recorder == [("nvfp4", te)]


def test_quantize_nvfp4_unsupported_on_float16_is_noop(monkeypatch):
    _stub_torch(monkeypatch, cc = (7, 5))
    recorder: list = []
    _stub_casters(monkeypatch, recorder)
    pipe = types.SimpleNamespace(text_encoder = object())
    outcome = quantize_text_encoders(pipe, _target(dtype = "float16", cc = (7, 5)), mode = "nvfp4")
    assert outcome.mode is None
    assert outcome.status == "unsupported"
    assert "'nvfp4' needs an NVIDIA GPU that runs bf16" in outcome.reason
    assert recorder == []


def test_nvfp4_weight_only_probe_reads_the_installed_torchao(monkeypatch):
    def _rejects_this_torch():
        raise RuntimeError("requires PyTorch 2.8 or later")

    probe = dp.nvfp4_weight_only_importable.__wrapped__
    tq = types.ModuleType("core.inference.diffusion_transformer_quant")
    tq._quiet_config = lambda config_cls, **kwargs: config_cls(**kwargs)
    monkeypatch.setitem(sys.modules, "core.inference.diffusion_transformer_quant", tq)
    mx = types.ModuleType("torchao.prototype.mx_formats")
    monkeypatch.setitem(sys.modules, "torchao", types.ModuleType("torchao"))
    monkeypatch.setitem(sys.modules, "torchao.prototype", types.ModuleType("torchao.prototype"))
    monkeypatch.setitem(sys.modules, "torchao.prototype.mx_formats", mx)
    assert probe() is False
    mx.NVFP4WeightOnlyConfig = _rejects_this_torch
    assert probe() is False
    mx.NVFP4WeightOnlyConfig = lambda: "nvfp4cfg"
    assert probe() is True


@pytest.mark.parametrize("mode", TE_QUANT_MODES)
def test_every_mode_has_an_unsupported_reason(mode):
    reason = te_quant_unsupported_reason(mode)
    assert f"'{mode}' needs " in reason and "Blackwell" not in reason


def test_quantize_tolerates_caster_failure(monkeypatch):
    _stub_torch(monkeypatch)
    hooks = types.ModuleType("diffusers.hooks")
    casting = types.ModuleType("diffusers.hooks.layerwise_casting")
    casting.DEFAULT_SKIP_MODULES_PATTERN = ("norm",)

    def _boom(module, **kwargs):
        raise RuntimeError("fp8 unsupported for this layer")

    hooks.apply_layerwise_casting = _boom
    monkeypatch.setitem(sys.modules, "diffusers.hooks", hooks)
    monkeypatch.setitem(sys.modules, "diffusers.hooks.layerwise_casting", casting)
    pipe = types.SimpleNamespace(text_encoder = object())
    outcome = quantize_text_encoders(pipe, _target(), mode = "fp8")
    assert outcome.mode is None and outcome.status == "fell_back"


def test_quantize_int8_uses_family_keep_bf16_schedule(monkeypatch):
    # qwen-image keeps the first and last 6 blocks bf16
    _stub_torch(monkeypatch, cc = (10, 0))
    calls: list = []
    monkeypatch.setattr(
        dp, "_cast_int8_selective", lambda enc, tgt, first, last: calls.append((enc, first, last))
    )
    # A family with a schedule and no hosted int8 ConvRot file (qwen-image now hosts one, so it never takes this path).
    monkeypatch.setitem(dp._TE_INT8_SKIP, "scheduled-family", (6, 6))
    te = object()
    pipe = types.SimpleNamespace(text_encoder = te)
    outcome = quantize_text_encoders(pipe, _target(), mode = "int8", family = "scheduled-family")
    assert outcome.mode == TE_QUANT_INT8
    assert outcome.status == "applied"
    assert calls == [(te, 6, 6)]


def test_int8_never_takes_the_torchao_cast_over_a_pre_cast_encoder(monkeypatch):
    # qwen-image has a keep-bf16 schedule AND a hosted int8 ConvRot file: an int8 request whose encoder came from a
    # pre-cast fp8 file is the (idempotent) fp8 cast, never torchao on top of fp8 storage.
    _stub_torch(monkeypatch, cc = (10, 0))
    monkeypatch.setattr(dp, "_cast_int8_selective", lambda *a: pytest.fail("torchao int8 cast"))
    fp8_calls: list = []
    monkeypatch.setattr(dp, "_cast_fp8", lambda enc, tgt: fp8_calls.append(enc))
    te = types.SimpleNamespace(_unsloth_te_prequant_scheme = "fp8")
    outcome = quantize_text_encoders(
        types.SimpleNamespace(text_encoder = te), _target(), mode = "int8", family = "qwen-image"
    )
    assert (outcome.mode, outcome.status) == (TE_QUANT_FP8, "fell_back")
    assert "int8 ConvRot text encoder is not available" in outcome.reason
    assert fp8_calls == [te]


def test_quantize_int8_unknown_family_falls_back_to_fp8(monkeypatch):
    # no int8 schedule: fall back to layerwise fp8, never full int8
    _stub_torch(monkeypatch, cc = (10, 0))
    int8_calls: list = []
    fp8_calls: list = []
    monkeypatch.setattr(dp, "_cast_int8_selective", lambda *a: int8_calls.append(a))
    monkeypatch.setattr(dp, "_cast_fp8", lambda enc, tgt: fp8_calls.append(enc))
    te = object()
    pipe = types.SimpleNamespace(text_encoder = te)
    outcome = quantize_text_encoders(pipe, _target(), mode = "int8", family = "wan-umt5")
    assert outcome.mode == TE_QUANT_FP8
    assert outcome.status == "fell_back"
    assert "no measured keep-bf16 schedule" in outcome.reason and "wan-umt5" in outcome.reason
    assert int8_calls == [] and fp8_calls == [te]


def test_quantize_fp8_dynamic_uses_compute_caster(monkeypatch):
    _stub_torch(monkeypatch, cc = (9, 0))
    calls: list = []
    monkeypatch.setattr(dp, "_cast_fp8_dynamic", lambda enc, tgt: calls.append(enc))
    te = object()
    pipe = types.SimpleNamespace(text_encoder = te)
    outcome = quantize_text_encoders(pipe, _target(), mode = "fp8_dynamic")
    assert outcome.mode == TE_QUANT_FP8_DYNAMIC
    assert calls == [te]


def test_quantize_int8_unsupported_hw_is_noop(monkeypatch):
    _stub_torch(monkeypatch, cc = (7, 5))
    monkeypatch.setattr(dp, "_cast_int8_selective", lambda *a: pytest.fail("must not cast"))
    pipe = types.SimpleNamespace(text_encoder = object())
    assert quantize_text_encoders(pipe, _target(), mode = "int8", family = "qwen-image").mode is None


def test_quantize_te_skips_torchao_modes_under_offload(monkeypatch):
    # torchao subclasses reject Module.to() used by offload hooks; the casters fail if invoked
    _stub_torch(monkeypatch, cc = (10, 0))
    monkeypatch.setattr(
        dp, "_cast_fp8_dynamic", lambda *a: pytest.fail("torchao caster must not run")
    )
    monkeypatch.setattr(dp, "_cast_nvfp4", lambda *a: pytest.fail("torchao caster must not run"))
    monkeypatch.setattr(
        dp, "_cast_int8_selective", lambda *a: pytest.fail("torchao caster must not run")
    )
    pipe = types.SimpleNamespace(text_encoder = object())
    skipped = quantize_text_encoders(pipe, _target(), mode = "fp8_dynamic", offload_active = True)
    assert skipped.mode is None and skipped.status == "unsupported"
    assert "offload" in skipped.reason
    assert quantize_text_encoders(pipe, _target(), mode = "nvfp4", offload_active = True).mode is None
    assert (
        quantize_text_encoders(
            pipe, _target(), mode = "int8", family = "qwen-image", offload_active = True
        ).mode
        is None
    )
    fp8_calls: list = []
    monkeypatch.setattr(dp, "_cast_fp8", lambda enc, tgt: fp8_calls.append(enc))
    assert (
        quantize_text_encoders(pipe, _target(), mode = "fp8", offload_active = True).mode
        == TE_QUANT_FP8
    )
    assert len(fp8_calls) == 1


def test_keep_bf16_block_fqns_selects_first_and_last(monkeypatch):
    torch = _stub_torch(monkeypatch)
    module_list = torch.nn.ModuleList
    layers = module_list([object() for _ in range(10)])
    short = module_list([object() for _ in range(4)])
    enc = types.SimpleNamespace()
    enc.named_modules = lambda: [("", enc), ("model.layers", layers), ("aux.blocks", short)]
    keep = _keep_bf16_block_fqns(enc, 3, 2)
    assert keep == {
        "model.layers.0",
        "model.layers.1",
        "model.layers.2",
        "model.layers.8",
        "model.layers.9",
    }


def _stub_transformer_quant(monkeypatch, captured):
    dtq = types.ModuleType("core.inference.diffusion_transformer_quant")
    dtq.TQ_INT8 = "int8"
    dtq.TQ_FP8 = "fp8"
    dtq.DEFAULT_MIN_LINEAR_FEATURES = 512
    dtq._make_quant_config = lambda scheme, *a, **k: f"cfg:{scheme}"
    dtq._quiet_config = lambda cls, **kw: cls(**kw)
    dtq.exclude_tokens_for_scheme = lambda scheme: ("modulation",)

    def _make_filter_fn(
        min_features,
        exclude_name_tokens = (),
        *,
        require_bf16 = False,
    ):
        def _f(module, fqn = ""):
            return not any(tok in fqn for tok in exclude_name_tokens)

        return _f

    dtq.make_filter_fn = _make_filter_fn
    monkeypatch.setitem(sys.modules, "core.inference.diffusion_transformer_quant", dtq)

    tq = types.ModuleType("torchao.quantization")

    def _quantize_(
        module,
        config,
        filter_fn = None,
    ):
        captured["config"] = config
        captured["filter_fn"] = filter_fn

    tq.quantize_ = _quantize_
    monkeypatch.setitem(sys.modules, "torchao.quantization", tq)
    mx = types.ModuleType("torchao.prototype.mx_formats")
    mx.NVFP4WeightOnlyConfig = lambda: "nvfp4cfg"
    monkeypatch.setitem(sys.modules, "torchao.prototype.mx_formats", mx)


def test_int8_filter_keeps_blocks_and_towers_dense(monkeypatch):
    torch = _stub_torch(monkeypatch)
    captured: dict = {}
    _stub_transformer_quant(monkeypatch, captured)
    layers = torch.nn.ModuleList([object() for _ in range(8)])
    enc = types.SimpleNamespace(_keep_in_fp32_modules = ["wo"])
    enc.named_modules = lambda: [("model.layers", layers)]

    _cast_int8_selective(enc, _target(), 3, 0)
    assert captured["config"] == "cfg:int8"
    ff = captured["filter_fn"]
    assert ff(object(), "model.layers.0.self_attn.q_proj") is False
    assert ff(object(), "model.layers.2.mlp.gate_proj") is False
    assert ff(object(), "model.layers.5.self_attn.q_proj") is True
    assert ff(object(), "visual.blocks.0.attn.qkv") is False
    assert ff(object(), "lm_head") is False
    assert ff(object(), "model.decoder.wo") is False


def test_nvfp4_filter_keeps_vision_tower_dense(monkeypatch):
    # 4-bit Qwen2.5-VL vision tower degrades edit conditioning, so nvfp4 must exclude it
    _stub_torch(monkeypatch)
    captured: dict = {}
    _stub_transformer_quant(monkeypatch, captured)
    enc = types.SimpleNamespace(_keep_in_fp32_modules = ["wo"])

    _cast_nvfp4(enc, _target())

    assert captured["config"] == "nvfp4cfg"
    ff = captured["filter_fn"]
    assert ff is not None
    assert ff(object(), "visual.blocks.0.attn.qkv") is False
    assert ff(object(), "vision_tower.encoder.layers.0.mlp.fc1") is False
    assert ff(object(), "lm_head") is False
    assert ff(object(), "model.decoder.wo") is False
    assert ff(object(), "model.layers.5.self_attn.q_proj") is True


class _FakeAmaxVec:
    def __init__(self, vals):
        self._vals = vals

    def __eq__(self, other):  # noqa: PLW0642 -- tensor-style elementwise compare
        return _FakeAmaxVec([v == other for v in self._vals])

    def any(self):
        return _FakeScalar(any(self._vals))


class _FakeScalar:
    def __init__(self, v):
        self._v = v

    def item(self):
        return self._v


class _FakeWeight:
    """Tensor-shaped stand-in supporting the exact chain the guard runs:
    ``weight.abs().amax(dim = -1) == 0 -> .any().item()``."""

    ndim = 2

    def __init__(self, rows):
        self._rows = rows

    def abs(self):
        return _FakeWeight([[abs(v) for v in r] for r in self._rows])

    def amax(self, dim = -1):
        return _FakeAmaxVec([max(r) for r in self._rows])


def test_weight_zero_output_row_detection():
    # a zero output row NaNs torchao per-row fp8 (0/0); SDXL text_encoder_2 ships one
    zero_row = types.SimpleNamespace(weight = _FakeWeight([[0.1, 0.2], [0.0, 0.0]]))
    dense = types.SimpleNamespace(weight = _FakeWeight([[0.1, 0.2], [0.3, 0.0]]))
    assert dp._weight_has_zero_output_row(zero_row) is True
    assert dp._weight_has_zero_output_row(dense) is False
    w3 = _FakeWeight([[1.0]])
    w3.ndim = 3
    assert dp._weight_has_zero_output_row(types.SimpleNamespace(weight = w3)) is False
    assert dp._weight_has_zero_output_row(types.SimpleNamespace()) is False

    class _Boom:
        @property
        def weight(self):
            raise RuntimeError("meta tensor")

    assert dp._weight_has_zero_output_row(_Boom()) is False


def test_fp8_dynamic_filter_skips_zero_row_linear(monkeypatch):
    # only the zero-row Linear stays dense; a family-wide deny would forfeit the win
    _stub_torch(monkeypatch)
    captured: dict = {}
    _stub_transformer_quant(monkeypatch, captured)
    enc = types.SimpleNamespace(_keep_in_fp32_modules = [])

    dp._cast_fp8_dynamic(enc, _target())

    ff = captured["filter_fn"]
    dead = types.SimpleNamespace(weight = _FakeWeight([[0.5, 0.5], [0.0, 0.0]]))
    live = types.SimpleNamespace(weight = _FakeWeight([[0.5, 0.5], [0.5, 0.5]]))
    assert ff(dead, "text_model.encoder.layers.2.self_attn.out_proj") is False
    assert ff(live, "text_model.encoder.layers.2.mlp.fc1") is True


def test_quantize_partial_cast_is_reported_as_a_mixture(monkeypatch):
    # a partial cast still engages the mode, so loaders must not report it as applied
    _stub_torch(monkeypatch)
    good, bad = object(), object()

    def _caster(enc, tgt):
        if enc is bad:
            raise RuntimeError("fp8 unsupported for this layer")

    monkeypatch.setattr(dp, "_cast_fp8", _caster)
    pipe = types.SimpleNamespace(text_encoder = good, text_encoder_2 = bad)
    outcome = quantize_text_encoders(pipe, _target(), mode = "fp8")
    assert outcome.mode == TE_QUANT_FP8
    assert outcome.partial is True
    assert outcome.status == "fell_back"
    assert "text_encoder_2" in outcome.reason


def test_quantize_full_cast_is_not_partial(monkeypatch):
    _stub_torch(monkeypatch)
    monkeypatch.setattr(dp, "_cast_fp8", lambda enc, tgt: None)
    pipe = types.SimpleNamespace(text_encoder = object(), text_encoder_2 = object())
    outcome = quantize_text_encoders(pipe, _target(), mode = "fp8")
    assert outcome.partial is False and outcome.status == "applied"


def test_int8_without_a_schedule_reports_fp8_as_the_effective_mode():
    # unscheduled families run int8 as layerwise fp8 (no torchao), so gate on the effective mode
    assert effective_te_quant(TE_QUANT_INT8, "z-image-turbo") == TE_QUANT_FP8
    assert effective_te_quant(TE_QUANT_INT8, None) == TE_QUANT_FP8
    # Int8 ConvRot loads as plain fp8 tensors, so gate on fp8 even where keep-bf16 exists.
    assert effective_te_quant(TE_QUANT_INT8, "qwen-image") == TE_QUANT_FP8
    assert effective_te_quant(TE_QUANT_INT8, "Flux.2-Dev") == TE_QUANT_FP8
    # Every other mode is its own effective mode, and absent stays absent.
    assert effective_te_quant(TE_QUANT_FP8_DYNAMIC, "z-image-turbo") == TE_QUANT_FP8_DYNAMIC
    assert effective_te_quant(None, "qwen-image") is None


def test_nvfp4_te_cast_builds_its_config_through_quiet_config(monkeypatch):
    """NVFP4 has no set_inductor_config knob, so the risk of routing it through _quiet_config is a TypeError."""
    _stub_torch(monkeypatch, cc = (10, 0))
    captured: dict = {}
    _stub_transformer_quant(monkeypatch, captured)
    seen: list = []
    dtq = sys.modules["core.inference.diffusion_transformer_quant"]
    dtq._quiet_config = lambda cls, **kw: seen.append((cls, kw)) or cls(**kw)
    outcome = quantize_text_encoders(
        types.SimpleNamespace(text_encoder = object()), _target(), mode = "nvfp4"
    )
    assert outcome.mode == TE_QUANT_NVFP4
    assert len(seen) == 1 and seen[0][1] == {}
    assert captured["config"] == "nvfp4cfg"


def test_int8_and_fp8_dynamic_te_casts_reuse_the_quiet_factory(monkeypatch):
    torch = _stub_torch(monkeypatch, cc = (10, 0))
    captured: dict = {}
    _stub_transformer_quant(monkeypatch, captured)
    layers = torch.nn.ModuleList([object() for _ in range(8)])
    enc = types.SimpleNamespace(_keep_in_fp32_modules = ["wo"])
    enc.named_modules = lambda: [("model.layers", layers)]
    _cast_int8_selective(enc, _target(), 3, 0)
    assert captured["config"] == "cfg:int8"
    _cast_fp8_dynamic(enc, _target())
    assert captured["config"] == "cfg:fp8"


def test_no_torchao_config_is_constructed_outside_quiet_config():
    """Every torchao config must be built through ``_quiet_config``, whose default makes renders differ."""
    import ast
    from pathlib import Path

    backend = Path(__file__).resolve().parents[1]
    # sglang_server.py runs in SGLang's own Python and never imports Studio
    files = [
        path
        for path in sorted((backend / "core" / "inference").glob("*.py"))
        if path.name != "sglang_server.py"
    ] + [
        backend / "core" / "training" / "diffusion_dit_trainer.py",
    ]
    offenders: list[str] = []
    for path in files:
        tree = ast.parse(path.read_text(encoding = "utf-8"))
        for node in ast.walk(tree):
            if not isinstance(node, ast.Call):
                continue
            func = node.func
            name = (
                func.id
                if isinstance(func, ast.Name)
                else func.attr
                if isinstance(func, ast.Attribute)
                else ""
            )
            if not (name.endswith("WeightConfig") or name.endswith("WeightOnlyConfig")):
                continue
            offenders.append(f"{path.relative_to(backend)}:{node.lineno} {name}(...)")
    assert not offenders, (
        "torchao config constructed outside _quiet_config (pass the CLASS as its first argument instead):\n  "
        + "\n  ".join(offenders)
    )


def test_unset_and_auto_are_the_only_spellings_that_invite_a_family_default():
    """Only unset and auto invite a family default; an explicit off must never read as auto."""
    for auto in (None, "", "   ", "auto", "AUTO", " Auto "):
        assert te_quant_is_auto(auto) is True
    for pinned in ("none", "off", "OFF", " None ", "fp8", "int8", "nvfp4", "fp8_dynamic"):
        assert te_quant_is_auto(pinned) is False


def test_an_unset_request_takes_the_family_scheme_and_is_marked_as_not_asked_for():
    """Unset takes the hosted encoder; auto_selected stops loader refusals when the scheme won't engage."""
    assert resolve_te_quant_request(None, "fp8") == ("fp8", True)
    assert resolve_te_quant_request("auto", "fp8") == ("fp8", True)
    assert resolve_te_quant_request("", "fp8") == ("fp8", True)


def test_an_opt_out_still_pins_the_released_bf16_encoder():
    """none/off must still opt out after the new default, or the bf16 reference is unreachable."""
    for opt_out in ("none", "off", " OFF "):
        assert resolve_te_quant_request(opt_out, "fp8") == (None, False)


def test_an_explicit_scheme_still_wins_over_the_family_default():
    assert resolve_te_quant_request("int8", "fp8") == ("int8", False)
    assert resolve_te_quant_request("nvfp4", "fp8") == ("nvfp4", False)
    with pytest.raises(ValueError):
        resolve_te_quant_request("int3", "fp8")


def test_a_family_that_has_not_opted_in_keeps_todays_dense_bf16_default():
    """Backwards compatibility for every family without ``te_quant_auto``: unset must still
    mean the released encoder, not a scheme inferred from the fact that an artifact exists."""
    for unset in (None, "auto", ""):
        assert resolve_te_quant_request(unset, None) == (None, False)


def test_a_typo_in_a_familys_own_default_is_refused_rather_than_passed_through():
    """The field is code, not a request, so a bad value would otherwise reach
    ``quantize_text_encoders`` as an unknown mode on EVERY default load of that family."""
    with pytest.raises(ValueError):
        resolve_te_quant_request(None, "fp9")


def test_the_dense_opt_out_survives_the_image_request_schema_too():
    """The API request must accept the dense opt-out none, or the bf16 reference is unreachable."""
    from pydantic import ValidationError

    from models.inference import DiffusionLoadRequest

    def _request(value):
        return DiffusionLoadRequest(model_path = "Qwen/Qwen-Image-2.1", text_encoder_quant = value)

    for accepted in (None, "auto", "none", "off", "fp8", "fp8_dynamic", "int8", "nvfp4"):
        assert _request(accepted).text_encoder_quant == accepted
    with pytest.raises(ValidationError):
        _request("int3")