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.

42.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

"""Pre-cast text-encoder load path: resolution, fallback and gating, with no CUDA or Hub."""

from __future__ import annotations

import types
from pathlib import Path

import pytest

import core.inference.diffusion_te_prequant as tpq
from core.inference.diffusion_te_prequant import (
    TE_PREQUANT_FORMAT,
    TePrequantSource,
    family_te_prequant_repo,
    resolve_te_prequant_source,
    te_prequant_pipe_kwargs,
    te_prequant_repo_filenames,
)


@pytest.fixture(autouse = True)
def _safetensors_readable_regardless_of_the_installed_torchao(monkeypatch):
    """Pin the torchao floor so planning tests ignore the installed release."""
    import core.inference.prequant_safetensors as prequant_safetensors
    monkeypatch.setattr(prequant_safetensors, "_torchao_version", lambda: None)


def _fam(
    te_prequant_repos = (),
    name = "ltx-2",
    base_repo = "Lightricks/LTX-2",
):
    return types.SimpleNamespace(
        name = name,
        base_repo = base_repo,
        te_prequant_repos = te_prequant_repos,
    )


def test_repo_filename_convention():
    # safetensors first, legacy pickle second: both are live and the reader takes either.
    assert te_prequant_repo_filenames("unsloth/LTX-2-FP8", "text_encoder", "fp8") == (
        "LTX-2-text_encoder-FP8.safetensors",
        "LTX-2-text_encoder-FP8.pt",
    )
    assert te_prequant_repo_filenames("org/Some-Model-quantized", "text_encoder_2", "fp8") == (
        "Some-Model-text_encoder_2-FP8.safetensors",
        "Some-Model-text_encoder_2-FP8.pt",
    )
    assert te_prequant_repo_filenames("org/PlainRepo", "text_encoder", "fp8") == (
        "PlainRepo-text_encoder-FP8.safetensors",
        "PlainRepo-text_encoder-FP8.pt",
    )


def test_family_repo_by_scheme_and_component():
    fam = _fam(
        te_prequant_repos = (
            ("fp8", "text_encoder", "org/hosted-fp8"),
            ("fp8", "text_encoder_2", "org/hosted-2-fp8"),
        )
    )
    assert family_te_prequant_repo(fam, "fp8", "text_encoder") == "org/hosted-fp8"
    assert family_te_prequant_repo(fam, "fp8", "text_encoder_2") == "org/hosted-2-fp8"
    assert family_te_prequant_repo(fam, "fp8", "text_encoder_3") is None
    assert family_te_prequant_repo(fam, "int8", "text_encoder") is None
    assert (
        family_te_prequant_repo(_fam(te_prequant_repos = (("bad",),)), "fp8", "text_encoder") is None
    )
    # A fake or older family object without the field must resolve to None, not break.
    assert family_te_prequant_repo(types.SimpleNamespace(name = "x"), "fp8", "text_encoder") is None


def test_resolve_priority_and_scheme_gate():
    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted-fp8"),))
    src = resolve_te_prequant_source(fam, "text_encoder", "fp8", path_override = "/tmp/te.pt")
    assert src == TePrequantSource(kind = "path", location = "/tmp/te.pt", filename = None)
    src = resolve_te_prequant_source(fam, "text_encoder", "fp8")
    assert src.kind == "repo" and src.location == "org/hosted-fp8"
    assert src.filename == "hosted-text_encoder-FP8.safetensors"
    assert src.fallback_filenames == ("hosted-text_encoder-FP8.pt",)
    assert resolve_te_prequant_source(_fam(), "text_encoder", "fp8") is None
    # v1 hosts the layerwise fp8 storage scheme only.
    assert resolve_te_prequant_source(fam, "text_encoder", "int8") is None
    assert resolve_te_prequant_source(fam, "text_encoder", "fp8_dynamic") is None


def test_a_hosted_safetensors_encoder_is_asked_for_and_a_pickle_repo_still_resolves(monkeypatch):
    """Resolver must ask for safetensors as well as .pt, or the dense encoder loads silently."""
    from huggingface_hub.errors import EntryNotFoundError

    asked = []

    def fake_download(*, repo_id, filename, token, cache_dir, local_files_only):
        asked.append(filename)
        if filename not in hosted:
            raise EntryNotFoundError(f"no {filename} in {repo_id}")
        return f"/cache/{filename}"

    monkeypatch.setattr("huggingface_hub.hf_hub_download", fake_download)
    src = resolve_te_prequant_source(
        _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted-fp8"),)),
        "text_encoder",
        "fp8",
    )

    hosted = {"hosted-text_encoder-FP8.safetensors"}
    asked.clear()
    assert tpq._resolve_checkpoint_path(src, None, cache_dir = "/cache") == (
        "/cache/hosted-text_encoder-FP8.safetensors"
    )
    assert asked == ["hosted-text_encoder-FP8.safetensors"]

    hosted = {"hosted-text_encoder-FP8.pt"}
    asked.clear()
    assert tpq._resolve_checkpoint_path(src, None, cache_dir = "/cache") == (
        "/cache/hosted-text_encoder-FP8.pt"
    )
    assert asked == ["hosted-text_encoder-FP8.safetensors", "hosted-text_encoder-FP8.pt"]

    # The miss must surface, not become a None indistinguishable from "hosts nothing".
    hosted = set()
    with pytest.raises(EntryNotFoundError):
        tpq._resolve_checkpoint_path(src, None, cache_dir = "/cache")


def test_a_transport_failure_is_not_mistaken_for_a_missing_file(monkeypatch):
    """Only a missing filename advances to the next candidate; auth and network errors must surface."""

    def fake_download(*, repo_id, filename, token, cache_dir, local_files_only):
        raise PermissionError("401 unauthorized")

    monkeypatch.setattr("huggingface_hub.hf_hub_download", fake_download)
    src = resolve_te_prequant_source(
        _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted-fp8"),)),
        "text_encoder",
        "fp8",
    )
    with pytest.raises(PermissionError):
        tpq._resolve_checkpoint_path(src, None, cache_dir = "/cache")


def _good_ckpt(
    scheme = "fp8",
    component = "text_encoder",
    base = "Lightricks/LTX-2",
):
    return {
        "format": TE_PREQUANT_FORMAT,
        "metadata": {
            "scheme": scheme,
            "component": component,
            "base_model_id": base,
            "te_class": "Gemma3ForConditionalGeneration",
        },
        "state_dict": {"weight": object()},
    }


@pytest.mark.parametrize(
    "mutate, reason",
    [
        (lambda c: c.update(format = "other"), "format"),
        (lambda c: c.pop("state_dict"), "state_dict"),
        (lambda c: c["metadata"].update(scheme = "int8"), "scheme"),
        (lambda c: c["metadata"].update(component = "text_encoder_2"), "component"),
        (lambda c: c["metadata"].update(base_model_id = "other/repo"), "base"),
        (lambda c: c["metadata"].pop("base_model_id"), "missing base"),
    ],
)
def test_validate_rejects_mismatches(mutate, reason):
    ckpt = _good_ckpt()
    mutate(ckpt)
    assert (
        tpq._validate_checkpoint(ckpt, "fp8", "text_encoder", "Lightricks/LTX-2", None) is False
    ), reason


def test_validate_accepts_good_checkpoint_and_base_case_folding():
    assert tpq._validate_checkpoint(_good_ckpt(), "fp8", "text_encoder", "Lightricks/LTX-2", None)
    assert tpq._validate_checkpoint(_good_ckpt(), "fp8", "text_encoder", "lightricks/ltx-2", None)


def test_load_refuses_unallowlisted_local_path(monkeypatch, tmp_path):
    from core.inference.diffusion_prequant import ALLOW_LOCAL_PREQUANT_PATH_ENV

    monkeypatch.delenv(ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)
    path = tmp_path / "te.pt"
    path.write_bytes(b"x")
    out = tpq.load_prequant_text_encoder(
        "Lightricks/LTX-2",
        "text_encoder",
        TePrequantSource(kind = "path", location = str(path)),
        dtype = None,
    )
    assert out is None


def test_load_missing_file_returns_none(monkeypatch, tmp_path):
    from core.inference.diffusion_prequant import ALLOW_LOCAL_PREQUANT_PATH_ENV

    monkeypatch.setenv(ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
    out = tpq.load_prequant_text_encoder(
        "Lightricks/LTX-2",
        "text_encoder",
        TePrequantSource(kind = "path", location = str(tmp_path / "absent.pt")),
        dtype = None,
    )
    assert out is None


def test_hosted_checkpoint_and_config_honor_cache_only_and_the_active_root(monkeypatch, tmp_path):
    import huggingface_hub
    import torch
    import transformers
    from utils import hf_cache_settings

    seen: dict = {"download": {}, "config": {}}

    def fake_download(**kwargs):
        seen["download"].update(kwargs)
        return "/cache/encoder.pt"

    def fake_config(repo_id, **kwargs):
        seen["config"] = {"repo_id": repo_id, **kwargs}
        raise FileNotFoundError("stop after config lookup")

    monkeypatch.setattr(huggingface_hub, "hf_hub_download", fake_download)
    monkeypatch.setattr(torch, "load", lambda *_a, **_k: _good_ckpt())
    monkeypatch.setattr(transformers.AutoConfig, "from_pretrained", fake_config)
    monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(tmp_path))
    out = tpq.load_prequant_text_encoder(
        "Lightricks/LTX-2",
        "text_encoder",
        TePrequantSource(kind = "repo", location = "org/hosted", filename = "encoder.pt"),
        dtype = None,
        local_files_only = True,
    )
    assert out is None
    assert seen["download"]["local_files_only"] is True
    assert seen["download"]["cache_dir"] == str(tmp_path)
    assert seen["config"]["repo_id"] == "Lightricks/LTX-2"
    assert seen["config"]["subfolder"] == "text_encoder"
    assert seen["config"]["local_files_only"] is True
    assert seen["config"]["cache_dir"] == str(tmp_path)


def _target():
    return types.SimpleNamespace(device = "cuda", dtype = None)


def _budget_scale(
    fam,
    mode = "fp8",
    *,
    base = None,
):
    return tpq.te_prequant_budget_scale(
        fam, te_quant_mode = mode, target = _target(), base = base or fam.base_repo
    )


def test_pipe_kwargs_empty_when_mode_not_fp8(monkeypatch):
    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    for mode in (None, "", "off", "int8", "fp8_dynamic"):
        assert (
            te_prequant_pipe_kwargs(
                fam, "Lightricks/LTX-2", te_quant_mode = mode, target = _target(), dtype = None
            )
            == {}
        )


def test_pipe_kwargs_empty_without_hosted_entry(monkeypatch):
    import core.inference.diffusion_precision as precision
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    assert (
        te_prequant_pipe_kwargs(
            _fam(), "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
        )
        == {}
    )


def test_pipe_kwargs_empty_when_device_unsupported(monkeypatch):
    import core.inference.diffusion_precision as precision

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: False)
    assert (
        te_prequant_pipe_kwargs(
            fam, "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
        )
        == {}
    )


def test_pipe_kwargs_respects_family_deny(monkeypatch):
    import core.inference.diffusion_precision as precision

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    # The deny helper ships on the video branch's precision module; simulate it here.
    monkeypatch.setattr(
        precision, "_te_family_denied", lambda family, mode: family == "ltx-2", raising = False
    )
    assert (
        te_prequant_pipe_kwargs(
            fam, "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
        )
        == {}
    )


def test_pipe_kwargs_injects_loaded_encoder(monkeypatch):
    import core.inference.diffusion_precision as precision

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    marker = object()
    seen = {}

    def fake_load(base, component, source, **kw):
        seen.update(base = base, component = component, source = source)
        return marker

    monkeypatch.setattr(tpq, "load_prequant_text_encoder", fake_load)
    out = te_prequant_pipe_kwargs(
        fam, "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
    )
    assert out == {"text_encoder": marker}
    assert seen["base"] == "Lightricks/LTX-2"
    assert seen["source"].location == "org/hosted"


def test_pipe_kwargs_does_not_download_a_checkpoint_for_a_custom_base(monkeypatch):
    import core.inference.diffusion_precision as precision

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)

    def unexpected_load(*_args, **_kwargs):
        raise AssertionError("an incompatible hosted checkpoint must not be opened")

    monkeypatch.setattr(tpq, "load_prequant_text_encoder", unexpected_load)
    assert (
        te_prequant_pipe_kwargs(
            fam,
            "someone/custom-ltx-2",
            te_quant_mode = "fp8",
            target = _target(),
            dtype = None,
        )
        == {}
    )


def test_pipe_kwargs_empty_when_load_fails(monkeypatch):
    import core.inference.diffusion_precision as precision

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    monkeypatch.setattr(tpq, "load_prequant_text_encoder", lambda *a, **k: None)
    assert (
        te_prequant_pipe_kwargs(
            fam, "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
        )
        == {}
    )


def test_pipe_kwargs_raises_when_load_fails_and_dense_shards_were_skipped(monkeypatch, tmp_path):
    """#12860: the plan skips the dense shards a pre-cast encoder replaces, so a failed pre-cast load
    (os error 1455 on Windows) must stop with a clear error, not fall back to shards that are not there."""
    pytest.importorskip("torch")
    import json

    import core.inference.diffusion_precision as precision
    import core.inference.prequant_safetensors as prequant_safetensors

    fam = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),), base_repo = str(tmp_path))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    ckpt = tmp_path / "te.safetensors"
    ckpt.write_bytes(b"")
    monkeypatch.setattr(tpq, "_resolve_checkpoint_path", lambda *a, **k: str(ckpt))

    def out_of_commit(*a, **k):
        raise OSError(
            "The paging file is too small for this operation to complete. (os error 1455)"
        )

    monkeypatch.setattr(prequant_safetensors, "load_plain_prequant_safetensors", out_of_commit)
    encoder = tmp_path / "text_encoder"
    encoder.mkdir()
    (encoder / "config.json").write_text("{}")
    shard = "model-00001-of-00001.safetensors"
    (encoder / "model.safetensors.index.json").write_text(json.dumps({"weight_map": {"w": shard}}))

    def load(dense_source):
        return te_prequant_pipe_kwargs(
            fam,
            str(tmp_path),
            te_quant_mode = "fp8",
            target = _target(),
            dtype = None,
            dense_source = dense_source,
        )

    # assembly that can still fetch the shards keeps the dense fallback
    assert load(None) == {}
    with pytest.raises(RuntimeError, match = r"text_encoder .*\(os error 1455\).*Dense \(bf16\)"):
        load(str(tmp_path))
    (encoder / shard).write_bytes(b"")
    assert load(str(tmp_path)) == {}


def test_pipe_kwargs_injects_every_hosted_component(monkeypatch):
    """A family hosting several TE components (flux.1: T5 as text_encoder_2) gets each
    one injected under its own attr; unhosted components stay dense."""
    import core.inference.diffusion_precision as precision

    fam = _fam(
        te_prequant_repos = (
            ("fp8", "text_encoder", "org/hosted"),
            ("fp8", "text_encoder_2", "org/hosted-2"),
        )
    )
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    markers = {"text_encoder": object(), "text_encoder_2": object()}
    monkeypatch.setattr(
        tpq,
        "load_prequant_text_encoder",
        lambda base, component, source, **kw: markers[component],
    )
    out = te_prequant_pipe_kwargs(
        fam, "Lightricks/LTX-2", te_quant_mode = "fp8", target = _target(), dtype = None
    )
    assert out == markers


def test_te_base_equivalent_groups():
    from core.inference.diffusion_te_prequant import te_base_equivalent

    assert te_base_equivalent("Qwen/Qwen-Image", "qwen/qwen-image")
    assert te_base_equivalent(
        "Qwen/Qwen-Image", "hunyuanvideo-community/HunyuanImage-2.1-Diffusers"
    )
    assert te_base_equivalent("black-forest-labs/FLUX.1-schnell", "black-forest-labs/FLUX.1-dev")
    assert te_base_equivalent(
        "black-forest-labs/FLUX.1-Krea-dev", "black-forest-labs/FLUX.1-schnell"
    )
    # Z-Image Turbo and base share one Qwen3-4B encoder, so the Turbo-baked artifact serves both.
    assert te_base_equivalent("Tongyi-MAI/Z-Image-Turbo", "Tongyi-MAI/Z-Image")
    assert te_base_equivalent("Tongyi-MAI/Z-Image", "Tongyi-MAI/Z-Image-Turbo")
    assert not te_base_equivalent("Qwen/Qwen-Image", "black-forest-labs/FLUX.1-schnell")
    assert not te_base_equivalent("Tongyi-MAI/Z-Image-Turbo", "black-forest-labs/FLUX.2-klein-4B")
    assert not te_base_equivalent("Tongyi-MAI/Z-Image", "Qwen/Qwen-Image")


def test_validate_accepts_equivalent_base():
    ckpt = {
        "format": TE_PREQUANT_FORMAT,
        "state_dict": {},
        "metadata": {
            "scheme": "fp8",
            "component": "text_encoder",
            "base_model_id": "Qwen/Qwen-Image",
        },
    }
    assert tpq._validate_checkpoint(
        ckpt,
        "fp8",
        "text_encoder",
        "hunyuanvideo-community/HunyuanImage-2.1-Diffusers",
        None,
    )
    assert not tpq._validate_checkpoint(
        ckpt, "fp8", "text_encoder", "black-forest-labs/FLUX.1-schnell", None
    )


def test_family_dataclasses_declare_te_prequant_field():
    from core.inference.diffusion_families import DiffusionFamily, detect_family
    from core.inference.video_families import VideoFamily

    assert DiffusionFamily.__dataclass_fields__["te_prequant_repos"].default_factory is tuple
    assert VideoFamily.__dataclass_fields__["te_prequant_repos"].default_factory is tuple
    fam = detect_family("stabilityai/stable-diffusion-xl-base-1.0")
    assert fam.te_prequant_repos == ()


def test_hosted_te_prequant_entries():
    """The hosted pre-cast fp8 text encoders live in the family's own -FP8 repos."""
    from core.inference.diffusion_families import detect_family
    from core.inference.video_families import detect_video_family

    assert detect_family("Qwen/Qwen-Image").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/Qwen-Image-FP8"),
    )
    assert detect_family("black-forest-labs/FLUX.2-dev").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/FLUX.2-dev-FP8"),
    )
    assert detect_video_family("Lightricks/LTX-2").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/LTX-2-FP8"),
    )
    assert te_prequant_repo_filenames("unsloth/Qwen-Image-FP8", "text_encoder", "fp8") == (
        "Qwen-Image-text_encoder-FP8.safetensors",
        "Qwen-Image-text_encoder-FP8.pt",
    )
    assert te_prequant_repo_filenames("unsloth/FLUX.2-dev-FP8", "text_encoder", "fp8") == (
        "FLUX.2-dev-text_encoder-FP8.safetensors",
        "FLUX.2-dev-text_encoder-FP8.pt",
    )
    assert te_prequant_repo_filenames("unsloth/LTX-2-FP8", "text_encoder", "fp8") == (
        "LTX-2-text_encoder-FP8.safetensors",
        "LTX-2-text_encoder-FP8.pt",
    )
    # HiDream's heavyweight is TE4 (Llama-3.1-8B), engaged via hidream_te4_kwargs since the generic pass only covers
    # text_encoder.._3; its text_encoder_3 is FLUX.1's T5-XXL, loaded from FLUX.1's text_encoder_2 file.
    assert detect_family("HiDream-ai/HiDream-I1-Full").te_prequant_repos == (
        ("fp8", "text_encoder_4", "unsloth/HiDream-I1-Full-FP8"),
        ("fp8", "text_encoder_3", "unsloth/FLUX.1-schnell-FP8", "text_encoder_2"),
    )
    assert te_prequant_repo_filenames("unsloth/HiDream-I1-Full-FP8", "text_encoder_4", "fp8") == (
        "HiDream-I1-Full-text_encoder_4-FP8.safetensors",
        "HiDream-I1-Full-text_encoder_4-FP8.pt",
    )
    assert detect_family("black-forest-labs/FLUX.1-schnell").te_prequant_repos == (
        ("fp8", "text_encoder_2", "unsloth/FLUX.1-schnell-FP8"),
    )
    assert te_prequant_repo_filenames("unsloth/FLUX.1-schnell-FP8", "text_encoder_2", "fp8") == (
        "FLUX.1-schnell-text_encoder_2-FP8.safetensors",
        "FLUX.1-schnell-text_encoder_2-FP8.pt",
    )
    assert detect_family("Alpha-VLLM/Lumina-Image-2.0").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/Lumina-Image-2.0-FP8"),
    )
    assert detect_family("Tongyi-MAI/Z-Image-Turbo").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/Z-Image-Turbo-FP8"),
    )
    assert detect_family("krea/Krea-2-Turbo").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/Krea-2-Turbo-FP8"),
    )
    assert detect_family("hunyuanvideo-community/HunyuanImage-2.1-Diffusers").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/Qwen-Image-FP8"),
    )
    # flux.2-klein-4B hosts its OWN entry: it ships stock Qwen3-4B while Z-Image's encoder is a variant of it (layer 35
    # MLP maxdiff 0.86), so the z-image artifact must not serve it.
    assert detect_family("black-forest-labs/FLUX.2-klein-4B").te_prequant_repos == (
        ("fp8", "text_encoder", "unsloth/FLUX.2-klein-4B-FP8"),
    )


def _hidream_transformers_stub(monkeypatch, recorder):
    """Fake transformers surface for hidream_te4_kwargs: records from_pretrained calls."""
    import sys

    class _FakeLlama:
        def __init__(self, tag):
            self.tag = tag

    class _LlamaCls:
        @staticmethod
        def from_pretrained(repo, **kwargs):
            recorder.append(("llama_from_pretrained", repo))
            return _FakeLlama(f"dense{len(recorder)}")

    class _TokCls:
        @staticmethod
        def from_pretrained(repo, **kwargs):
            recorder.append(("tokenizer", repo))
            return "tok4"

    fake = types.ModuleType("transformers")
    fake.AutoTokenizer = _TokCls
    fake.LlamaForCausalLM = _LlamaCls
    monkeypatch.setitem(sys.modules, "transformers", fake)
    return _FakeLlama


def test_hidream_te4_stays_dense_without_fp8(monkeypatch):
    from core.inference.diffusion_hidream import hidream_te4_kwargs

    recorder: list = []
    _hidream_transformers_stub(monkeypatch, recorder)
    out = hidream_te4_kwargs(
        None, None, fam = _fam(name = "hidream-i1"), te_quant_mode = None, target = _target()
    )
    assert out["tokenizer_4"] == "tok4"
    assert getattr(out["text_encoder_4"], "tag", "").startswith("dense")
    assert ("llama_from_pretrained", "unsloth/Meta-Llama-3.1-8B-Instruct") in recorder


def test_hidream_te4_prefers_precast_checkpoint(monkeypatch):
    import core.inference.diffusion_hidream as dh
    import core.inference.diffusion_precision as precision

    recorder: list = []
    _hidream_transformers_stub(monkeypatch, recorder)
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    precast = object()
    calls: dict = {}

    def _fake_load(base, component, source, **kwargs):
        calls["base"] = base
        calls["component"] = component
        calls["config_subfolder"] = kwargs.get("config_subfolder")
        calls["config_overrides"] = kwargs.get("config_overrides")
        calls["local_files_only"] = kwargs.get("local_files_only")
        return precast

    monkeypatch.setattr(tpq, "load_prequant_text_encoder", _fake_load)
    fam = _fam(
        te_prequant_repos = (("fp8", "text_encoder_4", "unsloth/HiDream-I1-Full-FP8"),),
        name = "hidream-i1",
    )
    out = dh.hidream_te4_kwargs(
        None,
        None,
        fam = fam,
        te_quant_mode = "fp8",
        target = _target(),
        local_files_only = True,
    )
    assert out["text_encoder_4"] is precast
    assert calls["base"] == "unsloth/Meta-Llama-3.1-8B-Instruct"
    assert calls["component"] == "text_encoder_4"
    assert calls["config_subfolder"] == ""
    assert calls["config_overrides"] == {"output_hidden_states": True, "output_attentions": True}
    assert calls["local_files_only"] is True
    assert ("llama_from_pretrained", "unsloth/Meta-Llama-3.1-8B-Instruct") not in recorder


def test_hidream_te4_falls_back_to_dense_cast(monkeypatch):
    import core.inference.diffusion_hidream as dh
    import core.inference.diffusion_precision as precision

    recorder: list = []
    _hidream_transformers_stub(monkeypatch, recorder)
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    monkeypatch.setattr(tpq, "load_prequant_text_encoder", lambda *a, **k: None)
    cast: list = []
    monkeypatch.setattr(precision, "_cast_fp8", lambda enc, tgt: cast.append(enc))
    fam = _fam(
        te_prequant_repos = (("fp8", "text_encoder_4", "unsloth/HiDream-I1-Full-FP8"),),
        name = "hidream-i1",
    )
    out = dh.hidream_te4_kwargs(None, None, fam = fam, te_quant_mode = "fp8", target = _target())
    assert cast == [out["text_encoder_4"]]
    assert ("llama_from_pretrained", "unsloth/Meta-Llama-3.1-8B-Instruct") in recorder


def test_hidream_te4_partial_cast_reloads_dense(monkeypatch):
    """A mid-pass TE4 cast failure must ship a FRESH dense encoder, not partial fp8 state."""
    import core.inference.diffusion_hidream as dh
    import core.inference.diffusion_precision as precision

    recorder: list = []
    _hidream_transformers_stub(monkeypatch, recorder)
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)

    def _boom(enc, tgt):
        raise RuntimeError("cast failed mid-pass")

    monkeypatch.setattr(precision, "_cast_fp8", _boom)
    fam = _fam(name = "hidream-i1")
    out = dh.hidream_te4_kwargs(None, None, fam = fam, te_quant_mode = "fp8", target = _target())
    dense_loads = [r for r in recorder if r[0] == "llama_from_pretrained"]
    assert len(dense_loads) == 2  # initial load + the fail-safe reload
    assert getattr(out["text_encoder_4"], "tag", "").startswith("dense")


def test_assemble_pipe_injects_precast_te(monkeypatch):
    """The dense transformer_quant fast path assembles companions through _assemble_pipe,
    which must inject the hosted pre-cast TE like the full-pipeline and GGUF branches."""
    import core.inference.diffusion as dif

    seen: dict = {}

    class FakePipe:
        def to(self, device):
            return self

    class FakePipelineCls:
        @staticmethod
        def from_pretrained(base, **kw):
            seen.update(kw)
            return FakePipe()

    monkeypatch.setattr(dif, "te_prequant_pipe_kwargs", lambda *a, **k: {"text_encoder": "PRECAST"})
    dif.DiffusionBackend._assemble_pipe(
        FakePipelineCls,
        "org/base",
        "TR",
        None,
        None,
        "cpu",
        None,
        fam = None,
        te_quant_mode = "fp8",
        target = object(),
    )
    assert seen["text_encoder"] == "PRECAST"
    seen.clear()
    dif.DiffusionBackend._assemble_pipe(
        FakePipelineCls,
        "org/base",
        "TR",
        None,
        None,
        "cpu",
        None,
        fam = None,
    )
    assert "text_encoder" not in seen


def test_cast_fp8_is_idempotent_on_precast_encoder():
    """Re-applying the cast to a pre-cast encoder must be a no-op: re-registering the hook name
    raises and reports the cast as failed."""
    import torch

    pytest.importorskip("diffusers")  # _cast_fp8 installs diffusers' layerwise hooks
    from core.inference.diffusion_precision import _cast_fp8

    target = types.SimpleNamespace(dtype = torch.bfloat16)
    enc = torch.nn.Sequential(torch.nn.Linear(64, 64), torch.nn.LayerNorm(64))
    _cast_fp8(enc, target)
    assert enc[0].weight.dtype == torch.float8_e4m3fn
    # Must report the COMPUTE dtype: pipelines feed it to randn_tensor, which has no fp8 kernel.
    assert enc.dtype == torch.bfloat16
    # Exact class identity: a dynamic-subclass swap broke transformers' kwargs-based output recording.
    assert type(enc) is torch.nn.Sequential
    sibling = torch.nn.Sequential(torch.nn.Linear(8, 8))
    with pytest.raises(AttributeError):
        sibling.dtype
    _cast_fp8(enc, target)
    assert enc[0].weight.dtype == torch.float8_e4m3fn
    assert enc.dtype == torch.bfloat16


def test_builder_metadata_survives_weights_only_load(tmp_path):
    """Metadata must be plain str so torch.load(weights_only=True) accepts it; a pickled
    TorchVersion silently falls back to dense."""
    import sys

    import torch

    scripts = Path(__file__).resolve().parents[3] / "scripts"
    sys.path.insert(0, str(scripts))
    try:
        import build_te_prequant_checkpoint  # noqa: F401  (import proves the module parses)
    finally:
        sys.path.remove(str(scripts))
    ckpt = {
        "format": TE_PREQUANT_FORMAT,
        "metadata": {
            "scheme": "fp8",
            "component": "text_encoder",
            "base_model_id": "Lightricks/LTX-2",
            "te_class": "Gemma3ForConditionalGeneration",
            "torch_version": str(torch.__version__),
            "transformers_version": "0.0.0",
        },
        "state_dict": {"weight": torch.zeros(1)},
    }
    path = tmp_path / "te.pt"
    torch.save(ckpt, path)
    loaded = torch.load(path, weights_only = True, map_location = "cpu")
    assert tpq._validate_checkpoint(loaded, "fp8", "text_encoder", "Lightricks/LTX-2", None)
    # An unstringified TorchVersion in metadata must fail weights_only.
    bad = dict(ckpt, metadata = dict(ckpt["metadata"], torch_version = torch.__version__))
    bad_path = tmp_path / "bad.pt"
    torch.save(bad, bad_path)
    if not isinstance(torch.__version__, str):
        with pytest.raises(Exception):
            torch.load(bad_path, weights_only = True, map_location = "cpu")


# Hosted checkpoint bytes / bf16 dense bytes (Hub metadata); the budget constant must be a ceiling.
_MEASURED_FP8_RATIOS = {
    "flux.2-dev/text_encoder": (24_683_130_873, 48_022_800_560),
    "hidream-i1-full/text_encoder_4": (8_555_963_320, 16_060_556_376),
    "qwen-image/text_encoder": (8_839_210_073, 16_584_414_544),
    "ltx-2/text_encoder": (13_205_302_695, 24_374_720_836),
    "krea-2-turbo/text_encoder": (4_831_262_424, 8_875_715_136),
    "z-image-turbo/text_encoder": (4_411_751_967, 8_044_982_000),
    "lumina-image-2.0/text_encoder": (3_204_501_909, 5_228_699_608),
    "flux.1-schnell/text_encoder_2": (5_900_818_800, 9_524_648_584),
}


def test_budget_scale_over_states_every_measured_artifact():
    worst = max(fp8 / dense for fp8, dense in _MEASURED_FP8_RATIOS.values())
    assert tpq.TE_PREQUANT_BUDGET_SCALE >= worst
    assert tpq.TE_PREQUANT_BUDGET_SCALE < 1.0
    # fp8 is one byte per param vs bf16's two, so nothing can come in under 0.5.
    assert min(fp8 / dense for fp8, dense in _MEASURED_FP8_RATIOS.values()) > 0.5


def test_budget_scale_applies_only_when_a_pre_cast_checkpoint_resolves(monkeypatch):
    import core.inference.diffusion_precision as precision

    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    hosted = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    assert _budget_scale(hosted) == tpq.TE_PREQUANT_BUDGET_SCALE
    assert _budget_scale(hosted, base = "someone/custom-ltx-2") == 1.0
    # No hosted checkpoint: encoder is cast in place AFTER assembly, so its peak and budget stay bf16.
    assert _budget_scale(_fam()) == 1.0
    for mode in (None, "", "off", "int8", "fp8_dynamic", "nvfp4"):
        assert _budget_scale(hosted, mode) == 1.0


def test_budget_scale_is_bf16_when_the_device_cannot_quantise(monkeypatch):
    import core.inference.diffusion_precision as precision

    hosted = _fam(te_prequant_repos = (("fp8", "text_encoder", "org/hosted"),))
    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: False)
    assert _budget_scale(hosted) == 1.0


def test_budget_scale_fails_open_to_bf16(monkeypatch):
    # An unresolvable pick keeps the larger budget rather than guessing small.
    def _boom(*args, **kwargs):
        raise RuntimeError("hub down")

    monkeypatch.setattr(tpq, "te_prequant_sources", _boom)
    assert _budget_scale(_fam()) == 1.0


def test_shipped_video_and_image_families_resolve_the_scale(monkeypatch):
    import core.inference.diffusion_precision as precision
    from core.inference.diffusion_families import detect_family
    from core.inference.video_families import detect_video_family

    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    scale = tpq.TE_PREQUANT_BUDGET_SCALE
    # ltx-2 hosts its Gemma3-12B encoder pre-cast, and every Wan family the one UMT5-XXL file.
    for repo, expected in (
        ("Lightricks/LTX-2", scale),
        ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", scale),
        ("Wan-AI/Wan2.2-T2V-A14B-Diffusers", scale),
        ("Wan-AI/Wan2.1-T2V-1.3B-Diffusers", scale),
        ("Wan-AI/Wan2.1-T2V-14B-Diffusers", scale),
    ):
        fam = detect_video_family(repo)
        assert _budget_scale(fam, base = repo) == expected, repo
    assert _budget_scale(detect_family("Qwen/Qwen-Image"), base = "Qwen/Qwen-Image") == scale


def test_a_sibling_release_keeps_the_pre_cast_encoder(monkeypatch):
    """Releases that ship their sibling's text encoder byte for byte must keep the pre-cast encoder."""
    import core.inference.diffusion_precision as precision
    from core.inference.diffusion_families import detect_family_for_pick

    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    for base in (
        "Qwen/Qwen-Image",
        "Qwen/Qwen-Image-2512",
        "unsloth/Qwen-Image-2512",
        "krea/Krea-2-Turbo",
        "krea/Krea-2-Raw",
    ):
        fam = detect_family_for_pick(base, None, None)
        assert fam is not None, base
        sources = tpq.te_prequant_sources_for_base(fam, base, te_quant_mode = "fp8", target = _target())
        assert "text_encoder" in sources, base
        assert _budget_scale(fam, base = base) == tpq.TE_PREQUANT_BUDGET_SCALE, base


def test_an_unrelated_custom_base_still_loses_it(monkeypatch):
    """An unrelated custom base keeps the strict refusal, since the hosted artifact would download
    before its metadata could reject it."""
    import core.inference.diffusion_precision as precision
    from core.inference.diffusion_families import detect_family_for_pick

    monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
    fam = detect_family_for_pick("Qwen/Qwen-Image", None, None)
    for base in ("someone/my-qwen-image-finetune", "randomuser/qwen-image-merged"):
        assert (
            tpq.te_prequant_sources_for_base(fam, base, te_quant_mode = "fp8", target = _target()) == {}
        ), base


def test_the_plan_recognises_the_pt_repos_that_already_exist(monkeypatch):
    """Preferring safetensors may only add a name: the plan must still recognise existing .pt repos."""
    src = TePrequantSource(
        kind = "repo",
        location = "unsloth/LTX-2-FP8",
        filename = "LTX-2-text_encoder-FP8.safetensors",
        fallback_filenames = ("LTX-2-text_encoder-FP8.pt",),
    )

    class _Sib:
        def __init__(self, name, size):
            self.rfilename, self.size = name, size

    class _Api:
        def __init__(self, files):
            self._files = files

        def model_info(self, *a, **k):
            outer = self

            class _I:
                siblings = outer._files

            return _I()

    def plan(hosted):
        return tpq.te_prequant_hub_files({"text_encoder": src}, _Api(hosted), None)

    pt, st = "LTX-2-text_encoder-FP8.pt", "LTX-2-text_encoder-FP8.safetensors"
    assert plan([_Sib(pt, 9_000_000_000)]) == {"text_encoder": [(pt, 9_000_000_000)]}
    assert plan([_Sib(st, 9_400_000_000)]) == {"text_encoder": [(st, 9_400_000_000)]}
    # Both hosted: the preferred one wins, matching the resolver's download order.
    assert plan([_Sib(pt, 9_000_000_000), _Sib(st, 9_400_000_000)]) == {
        "text_encoder": [(st, 9_400_000_000)]
    }
    assert plan([_Sib("unrelated.bin", 1)]) == {}

    # Without safetensors support, plan the pickle; planning a refused file leaves no encoder.
    monkeypatch.setattr(tpq, "te_candidate_is_readable", lambda n: bool(n) and n.endswith(".pt"))
    assert plan([_Sib(pt, 9_000_000_000), _Sib(st, 9_400_000_000)]) == {
        "text_encoder": [(pt, 9_000_000_000)]
    }


def test_the_te_capability_question_is_not_the_transformers_one():
    """A pre-cast encoder .pt is plain tensors under a bare weights_only load, so it needs no
    constructor allowlist, unlike the DiT question."""
    assert tpq.te_candidate_is_readable("X-text_encoder-FP8.pt") is True
    assert tpq.te_candidate_is_readable(None) is False


def test_the_candidate_accessor_tolerates_a_planner_stand_in():
    """Planners pass lightweight objects carrying only ``filename``; reading the chain off one
    must not raise, or the whole pre-cast plan is swallowed into a silent dense fallback."""
    import types

    assert tpq.te_candidate_filenames(types.SimpleNamespace(filename = "a.pt")) == ("a.pt",)
    assert tpq.te_candidate_filenames(types.SimpleNamespace()) == ()


def test_an_unreachable_hub_is_not_a_missing_filename(monkeypatch):
    """``LocalEntryNotFoundError`` means two different things and only one of them is a miss.

    huggingface_hub documents it as "not on the disk when network is disabled OR UNAVAILABLE
    (connection issue). The entry may exist on the Hub", and it SUBCLASSES
    ``EntryNotFoundError``. Treating it as a candidate miss online spends a second full attempt on
    the next name and reports that one's error instead of the connection failure that happened.
    """
    import huggingface_hub
    from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError

    assert issubclass(
        LocalEntryNotFoundError, EntryNotFoundError
    ), "if this stops holding the ordering below is no longer load-bearing"
    src = TePrequantSource(
        kind = "repo",
        location = "org/hosted-fp8",
        filename = "hosted-text_encoder-FP8.safetensors",
        fallback_filenames = ("hosted-text_encoder-FP8.pt",),
    )
    asked: list = []

    def unreachable(**kw):
        asked.append(kw["filename"])
        online.append(not kw.get("local_files_only"))
        raise LocalEntryNotFoundError("Hub unreachable")

    online: list = []
    monkeypatch.setattr(huggingface_hub, "hf_hub_download", unreachable)
    # Online, the error surfaces and the 2nd candidate is only cache-checked (no network attempt).
    with pytest.raises(LocalEntryNotFoundError, match = "Hub unreachable"):
        tpq._resolve_checkpoint_path(src, None, cache_dir = "/tmp/x", local_files_only = False)
    assert asked == ["hosted-text_encoder-FP8.safetensors", "hosted-text_encoder-FP8.pt"], asked
    assert online == [True, False], online

    asked.clear()
    with pytest.raises(LocalEntryNotFoundError):
        tpq._resolve_checkpoint_path(src, None, cache_dir = "/tmp/x", local_files_only = True)
    assert asked == ["hosted-text_encoder-FP8.safetensors", "hosted-text_encoder-FP8.pt"], asked

    asked.clear()

    def only_pt(**kw):
        asked.append(kw["filename"])
        if kw["filename"].endswith(".safetensors"):
            raise EntryNotFoundError("404")
        return "/cache/hosted-text_encoder-FP8.pt"

    monkeypatch.setattr(huggingface_hub, "hf_hub_download", only_pt)
    got = tpq._resolve_checkpoint_path(src, None, cache_dir = "/tmp/x", local_files_only = False)
    assert got == "/cache/hosted-text_encoder-FP8.pt", got
    assert len(asked) == 2, asked


def test_the_video_prefetch_advances_only_on_a_missing_name():
    """The video prefetch must advance only on a missing name, matching the resolver and the load."""
    from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError

    from core.inference.video import VideoBackend

    miss = VideoBackend._te_fetch_miss
    assert miss(EntryNotFoundError("404"), local_files_only = False) is True
    assert miss(EntryNotFoundError("404"), local_files_only = True) is True
    assert miss(LocalEntryNotFoundError("no local copy"), local_files_only = True) is True
    # Online, this exception means the Hub was unreachable: stop, do not blame the name.
    assert miss(LocalEntryNotFoundError("connection error"), local_files_only = False) is False
    assert miss(PermissionError("401"), local_files_only = False) is False
    assert miss(OSError("corrupt cache"), local_files_only = True) is False


def test_every_family_default_scheme_is_one_we_actually_host_for_that_family():
    """Every family's default te_quant_auto scheme must be one actually hosted for that family."""
    from core.inference.diffusion_families import _FAMILIES
    from core.inference.diffusion_te_prequant import resolve_te_prequant_source

    offenders = []
    for fam in _FAMILIES:
        scheme = getattr(fam, "te_quant_auto", None)
        if scheme is None:
            continue
        # Check the resolver, not the fp8 table: a hosted int8 encoder lists the fp8 file behind it.
        if not any(
            resolve_te_prequant_source(fam, component, scheme)
            for component in tpq.TE_PREQUANT_COMPONENTS
        ):
            offenders.append(
                f"{fam.name}: te_quant_auto={scheme!r} with no hosted {scheme} encoder"
            )
    assert not offenders, "\n  ".join(
        ["families default to an unhosted encoder scheme:", *offenders]
    )


def test_qwen_image_2_1_defaults_to_a_hosted_encoder():
    """Qwen-Image-2.1 must default to a hosted encoder; dense, it outweighs the int8 denoiser."""
    from core.inference.diffusion_families import detect_family
    from core.inference.diffusion_te_prequant import resolve_te_prequant_source

    fam = detect_family("Qwen/Qwen-Image-2.1")
    assert fam.te_quant_auto == "int8"
    source = resolve_te_prequant_source(fam, "text_encoder", "int8")
    assert source is not None and source.kind == "repo"
    assert source.location == "unsloth/Qwen-Image-2.1-FP8"
    assert source.filename == "Qwen-Image-2.1-text_encoder-INT8-ConvRot.safetensors"
    assert source.fallback_filenames[0] == "Qwen-Image-2.1-text_encoder-FP8.safetensors"
    source = resolve_te_prequant_source(fam, "text_encoder", "fp8")
    assert source is not None and source.kind == "repo"
    assert source.location == "unsloth/Qwen-Image-2.1-FP8"
    assert source.filename == "Qwen-Image-2.1-text_encoder-FP8.safetensors"