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.

41.5 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

"""Attention-backend tests run without torch: _is_cuda_nvidia is patched, the apply path faked."""

from __future__ import annotations

import sys
import types

import pytest

import core.inference.diffusion_attention as att
from core.inference.diffusion_attention import (
    ATTN_AUTO,
    apply_attention_backend,
    normalize_attention_backend,
    select_attention_backend,
)


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


def test_normalize_defaults_and_aliases():
    assert normalize_attention_backend(None) == ATTN_AUTO
    assert normalize_attention_backend("") == ATTN_AUTO
    assert normalize_attention_backend("auto") == ATTN_AUTO
    assert normalize_attention_backend("CuDNN") == "cudnn"
    assert normalize_attention_backend("FLASH3") == "flash3"
    assert normalize_attention_backend("sdpa") == "sdpa"


def test_normalize_rejects_unknown():
    with pytest.raises(ValueError):
        normalize_attention_backend("bogus")
    with pytest.raises(ValueError):
        normalize_attention_backend("flash-3")


def test_sdpa_alias_maps_to_native():
    assert select_attention_backend(_target(), "sdpa", speed_active = True) is None


def test_auto_upgrades_to_cudnn_on_nvidia_when_speed_active(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: True)
    monkeypatch.setattr(att, "_cuda_capability", lambda: (8, 0))
    assert select_attention_backend(_target(), "auto", speed_active = True) == "_native_cudnn"


def test_auto_does_not_pin_cudnn_below_sm80(monkeypatch):
    # cuDNN fused SDPA fails at run time on pre-SM80 (T4 / V100).
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: True)
    monkeypatch.setattr(att, "_cuda_capability", lambda: (7, 5))
    assert select_attention_backend(_target(), "auto", speed_active = True) is None


def test_auto_stays_native_when_speed_off(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: True)
    assert select_attention_backend(_target(), "auto", speed_active = False) is None


def test_auto_stays_native_off_nvidia(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: False)
    assert select_attention_backend(_target(device = "mps"), "auto", speed_active = True) is None


def test_explicit_backend_honored_regardless_of_speed(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: True)
    monkeypatch.setattr(att, "_cuda_capability", lambda: (10, 0))
    assert select_attention_backend(_target(), "sage", speed_active = False) == "sage"
    assert select_attention_backend(_target(), "flash4", speed_active = False) == "flash_4_hub"
    assert select_attention_backend(_target(), "cudnn", speed_active = False) == "_native_cudnn"


def test_explicit_backend_dropped_off_nvidia_cuda(monkeypatch):
    # Explicit cuDNN/flash/sage on ROCm/MPS/CPU passes diffusers' set-time check, then crashes.
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: False)
    monkeypatch.setattr(att, "_cuda_capability", lambda: (10, 0))
    for alias in ("sage", "flash", "flash4", "cudnn"):
        assert select_attention_backend(_target(device = "mps"), alias, speed_active = True) is None


def test_aiter_honored_on_rocm(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: False)
    assert select_attention_backend(_target(), "aiter", speed_active = False) == "aiter"


def test_aiter_dropped_off_rocm(monkeypatch):
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: True)
    assert select_attention_backend(_target(), "aiter", speed_active = False) is None
    monkeypatch.setattr(att, "_is_cuda_nvidia", lambda target: False)
    assert select_attention_backend(_target(device = "mps"), "aiter", speed_active = False) is None


def test_explicit_native_returns_none():
    assert select_attention_backend(_target(), "native", speed_active = True) is None


def test_flash3_dropped_below_hopper(monkeypatch):
    monkeypatch.setattr(att, "_cuda_capability", lambda: (8, 9))
    assert select_attention_backend(_target(), "flash3", speed_active = False) is None


def test_flash4_dropped_below_blackwell(monkeypatch):
    monkeypatch.setattr(att, "_cuda_capability", lambda: (9, 0))
    assert select_attention_backend(_target(), "flash4", speed_active = False) is None
    assert select_attention_backend(_target(), "flash3", speed_active = False) == "_flash_3_hub"


def test_arch_gate_does_not_block_when_capability_unknown(monkeypatch):
    monkeypatch.setattr(att, "_cuda_capability", lambda: None)
    assert select_attention_backend(_target(), "flash4", speed_active = False) == "flash_4_hub"


def test_flash3_dropped_on_blackwell(monkeypatch):
    # FA3 is Hopper-only (no Blackwell kernel): it would set fine on B200, then crash.
    monkeypatch.setattr(att, "_cuda_capability", lambda: (10, 0))
    assert select_attention_backend(_target(), "flash3", speed_active = False) is None
    assert select_attention_backend(_target(), "flash4", speed_active = False) == "flash_4_hub"
    monkeypatch.setattr(att, "_cuda_capability", lambda: (9, 0))
    assert select_attention_backend(_target(), "flash3", speed_active = False) == "_flash_3_hub"


def test_explicit_cudnn_dropped_below_sm80(monkeypatch):
    monkeypatch.setattr(att, "_cuda_capability", lambda: (7, 5))
    assert select_attention_backend(_target(), "cudnn", speed_active = False) is None
    monkeypatch.setattr(att, "_cuda_capability", lambda: (8, 0))
    assert select_attention_backend(_target(), "cudnn", speed_active = False) == "_native_cudnn"


class _FakeTransformer:
    def __init__(self, *, fail = False):
        self.fail = fail
        self.set_to = None

    def set_attention_backend(self, name):
        if self.fail:
            raise RuntimeError(f"{name} kernel unavailable")
        self.set_to = name


def _pipe(transformer):
    return types.SimpleNamespace(transformer = transformer)


def test_apply_none_leaves_native_when_global_already_native(monkeypatch):
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
    t = _FakeTransformer()
    assert apply_attention_backend(_pipe(t), None) is None
    assert t.set_to is None


def test_apply_none_restores_native_when_global_polluted(monkeypatch):
    # A previous load pinned cuDNN process-wide; a native load must reset it.
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "_native_cudnn")
    t = _FakeTransformer()
    assert apply_attention_backend(_pipe(t), None) is None
    assert t.set_to == "native"


def test_apply_sets_backend():
    t = _FakeTransformer()
    engaged = apply_attention_backend(_pipe(t), "_native_cudnn")
    assert engaged == "_native_cudnn" and t.set_to == "_native_cudnn"


def test_apply_sets_backend_on_both_dits():
    # Ideogram runs both DiTs each step, so the backend must be set on both.
    t1, t2 = _FakeTransformer(), _FakeTransformer()
    pipe = types.SimpleNamespace(transformer = t1, unconditional_transformer = t2)
    engaged = apply_attention_backend(pipe, "_native_cudnn")
    assert engaged == "_native_cudnn"
    assert t1.set_to == "_native_cudnn" and t2.set_to == "_native_cudnn"


def test_apply_falls_back_on_unavailable_kernel(monkeypatch):
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
    t = _FakeTransformer(fail = True)
    assert apply_attention_backend(_pipe(t), "sage") is None


def test_apply_failed_kernel_restores_native_when_polluted(monkeypatch):
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "_native_cudnn")
    monkeypatch.setattr(att, "_sage_version_too_old", lambda: None)
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True)
    monkeypatch.setattr(att, "_install_sage_dispatch_guard", lambda: True)

    class _FailOnceTransformer:
        def __init__(self):
            self.calls = []

        def set_attention_backend(self, name):
            self.calls.append(name)
            if name != "native":
                raise RuntimeError(f"{name} kernel unavailable")

    t = _FailOnceTransformer()
    assert apply_attention_backend(_pipe(t), "sage") is None
    assert t.calls == ["sage", "native"]


def test_apply_handles_missing_method():
    pipe = types.SimpleNamespace(transformer = types.SimpleNamespace())
    assert apply_attention_backend(pipe, "_native_cudnn") is None


def test_apply_resets_global_registry_after_success(monkeypatch):
    called = {"reset": False}
    monkeypatch.setattr(
        att, "_reset_global_backend_to_native", lambda logger: called.__setitem__("reset", True)
    )
    t = _FakeTransformer()
    engaged = apply_attention_backend(_pipe(t), "_native_cudnn")
    assert engaged == "_native_cudnn" and t.set_to == "_native_cudnn"
    assert called["reset"] is True


def test_active_attention_backend_reads_tuple_return():
    # get_active_backend() returns (AttentionBackendName, fn); read the name's .value.
    pytest.importorskip("diffusers")
    from diffusers.models.attention_dispatch import (
        AttentionBackendName,
        _AttentionBackendRegistry,
    )

    _AttentionBackendRegistry.set_active_backend(AttentionBackendName.NATIVE)
    assert att._active_attention_backend() == "native"


@pytest.fixture(autouse = True)
def _no_real_installs(monkeypatch):
    # Never shell out to pip in unit tests; install tests re-enable with a stubbed subprocess.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "0")
    att._INSTALL_ATTEMPTED.clear()
    # The resolved xFormers wheel is cached too; left set, one test's stub decides the next.
    monkeypatch.setattr(att, "_XFORMERS_WHEEL_TARGET", None)


class _Recorder:
    def __init__(self):
        self.calls = []

    def __call__(self, cmd, **kwargs):
        self.calls.append(list(cmd))
        return types.SimpleNamespace(returncode = 0)


def _pip_calls(run):
    # A kernels install is followed by a `python -c "import transformers.activations"` check.
    return [c for c in run.calls if "pip" in c]


def _stub_subprocess(monkeypatch, run):
    import subprocess
    monkeypatch.setattr(subprocess, "run", run)


def test_install_skipped_when_gate_disabled(monkeypatch):
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("sage")
    assert run.calls == []


def test_install_skipped_when_module_present(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(
        importlib.util, "find_spec", lambda name: object() if name == "sageattention" else None
    )
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: True)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("sage")
    assert run.calls == []


def test_install_runs_wheel_only_for_missing_kernel(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("sage")
    assert len(_pip_calls(run)) == 1
    cmd = run.calls[0]
    assert "--only-binary" in cmd and ":all:" in cmd


def test_sage_install_never_asks_pypi_for_sageattention(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("sage")
    assert run.calls and not any("sageattention" in part for cmd in run.calls for part in cmd)
    assert run.calls[0][-1] in ("kernels==0.12.3", "kernels>=0.12.3")


_XFORMERS_WHEEL = "https://download.pytorch.org/whl/cu130/xformers-0.0.34-cp39-abi3-win_amd64.whl"


def _stub_xformers_wheel(
    monkeypatch,
    url = _XFORMERS_WHEEL,
    reason = None,
):
    """Pin the resolved xFormers wheel so no test probes the real torch."""
    monkeypatch.setattr(att, "_xformers_wheel_target", lambda: (url, reason))


def test_install_uses_no_deps_to_protect_core_deps(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("xformers")
    assert len(run.calls) == 1
    assert "--no-deps" in run.calls[0]


def test_xformers_installs_the_cuda_matched_wheel_not_the_package_name(monkeypatch):
    """Install xformers from a URL matched to the running torch; the PyPI wheel is CUDA 12.8 only."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)

    assert att._ensure_attention_backend_installed("xformers") is None
    assert len(run.calls) == 1
    assert _XFORMERS_WHEEL in run.calls[0]
    assert "xformers" not in [arg for arg in run.calls[0] if arg != _XFORMERS_WHEEL]


def test_a_hidden_xformers_is_not_reinstalled_in_the_same_process(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    monkeypatch.setitem(sys.modules, "xformers", None)

    def _no_resolve():
        raise AssertionError("resolved a wheel for a hidden xformers")

    monkeypatch.setattr(att, "_xformers_wheel_target", _no_resolve)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    logger = _CapturingLogger()

    reason = att._ensure_attention_backend_installed("xformers", logger)

    assert reason and "requires a different torch" in reason
    assert run.calls == []
    assert any("restart Unsloth" in line for line in logger.lines)


def test_the_hidden_xformers_refusal_records_no_attempt(monkeypatch):
    """Policy, not a failed attempt: once the entry is gone the same process may still install."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    monkeypatch.setitem(sys.modules, "xformers", None)
    att._ensure_attention_backend_installed("xformers")
    monkeypatch.delitem(sys.modules, "xformers")

    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("xformers")
    assert len(run.calls) == 1


_CREDENTIALED_WHEEL = (
    "https://svc:[email protected]/whl/cu130/xformers-0.0.34-cp39-abi3-win_amd64.whl"
)
_REDACTED_WHEEL = "https://mirror.internal/whl/cu130/xformers-0.0.34-cp39-abi3-win_amd64.whl"


class _CapturingLogger:
    def __init__(self):
        self.lines: list[str] = []

    def info(self, msg, *args):
        self.lines.append(msg % args if args else msg)

    def warning(self, msg, *args):
        self.lines.append(msg % args if args else msg)


def test_a_private_mirrors_credentials_never_reach_the_log(monkeypatch):
    """UNSLOTH_PYTORCH_MIRROR can embed credentials in the wheel URL; pip gets the real URL, but the
    log and pip's echoed stderr are redacted."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util
    import subprocess as sp

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch, url = _CREDENTIALED_WHEEL)

    def _boom(cmd, **kwargs):
        raise sp.CalledProcessError(
            returncode = 1,
            cmd = cmd,
            stderr = f"ERROR: Could not install {_CREDENTIALED_WHEEL} (404)".encode(),
        )

    _stub_subprocess(monkeypatch, _boom)
    logger = _CapturingLogger()

    att._ensure_attention_backend_installed("xformers", logger)

    assert logger.lines
    for line in logger.lines:
        assert "s3cr3t" not in line
        assert _REDACTED_WHEEL in line


def test_a_query_string_token_is_stripped_too():
    redacted = att._redacted_for_log(
        "ERROR: HTTP 403 for https://mirror.internal/whl/cu130/x.whl?token=abc123 -- retry"
    )
    assert "abc123" not in redacted
    assert "https://mirror.internal/whl/cu130/x.whl" in redacted


def test_xformers_install_refused_when_no_matching_wheel_exists(monkeypatch):
    """No matched wheel means no install; an unpinned resolve is the bug, so SDPA is kept."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(
        monkeypatch, url = None, reason = "no xFormers wheel is published for torch 2.11.0"
    )
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)

    reason = att._ensure_attention_backend_installed("xformers")
    assert reason == "no xFormers wheel is published for torch 2.11.0"
    assert run.calls == []


def test_xformers_refusal_is_logged_with_its_reason(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch, url = None, reason = "torch could not be probed")
    _stub_subprocess(monkeypatch, _Recorder())

    warnings = []

    class _Logger:
        def info(self, *args, **kwargs):
            pass

        def warning(self, msg, *args, **kwargs):
            warnings.append(msg % args if args else msg)

    att._ensure_attention_backend_installed("xformers", _Logger())
    assert len(warnings) == 1
    assert "torch could not be probed" in warnings[0]
    assert "not installing" in warnings[0]


def test_xformers_refusal_records_no_attempt(monkeypatch):
    """Refusal is a POLICY decision, like the kernels/hub gate, so it must not burn the
    one-shot install slot: once the resolver can answer, the install still happens."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_xformers_wheel(monkeypatch, url = None, reason = "nope")
    _stub_subprocess(monkeypatch, _Recorder())

    att._ensure_attention_backend_installed("xformers")
    assert att._INSTALL_ATTEMPTED == set()

    _stub_xformers_wheel(monkeypatch)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("xformers")
    assert len(run.calls) == 1
    assert _XFORMERS_WHEEL in run.calls[0]


def test_xformers_resolution_skipped_when_already_installed(monkeypatch):
    """find_spec runs first, so a working xformers never pays for the torch probe."""
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
    resolved = []
    monkeypatch.setattr(att, "_xformers_wheel_target", lambda: resolved.append(1) or (None, "x"))
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)

    assert att._ensure_attention_backend_installed("xformers") is None
    assert resolved == []
    assert run.calls == []


def test_matched_wheel_path_does_not_touch_other_backends(monkeypatch):
    """Only xFormers has a silent ABI failure; sage, flash and kernels still install by name."""
    assert att._MATCHED_WHEEL_BACKENDS == frozenset({"xformers"})
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(
        att, "_xformers_wheel_target", lambda: pytest.fail("resolver must not run for sage")
    )
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
    att._ensure_attention_backend_installed("sage")
    assert len(_pip_calls(run)) == 1
    assert run.calls[0][-1] in ("kernels==0.12.3", "kernels>=0.12.3")


def test_failed_install_not_retried_in_same_process(monkeypatch):
    # A failed pre-install must not re-run pip under _generate_lock (600s would block unload).
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util
    import subprocess as sp

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)

    calls: list[list[str]] = []

    def _boom(cmd, **kwargs):
        calls.append(list(cmd))
        raise sp.CalledProcessError(returncode = 1, cmd = cmd)

    _stub_subprocess(monkeypatch, _boom)
    att._ensure_attention_backend_installed("flash")
    att._ensure_attention_backend_installed("flash")
    assert len(calls) == 1


def test_install_invalidates_import_caches_on_success(monkeypatch):
    # A wheel written after the finder cached site-packages can be missed: invalidate caches.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    _stub_subprocess(monkeypatch, _Recorder())
    invalidated = []
    monkeypatch.setattr(importlib, "invalidate_caches", lambda: invalidated.append(True))
    att._ensure_attention_backend_installed("flash")
    assert invalidated == [True]


def test_install_failure_skips_cache_invalidation(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib
    import importlib.util
    import subprocess as sp

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)

    def _boom(cmd, **kwargs):
        raise sp.CalledProcessError(returncode = 1, cmd = cmd)

    _stub_subprocess(monkeypatch, _boom)
    invalidated = []
    monkeypatch.setattr(importlib, "invalidate_caches", lambda: invalidated.append(True))
    att._ensure_attention_backend_installed("sage")
    assert invalidated == []


def test_install_never_attempted_for_builtin_backends(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("_native_cudnn")
    att._ensure_attention_backend_installed("native")
    assert run.calls == []


def test_install_failure_logs_pip_stderr(monkeypatch):
    # CalledProcessError's str() hides the pip reason; surface the captured stderr.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util
    import subprocess as sp

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)

    def _boom(cmd, **kwargs):
        raise sp.CalledProcessError(
            returncode = 1, cmd = cmd, stderr = b"ERROR: No matching distribution found"
        )

    _stub_subprocess(monkeypatch, _boom)

    warnings: list[str] = []

    class _Logger:
        def info(self, *a, **k):
            pass

        def warning(self, msg, *args):
            warnings.append(msg % args if args else msg)

    att._ensure_attention_backend_installed("flash", _Logger())
    assert warnings and "No matching distribution found" in warnings[-1]


def test_install_failure_falls_back_to_native(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util
    import subprocess as sp

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)

    def _boom(cmd, **kwargs):
        raise sp.CalledProcessError(returncode = 1, cmd = cmd)

    _stub_subprocess(monkeypatch, _boom)
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
    t = _FakeTransformer(fail = True)
    assert apply_attention_backend(_pipe(t), "sage") is None


def test_kernels_install_skipped_on_old_hub(monkeypatch):
    # kernels needs huggingface_hub >= 1.10; older hubs make `import kernels` raise at module
    # scope, and diffusers imports kernels whenever installed, breaking every pipeline import.
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: False)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("flash_4_hub")
    assert run.calls == []
    # A policy refusal is not memoised, so a fixed environment can still install later.
    assert "kernels" not in att._INSTALL_ATTEMPTED


def test_kernels_install_allowed_on_supported_hub(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: True)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    att._ensure_attention_backend_installed("flash_4_hub")
    pip = _pip_calls(run)
    assert len(pip) == 1 and pip[0][-1] in ("kernels==0.12.3", "kernels>=0.12.3")


def test_kernels_gate_also_covers_sage(monkeypatch):
    monkeypatch.setenv("UNSLOTH_DIFFUSION_ATTENTION_INSTALL", "auto")
    import importlib.util

    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
    monkeypatch.setattr(att, "_kernels_hub_compatible", lambda: False)
    monkeypatch.setattr(att, "_pip_sage2_installed", lambda: False)
    run = _Recorder()
    _stub_subprocess(monkeypatch, run)
    assert att._ensure_attention_backend_installed("sage") is not None
    assert run.calls == []
    att._ensure_attention_backend_installed("flash")
    assert len(run.calls) == 1 and any("flash-attn" in part for part in run.calls[0])


def test_kernels_hub_compatible_reads_hub_version(monkeypatch):
    import importlib.metadata

    # Gate is (major, minor) >= 1.10: hub 1.0-1.2 fail `import kernels`, 1.3-1.9 are below the floor.
    for bad in ("0.36.2", "1.0.0", "1.2.4", "1.3.5", "1.9.2", "1.9"):
        monkeypatch.setattr(importlib.metadata, "version", lambda name, v = bad: v)
        assert att._kernels_hub_compatible() is False, bad
    for good in ("1.10.0", "1.10.0rc0", "1.23.0", "2.0.0"):
        monkeypatch.setattr(importlib.metadata, "version", lambda name, v = good: v)
        assert att._kernels_hub_compatible() is True, good

    def _boom(name):
        raise importlib.metadata.PackageNotFoundError(name)

    monkeypatch.setattr(importlib.metadata, "version", _boom)
    assert att._kernels_hub_compatible() is True


def test_transient_resolution_failure_is_not_memoised(monkeypatch):
    """A probe that times out on a loaded box is transient. Caching it would turn one
    hiccup into "no xFormers for the rest of this Unsloth session", so only DETERMINISTIC
    answers (a URL, or a refusal that depends purely on the resident torch) are cached."""
    import utils.wheel_utils as wu

    calls = []

    def _probe(**kwargs):
        calls.append(kwargs)
        return (
            None
            if len(calls) == 1
            else {
                "platform_tag": "win_amd64",
                "python_tag": "cp313",
                "torch_version": "2.10.0+cu130",
                "cuda_version": "13.0",
            }
        )

    monkeypatch.setattr(wu, "probe_torch_wheel_env", _probe)

    url, reason = att._xformers_wheel_target()
    assert url is None and "could not be probed" in reason
    assert att._XFORMERS_WHEEL_TARGET is None, "a transient failure must not be cached"

    url, reason = att._xformers_wheel_target()
    assert reason is None and url == _XFORMERS_WHEEL
    assert att._XFORMERS_WHEEL_TARGET == (_XFORMERS_WHEEL, None)
    assert len(calls) == 2


def test_deterministic_refusal_is_memoised(monkeypatch):
    """torch cannot change under a running interpreter, so "no wheel for this torch" is
    settled; re-probing it on every request would re-pay the subprocess under the lock."""
    import utils.wheel_utils as wu

    calls = []

    def _probe(**kwargs):
        calls.append(kwargs)
        return {
            "platform_tag": "win_amd64",
            "python_tag": "cp313",
            "torch_version": "2.11.0+cu124",
            "cuda_version": "12.4",
        }

    monkeypatch.setattr(wu, "probe_torch_wheel_env", _probe)

    for _ in range(3):
        url, reason = att._xformers_wheel_target()
        assert url is None
        assert "no xFormers wheel is published for torch 2.11.0+cu124" in reason
    assert len(calls) == 1


def test_resolution_does_no_network_io(monkeypatch):
    """It can run under _generate_lock (the video loader has no out-of-lock pre-install),
    so it must not add a HEAD to a path that already blocks unload/cancel."""
    import utils.wheel_utils as wu

    monkeypatch.setattr(
        wu,
        "probe_torch_wheel_env",
        lambda **kw: {
            "platform_tag": "win_amd64",
            "python_tag": "cp313",
            "torch_version": "2.10.0+cu130",
            "cuda_version": "13.0",
        },
    )
    monkeypatch.setattr(
        wu, "url_exists", lambda url: pytest.fail("resolution must not hit the network")
    )
    assert att._xformers_wheel_target() == (_XFORMERS_WHEEL, None)


def test_probe_timeout_matches_the_other_wheel_callers(monkeypatch):
    import utils.wheel_utils as wu

    seen = {}

    def _probe(**kwargs):
        seen.update(kwargs)
        return None

    monkeypatch.setattr(wu, "probe_torch_wheel_env", _probe)
    att._xformers_wheel_target()
    assert seen == {"timeout": 30, "include_windows": True}


@pytest.fixture(autouse = True)
def _clear_sdpa_probe_cache():
    """The probe memoises per (device, dtype) for the process; tests must not inherit it."""
    att._SDPA_PROBE_CACHE.clear()
    yield
    att._SDPA_PROBE_CACHE.clear()


def _stub_probe(
    monkeypatch,
    kernels,
    *,
    record = None,
):
    def _probe(device, dtype):
        if record is not None:
            record.append((device, dtype))
        return tuple(kernels)

    monkeypatch.setattr(att, "_probe_sdpa_kernels", _probe)
    # Importing unsloth on SM100 turns cuDNN SDPA off process-wide; these tests pin the probe alone.
    monkeypatch.setattr(att, "_enabled_sdpa_kernels", lambda found: found)


def test_math_only_is_read_off_a_probe_not_the_flags(monkeypatch):
    # Some ROCm builds (gfx1200) report flash/mem-efficient enabled but every dispatch raises,
    # so dispatch degrades to math (N x N scores). Only a probe sees that.
    _stub_probe(monkeypatch, ("math",))
    assert att.sdpa_math_only(_target()) is True
    assert att.available_sdpa_kernels(_target()) == ("math",)


@pytest.mark.parametrize(
    "kernels",
    [
        ("flash", "mem_efficient", "cudnn", "math"),
        ("flash", "math"),
        ("mem_efficient", "math"),
        ("cudnn", "math"),
    ],
)
def test_any_subquadratic_kernel_means_not_math_only(kernels, monkeypatch):
    _stub_probe(monkeypatch, kernels)
    assert att.sdpa_math_only(_target()) is False


def test_a_fused_launch_that_fails_late_is_not_reported_available(monkeypatch):
    # Windows ROCm gfx1151: hipErrorInvalidValue surfaces on the next checked kernel; probe takes it.
    torch = pytest.importorskip("torch")

    class _Pending:
        def float(self):
            raise RuntimeError("CUDA error: invalid argument")

    real = torch.nn.functional.scaled_dot_product_attention

    def _sdpa(q, k, v, *a, **kw):
        if not torch.backends.cuda.math_sdp_enabled():
            return _Pending()
        return real(q, k, v, *a, **kw)

    monkeypatch.setattr(torch.nn.functional, "scaled_dot_product_attention", _sdpa)
    assert att._probe_sdpa_kernels("cpu", torch.float32) == ("math",)


@pytest.mark.parametrize(
    "version, env, fused",
    [
        ("2.10.0", None, False),
        ("2.12.1", None, False),
        ("2.13.0", None, True),
        ("2.14.1", "0", True),
        ("2.14.1", "", False),
        ("2.14.1", "false", False),
        ("2.14.1", "1", False),
    ],
)
def test_mps_answers_from_the_torch_build_not_an_execution_probe(version, env, fused, monkeypatch):
    torch = pytest.importorskip("torch")
    monkeypatch.setattr(torch, "__version__", version)
    if env is None:
        monkeypatch.delenv(att.MPS_PREFILL_ATTENTION_OFF_ENV, raising = False)
    else:
        monkeypatch.setenv(att.MPS_PREFILL_ATTENTION_OFF_ENV, env)
    monkeypatch.setattr(
        torch.nn.functional,
        "scaled_dot_product_attention",
        lambda *a, **k: pytest.fail("MPS must not be execution-probed"),
    )
    monkeypatch.setattr(torch.backends.cuda, "flash_sdp_enabled", lambda: False)
    target = _target("mps")
    assert att.sdpa_subquadratic_confirmed(target) is fused
    assert att.sdpa_math_only(target) is not fused


def _mps_tensor(
    shape,
    dtype,
    requires_grad = False,
):
    return types.SimpleNamespace(
        device = types.SimpleNamespace(type = "mps"),
        shape = shape,
        dtype = dtype,
        requires_grad = requires_grad,
    )


@pytest.mark.parametrize(
    "change, prefill",
    [
        ({}, True),
        ({"q_len": 9}, True),
        ({"q_len": 8}, False),
        ({"head_dim": 72}, True),
        ({"head_dim": 48}, False),
        ({"head_dim": 160}, False),
        ({"v_dim": 64}, False),
        ({"dtype": "float32"}, True),
        ({"dtype": "float64"}, False),
        ({"mask": "bool"}, True),
        ({"mask": "bfloat16"}, True),
        ({"mask": "float32"}, False),
        ({"grad": True}, False),
        ({"device": "cpu"}, False),
        ({"version": "2.12.1"}, False),
    ],
)
def test_mps_prefill_attention_follows_the_torch_dispatch(change, prefill, monkeypatch):
    # The rule torch 2.13-2.15 applies in _scaled_dot_product_attention_math_mps: anything else builds the scores.
    torch = pytest.importorskip("torch")
    monkeypatch.setattr(torch, "__version__", change.get("version", "2.14.1"))
    monkeypatch.delenv(att.MPS_PREFILL_ATTENTION_OFF_ENV, raising = False)
    dtype = getattr(torch, change.get("dtype", "bfloat16"))
    head_dim = change.get("head_dim", 128)
    q = _mps_tensor((1, 24, change.get("q_len", 4096), head_dim), dtype, change.get("grad", False))
    k = _mps_tensor((1, 24, 4096, head_dim), dtype)
    v = _mps_tensor((1, 24, 4096, change.get("v_dim", head_dim)), dtype)
    if "device" in change:
        q.device = types.SimpleNamespace(type = change["device"])
    mask = (
        _mps_tensor((1, 1, 1, 4096), getattr(torch, change["mask"])) if "mask" in change else None
    )
    with torch.enable_grad():
        assert att.mps_prefill_attention(q, k, v, mask) is prefill
    q.shape = (q.shape[0], q.shape[2], q.shape[1], q.shape[3])
    k.shape = (k.shape[0], k.shape[2], k.shape[1], k.shape[3])
    with torch.enable_grad():
        assert att.mps_prefill_attention(q, k, v, mask, seq_dim = 1) is prefill


@pytest.mark.parametrize(
    "device, version, head_dims, math_only",
    [
        ("mps", "2.14.1", None, False),
        ("mps", "2.14.1", {128}, False),
        ("mps", "2.14.1", {64, 128}, False),
        ("mps", "2.14.1", {128, 160}, True),
        ("mps", "2.12.1", {128}, True),
        ("cuda", "2.14.1", {160}, False),
    ],
)
def test_family_head_dims_narrow_the_mps_answer(device, version, head_dims, math_only, monkeypatch):
    # A family whose head dim has no prefill instance builds the scores on every call, whatever the torch build.
    torch = pytest.importorskip("torch")
    monkeypatch.setattr(torch, "__version__", version)
    monkeypatch.delenv(att.MPS_PREFILL_ATTENTION_OFF_ENV, raising = False)
    if device == "cuda":
        _stub_probe(monkeypatch, ("flash", "math"))
    target = _target(device)
    assert att.sdpa_math_only(target, head_dims) is math_only
    assert att.sdpa_subquadratic_confirmed(target, head_dims) is not math_only
    records = []
    logger = types.SimpleNamespace(warning = lambda *a: records.append(a))
    config = {"attention_head_dim": sorted(head_dims or ())}
    pipe = types.SimpleNamespace(transformer = types.SimpleNamespace(config = config))
    att._configure_native_attention(pipe, target, logger)
    assert any("math_only" in record[0] for record in records) is math_only
    from core.inference.diffusion import _quadratic_attention

    assert _quadratic_attention(target, None, pipe) is math_only


def test_an_unanswerable_probe_is_not_a_math_only_verdict(monkeypatch):
    _stub_probe(monkeypatch, ())
    assert att.sdpa_math_only(_target()) is False
    assert att.warn_if_sdpa_math_only(_target(), None) is False


def test_a_probe_that_raises_is_swallowed(monkeypatch):
    def _boom(device, dtype):
        raise RuntimeError("probe exploded")

    monkeypatch.setattr(att, "_probe_sdpa_kernels", _boom)
    assert att.available_sdpa_kernels(_target()) == ()
    assert att.sdpa_math_only(_target()) is False


def test_a_target_with_no_device_is_never_probed(monkeypatch):
    seen: list = []
    _stub_probe(monkeypatch, ("math",), record = seen)
    assert att.available_sdpa_kernels(types.SimpleNamespace(device = "", dtype = None)) == ()
    assert att.available_sdpa_kernels(types.SimpleNamespace(device = None, dtype = None)) == ()
    assert seen == []


def test_the_probe_runs_once_per_device_and_dtype(monkeypatch):
    # A kernel cannot appear or vanish under a running interpreter, and this sits on the load
    # path, so the probe is memoised. each indexed GPU has its own capability result.
    import torch

    monkeypatch.setattr(torch.cuda, "current_device", lambda: 0)
    seen: list = []
    _stub_probe(monkeypatch, ("math",), record = seen)
    for device in ("cuda", "cuda:0", "cuda:1"):
        assert att.sdpa_math_only(types.SimpleNamespace(device = device, dtype = "fp16")) is True
    assert len(seen) == 2
    # A different dtype is a different question: fused kernels are half-precision only.
    att.sdpa_math_only(types.SimpleNamespace(device = "cuda", dtype = "fp32"))
    assert len(seen) == 3


def test_a_dtypeless_target_probes_in_half_precision(monkeypatch):
    # fp32 has no fused kernel anywhere, so probing at fp32 would always report math only.
    import torch

    seen: list = []
    _stub_probe(monkeypatch, ("flash", "math"), record = seen)
    att.available_sdpa_kernels(types.SimpleNamespace(device = "cuda", dtype = None))
    assert seen == [(att._indexed_cuda_device("cuda"), torch.float16)]


def test_warn_names_the_quadratic_cost(monkeypatch):
    _stub_probe(monkeypatch, ("math",))
    logged: list = []
    logger = types.SimpleNamespace(warning = lambda fmt, *a: logged.append(fmt % a))

    assert att.warn_if_sdpa_math_only(_target(), logger) is True
    assert len(logged) == 1
    assert "math_only" in logged[0]
    assert "score matrix" in logged[0] and "SQUARE" in logged[0]


def test_warn_is_silent_on_a_healthy_device(monkeypatch):
    _stub_probe(monkeypatch, ("flash", "math"))
    logged: list = []
    logger = types.SimpleNamespace(warning = lambda fmt, *a: logged.append(fmt % a))
    assert att.warn_if_sdpa_math_only(_target(), logger) is False
    assert logged == []


def test_apply_native_reports_a_math_only_device(monkeypatch):
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
    _stub_probe(monkeypatch, ("math",))
    logged: list = []
    logger = types.SimpleNamespace(
        warning = lambda fmt, *a: logged.append(fmt % a),
        info = lambda *a, **k: None,
    )

    assert (
        apply_attention_backend(_pipe(_FakeTransformer()), None, logger = logger, target = _target())
        is None
    )
    assert len(logged) == 1 and "math_only" in logged[0]


def test_apply_reports_a_math_only_device_for_a_unet_pipeline(monkeypatch):
    # SDXL's pipe.unet has no dispatcher setter but runs the same SDPA, so still diagnose it.
    _stub_probe(monkeypatch, ("math",))
    logged: list = []
    logger = types.SimpleNamespace(
        warning = lambda fmt, *a: logged.append(fmt % a),
        info = lambda *a, **k: None,
    )
    unet_pipe = types.SimpleNamespace(unet = object())

    assert apply_attention_backend(unet_pipe, None, logger = logger, target = _target()) is None
    assert len(logged) == 1 and "math_only" in logged[0]


def test_apply_without_a_target_probes_nothing(monkeypatch):
    monkeypatch.setattr(att, "_active_attention_backend", lambda: "native")
    seen: list = []
    _stub_probe(monkeypatch, ("math",), record = seen)
    assert apply_attention_backend(_pipe(_FakeTransformer()), None) is None
    assert seen == []


def test_apply_does_not_warn_when_a_real_backend_engaged(monkeypatch):
    seen: list = []
    _stub_probe(monkeypatch, ("math",), record = seen)
    logged: list = []
    logger = types.SimpleNamespace(
        warning = lambda fmt, *a: logged.append(fmt % a),
        info = lambda *a, **k: None,
    )
    t = _FakeTransformer()
    assert (
        apply_attention_backend(_pipe(t), "_native_cudnn", logger = logger, target = _target())
        == "_native_cudnn"
    )
    assert seen == [] and logged == []


def test_an_unanswerable_probe_is_not_memoised(monkeypatch):
    """A probe that could not run says nothing about hardware; caching it would disable the warning
    for the whole process, even after memory frees."""
    calls: list = []

    def _flaky(device, dtype):
        calls.append(dtype)
        if len(calls) == 1:
            raise RuntimeError("CUDA out of memory while allocating the probe tensor")
        return ("flash", "math")

    monkeypatch.setattr(att, "_probe_sdpa_kernels", _flaky)

    assert att.available_sdpa_kernels(_target()) == ()
    assert att.sdpa_math_only(_target()) is False
    assert att.available_sdpa_kernels(_target()) == ("flash", "math")
    assert att.available_sdpa_kernels(_target()) == ("flash", "math")
    assert len(calls) == 2, "the answer must be memoised; the failure must not be"