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.

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

"""Opt-in planning for device_map unsloth; most checks pin the placements existing callers keep."""

import ast
import os
import sys
import types

import pytest

HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
MODELS = os.path.join(HERE, "unsloth", "models")
LOADER_UTILS = os.path.join(MODELS, "loader_utils.py")
_SRC = open(LOADER_UTILS, encoding = "utf-8").read()
_SKIP_MODULES = ["lm_head", "vision_tower", "audio_tower"]


# _load stubs these; a later real import in the same xdist worker would get the stub.
_STUBBED_ZOO_MODULES = ("unsloth_zoo.peft_utils", "unsloth_zoo.device_map_planner")


@pytest.fixture(autouse = True)
def _restore_stubbed_zoo_modules():
    saved = {name: sys.modules.get(name) for name in _STUBBED_ZOO_MODULES}
    yield
    for name, module in saved.items():
        if module is None:
            sys.modules.pop(name, None)
        else:
            sys.modules[name] = module


class _FakeCuda:
    def __init__(
        self,
        count,
        free = None,
    ):
        self._count = count
        self._free = free or {}

    def device_count(self):
        return self._count

    def mem_get_info(self, index):
        # (free, total). The planner must read the first, not the second.
        return (self._free.get(index, 8 * 2**30), 16 * 2**30)


def _load(
    *,
    devices = 2,
    device_type = "cuda",
    free = None,
    planner = None,
    distributed = False,
):
    """Rebuild the two functions over a fabricated CUDA and unsloth_zoo."""
    ns = {
        "os": os,
        "torch": types.SimpleNamespace(cuda = _FakeCuda(devices, free)),
        "DEVICE_TYPE_TORCH": device_type,
        "is_distributed": lambda: distributed,
    }
    for node in ast.parse(_SRC).body:
        if isinstance(node, ast.FunctionDef) and node.name in (
            "requested_device_map",
            "resolve_unsloth_device_map",
            "planner_quantization_kwargs",
            "planner_class_mismatch_reason",
            "_as_bytes",
        ):
            exec(ast.get_source_segment(_SRC, node), ns)
        elif isinstance(node, ast.ClassDef) and node.name == "_DefaultDeviceMap":
            exec(ast.get_source_segment(_SRC, node), ns)
        elif isinstance(node, ast.Assign) and getattr(node.targets[0], "id", None) in (
            "UNSLOTH_DEVICE_MAP",
            "UNSLOTH_BALANCED_DEVICE_MAP",
            "_PLANNED_DEVICE_MAPS",
            "DEFAULT_DEVICE_MAP",
            "_SIZE_UNITS",
        ):
            exec(ast.get_source_segment(_SRC, node), ns)

    # Stub so the test never imports the real unsloth_zoo or tracks its skip list contents.
    peft_utils = types.ModuleType("unsloth_zoo.peft_utils")
    peft_utils.SKIP_QUANTIZATION_MODULES = list(_SKIP_MODULES)
    sys.modules["unsloth_zoo.peft_utils"] = peft_utils

    if planner is not None:
        module = types.ModuleType("unsloth_zoo.device_map_planner")
        module.plan_device_map_for_pretrained = planner
        sys.modules["unsloth_zoo.device_map_planner"] = module
    return ns


class _Plan:
    def __init__(self, device_map):
        self.device_map = device_map

    def describe(self):
        return "  (fabricated plan)"


@pytest.mark.parametrize(
    "device_map",
    [
        "sequential",  # today's default
        "auto",  # accelerate's, which this must never reinterpret
        "balanced",  # what Unsloth Studio passes
        "balanced_low_0",
        None,
    ],
)
def test_every_existing_device_map_is_returned_untouched(device_map):
    """The whole opt-in claim in one test. If any of these changed, every multi-GPU user
    who never asked for planning would silently get a different placement."""
    ns = _load(planner = lambda *a, **k: pytest.fail("the planner must not run"))
    assert ns["resolve_unsloth_device_map"](device_map, "some/model") is device_map


def test_an_explicit_dict_is_returned_untouched():
    explicit = {"": 0, "model.vision_tower": 1}
    ns = _load(planner = lambda *a, **k: pytest.fail("the planner must not run"))
    assert ns["resolve_unsloth_device_map"](explicit, "some/model") is explicit


@pytest.mark.parametrize("switch", [None, "1"])
def test_only_the_default_is_ever_upgraded(monkeypatch, switch):
    """Only the untouched default is upgraded; a typed sequential equals the default, hence the marker."""
    ns = _load()
    if switch is None:
        monkeypatch.delenv("UNSLOTH_AUTO_DEVICE_MAP", raising = False)
    else:
        monkeypatch.setenv("UNSLOTH_AUTO_DEVICE_MAP", switch)
    assert ns["requested_device_map"](ns["DEFAULT_DEVICE_MAP"]) == "unsloth"
    assert ns["requested_device_map"]("sequential") == "sequential"
    assert ns["requested_device_map"]("auto") == "auto"
    assert ns["requested_device_map"]("balanced") == "balanced"
    assert ns["requested_device_map"]({"": 0}) == {"": 0}


def test_the_env_var_can_turn_planning_back_off(monkeypatch):
    """The multi-GPU operator who wants accelerate's greedy fill back needs a switch that
    does not require editing call sites, so `0` has to reach the default itself."""
    ns = _load()
    monkeypatch.setenv("UNSLOTH_AUTO_DEVICE_MAP", "0")
    assert ns["requested_device_map"](ns["DEFAULT_DEVICE_MAP"]) == "sequential"
    assert ns["requested_device_map"](ns["DEFAULT_DEVICE_MAP"]) == ns["DEFAULT_DEVICE_MAP"]


def test_an_unset_switch_plans_so_a_bare_from_pretrained_needs_no_device_map(monkeypatch):
    """The reason the default flipped: a notebook should not have to pass
    `device_map = "unsloth"` to get the placement that fits."""
    monkeypatch.delenv("UNSLOTH_AUTO_DEVICE_MAP", raising = False)
    planned = {"model.embed_tokens": 0, "lm_head": 1}
    calls = []
    ns = _load(
        devices = 2,
        free = {0: 16 * 2**30, 1: 16 * 2**30},
        planner = lambda name, **kw: calls.append(name) or _Plan(planned),
    )
    resolved = ns["resolve_unsloth_device_map"](
        ns["requested_device_map"](ns["DEFAULT_DEVICE_MAP"]),
        "unsloth/Muse-Glimmer-30B-unsloth-bnb-4bit",
    )
    assert resolved == planned
    assert calls == ["unsloth/Muse-Glimmer-30B-unsloth-bnb-4bit"]


@pytest.mark.parametrize(
    "kwargs,why",
    [
        ({"fast_inference": True}, "vLLM places its own weights"),
        ({"full_finetuning": True}, "no bnb layout to plan"),
    ],
)
def test_planning_is_declined_where_something_else_owns_placement(kwargs, why):
    ns = _load(planner = lambda *a, **k: pytest.fail(f"must not plan: {why}"))
    assert ns["resolve_unsloth_device_map"]("unsloth", "m", **kwargs) == "sequential"


def test_a_caller_that_vetoes_planning_is_obeyed():
    """Only the leaf knows when the config it is about to load is not the one the planner
    would rebuild from the repo, so it needs a way to say so."""
    ns = _load(planner = lambda *a, **k: pytest.fail("planned despite the veto"))
    assert ns["resolve_unsloth_device_map"]("unsloth", "m", skip_reason = "text_only") == "sequential"
    # A veto is not a licence to reinterpret a placement the caller chose.
    assert ns["resolve_unsloth_device_map"]("auto", "m", skip_reason = "text_only") == "auto"


def test_a_text_only_decoder_is_never_planned_against_the_full_vlm():
    """A text_only decoder must not be planned against the full VLM; no decoder weight matches its map."""
    models = os.path.join(HERE, "unsloth", "models")

    vision = open(os.path.join(models, "vision.py"), encoding = "utf-8").read()
    tree = ast.parse(vision)
    signature = [
        node
        for node in ast.walk(tree)
        if isinstance(node, ast.FunctionDef)
        and node.name == "from_pretrained"
        and any(a.arg == "text_only" for a in node.args.args + node.args.kwonlyargs)
    ]
    assert signature, "vision.py no longer takes text_only"
    for node in signature:
        args = {a.arg for a in node.args.args + node.args.kwonlyargs}
        assert "text_only_decoder" in args, f"vision.py:{node.lineno}"
    assert "text_only_decoder = True" in vision

    assignments = {}
    for node in ast.walk(tree):
        if not isinstance(node, ast.Assign):
            continue
        for target in node.targets:
            if isinstance(target, ast.Name):
                assignments[target.id] = assignments.get(target.id, "") + ast.unparse(node.value)
    for call in _resolve_calls(vision):
        passed = {kw.arg: ast.unparse(kw.value) for kw in call.keywords}
        assert "planner_config" in passed, f"vision.py:{call.lineno} plans the full VLM"
        planned = passed["planner_config"] + assignments.get(passed["planner_config"], "")
        assert "text_only_decoder" in planned, f"vision.py:{call.lineno}"
        assert "skip_reason" in passed, f"vision.py:{call.lineno}"
        source = passed["skip_reason"] + assignments.get(passed["skip_reason"], "")
        assert "planner_class_mismatch_reason" in source, f"vision.py:{call.lineno}"

    loader = open(os.path.join(models, "loader.py"), encoding = "utf-8").read()
    assert "text_only_decoder = True" in loader
    forwarded = [
        node
        for node in ast.walk(ast.parse(loader))
        if isinstance(node, ast.Call) and any(kw.arg == "text_only_decoder" for kw in node.keywords)
    ]
    assert forwarded, "loader.py swaps the config but never tells the leaf"


def test_a_task_head_the_planner_cannot_see_declines_planning():
    """A task head the planner cannot see, like score from num_labels, must decline planning."""
    ns = _load()
    mismatch = ns["planner_class_mismatch_reason"]

    class LlamaForCausalLM:
        pass

    class LlamaForSequenceClassification:
        pass

    reason = mismatch(LlamaForSequenceClassification, LlamaForCausalLM)
    assert reason and "LlamaForSequenceClassification" in reason
    assert mismatch(LlamaForCausalLM, LlamaForCausalLM) is None
    # Unknown is not mismatched: an unsloth_zoo too old to name the class has no planner.
    assert mismatch(LlamaForCausalLM, None) is None
    assert mismatch(None, LlamaForCausalLM) is None

    ns = _load(planner = lambda *a, **k: pytest.fail("planned a head the plan does not name"))
    assert ns["resolve_unsloth_device_map"]("unsloth", "m", skip_reason = reason) == "sequential"


def test_the_optimized_llama_path_also_declines_a_classification_load():
    """The optimized Llama path must decline planning for num_labels loads; it would plan the causal LM."""
    llama = open(os.path.join(HERE, "unsloth", "models", "llama.py"), encoding = "utf-8").read()
    tree = ast.parse(llama)

    assignments = {}
    for node in ast.walk(tree):
        if not isinstance(node, ast.Assign):
            continue
        for target in node.targets:
            if isinstance(target, ast.Name):
                assignments[target.id] = assignments.get(target.id, "") + ast.unparse(node.value)

    calls = _resolve_calls(llama)
    assert calls, "llama.py no longer plans a device map"
    for call in calls:
        passed = {kw.arg: ast.unparse(kw.value) for kw in call.keywords}
        assert "skip_reason" in passed, f"llama.py:{call.lineno} plans a classification load"
        source = passed["skip_reason"] + assignments.get(passed["skip_reason"], "")
        assert "num_labels" in source, f"llama.py:{call.lineno}"
        assert "planner_class_mismatch_reason" in source, f"llama.py:{call.lineno}"

    # The veto must be decided before the call, or it is a NameError on every load.
    veto_line = min(
        node.lineno
        for node in ast.walk(tree)
        if isinstance(node, ast.Assign)
        and any(getattr(t, "id", None) == "_planner_skip_reason" for t in node.targets)
    )
    assert veto_line < min(call.lineno for call in calls)


def test_a_distributed_launch_never_gets_an_intra_model_split():
    """Distributed launches get one model per rank, so planning must never split a model across cards."""
    ns = _load(
        distributed = True, planner = lambda *a, **k: pytest.fail("planned inside a distributed launch")
    )
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == "sequential"


@pytest.mark.parametrize("device_type", ["xpu", "mps", "cpu", "hpu"])
def test_a_non_cuda_backend_never_reaches_the_cuda_planner(device_type):
    """The planner sizes cards through torch.cuda. On XPU or MPS that is either absent or
    lying, so falling back beats planning against numbers from the wrong device."""
    ns = _load(
        device_type = device_type,
        planner = lambda *a, **k: pytest.fail("CUDA planner on a non-CUDA backend"),
    )
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == "sequential"


@pytest.mark.parametrize("devices", [0, 1])
def test_one_gpu_or_none_falls_back_silently(devices):
    """Not a failure, just nothing to split across, so it prints nothing."""
    ns = _load(devices = devices, planner = lambda *a, **k: pytest.fail("nothing to plan across"))
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == "sequential"


def test_a_planner_that_declines_falls_back():
    ns = _load(planner = lambda *a, **k: None)
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == "sequential"


def test_a_planner_that_raises_falls_back_rather_than_failing_the_load():
    """A model that loads the old way beats one that will not load at all."""

    def _boom(*a, **k):
        raise RuntimeError("hub unreachable")

    ns = _load(planner = _boom)
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == "sequential"


def test_an_infeasible_plan_is_raised_not_swallowed():
    """The planner raises this instead of spilling a bitsandbytes model to CPU. Turning it
    back into "sequential" would hand the user an OOM in place of the diagnosis."""

    class DeviceMapInfeasible(RuntimeError):
        pass

    def _infeasible(*a, **k):
        raise DeviceMapInfeasible("needs 7.57 GiB free on cuda:0, has 4.10 GiB")

    ns = _load(planner = _infeasible)
    with pytest.raises(DeviceMapInfeasible):
        ns["resolve_unsloth_device_map"]("unsloth", "m")


@pytest.mark.parametrize(
    "kwargs,devices,planner",
    [
        ({"skip_reason": "text_only"}, 2, None),
        ({"fast_inference": True}, 2, None),
        ({"full_finetuning": True}, 2, None),
        ({}, 2, lambda *a, **k: None),
        ({}, 2, lambda *a, **k: (_ for _ in ()).throw(RuntimeError("hub unreachable"))),
    ],
)
def test_the_balanced_sentinel_declines_to_balanced_not_sequential(kwargs, devices, planner):
    """unsloth_balanced declines to balanced, since sequential fills cuda:0 first and never shards."""
    ns = _load(devices = devices, planner = planner)
    assert ns["resolve_unsloth_device_map"]("unsloth_balanced", "m", **kwargs) == "balanced"
    assert ns["resolve_unsloth_device_map"]("unsloth", "m", **kwargs) == "sequential"


@pytest.mark.parametrize("devices", [0, 1])
def test_the_balanced_sentinel_declines_to_balanced_on_one_device_too(devices):
    """The silent fallbacks are the easy ones to leave hardcoded, and both were."""
    ns = _load(devices = devices, planner = lambda *a, **k: pytest.fail("nothing to plan"))
    assert ns["resolve_unsloth_device_map"]("unsloth_balanced", "m") == "balanced"


def test_both_names_plan_identically_when_the_planner_answers():
    """The name chooses the fallback and nothing else, so a plan is not a second code
    path that could drift."""
    planned = {"": 0, "model.vision_tower": 1}
    for name in ("unsloth", "unsloth_balanced"):
        ns = _load(planner = lambda *a, **k: _Plan(dict(planned)))
        assert ns["resolve_unsloth_device_map"](name, "m") == planned


def test_an_infeasible_plan_is_still_raised_for_the_balanced_name():
    """The one deliberate raise must not be softened into a shard by the new name."""

    class DeviceMapInfeasible(RuntimeError):
        pass

    def _infeasible(*a, **k):
        raise DeviceMapInfeasible("needs 7.57 GiB free on cuda:0, has 4.10 GiB")

    ns = _load(planner = _infeasible)
    with pytest.raises(DeviceMapInfeasible):
        ns["resolve_unsloth_device_map"]("unsloth_balanced", "m")


def test_the_default_device_map_still_resolves_to_the_plain_sentinel():
    """An omitted device_map resolves to the planner, whose decline stays sequential as it was
    before planning existed; widening that to balanced would change single-card loads."""
    ns = _load()
    assert ns["requested_device_map"](ns["DEFAULT_DEVICE_MAP"]) == "unsloth"


def test_the_plan_is_returned_and_the_model_name_reaches_the_planner():
    seen = {}

    def _planner(model_name, **kwargs):
        seen.update(kwargs, model_name = model_name)
        return _Plan({"": 0, "model.vision_tower": 1})

    ns = _load(planner = _planner)
    result = ns["resolve_unsloth_device_map"](
        "unsloth",
        "unsloth/Muse-Glimmer-30B-unsloth-bnb-4bit",
        load_in_4bit = True,
    )
    assert result == {"": 0, "model.vision_tower": 1}
    assert seen["model_name"] == "unsloth/Muse-Glimmer-30B-unsloth-bnb-4bit"
    assert seen["load_in_4bit"] is True


def test_free_memory_is_planned_against_not_total():
    """Planning against total memory OOMed the notebook's first attempt (unsloth-zoo#1048): a
    resident CUDA context leaves far less than 16 GB free on each 16 GB card."""
    seen = {}
    ns = _load(
        free = {0: 4 * 2**30, 1: 15 * 2**30},
        planner = lambda name, **kw: seen.update(kw) or _Plan({"": 0}),
    )
    ns["resolve_unsloth_device_map"]("unsloth", "m")
    assert seen["max_memory"] == {0: 4 * 2**30, 1: 15 * 2**30}
    assert 16 * 2**30 not in seen["max_memory"].values(), "that is the total, not the free"


def test_planning_happens_only_where_the_model_name_is_final():
    """Plan only in llama.py and vision.py: loader.py remaps model_name after its device_map block."""
    models = os.path.join(HERE, "unsloth", "models")
    loader = open(os.path.join(models, "loader.py"), encoding = "utf-8").read()
    assert (
        "resolve_unsloth_device_map(" not in loader
    ), "loader.py plans before get_model_name has had its say"
    for name in ("llama.py", "vision.py"):
        source = open(os.path.join(models, name), encoding = "utf-8").read()
        assert "resolve_unsloth_device_map(" in source, name


def test_every_entry_point_accepts_the_planner_kwargs():
    """FastLanguageModel and FastModel only forward what they were given, so a signature
    that quietly lacks the parameter turns the notebook's hint into a TypeError."""
    import ast as _ast

    models = os.path.join(HERE, "unsloth", "models")
    for name in ("loader.py", "llama.py", "vision.py"):
        source = open(os.path.join(models, name), encoding = "utf-8").read()
        found = [
            node
            for node in _ast.walk(_ast.parse(source))
            if isinstance(node, _ast.FunctionDef)
            and node.name == "from_pretrained"
            and any(a.arg == "device_map" for a in node.args.args + node.args.kwonlyargs)
        ]
        assert found, f"no from_pretrained taking device_map in {name}"
        for node in found:
            args = {a.arg for a in node.args.args + node.args.kwonlyargs}
            assert "device_map_planner_kwargs" in args, f"{name}:{node.lineno}"


def test_planner_kwargs_reach_the_planner():
    """A GRPO backward retains rows the planner's inference-shaped default (0) does not
    reserve for, so the notebook has to be able to say so."""
    seen = {}
    ns = _load(planner = lambda name, **kw: seen.update(kw) or _Plan({"": 0}))
    ns["resolve_unsloth_device_map"](
        "unsloth",
        "m",
        planner_kwargs = {"rows_per_chunk": 128, "retained_rows": 6144, "softcapped": True},
    )
    assert seen["rows_per_chunk"] == 128
    assert seen["retained_rows"] == 6144
    assert seen["softcapped"] is True


def test_a_user_quantization_config_replaces_the_flags_for_the_planner():
    """Planner must use the caller's quantization_config, else a QLoRA is sized as full precision."""
    ns = _load()
    config = types.SimpleNamespace(load_in_4bit = True, load_in_8bit = False)
    kwargs = ns["planner_quantization_kwargs"](
        load_in_4bit = False,
        load_in_8bit = False,
        quantization_config = config,
    )
    assert kwargs == {"quantization_config": config}
    # transformers and the planner reject both at once.
    assert "load_in_4bit" not in kwargs
    assert "load_in_8bit" not in kwargs


@pytest.mark.parametrize("four_bit, eight_bit", [(True, False), (False, True)])
def test_the_flags_are_used_when_no_config_was_given(four_bit, eight_bit):
    ns = _load()
    assert ns["planner_quantization_kwargs"](
        load_in_4bit = four_bit,
        load_in_8bit = eight_bit,
    ) == {
        "load_in_4bit": four_bit,
        "load_in_8bit": eight_bit,
        "llm_int8_skip_modules": _SKIP_MODULES,
    }


def test_a_16bit_load_is_planned_without_a_skip_list():
    """Nothing is being quantized, so there is nothing to keep out of it. A stray
    llm_int8_skip_modules would reach AutoConfig as an attribute of the model config."""
    ns = _load()
    assert ns["planner_quantization_kwargs"]() == {"load_in_4bit": False, "load_in_8bit": False}


def test_the_modules_unsloth_keeps_in_compute_dtype_are_sized_that_way():
    """Planner must size SKIP_QUANTIZATION_MODULES at compute dtype, not 4bit, as bnb keeps them dense."""
    seen = {}
    ns = _load(planner = lambda name, **kw: seen.update(kw) or _Plan({"": 0}))
    ns["resolve_unsloth_device_map"](
        "unsloth",
        "m",
        **ns["planner_quantization_kwargs"](
            load_in_4bit = True,
            extra_skip_modules = ["out_proj"],
        ),
    )
    assert seen["load_in_4bit"] is True
    assert seen["llm_int8_skip_modules"] == _SKIP_MODULES + ["out_proj"]


def test_the_skip_list_is_not_sent_alongside_a_user_config():
    """The config already carries its own; sending both is what transformers refuses."""
    ns = _load()
    kwargs = ns["planner_quantization_kwargs"](
        quantization_config = types.SimpleNamespace(load_in_4bit = True),
        extra_skip_modules = ["out_proj"],
    )
    assert kwargs == {"quantization_config": kwargs["quantization_config"]}


def test_the_config_is_what_reaches_the_planner():
    seen = {}
    ns = _load(planner = lambda name, **kw: seen.update(kw) or _Plan({"": 0}))
    config = types.SimpleNamespace(load_in_4bit = True, load_in_8bit = False)
    ns["resolve_unsloth_device_map"](
        "unsloth",
        "m",
        **ns["planner_quantization_kwargs"](quantization_config = config),
    )
    assert seen["quantization_config"] is config
    assert "load_in_4bit" not in seen


def test_the_leaf_loaders_derive_the_planner_quantization_from_the_config():
    """A bare `load_in_4bit = load_in_4bit` at the call site is the bug above: the leaf
    receives the flag already cleared by loader.py."""
    models = os.path.join(HERE, "unsloth", "models")
    for name in ("llama.py", "vision.py", "diffusion.py"):
        source = open(os.path.join(models, name), encoding = "utf-8").read()
        for node in ast.walk(ast.parse(source)):
            if not (
                isinstance(node, ast.Call)
                and getattr(node.func, "id", None) == "resolve_unsloth_device_map"
            ):
                continue
            keywords = {kw.arg for kw in node.keywords}
            assert "load_in_4bit" not in keywords, f"{name}:{node.lineno} plans on the cleared flag"
            assert "load_in_8bit" not in keywords, f"{name}:{node.lineno} plans on the cleared flag"
            unpacked = [
                kw.value
                for kw in node.keywords
                if kw.arg is None and isinstance(kw.value, ast.Call)
            ]
            assert any(
                getattr(call.func, "id", None) == "planner_quantization_kwargs" for call in unpacked
            ), f"{name}:{node.lineno}"


def _resolve_calls(source):
    return [
        node
        for node in ast.walk(ast.parse(source))
        if isinstance(node, ast.Call)
        and getattr(node.func, "id", None) == "resolve_unsloth_device_map"
    ]


@pytest.mark.parametrize("name", ["llama.py", "vision.py", "diffusion.py"])
def test_the_planner_sizes_the_dtype_the_load_will_really_use(name):
    """Planner must size the dtype from_pretrained uses, not config.json's, via add_dtype_kwargs."""
    source = open(os.path.join(HERE, "unsloth", "models", name), encoding = "utf-8").read()
    calls = _resolve_calls(source)
    assert calls, f"{name} never resolves a device map"
    for call in calls:
        unpacked = [
            kw.value for kw in call.keywords if kw.arg is None and isinstance(kw.value, ast.Call)
        ]
        assert any(
            getattr(unpack.func, "id", None) == "add_dtype_kwargs" for unpack in unpacked
        ), f"{name}:{call.lineno} plans against the checkpoint's dtype, not the load's"


def test_the_diffusion_plan_is_sized_against_the_config_the_load_applies():
    """Diffusion plan must use the config the load applies, since bnb keeps lm_head and experts dense."""
    path = os.path.join(HERE, "unsloth", "models", "diffusion.py")
    source = open(path, encoding = "utf-8").read()
    tree = ast.parse(source)

    built = [
        node.lineno
        for node in ast.walk(tree)
        if isinstance(node, ast.Assign)
        and getattr(node.value, "func", None) is not None
        and getattr(node.value.func, "id", None) == "BitsAndBytesConfig"
        and any(getattr(target, "id", None) == "qcfg" for target in node.targets)
    ]
    assert built, "diffusion.py no longer builds its own BitsAndBytesConfig"

    calls = _resolve_calls(source)
    assert calls, "diffusion.py never resolves a device map"
    for call in calls:
        assert (
            max(built) < call.lineno
        ), f"diffusion.py:{call.lineno} plans before the quantization config exists"
        forwarded = [
            unpack
            for unpack in (
                kw.value
                for kw in call.keywords
                if kw.arg is None and isinstance(kw.value, ast.Call)
            )
            if getattr(unpack.func, "id", None) == "planner_quantization_kwargs"
        ]
        assert forwarded, f"diffusion.py:{call.lineno} plans without the load's quantization"
        for unpack in forwarded:
            passed = {kw.arg: ast.unparse(kw.value) for kw in unpack.keywords}
            assert (
                passed.get("quantization_config") == "qcfg"
            ), f"diffusion.py:{call.lineno} plans without the skip list the load applies"


def _helpers():
    """`planner_kwargs_with_max_memory` / `planner_hub_kwargs`, without importing torch."""
    src = open(LOADER_UTILS, encoding = "utf-8").read()
    ns = {"os": os}
    for node in ast.parse(src).body:
        keep = (
            isinstance(node, ast.FunctionDef)
            and node.name
            in (
                "planner_kwargs_with_max_memory",
                "planner_hub_kwargs",
                "planner_config_overrides",
                "_get_effective_local_files_only",
                "_env_says_offline",
            )
        ) or (
            isinstance(node, ast.Assign)
            and getattr(node.targets[0], "id", "").startswith("_OFFLINE_ENV_")
        )
        if keep:
            exec(ast.get_source_segment(src, node), ns)
    return ns


def test_a_transformers_max_memory_reaches_the_planner():
    """max_memory must reach the planner, since transformers ignores it once device_map is a dict."""
    ns = _helpers()
    merged = ns["planner_kwargs_with_max_memory"](None, {"max_memory": {0: "12GiB"}})
    assert merged["max_memory"] == {0: "12GiB"}


def test_an_explicit_planner_max_memory_wins_over_the_loader_one():
    ns = _helpers()
    merged = ns["planner_kwargs_with_max_memory"](
        {"max_memory": {0: "4GiB"}}, {"max_memory": {0: "12GiB"}}
    )
    assert merged["max_memory"] == {0: "4GiB"}


def test_no_max_memory_leaves_the_planner_kwargs_untouched():
    ns = _helpers()
    assert ns["planner_kwargs_with_max_memory"](None, {}) is None
    same = {"retained_rows": 8}
    assert ns["planner_kwargs_with_max_memory"](same, {"token": "x"}) is same


def test_the_planner_is_told_where_the_hub_is(monkeypatch):
    """It resolves the config a second time from `model_name`. Without these it can reach
    the network behind `local_files_only`, or miss a model that only exists in the caller's
    cache and lose a plan the load needed."""
    monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
    monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)
    ns = _helpers()
    assert ns["planner_hub_kwargs"]({"cache_dir": "/models", "local_files_only": True}) == {
        "cache_dir": "/models",
        "local_files_only": True,
    }
    assert ns["planner_hub_kwargs"]({}) == {}
    assert ns["planner_hub_kwargs"]({"local_files_only": False}) == {}


@pytest.mark.parametrize("name", ["vision.py", "llama.py", "diffusion.py"])
def test_every_leaf_planner_call_forwards_the_budget_and_the_hub(name):
    """A leaf that misses either one silently plans against the wrong facts."""
    source = open(os.path.join(MODELS, name), encoding = "utf-8").read()
    for node in ast.walk(ast.parse(source)):
        if not isinstance(node, ast.Call):
            continue
        if getattr(node.func, "id", None) != "resolve_unsloth_device_map":
            continue
        rendered = ast.unparse(node)
        assert (
            "planner_kwargs_with_max_memory" in rendered
        ), f"{name}:{node.lineno} plans without the caller's max_memory"
        assert (
            "planner_hub_kwargs" in rendered
        ), f"{name}:{node.lineno} plans without the caller's cache_dir/local_files_only"
        assert (
            "planner_config_overrides" in rendered
        ), f"{name}:{node.lineno} plans without the caller's config overrides"
        return
    raise AssertionError(f"no resolve_unsloth_device_map call in {name}")


def test_the_wrapper_tells_the_leaf_the_config_was_the_callers():
    """The caller-config flag must be passed explicitly, since FastModel renames config to auto_config."""
    loader = open(os.path.join(MODELS, "loader.py"), encoding = "utf-8").read()
    assert "auto_config_from_caller = user_config is not None" in loader

    vision = open(os.path.join(MODELS, "vision.py"), encoding = "utf-8").read()
    args = [
        a.arg
        for node in ast.walk(ast.parse(vision))
        if isinstance(node, ast.FunctionDef) and node.name == "from_pretrained"
        for a in list(node.args.args) + list(node.args.kwonlyargs)
    ]
    assert "auto_config_from_caller" in args, "the leaf cannot see that the config was theirs"
    assert "or auto_config_from_caller" in vision


def test_a_resize_declines_the_automatic_offload():
    """`resize_token_embeddings` replaces the embedding module, and forward hooks do not
    travel to the replacement, so an offload installed during the load would leave a CPU
    embedding feeding a GPU decoder. An explicit request is left alone."""
    loader = open(os.path.join(MODELS, "loader.py"), encoding = "utf-8").read()
    assert "resize_model_vocab is not None" in loader
    assert "and offload_embedding == OFFLOAD_EMBEDDING_AUTO" in loader


def test_a_caller_supplied_config_declines_planning():
    """The weights load against their config; the planner rebuilds the repo's. Same class,
    different `num_hidden_layers` or `vocab_size`, and the map omits blocks or under-budgets
    weights -- which the class comparison cannot see."""
    source = open(os.path.join(MODELS, "vision.py"), encoding = "utf-8").read()
    assert "user_config is not None" in source
    tree = ast.parse(source)
    for node in ast.walk(tree):
        if not isinstance(node, ast.If):
            continue
        rendered = ast.unparse(node)
        if "user_config is not None" in rendered and "_planner_skip_reason" in rendered:
            return
    raise AssertionError("vision.py plans without vetoing a caller-supplied config")


def test_the_optimized_path_honours_offload_embedding():
    """`FastLanguageModel` accepts `offload_embedding`, and the optimized architectures used to
    drop it in silence. Now the loader forwards it and FastLlamaModel applies the same offload as
    FastModel, through the shared helper."""
    loader = open(os.path.join(MODELS, "loader.py"), encoding = "utf-8").read()
    assert "does not support it" not in loader
    llama = open(os.path.join(MODELS, "llama.py"), encoding = "utf-8").read()
    assert 'kwargs.pop("offload_embedding", False)' in llama
    assert "offload_input_embedding(model)" in llama


def test_the_auto_mode_is_recognised_by_value_everywhere():
    """Auto mode must be tested with ==, not is, so an equal but non-interned auto string is recognised."""
    loader = open(os.path.join(MODELS, "loader.py"), encoding = "utf-8").read()
    for node in ast.walk(ast.parse(loader)):
        if not isinstance(node, ast.Compare):
            continue
        rendered = ast.unparse(node)
        if "OFFLOAD_EMBEDDING_AUTO" not in rendered:
            continue
        assert not any(
            isinstance(op, (ast.Is, ast.IsNot)) for op in node.ops
        ), f"loader.py:{node.lineno} compares the auto mode by identity: {rendered}"


def test_the_optimized_path_declines_a_caller_supplied_config():
    """The optimized path must decline planning for a caller config; the planner rebuilds from the name."""
    llama = open(os.path.join(MODELS, "llama.py"), encoding = "utf-8").read()
    tree = ast.parse(llama)
    body = None
    for node in ast.walk(tree):
        if isinstance(node, ast.Assign) and ast.unparse(node) == "_planner_skip_reason = None":
            body = node
    assert body is not None, "llama.py no longer starts a planner skip reason"

    assert "if user_config is not None:" in llama
    assert (
        "a caller-supplied config may not describe the repo the planner rebuilds" in llama
    ), "the optimized path plans against a config the load does not use"

    # The veto has to come first, or a later branch with no reason overwrites it.
    veto = llama.index("a caller-supplied config may not describe the repo the planner rebuilds")
    num_labels = llama.index("num_labels loads a task head the repo config does not describe")
    assert veto < num_labels, "the caller-config veto is set after another branch clears it"
    assert "if _planner_skip_reason is None and num_labels is not None:" in llama


def test_the_diffusion_leaf_plans_with_the_locality_the_load_uses():
    """The planner needs the resolved local_files_only; raw kwargs would miss the offline env vars."""
    source = open(os.path.join(MODELS, "diffusion.py"), encoding = "utf-8").read()
    for node in ast.walk(ast.parse(source)):
        if not isinstance(node, ast.Call):
            continue
        if getattr(node.func, "id", None) != "resolve_unsloth_device_map":
            continue
        rendered = ast.unparse(node)
        assert (
            "local_files_only" in rendered and "cache_dir" in rendered
        ), f"diffusion.py:{node.lineno} plans without the locality the load resolved"
        return
    raise AssertionError("no resolve_unsloth_device_map call in diffusion.py")


def test_a_code_revision_reaches_the_planner():
    """`trust_remote_code` makes resolving the model class a second Hub lookup, and the
    planner honours `code_revision` for it. The load already gets it through kwargs, so
    leaving it out plans one revision of the remote code and loads another."""
    ns = _helpers()
    assert ns["planner_hub_kwargs"]({"code_revision": "abc123"}) == {"code_revision": "abc123"}
    assert "code_revision" not in ns["planner_hub_kwargs"]({})
    assert ns["planner_hub_kwargs"]({"code_revision": None}) == {}


def test_a_max_position_embeddings_override_reaches_the_planner():
    """Planner rebuilds config from the name, so a max_position_embeddings override must be forwarded."""
    ns = _helpers()
    assert ns["planner_config_overrides"]({"max_position_embeddings": 8192}) == {
        "max_position_embeddings": 8192,
    }
    assert ns["planner_config_overrides"]({}) == {}
    assert ns["planner_config_overrides"](None) == {}
    assert ns["planner_config_overrides"]({"max_position_embeddings": None}) == {}


def test_the_diffusion_leaf_plans_with_the_code_revision_too():
    """Same reason as its locality: this leaf builds the helper's input itself, so a key
    added to the helper does not reach it unless it is named here."""
    source = open(os.path.join(MODELS, "diffusion.py"), encoding = "utf-8").read()
    for node in ast.walk(ast.parse(source)):
        if isinstance(node, ast.Call) and getattr(node.func, "id", None) == "planner_hub_kwargs":
            assert "code_revision" in ast.unparse(
                node
            ), "the diffusion leaf plans against a different revision of the remote code"
            return
    raise AssertionError("no planner_hub_kwargs call in diffusion.py")


def test_an_unresolvable_explicit_model_class_declines_planning():
    """An explicit model class without an auto mapping must decline planning; unknown reads as a match."""
    vision = open(os.path.join(MODELS, "vision.py"), encoding = "utf-8").read()
    assert 'getattr(auto_model, "_model_mapping", None) is None' in vision
    assert "an explicit model class has no auto mapping" in vision

    # Ahead of the class comparison it backstops, or the caller-config branch claims the slot.
    veto = vision.index("an explicit model class has no auto mapping")
    caller = vision.index("a caller-supplied config may not describe the repo the planner")
    assert veto < caller, "the unresolvable-class veto never gets to run"


def test_an_auto_class_still_plans():
    """The veto is keyed on the absence of `_model_mapping`, which every Auto class has,
    so a remote-code checkpoint whose config simply is not in the mapping keeps its plan.
    Declining on `model_class is None` alone would have turned planning off for those."""
    import ast as _ast

    vision = open(os.path.join(MODELS, "vision.py"), encoding = "utf-8").read()
    idx = vision.index("an explicit model class has no auto mapping")
    guard = vision[vision.rindex("if (", 0, idx) : idx]
    assert "_model_mapping" in guard, "the veto is not keyed on the class being concrete"


LOADER = os.path.join(MODELS, "loader.py")
_QUANT_NAMES = ("is_quantized", "load_in_4bit", "load_in_8bit", "load_in_fp8")


def _prepare_device_map_guards():
    """Every `prepare_device_map()` call in loader.py, with the `if` tests enclosing it."""
    source = open(LOADER, encoding = "utf-8").read()
    tree = ast.parse(source)
    found = []

    def walk(node, guards):
        for child in ast.iter_child_nodes(node):
            if (
                isinstance(child, ast.Call)
                and getattr(child.func, "id", None) == "prepare_device_map"
            ):
                found.append((child.lineno, list(guards)))
            if isinstance(child, ast.If):
                walk_body(child.body, guards + [ast.unparse(child.test)])
                walk_body(child.orelse, guards)
            else:
                walk(child, guards)

    def walk_body(body, guards):
        for stmt in body:
            walk(stmt, guards)

    walk_body(tree.body, [])
    return found


def test_every_rank_of_a_16bit_distributed_launch_still_gets_its_own_device():
    """Every distributed rank must pin its own card at any precision, else all ranks queue on cuda:0."""
    calls = _prepare_device_map_guards()
    assert calls, "loader.py no longer pins a distributed rank to its own device"
    for lineno, guards in calls:
        for guard in guards:
            offending = [name for name in _QUANT_NAMES if name in guard]
            assert not offending, (
                f"loader.py:{lineno}: prepare_device_map() is gated on {offending} "
                f"({guard!r}), so a 16-bit distributed load keeps a string device_map "
                f"and every rank dispatches onto cuda:0"
            )


class _FakeDistributed:
    """torch.distributed as a rank sees it. `rank` is the GLOBAL rank, as get_rank() returns."""

    def __init__(
        self,
        rank = None,
        world_size = None,
    ):
        self._rank = rank
        self._world_size = world_size

    def is_available(self):
        return True

    def is_initialized(self):
        return self._rank is not None

    def get_rank(self):
        return self._rank

    def get_world_size(self):
        return self._world_size


class _FakeAccelerator(_FakeCuda):
    def __init__(self, count):
        super().__init__(count)
        self.pinned = []

    def set_device(self, index):
        if index >= self._count:
            raise RuntimeError(f"CUDA error: invalid device ordinal ({index} of {self._count})")
        self.pinned.append(index)


_DISTRIBUTED_NAMES = (
    "_get_env_int",
    "_infer_distributed_ranks",
    "_visible_device_count",
    "_infer_local_rank",
    "is_distributed",
    "prepare_device_map",
    "is_automatic_device_map",
    "requested_device_map",
)
_DISTRIBUTED_CONSTANTS = (
    "LOCAL_RANK_KEYS",
    "WORLD_SIZE_KEYS",
    "LOCAL_RANK_ONLY_KEYS",
    "UNSLOTH_DEVICE_MAP",
    "UNSLOTH_BALANCED_DEVICE_MAP",
    "DEFAULT_DEVICE_MAP",
    "TRANSFORMERS_PLACEMENT_STRATEGIES",
    "AUTOMATIC_DEVICE_MAPS",
)


def _load_distributed(
    monkeypatch,
    *,
    device_type = "cuda",
    devices = 8,
    rank = None,
    world_size = None,
    env = None,
):
    """The placement helpers over a fabricated launcher environment and accelerator."""
    for key in ("LOCAL_RANK", "RANK", "WORLD_SIZE"):
        monkeypatch.delenv(key, raising = False)
    for key, value in (env or {}).items():
        monkeypatch.setenv(key, value)

    accelerator = _FakeAccelerator(devices)
    torch_stub = types.SimpleNamespace(
        distributed = _FakeDistributed(rank, world_size),
        cuda = accelerator,
        xpu = accelerator,
        npu = accelerator,
    )
    ns = {"os": os, "torch": torch_stub, "DEVICE_TYPE_TORCH": device_type}
    for node in ast.parse(_SRC).body:
        if isinstance(node, ast.FunctionDef) and node.name in _DISTRIBUTED_NAMES:
            exec(ast.get_source_segment(_SRC, node), ns)
        elif isinstance(node, ast.ClassDef) and node.name == "_DefaultDeviceMap":
            exec(ast.get_source_segment(_SRC, node), ns)
        elif (
            isinstance(node, ast.Assign)
            and getattr(node.targets[0], "id", None) in _DISTRIBUTED_CONSTANTS
        ):
            exec(ast.get_source_segment(_SRC, node), ns)
    return ns, accelerator


def _pinned_device_map(ns):
    device_map, is_dist = ns["prepare_device_map"]()
    return device_map, is_dist


def test_the_second_node_of_a_multi_node_job_pins_to_its_own_card():
    """Pin to LOCAL_RANK, not get_rank(): the global rank is not a device index on later nodes."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, accelerator = _load_distributed(
            monkeypatch,
            devices = 8,
            rank = 8,
            world_size = 16,
            env = {"LOCAL_RANK": "0", "RANK": "8", "WORLD_SIZE": "16"},
        )
        device_map, is_dist = _pinned_device_map(ns)
        assert is_dist
        assert device_map == {"": "cuda:0"}, device_map
        assert accelerator.pinned == [0], accelerator.pinned
    finally:
        monkeypatch.undo()


def test_a_launcher_that_sets_no_local_rank_still_names_a_card_that_exists():
    """No LOCAL_RANK: the global rank is folded onto the visible cards rather than overflowing."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, accelerator = _load_distributed(
            monkeypatch,
            devices = 8,
            rank = 9,
            world_size = 16,
        )
        device_map, is_dist = _pinned_device_map(ns)
        assert is_dist
        assert device_map == {"": "cuda:1"}, device_map
        assert accelerator.pinned == [1], accelerator.pinned
    finally:
        monkeypatch.undo()


def test_a_per_rank_cuda_visible_devices_pins_to_the_one_card_it_can_see():
    """LOCAL_RANK=3 with a single visible card is card 0 -- cuda:3 does not exist here."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, accelerator = _load_distributed(
            monkeypatch,
            devices = 1,
            rank = 3,
            world_size = 4,
            env = {"LOCAL_RANK": "3", "RANK": "3", "WORLD_SIZE": "4"},
        )
        device_map, _ = _pinned_device_map(ns)
        assert device_map == {"": "cuda:0"}, device_map
        assert accelerator.pinned == [0], accelerator.pinned
    finally:
        monkeypatch.undo()


@pytest.mark.parametrize("local_rank", [0, 1])
def test_a_single_node_launch_keeps_the_rank_it_already_had(local_rank):
    """The case the PR exists for must not move: one node, one card per rank."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, accelerator = _load_distributed(
            monkeypatch,
            devices = 2,
            rank = local_rank,
            world_size = 2,
            env = {"LOCAL_RANK": str(local_rank), "RANK": str(local_rank), "WORLD_SIZE": "2"},
        )
        device_map, is_dist = _pinned_device_map(ns)
        assert is_dist
        assert device_map == {"": f"cuda:{local_rank}"}
        assert accelerator.pinned == [local_rank]
    finally:
        monkeypatch.undo()


def test_a_single_process_run_is_never_pinned():
    """No launcher, no distribution: one GPU and CPU-only runs keep their own placement."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, accelerator = _load_distributed(monkeypatch, devices = 1)
        assert _pinned_device_map(ns) == (None, False)
        assert accelerator.pinned == []
    finally:
        monkeypatch.undo()


@pytest.mark.parametrize(
    "device_map",
    ["auto", "balanced", "balanced_low_0", "sequential", "unsloth", "unsloth_balanced", "cuda"],
)
def test_an_unchosen_placement_is_the_one_a_rank_may_pin(device_map):
    """Every strategy name spreads one model over all the cards, which is the #3459 failure
    on every rank. A bare "cuda" names the type and leaves the index to us."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, _ = _load_distributed(monkeypatch)
        is_automatic = ns.get("is_automatic_device_map")
        assert is_automatic is not None, "loader_utils.py has no is_automatic_device_map"
        assert is_automatic(device_map) is True, device_map
        assert is_automatic(ns["DEFAULT_DEVICE_MAP"]) is True
    finally:
        monkeypatch.undo()


@pytest.mark.parametrize(
    "device_map", ["cpu", "cuda:2", "mps", "xpu:1", "meta", {"": "cpu"}, {"": 0}, 0, None]
)
def test_a_device_the_caller_named_survives_a_distributed_launch(device_map):
    """A device the caller named, like cpu or cuda:2, must not be replaced by the rank's own card."""
    monkeypatch = pytest.MonkeyPatch()
    try:
        ns, _ = _load_distributed(monkeypatch)
        is_automatic = ns.get("is_automatic_device_map")
        assert is_automatic is not None, "loader_utils.py has no is_automatic_device_map"
        assert is_automatic(device_map) is False, device_map
    finally:
        monkeypatch.undo()


def test_the_loader_pins_on_the_placement_being_unchosen_not_on_it_being_a_string():
    """The guard at both `prepare_device_map()` call sites, read off loader.py.

    `isinstance(device_map, str)` is true of "cpu" and "cuda:2" as well, so it was the
    broadened condition that clobbered them.
    """
    calls = _prepare_device_map_guards()
    assert calls, "loader.py no longer pins a distributed rank to its own device"
    for lineno, guards in calls:
        assert any("is_automatic_device_map(device_map)" in guard for guard in guards), (
            f"loader.py:{lineno}: prepare_device_map() is guarded by {guards}, which does not "
            f"distinguish a placement nobody chose from a device the caller named"
        )
        for guard in guards:
            assert "isinstance(device_map, str)" not in guard, (
                f"loader.py:{lineno}: an explicit device_map='cpu' is a str too, so this guard "
                f"moves the load onto the rank's GPU"
            )


# ------------------------------------------------- a model one card holds stays on one card


class _SizedPlan(_Plan):
    def __init__(
        self,
        total_gib,
        budget_gib = 14.4,
        headroom_gib = 0.5,
        devices = (0, 1),
        transient_gib = 0.0,
        reserve_gib = 0.0,
    ):
        super().__init__({"model.layers.0": devices[0], "lm_head": devices[-1]})
        self.raw_budgets = {d: int(budget_gib * 2**30) for d in devices}
        self.total_weight_bytes = int(total_gib * 2**30)
        self.headroom_bytes = int(headroom_gib * 2**30)
        self.load_transient_by_device = {devices[-1]: int(transient_gib * 2**30)}
        self.activation_reserve_by_device = {d: int(reserve_gib * 2**30) for d in devices}


@pytest.mark.parametrize("total_gib", [1.2, 6.2, 9.7])  # Qwen3-0.6B, DeepSeek-OCR, Gemma 3n fp32
def test_a_model_that_fits_one_card_is_not_split(total_gib, capsys):
    ns = _load(planner = lambda name, **kw: _SizedPlan(total_gib))
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == {"": 0}
    assert "fits on cuda:0" in capsys.readouterr().out


def test_the_single_card_is_one_the_caller_allowed():
    """max_memory {2, 3} withholds cuda:0 and cuda:1."""
    seen = {}

    def planner(name, max_memory, **kw):
        seen["devices"] = sorted(max_memory)
        return _SizedPlan(1.2, devices = sorted(max_memory))

    ns = _load(devices = 4, planner = planner)
    device_map = ns["resolve_unsloth_device_map"](
        "unsloth", "m", planner_kwargs = {"max_memory": {3: "14GiB", 2: "14GiB"}}
    )
    assert seen["devices"] == [2, 3]
    assert device_map == {"": 2}


@pytest.mark.parametrize(
    "total_gib, transient_gib, single",
    [
        (11.0, 0.0, True),  # 11.5 of 14.4 GiB: just under the 80% line
        (11.2, 0.0, False),
        (10.0, 1.5, False),  # the load transient counts too
    ],
)
def test_the_single_card_line_is_a_fifth_of_the_card_free(total_gib, transient_gib, single):
    plan = _SizedPlan(total_gib, transient_gib = transient_gib)
    ns = _load(planner = lambda name, **kw: plan)
    expected = {"": 0} if single else plan.device_map
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == expected


def test_a_plan_without_sizes_is_used_as_before():
    """An older unsloth_zoo whose plan carries no sizes keeps its split."""
    plan = _Plan({"model.layers.0": 0, "lm_head": 1})
    ns = _load(planner = lambda name, **kw: plan)
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == plan.device_map


def test_a_model_too_big_for_one_card_is_still_planned():
    plan = _SizedPlan(13.0)
    ns = _load(planner = lambda name, **kw: plan)
    assert ns["resolve_unsloth_device_map"]("unsloth", "m") == plan.device_map


def test_balanced_still_splits_a_small_model():
    plan = _SizedPlan(1.2)
    ns = _load(planner = lambda name, **kw: plan)
    assert ns["resolve_unsloth_device_map"]("unsloth_balanced", "m") == plan.device_map


@pytest.mark.parametrize(
    "planner_kwargs, single",
    [
        (None, True),  # an auto-derived reserve stays the planner's business
        ({"activation_reserve_bytes": 4 * 2**30}, True),
        ({"activation_reserve_bytes": 6 * 2**30}, False),
    ],
)
def test_a_reserve_the_caller_passed_is_kept_on_the_single_card(planner_kwargs, single):
    plan = _SizedPlan(
        9.7,
        reserve_gib = 6.0
        if planner_kwargs is None
        else planner_kwargs["activation_reserve_bytes"] / 2**30,
    )
    ns = _load(planner = lambda name, **kw: plan)
    got = ns["resolve_unsloth_device_map"]("unsloth", "m", planner_kwargs = planner_kwargs)
    assert got == ({"": 0} if single else plan.device_map)