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.

39.6 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

"""The torchao pick must match the resident torch, since its C++ extensions target one release."""

from __future__ import annotations

import importlib
import importlib.machinery
import sys
from pathlib import Path
from unittest.mock import MagicMock

import pytest

_INSTALL_SCRIPT = Path(__file__).resolve().parents[2] / "install_python_stack.py"
_EXTRAS_REQUIREMENTS = Path(__file__).resolve().parent.parent / "requirements" / "extras.txt"


def _load_module(monkeypatch):
    """(Re-)import install_python_stack and return it (mirrors test_pytorch_mirror)."""
    sys.modules.pop("install_python_stack", None)
    monkeypatch.syspath_prepend(str(_INSTALL_SCRIPT.parent))
    import install_python_stack

    return install_python_stack


@pytest.mark.parametrize(
    "torch_version, expected",
    [
        # torch 2.10 on CUDA <= 12 -> 0.16.0 (cpp built for 2.10.0, CUDA-12).
        ("2.10.0+cu128", "torchao==0.16.0"),
        ("2.10.0+cu126", "torchao==0.16.0"),
        ("2.10.0+rocm6.4", "torchao==0.16.0"),
        ("2.10.0+cpu", "torchao==0.16.0"),
        ("2.10.1", "torchao==0.16.0"),
        ("2.10.0", "torchao==0.16.0"),
        # torch 2.10 on CUDA >= 13: 0.16.0's CUDA-12 cpp fails (libcudart.so.12), use 0.17.0.
        ("2.10.0+cu130", "torchao==0.17.0"),
        ("2.10.0+cu140", "torchao==0.17.0"),
        ("2.10.0rc1", "torchao==0.16.0"),
        ("2.10.0.dev20250804+cu130", "torchao==0.17.0"),
        ("2.10.0.dev20250804+cu128", "torchao==0.16.0"),
        ("2.10rc1", "torchao==0.16.0"),
        # torchao 0.17.0 cpp is built for torch 2.11.
        ("2.11.0+cu130", "torchao==0.17.0"),
        ("2.11.0", "torchao==0.17.0"),
        ("2.11.1+cu126", "torchao==0.17.0"),
        # torchao 0.18.0 CI targets torch 2.13; torchao 0.17.0 supports only through torch 2.11.
        ("2.12.0", "torchao==0.18.0"),
        ("2.12.1+cu130", "torchao==0.18.0"),
        ("2.13.0+cu132", "torchao==0.18.0"),
        ("2.14.0+cu130", "torchao==0.18.0"),
        ("2.14.0+xpu", "torchao==0.18.0"),
        ("2.99.0", "torchao==0.18.0"),
        # CUDA 13 selection applies only to torch 2.10.
        ("2.12.0+cu126", "torchao==0.18.0"),
        ("2.12.0.dev20260801+cu132", "torchao==0.18.0"),
        # torchao 0.15.0 is the floor for diffusers 0.41's unconditional import (#13244).
        ("2.9.0+cu126", "torchao==0.15.0"),
        ("2.9.0+cu128", "torchao==0.15.0"),
        ("2.9.1", "torchao==0.15.0"),
        ("2.9.1+rocm6.4", "torchao==0.15.0"),
        # torch <= 2.8 gets 0.15.0 too: transformers 5 and diffusers 0.41 refuse TorchAoConfig on 0.14.
        ("2.8.0", "torchao==0.15.0"),
        ("2.8.0+cu128", "torchao==0.15.0"),
        ("2.7.1+cu126", "torchao==0.15.0"),
        ("2.6.0+cu124", "torchao==0.15.0"),
        # torchao 0.15 dropped torch <= 2.5, so those keep 0.14.0.
        ("2.5.1+cu124", "torchao==0.14.0"),
        ("2.4.0", "torchao==0.14.0"),
        # malformed, missing, and non-2.x versions use the conservative default.
        (None, "torchao==0.15.0"),
        ("", "torchao==0.15.0"),
        ("garbage", "torchao==0.15.0"),
        ("2", "torchao==0.15.0"),
        ("3.0.0", "torchao==0.15.0"),
    ],
)
def test_select_torchao_spec(monkeypatch, torch_version, expected):
    mod = _load_module(monkeypatch)
    assert mod._select_torchao_spec(torch_version) == expected


def test_default_spec_matches_table(monkeypatch):
    """torch 2.6-2.8 shares torch 2.9's torchao: below 0.15 transformers and diffusers refuse TorchAoConfig."""
    mod = _load_module(monkeypatch)
    assert mod._TORCHAO_DEFAULT_SPEC == "torchao==0.15.0"
    assert mod._select_torchao_spec("2.8.0") == mod._TORCHAO_DEFAULT_SPEC
    assert mod._TORCHAO_DEFAULT_SPEC == mod._TORCHAO_TORCH_29_SPEC


@pytest.mark.parametrize("installed", ["0.14.0", "0.14.0+cu128", "0.14.1+cu128", "0.13.0"])
def test_an_old_torch_install_on_torchao_014_is_repinned(monkeypatch, installed):
    """An existing torch <= 2.8 install keeps torchao 0.14 until its next dependency pass, which
    must force 0.15.0 over it even when the pass has evidence to skip satisfied steps."""
    mod = _load_module(monkeypatch)
    monkeypatch.setattr(mod, "IS_WINDOWS", False)
    monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: installed)
    monkeypatch.setattr(mod, "_may_skip_on_evidence", lambda: True)
    calls = []
    monkeypatch.setattr(mod, "pip_install_try", lambda *a, **k: calls.append(a) or True)
    monkeypatch.setattr(mod, "pip_install", lambda *a, **k: calls.append(a))
    monkeypatch.setattr(mod, "_record_step", lambda *a, **k: None)
    monkeypatch.setattr(mod, "_note", lambda *a, **k: None)
    mod._install_torchao_for_torch("2.8.0+cu128")
    assert len(calls) == 1, calls
    args = calls[0]
    assert "torchao==0.15.0" in args and "--force-reinstall" in args
    assert "https://download.pytorch.org/whl/cu128" in args


def test_matching_torchao_pin_does_not_need_force_reinstall(monkeypatch):
    mod = _load_module(monkeypatch)
    monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.17.0")
    assert mod._exact_distribution_spec_is_installed("torchao==0.17.0")
    assert not mod._exact_distribution_spec_is_installed("torchao==0.16.0")


@pytest.mark.parametrize(
    "torch_version, leaf",
    [
        ("2.12.0+cu126", "cu126"),
        ("2.13.0+cu132", "cu132"),
        ("2.14.0+cu130", "cu130"),
        ("2.11.0+rocm7.2", "rocm7.2"),  # rocm DOES publish torchao, unlike torchcodec
        ("2.9.0+rocm6.4", "rocm6.4"),
        ("2.14.0+xpu", "xpu"),
        ("2.12.0+cpu", "cpu"),
        # Untagged torch is PyPI's own build and its counterpart is PyPI's own torchao.
        ("2.14.0", None),
        ("2.11.0", None),
        (None, None),
        ("", None),
        ("garbage", None),
    ],
)
def test_the_torchao_index_follows_the_resident_torch_build(monkeypatch, torch_version, leaf):
    """The torchao index must follow the resident torch build; PyPI's default torchao is CUDA-12."""
    mod = _load_module(monkeypatch)
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
    got = mod._torch_accelerator_index_url(torch_version)
    assert got == (f"https://download.pytorch.org/whl/{leaf}" if leaf else None)


# only leaves missing a selected release are listed; omitted leaves cover their whole range.
_TORCHAO_INDEX_GAPS = {
    "cu118": ({m: f"0.{m}.0" for m in range(3, 12)}, range(5, 8)),
    "cu129": (
        {12: "0.12.0", 13: "0.13.0", 14: "0.14.1", 15: "0.15.0", 16: "0.16.0", 17: "0.17.0"},
        range(8, 14),
    ),
    "rocm7.0": ({16: "0.16.0"}, range(9, 11)),
    # Legacy leaves frozen before torchao 0.10 / 0.11: neither 0.14.0 nor 0.15.0 was ever there.
    "cu124": ({m: f"0.{m}.0" for m in range(3, 10)}, range(4, 7)),
    "rocm6.1": ({m: f"0.{m}.0" for m in range(7, 10)}, range(4, 7)),
}


def test_the_index_pin_starves_only_where_the_retry_covers_it(monkeypatch):
    """the default-index retry must cover every leaf missing its selected torchao release."""
    mod = _load_module(monkeypatch)
    starved = set()
    for leaf, (published, torch_minors) in _TORCHAO_INDEX_GAPS.items():
        for minor in torch_minors:
            version = f"2.{minor}.0+{leaf}"
            assert mod._torch_accelerator_index_url(version).endswith("/" + leaf)
            wanted = mod._select_torchao_spec(version).split("==", 1)[1]
            if wanted not in published.values():
                starved.add((leaf, minor, wanted))
    assert starved == {
        # cu118 lacks every selected torchao release for torch 2.5 through 2.7.
        ("cu118", 5, "0.14.0"),
        ("cu118", 6, "0.15.0"),
        ("cu118", 7, "0.15.0"),
        ("cu124", 4, "0.14.0"),
        ("cu124", 5, "0.14.0"),
        ("cu124", 6, "0.15.0"),
        ("rocm6.1", 4, "0.14.0"),
        ("rocm6.1", 5, "0.14.0"),
        ("rocm6.1", 6, "0.15.0"),
        # cu129 lacks releases after 0.17.0 (it does carry 0.15.0, which torch 2.8 now selects).
        ("cu129", 12, "0.18.0"),
        ("cu129", 13, "0.18.0"),
        # rocm7.0 provides only torchao 0.16.0.
        ("rocm7.0", 9, "0.15.0"),
    }, sorted(starved)


def _torchao_installer_source():
    source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
    body = source.split("def _install_torchao_for_torch(", 1)[1]
    return body.split("\ndef ", 1)[0]


def test_the_torchao_step_pins_the_index_and_retries_without_it():
    """a lagging accelerator leaf retries the default index, but failure there remains fatal."""
    body = _torchao_installer_source()
    assert "index = None if default_index else _torchao_index_url(torch_version)" in body
    assert '"--index-url", index, spec' in body
    assert "retrying from the default index" in body
    # The unpinned attempt is pip_install, not pip_install_try: still fatal on failure.
    retry = body.split("retrying from the default index", 1)[1]
    assert 'pip_install("Installing dependency overrides", *args, spec)' in retry
    assert "--index-url" not in retry
    # And the printed line redacts, since a mirror URL can carry credentials.
    assert "_strip_index_url_credentials(index)" in body


def test_the_fallback_is_never_conditioned_on_the_accelerator(monkeypatch):
    """A wrong-accelerator torchao costs its kernels, not its import, so the fallback stays
    unconditional -- guarding it on the CUDA major regressed CUDA-13/ROCm/XPU hosts from a
    slow torchao to none. torchao/__init__.py has wrapped the cpp load since 0.12.0."""
    body = _torchao_installer_source()
    fallback = body.split("retrying from the default index", 1)[1]
    assert 'pip_install("Installing dependency overrides", *args, spec)' in fallback
    # No branch between the failed pin and the retry. Comments carry the word; compare code.
    between = body.split("if pip_install_try(", 1)[1].split("retrying from the default index", 1)[0]
    code = [l for l in between.split("\n") if not l.strip().startswith("#")]
    assert not any(l.strip().startswith(("if ", "elif ")) for l in code), between
    mod = _load_module(monkeypatch)
    assert not hasattr(mod, "_default_index_torchao_can_load")


@pytest.mark.parametrize(
    "installed, spec, want_tag, expected",
    [
        ("0.18.0", "torchao==0.18.0", "<none>", False),
        ("0.18.0+cu130", "torchao==0.18.0", "<none>", True),
        ("0.17.0", "torchao==0.18.0", "<none>", True),
        (None, "torchao==0.18.0", "<none>", True),
        # Pinned: 0.18.0+cu126 satisfies ==0.18.0, so pip would keep the wrong build.
        ("0.18.0+cu130", "torchao==0.18.0", "cu130", False),
        ("0.18.0+cu126", "torchao==0.18.0", "cu130", True),
        ("0.18.0", "torchao==0.18.0", "cu130", True),
        ("0.18.0+rocm7.2", "torchao==0.18.0", "rocm7.2", False),
        ("0.17.0+cu130", "torchao==0.18.0", "cu130", True),
        # An opaque mirror proves nothing, so an untagged wheel is replaced.
        ("0.18.0", "torchao==0.18.0", None, True),
        ("0.18.0+cu130", "torchao==0.18.0", None, True),
    ],
)
def test_pin_needs_reinstall(monkeypatch, installed, spec, want_tag, expected):
    mod = _load_module(monkeypatch)
    monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: installed)
    tag = "" if want_tag == "<none>" else want_tag
    assert mod._pin_needs_reinstall(spec, tag) is expected


def test_the_wanted_tag_follows_the_index_that_will_be_pinned(monkeypatch):
    """The wanted tag must come from the index the pin resolves to, or pip skips the cu130 build."""
    mod = _load_module(monkeypatch)
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
    monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", "cu130")
    assert mod._torch_accelerator_index_url("2.13.0+cu128").endswith("/cu130")
    assert mod._torch_index_tag("2.13.0+cu128") == "cu130"

    monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.18.0+cu128")
    assert mod._pin_needs_reinstall("torchao==0.18.0", mod._torch_index_tag("2.13.0+cu128"))
    monkeypatch.setattr(mod, "_installed_distribution_version", lambda _name: "0.18.0+cu130")
    assert not mod._pin_needs_reinstall("torchao==0.18.0", mod._torch_index_tag("2.13.0+cu128"))

    monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", "https://mirror.corp.example/whl/cu130")
    assert mod._torch_index_tag("2.13.0+cu128") is None

    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL")
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY")
    assert mod._torch_index_tag("2.13.0+cu128") == "cu128"


_PYTORCH_WHL = "https://download.pytorch.org/whl"
_MIRROR_WHL = "https://mirror.example/whl"


@pytest.mark.parametrize(
    "is_windows, torch_version, family, url, base, expected",
    [
        (True, "2.13.0+cu130", "", "", _PYTORCH_WHL, None),
        (True, "2.12.0+cu126", "", "", _PYTORCH_WHL, None),
        (True, "2.10.0+cu128", "", "", _PYTORCH_WHL, None),
        (True, "2.13.0+cu128", "cu130", "", _PYTORCH_WHL, None),
        # The cpu and xpu leaves serve Windows a py3-none-any wheel.
        (True, "2.12.0+cpu", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cpu"),
        (True, "2.14.0+xpu", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/xpu"),
        (True, "2.13.0+cu130", "cpu", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cpu"),
        (True, "2.13.0", "", "", _PYTORCH_WHL, None),
        # Mirrors and explicit indexes stay pinned.
        (True, "2.13.0+cu130", "", "", _MIRROR_WHL, f"{_MIRROR_WHL}/cu130"),
        (True, "2.13.0+cu130", "", f"{_MIRROR_WHL}/cu130", _PYTORCH_WHL, f"{_MIRROR_WHL}/cu130"),
        # Not a CUDA leaf, though it starts with "cu".
        (True, "2.13.0+cu130", "current", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/current"),
        (False, "2.13.0+cu130", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cu130"),
        (False, "2.12.0+cu126", "", "", _PYTORCH_WHL, f"{_PYTORCH_WHL}/cu126"),
    ],
)
def test_windows_cuda_takes_torchao_unpinned(
    monkeypatch, is_windows, torch_version, family, url, base, expected
):
    mod = _load_module(monkeypatch)
    monkeypatch.setattr(mod, "IS_WINDOWS", is_windows)
    monkeypatch.setattr(mod, "_PYTORCH_WHL_BASE", base)
    monkeypatch.setenv("UNSLOTH_TORCH_INDEX_FAMILY", family)
    monkeypatch.setenv("UNSLOTH_TORCH_INDEX_URL", url)
    assert mod._torchao_index_url(torch_version) == expected


def test_a_windows_cuda_update_leaves_the_installed_torchao_alone(monkeypatch):
    """The untagged wheel the first run installs must satisfy the next run's tag check."""
    mod = _load_module(monkeypatch)
    monkeypatch.setattr(mod, "IS_WINDOWS", True)
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_URL", raising = False)
    monkeypatch.delenv("UNSLOTH_TORCH_INDEX_FAMILY", raising = False)
    monkeypatch.delenv(mod._FULL_DEPS_ENV, raising = False)
    notes: list[str] = []
    calls: list[tuple] = []
    monkeypatch.setattr(mod, "_note", notes.append)
    monkeypatch.setattr(mod, "pip_install", lambda *a, **k: calls.append(a))
    monkeypatch.setattr(mod, "pip_install_try", lambda *a, **k: calls.append(a) or True)

    installed = {"torchao": None}
    monkeypatch.setattr(mod, "_installed_distribution_version", lambda n: installed.get(n))
    monkeypatch.setattr(mod, "_PASS_EVIDENCE", None)
    mod._install_torchao_for_torch("2.13.0+cu130")
    assert len(calls) == 1 and "--index-url" not in calls[0], calls
    assert not any("did not serve" in n for n in notes), notes

    installed["torchao"] = "0.18.0"
    monkeypatch.setattr(mod, "_PASS_EVIDENCE", {"pass_inputs": {}, "step_results": {}})
    mod._install_torchao_for_torch("2.13.0+cu130")
    assert len(calls) == 1, calls
    assert mod._STEP_RESULTS.get("torchao") == "skipped"


def test_every_torchao_call_site_asks_for_the_pinned_tag():
    """Passing the torch version rather than the pinned tag would reintroduce the drift the
    helper exists to remove, so no call site may spell it any other way."""
    source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
    assert source.count("_pin_needs_reinstall(") == 3  # the def plus both call sites
    assert '_torch_index_tag(torch_version) if index else ""' in source
    assert '_torch_index_tag(_label_after) if _ao_index else ""' in source
    assert "_ao_index = _torchao_index_url(_label_after)" in source


def test_no_torchao_install_can_resolve_a_dependency():
    """Both call sites pass --no-deps; the post-repair one runs right after step 13 fixed the torch
    build; no torchao release needs torch today, so keep it if one ever does."""
    body = _torchao_installer_source()
    assert 'args = ["--no-deps", "--no-cache-dir"]' in body
    # --force-reinstall must not be able to widen the install back out.
    for call in ("pip_install(", "pip_install_try("):
        for fragment in body.split(call)[1:]:
            assert "*args" in fragment.split(")")[0], fragment[:120]
    source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
    resync = source.split("def _resync_torch_coupled_packages", 1)[1]
    ao = resync.split("_ao_index", 1)[1][:1200]
    assert "--no-deps" in ao


def test_torchao_is_re_selected_after_the_linux_torch_repair():
    """torchao is re-selected after the Linux torch repair, since only the Windows repair resyncs it."""
    source = _INSTALL_SCRIPT.read_text(encoding = "utf-8")
    step = source.split('_progress(_torch_step_label("final"))', 1)[1]
    step = step.split("# 13w.", 1)[0]
    assert '_torch_before_repair = str(_probe_installed_torch_version() or "")' in step
    assert "_install_torchao_for_torch(_torch_after_repair)" in step
    # Guarded on an actual move, so an install where nothing shifted pays no second resolve.
    assert "if _torch_after_repair and _torch_after_repair != _torch_before_repair:" in step
    assert '"torch>=2.6,<2.11.0",' in source


def test_windows_first_hop_uses_einx_wheel_without_shared_test_tree():
    requirements = _EXTRAS_REQUIREMENTS.read_text(encoding = "utf-8")
    assert 'einx<0.4.3; sys_platform == "win32"' in requirements
    # einx dropped 3.9 in 0.4.0, so the non-Windows side is split by interpreter.
    assert 'einx==0.4.3; sys_platform != "win32" and python_version >= "3.10"' in requirements
    assert 'einx==0.3.0; sys_platform != "win32" and python_version < "3.10"' in requirements


@pytest.mark.parametrize(
    ("rocm_windows_torch_installed", "installed_torch_is_windows_rocm"),
    [
        (True, False),
        (False, True),
        (True, True),
    ],
)
@pytest.mark.parametrize("torchao_install_ok", [True, False])
def test_installs_pypi_torchao_on_windows_rocm(
    monkeypatch,
    tmp_path,
    rocm_windows_torch_installed,
    installed_torch_is_windows_rocm,
    torchao_install_ok,
):
    """Windows ROCm gets the torch-matched torchao from PyPI (download.pytorch.org's rocm leaves
    serve Linux only); the export worker loads it through unsloth/_torchao_nodist.py. A failed
    torchao install does not fail the install: only export needs it."""
    mod = _load_module(monkeypatch)
    pip_calls: list[list[str]] = []
    progress_labels: list[str] = []

    def _record_pip_install(*args, **kwargs):
        pip_calls.append([str(arg) for arg in args])
        return 0

    unstructured_plugin = tmp_path / "unstructured"
    github_plugin = tmp_path / "github"
    unstructured_plugin.mkdir()
    github_plugin.mkdir()

    subprocess_result = MagicMock()
    subprocess_result.returncode = 0
    subprocess_result.stdout = ""

    monkeypatch.setenv("SKIP_STUDIO_BASE", "1")
    monkeypatch.setattr(mod, "IS_WINDOWS", True)
    monkeypatch.setattr(mod, "IS_MACOS", False)
    monkeypatch.setattr(mod, "IS_MAC_ARM", False)
    monkeypatch.setattr(mod, "NO_TORCH", False)
    monkeypatch.setattr(mod, "_rocm_windows_torch_installed", rocm_windows_torch_installed)
    monkeypatch.setattr(
        mod, "_installed_torch_is_windows_rocm", lambda: installed_torch_is_windows_rocm
    )
    # require_present refuses when a managed distribution is absent (SKIP_STUDIO_BASE
    # guarantees that here); stub it so the test does not depend on the env.
    monkeypatch.setattr(mod, "_repair_damaged_core_payload", lambda *a, **k: True)
    monkeypatch.setattr(mod, "_bootstrap_uv", lambda: False)
    monkeypatch.setattr(mod, "_repair_bad_anyio", lambda: None)
    monkeypatch.setattr(mod, "_repair_bad_accelerate", lambda: None)
    monkeypatch.setattr(mod, "_ensure_rocm_torch", lambda: None)
    monkeypatch.setattr(mod, "_ensure_cuda_torch", lambda: None)
    # A Windows ROCm box has no NVIDIA GPU; _expected_torch_flavor_tag reads this flag.
    monkeypatch.setattr(mod, "_has_usable_nvidia_gpu", lambda: False)
    # The installed torch is ambient; pin it so the verdict does not depend on the host.
    monkeypatch.setattr(mod, "_RECORDED_TORCH_TAG", "")
    monkeypatch.setattr(
        mod, "_probe_torch_runtime", lambda *args, **kwargs: (True, True, "2.9.1+cpu", "", "")
    )
    monkeypatch.setattr(mod, "run", lambda *args, **kwargs: None)

    def _fatal_pip_install(*args, **kwargs):
        # pip_install exits the installer on failure.
        _record_pip_install(*args, **kwargs)
        if not torchao_install_ok and any(str(a).startswith("torchao") for a in args):
            raise SystemExit(1)
        return 0

    monkeypatch.setattr(mod, "pip_install", _fatal_pip_install)
    monkeypatch.setattr(
        mod,
        "pip_install_try",
        lambda *a, **k: (
            _record_pip_install(*a, **k),
            torchao_install_ok or not any(str(x).startswith("torchao") for x in a),
        )[1],
    )
    monkeypatch.setattr(mod, "_progress", lambda label: progress_labels.append(label))
    monkeypatch.setattr(mod, "LOCAL_DD_UNSTRUCTURED_PLUGIN", unstructured_plugin)
    monkeypatch.setattr(mod, "LOCAL_DD_GITHUB_PLUGIN", github_plugin)
    monkeypatch.setattr(mod.subprocess, "run", lambda *args, **kwargs: subprocess_result)

    # Checked first so a regression names its cause instead of `assert 1 == 0` below.
    assert mod._expected_torch_flavor_tag() == "", (
        "no CUDA expectation may exist on a Windows ROCm host: a non-empty tag means "
        "the Windows flavor invariant will demand a cu* build, not find one, and fail "
        "the install long after the torchao branch this test is about"
    )

    assert mod.install_python_stack() == 0

    torchao_calls = [c for c in pip_calls if any(a.startswith("torchao") for a in c)]
    assert torchao_calls
    assert all("--index-url" not in c for c in torchao_calls)
    assert "dependency overrides (Windows ROCm)" in progress_labels


# Windows ROCm torchao export: real torchao via unsloth/_torchao_nodist.py, the stub as fallback.

import types

import core._torchao_stub as _stub

_BACKEND = Path(__file__).resolve().parents[1]
_EXPORT_HELPERS = ("_torchao_export_supported", "_torchao_runtime_unavailable", "_is_torchao_alias")


def _export_helpers():
    """Exec the gate helpers alone, avoiding export.py's heavy import chain."""
    import ast

    src = (_BACKEND / "core" / "export" / "export.py").read_text(encoding = "utf-8")
    ns: dict = {}
    for node in ast.parse(src).body:
        if isinstance(node, ast.FunctionDef) and node.name in _EXPORT_HELPERS:
            exec(ast.get_source_segment(src, node), ns)
    return ns


def _fake_normalize_torchao(save_method):
    if not isinstance(save_method, str):
        return None
    key = save_method.lower().strip().replace("-", "_").replace(" ", "_")
    ok = key in {"torchao_fp8", "torchao_int8", "portable_fp8", "portable_int8"}
    return ("fp8", "torchao-fp8") if ok else None


def _install_fake_unsloth_save(monkeypatch, *, has_method):
    unsloth = types.ModuleType("unsloth")
    save = types.ModuleType("unsloth.save")
    if has_method:
        save._normalize_torchao_method = _fake_normalize_torchao
    unsloth.save = save
    monkeypatch.setitem(sys.modules, "unsloth", unsloth)
    monkeypatch.setitem(sys.modules, "unsloth.save", save)


def _set_torchao(monkeypatch, state):
    if state == "absent":
        monkeypatch.delitem(sys.modules, "torchao", raising = False)
    elif state == "stub":
        monkeypatch.setitem(sys.modules, "torchao", _stub._make_mod_stub("torchao"))
    else:
        monkeypatch.setitem(sys.modules, "torchao", types.ModuleType("torchao"))


@pytest.mark.parametrize(
    ("win_rocm", "torchao", "has_method", "expected"),
    [
        (True, "stub", True, False),
        (True, "absent", True, False),
        (True, "real", True, True),
        (False, "real", True, True),
        (False, "absent", True, True),
        (False, "real", False, False),
    ],
)
def test_torchao_export_gate(monkeypatch, win_rocm, torchao, has_method, expected):
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: win_rocm)
    _set_torchao(monkeypatch, torchao)
    _install_fake_unsloth_save(monkeypatch, has_method = has_method)
    ns = _export_helpers()
    ns["sys"] = sys
    assert ns["_torchao_export_supported"]() is expected


def test_is_torchao_alias_recognizes_all_forms(monkeypatch):
    _install_fake_unsloth_save(monkeypatch, has_method = True)
    fn = _export_helpers()["_is_torchao_alias"]
    for alias in ("torchao_fp8", "portable_int8", "portable-fp8", "Portable FP8"):
        assert fn(alias) is True
    for alias in ("fp8", "nvfp4", "w8a8", "", None):
        assert fn(alias) is False


def _load_export_module_no_torch(monkeypatch):
    """Import core.export.export with torch/unsloth blocked, so the guard runs without a GPU."""
    import builtins
    import importlib

    real_import = builtins.__import__

    def blocking_import(name, *args, **kwargs):
        top = name.split(".")[0]
        if top in {"torch", "unsloth"} and top not in sys.modules:
            raise ImportError(f"blocked: {name}")
        return real_import(name, *args, **kwargs)

    for m in [k for k in list(sys.modules) if k.split(".")[0] in {"torch", "unsloth"}]:
        monkeypatch.delitem(sys.modules, m, raising = False)
    monkeypatch.delitem(sys.modules, "core.export.export", raising = False)
    monkeypatch.setattr(builtins, "__import__", blocking_import)
    return importlib.import_module("core.export.export")


def _bare_backend(mod):
    be = mod.ExportBackend.__new__(mod.ExportBackend)
    be.current_model = object()
    be.current_tokenizer = object()
    be._audio_type = None
    be.is_peft = True
    return be


@pytest.mark.parametrize("alias", ["torchao_fp8", "portable_fp8"])
def test_torchao_export_rejected_early_when_stubbed(monkeypatch, alias):
    mod = _load_export_module_no_torch(monkeypatch)
    monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    _set_torchao(monkeypatch, "stub")
    _install_fake_unsloth_save(monkeypatch, has_method = True)

    ok, message, out = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = alias)
    assert ok is False and out is None
    assert "Windows ROCm" in message and "torchao" in message.lower()


def test_torchao_export_not_rejected_with_real_torchao_on_windows_rocm(monkeypatch):
    mod = _load_export_module_no_torch(monkeypatch)
    monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    _set_torchao(monkeypatch, "real")
    _install_fake_unsloth_save(monkeypatch, has_method = True)

    ok, message, _ = _bare_backend(mod).export_merged_model(
        "/tmp/x", compressed_method = "torchao_int8"
    )
    assert ok is False and "Windows ROCm" not in message


@pytest.mark.parametrize(
    ("platform", "is_rocm", "loadable", "expected"),
    [
        ("win32", True, False, False),
        ("win32", True, True, True),
        # torchao_export_loadable is asked everywhere now: it also says no to torchao < 0.15.
        ("win32", False, False, False),
        ("win32", False, True, True),
        ("linux", True, False, False),
        ("linux", False, False, False),
        ("linux", False, True, True),
    ],
)
def test_export_capability_torchao_flag(monkeypatch, platform, is_rocm, loadable, expected):
    import utils.hardware.hardware as hw

    monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CUDA)
    monkeypatch.setattr(sys, "platform", platform)
    monkeypatch.setattr(hw, "IS_ROCM", is_rocm)
    monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: loadable)
    assert hw.export_capability()["torchao_export_supported"] is expected


@pytest.mark.parametrize(
    ("platform", "is_rocm", "expected"),
    [("win32", True, False), ("win32", False, True), ("linux", False, True), ("linux", True, True)],
)
def test_export_capability_fails_open_off_windows_rocm(monkeypatch, platform, is_rocm, expected):
    import utils.hardware.hardware as hw

    def broken():
        raise RuntimeError("probe failed")

    monkeypatch.setattr(hw, "get_device", lambda: hw.DeviceType.CUDA)
    monkeypatch.setattr(sys, "platform", platform)
    monkeypatch.setattr(hw, "IS_ROCM", is_rocm)
    monkeypatch.setattr(_stub, "torchao_export_loadable", broken)
    assert hw.export_capability()["torchao_export_supported"] is expected


@pytest.mark.parametrize(
    ("installed", "too_old"),
    [
        ("0.14.0", "0.14.0"),
        ("0.14.1+cu128", "0.14.1+cu128"),
        ("0.13.0", "0.13.0"),
        # PEP 440, as transformers compares: prereleases of 0.15.0 are still below it.
        ("0.15.0rc1", "0.15.0rc1"),
        ("0.15.0.dev20250901", "0.15.0.dev20250901"),
        ("0.15.0", None),
        ("0.15.0+cu126", None),
        ("0.17.0", None),
        ("0.18.0+rocm7.2", None),
        ("1.0.0", None),
        (None, None),
    ],
)
def test_torchao_export_loadable_needs_015_on_every_platform(monkeypatch, installed, too_old):
    """transformers 5 refuses torchao < 0.15 with "requires torchao to be installed"."""
    import importlib.metadata as md

    def version(name):
        if installed is None:
            raise md.PackageNotFoundError(name)
        return installed

    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
    monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
    monkeypatch.setattr(_stub.importlib.metadata, "version", version)
    saved = {n: m for n, m in sys.modules.items() if n == "torchao" or n.startswith("torchao.")}
    for name in saved:
        monkeypatch.delitem(sys.modules, name)
    assert _stub.torchao_export_loadable() is (too_old is None)
    # metadata only: never imports torchao.
    assert "torchao" not in sys.modules
    assert _stub.torchao_too_old_for_export() == too_old


@pytest.mark.parametrize("floor", ["0.4.0", None])
def test_torchao_014_stays_exportable_where_transformers_accepts_it(monkeypatch, floor):
    """transformers 4.57.6 (the Python 3.9 pin, torch 2.4 / 2.5 keep torchao 0.14) has a 0.4 floor;
    an unreadable floor never hides the formats either."""
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
    monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: floor)
    monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
    assert _stub.torchao_too_old_for_export() is None
    assert _stub.torchao_export_loadable() is True


@pytest.mark.parametrize(
    ("source", "expected"),
    [
        ('TORCHAO_MIN_VERSION = "0.15.0"\n', "0.15.0"),
        ("x = 1\nTORCHAO_MIN_VERSION = '0.4.0'\n", "0.4.0"),
        ("x = 1\n", None),
    ],
)
def test_transformers_torchao_min_read_without_import(monkeypatch, tmp_path, source, expected):
    pkg = tmp_path / "transformers"
    (pkg / "utils").mkdir(parents = True)
    (pkg / "__init__.py").write_text("raise RuntimeError('must not be imported')\n")
    (pkg / "utils" / "import_utils.py").write_text(source)
    for name in [n for n in sys.modules if n == "transformers" or n.startswith("transformers.")]:
        monkeypatch.delitem(sys.modules, name)
    monkeypatch.syspath_prepend(str(tmp_path))
    assert _stub._transformers_torchao_min() == expected
    assert "transformers" not in sys.modules


@pytest.mark.parametrize("alias", ["torchao_fp8", "portable_int8"])
def test_torchao_export_rejected_early_when_torchao_is_too_old(monkeypatch, alias):
    mod = _load_export_module_no_torch(monkeypatch)
    monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
    monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
    monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
    _set_torchao(monkeypatch, "real")
    _install_fake_unsloth_save(monkeypatch, has_method = True)

    ok, message, out = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = alias)
    assert ok is False and out is None
    assert "0.15" in message and "0.14.0" in message


def test_too_old_torchao_does_not_block_other_formats(monkeypatch):
    mod = _load_export_module_no_torch(monkeypatch)
    monkeypatch.setattr(mod, "_export_runtime_available", lambda: True)
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
    monkeypatch.setattr(_stub, "_transformers_torchao_min", lambda: "0.15.0")
    monkeypatch.setattr(_stub.importlib.metadata, "version", lambda name: "0.14.0")
    _install_fake_unsloth_save(monkeypatch, has_method = True)

    ok, message, _ = _bare_backend(mod).export_merged_model("/tmp/x", compressed_method = None)
    assert "0.15" not in (message or "")


def test_torchao_export_loadable_ignores_the_stub(monkeypatch):
    # The main process has already stubbed torchao; only an installed torchao counts.
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    _set_torchao(monkeypatch, "stub")
    real = importlib.machinery.PathFinder.find_spec
    monkeypatch.setattr(
        importlib.machinery.PathFinder,
        "find_spec",
        classmethod(lambda cls, name, *a, **k: None if name == "torchao" else real(name, *a, **k)),
    )
    assert _stub.torchao_export_loadable() is False


@pytest.mark.parametrize(
    ("installed", "expect"),
    [
        ("0.14.0", False),
        ("0.15.0rc1", False),
        ("0.15.0", True),
        ("0.17.0", True),
        ("0.18.0+rocm", True),
    ],
)
def test_torchao_export_loadable_needs_transformers_minimum(
    monkeypatch, tmp_path, installed, expect
):
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    (tmp_path / "unsloth").mkdir()
    (tmp_path / "unsloth" / "_torchao_nodist.py").write_text("")
    specs = {
        "torchao": importlib.machinery.ModuleSpec("torchao", None),
        "unsloth": importlib.machinery.ModuleSpec("unsloth", None, is_package = True),
    }
    specs["unsloth"].submodule_search_locations = [str(tmp_path / "unsloth")]
    monkeypatch.setattr(
        importlib.machinery.PathFinder,
        "find_spec",
        classmethod(lambda cls, name, *a, **k: specs.get(name)),
    )
    monkeypatch.setattr(importlib.util, "find_spec", lambda name, *a, **k: specs.get(name))
    monkeypatch.setattr(importlib.metadata, "version", lambda name: installed)
    assert _stub.torchao_export_loadable() is expect


@pytest.mark.parametrize(("fix_result", "expect_real"), [(True, True), (False, False)])
def test_real_or_stub(monkeypatch, fix_result, expect_real):
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: True)
    monkeypatch.delitem(sys.modules, "torchao", raising = False)
    calls = []

    def fix():
        calls.append(1)
        if fix_result:
            sys.modules["torchao"] = types.ModuleType("torchao")
        return fix_result

    monkeypatch.setattr(
        _stub,
        "_load_torchao_nodist",
        lambda: types.SimpleNamespace(fix_torchao_without_torch_distributed = fix),
    )
    stubbed = []
    monkeypatch.setattr(_stub, "install_torchao_windows_rocm_stub", lambda: stubbed.append(1))
    try:
        assert _stub.install_torchao_windows_rocm_real_or_stub() is expect_real
        assert calls == [1]
        assert bool(stubbed) is (not expect_real)
    finally:
        sys.modules.pop("torchao", None)


@pytest.mark.parametrize("consumer_loaded", [False, True])
def test_real_or_stub_replaces_a_stub_inherited_from_run_py(monkeypatch, consumer_loaded):
    """spawn re-runs run.py as __mp_main__, which stubs torchao before the export worker starts."""
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: True)
    # Simulated "already imported" consumer: json is always loaded; none of the real ones is required.
    monkeypatch.setattr(_stub, "_STUB_CONSUMERS", ("json",) if consumer_loaded else ())
    saved = {n: m for n, m in sys.modules.items() if n == "torchao" or n.startswith("torchao.")}
    for name in saved:
        monkeypatch.delitem(sys.modules, name)
    calls = []

    def fix():
        calls.append("torchao" in sys.modules)
        sys.modules["torchao"] = types.ModuleType("torchao")
        return True

    monkeypatch.setattr(
        _stub,
        "_load_torchao_nodist",
        lambda: types.SimpleNamespace(fix_torchao_without_torch_distributed = fix),
    )
    try:
        _stub.install_torchao_windows_rocm_stub()
        assert _stub.is_stubbed("torchao")
        result = _stub.install_torchao_windows_rocm_real_or_stub()
        if consumer_loaded:
            assert result is False and calls == [] and _stub.is_stubbed("torchao")
        else:
            assert result is True and calls == [False] and not _stub.is_stubbed("torchao")
            assert not any(n.startswith("torchao.") for n in sys.modules)
    finally:
        for name in [n for n in sys.modules if n == "torchao" or n.startswith("torchao.")]:
            del sys.modules[name]
        sys.modules.update(saved)


def test_real_or_stub_keeps_the_stub_when_torchao_is_not_loadable(monkeypatch):
    """an install still on torchao 0.14 (transformers 5 rejects it) never loads it."""
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: True)
    monkeypatch.setattr(_stub, "torchao_export_loadable", lambda: False)
    monkeypatch.delitem(sys.modules, "torchao", raising = False)
    monkeypatch.setattr(
        _stub, "_load_torchao_nodist", lambda: pytest.fail("must not load the shim")
    )
    stubbed = []
    monkeypatch.setattr(_stub, "install_torchao_windows_rocm_stub", lambda: stubbed.append(1))
    assert _stub.install_torchao_windows_rocm_real_or_stub() is False
    assert stubbed == [1]


def test_shim_found_through_an_editable_finder(monkeypatch, tmp_path):
    """setuptools editable installs can expose unsloth only through a meta-path finder."""
    (tmp_path / "unsloth").mkdir()
    (tmp_path / "unsloth" / "_torchao_nodist.py").write_text(
        "def fix_torchao_without_torch_distributed():\n    return 'ok'\n"
    )

    class EditableFinder:
        def find_spec(
            self,
            name,
            path = None,
            target = None,
        ):
            if name != "unsloth":
                return None
            spec = importlib.machinery.ModuleSpec("unsloth", None, is_package = True)
            spec.submodule_search_locations = [str(tmp_path / "unsloth")]
            return spec

    monkeypatch.delitem(sys.modules, "unsloth", raising = False)
    real = importlib.machinery.PathFinder.find_spec
    monkeypatch.setattr(
        importlib.machinery.PathFinder,
        "find_spec",
        classmethod(lambda cls, name, *a, **k: None if name == "unsloth" else real(name, *a, **k)),
    )
    monkeypatch.setattr(sys, "meta_path", [EditableFinder(), *sys.meta_path])
    module = _stub._load_torchao_nodist()
    assert module is not None and module.fix_torchao_without_torch_distributed() == "ok"


def test_real_or_stub_noop_off_windows_rocm(monkeypatch):
    monkeypatch.setattr(_stub, "_is_windows_rocm", lambda: False)
    monkeypatch.setattr(
        _stub, "_load_torchao_nodist", lambda: pytest.fail("must not load the shim")
    )
    assert _stub.install_torchao_windows_rocm_real_or_stub() is False


def test_load_torchao_nodist_reads_unsloths_file():
    module = _stub._load_torchao_nodist()
    if importlib.util.find_spec("unsloth") is None:
        assert module is None
    else:
        assert callable(module.fix_torchao_without_torch_distributed)