Skip to content

armgit / Soup

Public Imported from GitHub
0

Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.

28.7 KB
Raw Blame
"""Issue #724 / #745 — the LoRA+ optimizer wiring, in every trainer that should
have it.

#724 fixed the failure in ``trainer/sft.py``, ``pretrain.py`` and ``embedding.py``:
``loraplus_lr_ratio`` was forwarded into ``TrainingArguments``, which is not a
field there, so the run crashed before the first step. The fix routes it through
``attach_loraplus_optimizer`` instead, called after the trainer is built.

That change made the failure mode *quieter*, which is exactly why it needs this
scan. Before #724 a wrapper that never wired LoRA+ **crashed** on the unknown
keyword; after #724 a wrapper that never calls ``attach_loraplus_optimizer`` runs
to completion with LoRA+ silently disabled — the loss curve looks normal and the
B matrices simply trained at the base rate. A test has to provide the signal the
crash used to give for free.

**#745 extends the coverage from the three SFT-family wrappers to every wrapper
that builds a TRL/HF ``Trainer``.** LoRA+ is a shared ``TrainingConfig`` option
with no task gating, so a preference/RL/specialised wrapper that builds a PEFT
model and does not wire it silently ignores ``loraplus_lr_ratio``.

A wrapper wires LoRA+ one of two ways, and this scan accepts both:

- **Attach** — ``attach_loraplus_optimizer(trainer, tcfg)`` after construction.
  Correct for every trainer whose optimizer is created lazily at ``train()``
  (the SFT family and every preference/RL wrapper except PPO, online_dpo
  included).
- **Inject** — ``build_loraplus_optimizer(...)`` before construction, handed to
  the trainer via ``optimizers=(opt, None)``. This is PPO's shape: its
  ``trl.experimental`` trainer builds the optimizer and scheduler eagerly in
  ``__init__``, so a post-construction attach would leave the scheduler bound to
  the discarded default optimizer — see
  ``tests/test_issue745_ppo_loraplus_scheduler.py``.

The one genuine exception is ``unlearn.py``: it runs a self-contained
``torch.optim.AdamW`` loop (not a ``Trainer`` subclass), so there is neither a
``trainer.optimizer`` to attach to nor a constructor to inject into. Rather than
lump it in with the wired wrappers or leave it silently ignoring the option,
``loraplus_lr_ratio`` is **refused at config parse** for ``task='unlearn'`` — see
``test_unlearn_loraplus_is_refused_at_config_parse``. So the exemption below is
earned by a hard error, not by an unimplemented gap.

A wrapper counts as building a LoRA adapter when it calls ``get_peft_model``
itself OR hands a ``peft_config=`` to a TRL trainer that applies the adapter in
its own ``__init__`` (``online_dpo.py``). Until #745's second round the scan
only knew the first shape, so online_dpo ignored ``loraplus_lr_ratio`` unseen.
The MLX trainer builds its adapter with mlx-lm's ``linear_to_lora_layers``
instead; until #1324 the scan did not count it, so ``backend: mlx`` ignored
``loraplus_lr_ratio`` unseen too.

Coverage is derived by SCANNING ``soup_cli/trainer/`` (following
``tests/test_issue359_deepspeed_guard_coverage.py``) rather than a hand-written
list, so a wrapper added later cannot ship LoRA+-less without either wiring it or
being named — with a reason — in the exemption set below.
"""

from __future__ import annotations

import ast
import pathlib
import re

import pytest

_TRAINER_DIR = pathlib.Path(__file__).resolve().parents[1] / "src" / "soup_cli" / "trainer"
_TRAINER_SOURCES = sorted(_TRAINER_DIR.glob("*.py"))

#: A wrapper applies a LoRA adapter one of two ways, and either is the point at
#: which LoRA A/B matrices exist for LoRA+ to give different rates to: it calls
#: ``get_peft_model(...)`` itself, or it hands a ``peft_config=`` to a TRL trainer
#: that applies the adapter inside its own ``__init__`` (``online_dpo.py``). The
#: second shape is detected on the AST (see :func:`_hands_peft_config_to_trl`),
#: since ``self.peft_config = ...`` assignments share the spelling.
_BUILDS_PEFT = re.compile(r"(?:get_peft_model|linear_to_lora_layers)\s*\(")
#: The two wiring shapes (see the module docstring): attach after construction,
#: or build before it and inject via ``optimizers=``. A wrapper counts as wiring
#: LoRA+ if it does either.
_ATTACH_CALL = re.compile(r"attach_loraplus_optimizer\s*\(")
_INJECT_CALL = re.compile(r"build_loraplus_optimizer\s*\(")

#: PEFT-building wrappers that do NOT wire ``attach_loraplus_optimizer``, each
#: with the reason it is allowed to. After #745 there is exactly one: ``unlearn``
#: is not a ``Trainer`` subclass (it drives ``torch.optim.AdamW`` directly), so
#: there is nothing to attach to and ``loraplus_lr_ratio`` is refused at parse
#: instead. A wrapper is named here so a newly added LoRA-less trainer has to be
#: argued for rather than slipping through, and the "stays earned" test below
#: keeps each reason true.
_LORAPLUS_EXEMPT = {
    "csm.py": (
        "Native CSM accepts only standard LoRA; loraplus_lr_ratio is refused at "
        "config parse (tests/test_native_csm.py)."
    ),
    "unlearn.py": (
        "not a Trainer subclass — runs torch.optim.AdamW directly (unlearn.py), "
        "so there is no trainer.optimizer to attach LoRA+ to. loraplus_lr_ratio "
        "is refused at config parse for task='unlearn' instead of being silently "
        "ignored (see test_unlearn_loraplus_is_refused_at_config_parse)."
    ),
    "mlx_sft.py": (
        "builds its adapter with mlx-lm's linear_to_lora_layers and its optimizer "
        "from one learning rate (plan_optimizer), so there is no LoRA B group to "
        "give lr * ratio. loraplus_lr_ratio is refused at config parse for "
        "backend='mlx' instead (#1324, tests/test_issue1324_mlx_loraplus_refusal.py)."
    ),
}


def _code_without_comments(text: str) -> str:
    """Strip trailing comments so prose ABOUT the call is not read as a call."""
    return "\n".join(line.split("#", 1)[0] for line in text.splitlines())


def _hands_peft_config_to_trl(source: str) -> bool:
    """True when some call passes a ``peft_config=`` keyword that is not a
    literal ``None``, i.e. the wrapper delegates applying the adapter to TRL."""
    for node in ast.walk(ast.parse(source)):
        if not isinstance(node, ast.Call):
            continue
        for keyword in node.keywords:
            if keyword.arg != "peft_config":
                continue
            if isinstance(keyword.value, ast.Constant) and keyword.value.value is None:
                continue
            return True
    return False


def _source_builds_peft(source: str) -> bool:
    return bool(
        _BUILDS_PEFT.search(_code_without_comments(source))
        or _hands_peft_config_to_trl(source)
    )


def _builds_peft(path: pathlib.Path) -> bool:
    return _source_builds_peft(path.read_text(encoding="utf-8"))


def _wires_source(source: str) -> bool:
    """True if the source wires LoRA+ either way: attach or constructor inject."""
    code = _code_without_comments(source)
    return bool(_ATTACH_CALL.search(code) or _INJECT_CALL.search(code))


def _wires_loraplus(path: pathlib.Path) -> bool:
    return _wires_source(path.read_text(encoding="utf-8"))


def _is_loraplus_none_tuple(node: ast.AST) -> bool:
    """True for the literal ``(loraplus_optimizer, None)`` handed to the trainer."""
    return (
        isinstance(node, ast.Tuple)
        and len(node.elts) == 2
        and isinstance(node.elts[0], ast.Name)
        and node.elts[0].id == "loraplus_optimizer"
        and isinstance(node.elts[1], ast.Constant)
        and node.elts[1].value is None
    )


def _hands_optimizer_to_constructor(body: list[ast.stmt]) -> bool:
    """True if this branch body routes ``(loraplus_optimizer, None)`` into an
    ``optimizers`` slot, in any of these forms:
    ``trainer_kwargs["optimizers"] = (...)``, ``optimizers = (...)``, or a call
    keyword ``optimizers=(...)``.

    Walking the AST of one branch (rather than regex-scanning the whole file)
    is what pins the injection to the branch that actually runs; a copy sitting
    in a sibling branch does not satisfy it.
    """
    for stmt in body:
        for node in ast.walk(stmt):
            if (
                isinstance(node, ast.keyword)
                and node.arg == "optimizers"
                and _is_loraplus_none_tuple(node.value)
            ):
                return True
            if isinstance(node, ast.Assign) and _is_loraplus_none_tuple(node.value):
                for target in node.targets:
                    if (
                        isinstance(target, ast.Subscript)
                        and isinstance(target.slice, ast.Constant)
                        and target.slice.value == "optimizers"
                    ):
                        return True
                    if isinstance(target, ast.Name) and target.id == "optimizers":
                        return True
    return False


def _if_is_experimental_bodies(tree: ast.AST) -> list[list[ast.stmt]]:
    """Every ``if is_experimental:`` branch body in the tree, i.e. the live PPO
    construction path (trl >=0.28 always imports ``trl.experimental.ppo``)."""
    return [
        node.body
        for node in ast.walk(tree)
        if isinstance(node, ast.If)
        and isinstance(node.test, ast.Name)
        and node.test.id == "is_experimental"
    ]


class TestLoraPlusWiringCoverage:
    def test_the_scan_actually_sees_the_trainer_package(self):
        """Without this, a moved source tree turns the checks below into a
        vacuous pass over an empty file list."""
        assert _TRAINER_DIR.is_dir(), _TRAINER_DIR
        names = {path.name for path in _TRAINER_SOURCES}
        assert len(names) > 20
        assert {"sft.py", "pretrain.py", "embedding.py", "dpo.py", "ppo.py"} <= names

    def test_the_scan_finds_the_peft_builders(self):
        """If this ever collapses to a handful, the detector has broken rather
        than the codebase having shed its LoRA trainers."""
        building = [p.name for p in _TRAINER_SOURCES if _builds_peft(p)]
        assert len(building) >= 15, building
        assert {"sft.py", "pretrain.py", "embedding.py"} <= set(building)

    @pytest.mark.parametrize("path", _TRAINER_SOURCES, ids=[p.stem for p in _TRAINER_SOURCES])
    def test_every_peft_builder_wires_loraplus_or_is_exempt(self, path):
        code = _code_without_comments(path.read_text(encoding="utf-8"))
        if not _builds_peft(path):
            return
        if path.name in _LORAPLUS_EXEMPT:
            return
        assert _ATTACH_CALL.search(code) or _INJECT_CALL.search(code), (
            f"{path.name} applies a LoRA adapter (get_peft_model) but neither "
            "calls attach_loraplus_optimizer() nor builds one for constructor "
            "injection (build_loraplus_optimizer); training.loraplus_lr_ratio "
            "would be silently ignored on this task (#724/#745). Wire it, or add "
            "the module to _LORAPLUS_EXEMPT with a reason."
        )

    def test_every_builder_except_the_exempt_is_wired(self):
        """Pins the positive set so the parametrized check above is not vacuous:
        every PEFT-building wrapper except the earned exemptions wires LoRA+ (by
        attach or by constructor inject). #724 wired three; #745 wires all the
        rest: twelve by attach (dpo, kto, online_dpo, ...) and PPO by inject."""
        builders = {p.name for p in _TRAINER_SOURCES if _builds_peft(p)}
        wired = {p.name for p in _TRAINER_SOURCES if _wires_loraplus(p)}
        assert wired == builders - set(_LORAPLUS_EXEMPT), (
            "wired set must be exactly the PEFT builders minus the exemptions; "
            f"missing={sorted(builders - set(_LORAPLUS_EXEMPT) - wired)}, "
            f"unexpected={sorted(wired - (builders - set(_LORAPLUS_EXEMPT)))}"
        )

    def test_no_peft_builder_quietly_loses_the_wiring(self):
        """Aggregate form of the per-file check: every LoRA-building wrapper is
        either wired or explicitly exempt. Catches a new wrapper that builds a
        PEFT model and does neither."""
        offenders = []
        for path in _TRAINER_SOURCES:
            code = _code_without_comments(path.read_text(encoding="utf-8"))
            if not _builds_peft(path):
                continue
            if path.name in _LORAPLUS_EXEMPT:
                continue
            if not (_ATTACH_CALL.search(code) or _INJECT_CALL.search(code)):
                offenders.append(path.name)
        assert not offenders, (
            f"{', '.join(offenders)} apply a LoRA adapter but neither attach nor "
            "inject a LoRA+ optimizer. Wire LoRA+ or add to _LORAPLUS_EXEMPT "
            "with the reason."
        )

    def test_the_exemption_list_stays_earned(self):
        """An exemption that stops being true is worse than none. Each exempt
        module must still exist, must still build a PEFT model (else it does not
        belong in a PEFT-builder exemption), and must NOT already call the attach
        (if it does, it is wired and should leave the set)."""
        for name in _LORAPLUS_EXEMPT:
            path = _TRAINER_DIR / name
            assert path.is_file(), f"_LORAPLUS_EXEMPT names {name}, which no longer exists"
            code = _code_without_comments(path.read_text(encoding="utf-8"))
            assert _builds_peft(path), (
                f"{name} is exempt but no longer builds a PEFT model; drop it from "
                "_LORAPLUS_EXEMPT."
            )
            assert not (_ATTACH_CALL.search(code) or _INJECT_CALL.search(code)), (
                f"{name} now wires LoRA+ (attach or inject); remove it from "
                "_LORAPLUS_EXEMPT — it is wired, not exempt."
            )

    def test_the_test_files_an_exemption_names_exist(self):
        """A reason that points at a test file is only evidence while that file
        exists; a rename would otherwise leave the pointer stale without a word."""
        repo_root = _TRAINER_DIR.parents[2]
        for name, reason in _LORAPLUS_EXEMPT.items():
            for rel in re.findall(r"tests/[\w/]+\.py", reason):
                assert (repo_root / rel).is_file(), (
                    f"the _LORAPLUS_EXEMPT reason for {name} names {rel}, which "
                    "does not exist; point it at the file that pins the refusal."
                )

    def test_the_patterns_would_catch_the_unwired_shape(self):
        """A scanner nobody has watched fail is indistinguishable from a broken
        one. All three detectors are exercised here, comments included."""
        assert _BUILDS_PEFT.search("        self.model = get_peft_model(model, cfg)")
        assert not _BUILDS_PEFT.search("        # get_peft_model is applied elsewhere")
        assert _ATTACH_CALL.search("attach_loraplus_optimizer(self.trainer, tcfg)")
        assert not _ATTACH_CALL.search("# attach_loraplus_optimizer is needed here")
        assert _INJECT_CALL.search("opt = build_loraplus_optimizer(model, args, tcfg)")
        assert not _INJECT_CALL.search("# build_loraplus_optimizer builds it")

    def test_the_patterns_would_catch_a_trainer_that_hands_trl_a_peft_config(self):
        """online_dpo.py never calls get_peft_model: TRL applies the adapter from
        the peft_config it is handed. That shape builds a LoRA adapter too, so
        the scan must count it, and an unwired one must fail the scan."""
        delegated = (
            "self.peft_config = build_lora_config(tcfg)\n"
            "self.trainer = OnlineDPOTrainer(\n"
            "    model=self.model, args=args, peft_config=self.peft_config,\n"
            ")\n"
        )
        assert _source_builds_peft(delegated)
        assert not _wires_source(delegated)
        assert _wires_source(delegated + "attach_loraplus_optimizer(self.trainer, tcfg)\n")
        # The attribute assignment alone, a prose mention, and an explicit
        # peft_config=None do not apply an adapter.
        assert not _source_builds_peft("self.peft_config = None\n")
        assert not _source_builds_peft("# TRL applies peft_config=... itself\n")
        assert not _source_builds_peft("Trainer(model=m, peft_config=None)\n")

    def test_online_dpo_counts_as_a_peft_builder(self):
        """The live instance of the delegated shape: until #745's second round
        the scan could not see it, so it silently ignored loraplus_lr_ratio."""
        assert _builds_peft(_TRAINER_DIR / "online_dpo.py")

    def test_the_mlx_trainer_counts_as_a_peft_builder(self):
        """#1324: mlx-lm applies LoRA through linear_to_lora_layers, not peft.
        Before the scan knew that call, mlx_sft.py was neither wired nor exempt
        and backend: mlx ignored loraplus_lr_ratio without a test noticing."""
        assert _BUILDS_PEFT.search("        linear_to_lora_layers(model, n, cfg)")
        assert not _source_builds_peft("        # linear_to_lora_layers(model) runs later")
        assert _builds_peft(_TRAINER_DIR / "mlx_sft.py")

    def test_a_comment_mentioning_the_call_does_not_satisfy_it(self):
        """The positive check reads code, not prose — otherwise the note that
        explains the wiring would pass without calling it."""
        source = "self.trainer = SFTTrainer()  # attach_loraplus_optimizer(x)\n"
        assert not _ATTACH_CALL.search(_code_without_comments(source))


class TestPpoWiresLoraPlusByInjectionNotAttach:
    """PPO is the one trainer that must wire LoRA+ by constructor injection.

    Its ``trl.experimental`` trainer builds the optimizer and scheduler eagerly
    in ``__init__``, so the post-construction ``attach_loraplus_optimizer`` the
    other preference/RL wrappers use would leave the scheduler bound to the
    discarded default optimizer — the B group would train at a flat ``lr*ratio``
    with warmup and decay never reaching it. The behavioural proof lives in
    ``tests/test_issue745_ppo_loraplus_scheduler.py``; this pins the source
    shape so a refactor cannot quietly swap PPO back onto the attach path.
    """

    _PPO = _TRAINER_DIR / "ppo.py"

    def _code(self) -> str:
        return _code_without_comments(self._PPO.read_text(encoding="utf-8"))

    def test_ppo_builds_the_optimizer_for_injection(self):
        assert _INJECT_CALL.search(self._code()), (
            "ppo.py must build the LoRA+ optimizer with build_loraplus_optimizer "
            "before constructing the trainer."
        )

    def test_ppo_hands_the_optimizer_to_the_constructor(self):
        """The injection is only correct if the built optimizer actually reaches
        the constructor as optimizers=(opt, None); building it and dropping it
        would be worse than the attach it replaced."""
        code = self._code()
        # The built optimizer goes into an `optimizers` tuple on trainer_kwargs;
        # accept either `optimizers=(...)` or `trainer_kwargs["optimizers"] = (...)`.
        assert re.search(r"\(\s*loraplus_optimizer\s*,\s*None\s*\)", code) and (
            "optimizers" in code
        ), (
            "ppo.py builds a LoRA+ optimizer but does not pass it as "
            "optimizers=(loraplus_optimizer, None) to the PPOTrainer constructor."
        )

    def test_ppo_does_not_use_the_post_construction_attach(self):
        """The attach is the bug on PPO's eager-scheduler shape (#745). If it
        reappears here, the scheduler goes back to the wrong optimizer."""
        assert not _ATTACH_CALL.search(self._code()), (
            "ppo.py calls attach_loraplus_optimizer(), which binds the scheduler "
            "to the wrong optimizer on PPO's eager-construction trainer. Use "
            "build_loraplus_optimizer + optimizers=(opt, None) instead."
        )

    def test_the_live_experimental_branch_injects_the_optimizer(self):
        """The whole-file check above is necessary but not sufficient: ppo.py has
        more than one construction branch, and a file-wide regex is satisfied by
        an ``optimizers=(loraplus_optimizer, None)`` sitting in ANY of them. Only
        the ``if is_experimental:`` branch runs on supported trl (``trl>=0.29``
        always imports ``trl.experimental.ppo`` so ``_import_ppo_classes`` returns
        ``is_experimental=True``, and the transitional ``elif`` / legacy ``else``
        branches are unreachable there). So the injection that actually executes
        must live in the experimental branch; deleting it there while a dead
        branch keeps a copy would silently disable LoRA+ on every real PPO run
        yet leave the whole-file check green.

        Parsing the AST and inspecting that branch's body specifically closes
        that gap, which is the exact per-branch pin the #745 review asked for.
        """
        tree = ast.parse(self._PPO.read_text(encoding="utf-8"))
        branches = _if_is_experimental_bodies(tree)
        assert branches, (
            "ppo.py no longer has an `if is_experimental:` construction branch; "
            "the live PPO path can no longer be located to pin the injection."
        )
        assert any(_hands_optimizer_to_constructor(body) for body in branches), (
            "the live `if is_experimental:` branch in ppo.py does not hand the "
            "pre-built LoRA+ optimizer to the constructor as "
            "optimizers=(loraplus_optimizer, None). On trl >=0.29 this is the "
            "only branch that runs, so LoRA+ would be silently disabled on PPO "
            "even if a dead sibling branch still carries the injection."
        )

    def test_the_branch_pin_would_catch_an_empty_live_branch(self):
        """Guard the guard: prove ``_hands_optimizer_to_constructor`` reads the
        branch it is handed and is not vacuously true, so the pin above cannot
        rot into an always-pass.
        """
        wired = ast.parse(
            "if is_experimental:\n"
            "    trainer_kwargs = {'model': self.model}\n"
            "    if loraplus_optimizer is not None:\n"
            "        trainer_kwargs['optimizers'] = (loraplus_optimizer, None)\n"
            "    self.trainer = cls(**trainer_kwargs)\n"
        )
        unwired = ast.parse(
            "if is_experimental:\n"
            "    trainer_kwargs = {'model': self.model}\n"
            "    self.trainer = cls(**trainer_kwargs)\n"
        )
        kwarg_form = ast.parse(
            "if is_experimental:\n"
            "    self.trainer = cls(optimizers=(loraplus_optimizer, None))\n"
        )
        assert _hands_optimizer_to_constructor(_if_is_experimental_bodies(wired)[0])
        assert _hands_optimizer_to_constructor(_if_is_experimental_bodies(kwarg_form)[0])
        assert not _hands_optimizer_to_constructor(
            _if_is_experimental_bodies(unwired)[0]
        )


class TestUnlearnExemptionIsEarned:
    """The sole exemption (``unlearn``) is earned by a hard refusal, not silence.

    ``unlearn.py`` builds a PEFT model but drives its own ``torch.optim.AdamW``,
    so ``attach_loraplus_optimizer`` cannot reach it. #745's rule: refuse
    ``loraplus_lr_ratio`` for ``task='unlearn'`` at config parse, so a user is
    told rather than trained without the LoRA+ rates they asked for.
    """

    def _unlearn_config(self, *, loraplus: bool):
        """A valid ``task='unlearn'`` config (unlearn_method + forget set), with
        or without ``loraplus_lr_ratio`` — so the only variable is the option
        under test, not the unrelated unlearn-shape requirements."""
        from soup_cli.config.schema import SoupConfig

        training = {"unlearn_method": "npo"}
        if loraplus:
            training["loraplus_lr_ratio"] = 16.0
        return SoupConfig(
            base="hf-internal-testing/tiny-random-gpt2",
            task="unlearn",
            data={"train": "forget.jsonl", "forget_set": "forget.jsonl"},
            training=training,
        )

    def test_unlearn_loraplus_is_refused_at_config_parse(self):
        """task='unlearn' + loraplus_lr_ratio must raise at parse, naming the
        option, rather than parsing and silently ignoring it. The config is
        otherwise valid, so a pass here means the refusal fired (not the
        unrelated unlearn_method/forget requirements)."""
        with pytest.raises(ValueError, match="loraplus_lr_ratio"):
            self._unlearn_config(loraplus=True)

    def test_unlearn_without_loraplus_still_parses(self):
        """The refusal is scoped to the option, not the task: an otherwise
        identical unlearn config that does not set loraplus_lr_ratio parses."""
        self._unlearn_config(loraplus=False)

    def test_loraplus_is_allowed_on_a_wired_task(self):
        """Control: the same option on a Trainer-based task (sft) parses fine, so
        the refusal is specific to unlearn and not a blanket loraplus ban."""
        from soup_cli.config.schema import SoupConfig

        SoupConfig(
            base="hf-internal-testing/tiny-random-gpt2",
            task="sft",
            data={"train": "t.jsonl"},
            training={"loraplus_lr_ratio": 16.0},
        )


class TestLoraPlusRefusedWhereNoLoraBTrains:
    """#745: tasks that accept ``loraplus_lr_ratio`` but never train a LoRA B
    matrix refuse it at parse, the way unlearn does, instead of ignoring it or
    failing after the base model loads."""

    _BASE = "hf-internal-testing/tiny-random-gpt2"

    _NO_LORA_B = {
        # full fine-tune, no adapter
        "prm": ({}, _BASE),
        # adapters loaded frozen, only the routing gate trains
        "moe_lora_routing": ({"mole_task_adapters": ["a1", "a2"]}, _BASE),
        # full fine-tune unless the task's own LoRA flag is on
        "classifier": ({"num_labels": 2}, _BASE),
        "reranker": ({"num_labels": 1}, _BASE),
        "cross_encoder": ({"num_labels": 1}, _BASE),
        "asr": ({}, "openai/whisper-tiny"),
    }

    def _config(self, task, **training):
        from soup_cli.config.schema import SoupConfig

        extra, base = self._NO_LORA_B[task]
        return SoupConfig(
            base=base,
            task=task,
            data={"train": "t.jsonl"},
            training={**extra, **training},
        )

    @pytest.mark.parametrize("task", sorted(_NO_LORA_B))
    def test_loraplus_is_refused_at_parse(self, task):
        with pytest.raises(ValueError, match="loraplus_lr_ratio needs a trainable LoRA"):
            self._config(task, loraplus_lr_ratio=16.0)

    @pytest.mark.parametrize("task", sorted(_NO_LORA_B))
    def test_the_same_config_without_loraplus_parses(self, task):
        """Control: the config is otherwise valid, so the refusal above is the
        ratio's, not some unrelated requirement of the task."""
        self._config(task)

    @pytest.mark.parametrize(
        "task, flag",
        [
            ("classifier", "classifier_lora"),
            ("reranker", "classifier_lora"),
            ("cross_encoder", "classifier_lora"),
            ("asr", "asr_lora"),
        ],
    )
    def test_loraplus_parses_once_the_task_trains_a_lora_adapter(self, task, flag):
        """These tasks do wire LoRA+ (they are in the scan): it is only the
        default full fine-tune that has no B to speed up."""
        self._config(task, loraplus_lr_ratio=16.0, **{flag: True})

    @pytest.mark.parametrize("task, flag", [("classifier", "classifier_lora"), ("asr", "asr_lora")])
    def test_a_zero_rank_adapter_is_still_refused(self, task, flag):
        """The trainers apply LoRA only for the flag AND lora.r > 0."""
        with pytest.raises(ValueError, match="loraplus_lr_ratio needs a trainable LoRA"):
            self._config(task, loraplus_lr_ratio=16.0, lora={"r": 0}, **{flag: True})


class TestLoraPlusRefusedWithVera:
    """#745: VeRA trains ``vera_lambda_b`` / ``vera_lambda_d`` scaling vectors,
    not LoRA A/B matrices. peft's ``create_loraplus_optimizer`` puts every one
    of them in the ``lr * ratio`` groups and leaves group A empty, so the whole
    adapter would train at ``ratio`` times the learning rate. Refuse it at
    parse, as ``use_lorafa`` already refuses VeRA."""

    _TASKS = [
        "sft", "pretrain", "dpo", "kto", "orpo", "simpo", "ipo", "bco",
        "grpo", "ppo", "reward_model", "online_dpo",
    ]
    # What each task needs to parse at all, so the refusal tested is the ratio's.
    _EXTRA = {"online_dpo": {"reward_model": "hf-internal-testing/tiny-random-gpt2"}}

    def _config(self, task, *, use_vera, **training):
        from soup_cli.config.schema import SoupConfig

        return SoupConfig(
            base="hf-internal-testing/tiny-random-gpt2",
            task=task,
            data={"train": "t.jsonl"},
            training={
                "lora": {"use_vera": use_vera},
                **self._EXTRA.get(task, {}),
                **training,
            },
        )

    @pytest.mark.parametrize("task", _TASKS)
    def test_loraplus_with_vera_is_refused_at_parse(self, task):
        with pytest.raises(ValueError, match="use_vera"):
            self._config(task, use_vera=True, loraplus_lr_ratio=16.0)

    @pytest.mark.parametrize("task", _TASKS)
    def test_vera_without_loraplus_parses(self, task):
        """Control: VeRA alone is valid, so the refusal is the ratio's."""
        self._config(task, use_vera=True)

    @pytest.mark.parametrize("task", _TASKS)
    def test_loraplus_without_vera_parses(self, task):
        """Control: the ratio alone is valid on these tasks."""
        self._config(task, use_vera=False, loraplus_lr_ratio=16.0)