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.

105 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

"""Shared diffusion LoRA helpers and family registry; pure helpers avoid torch, so tests need no GPU."""

from __future__ import annotations

import json
import math
import os
import random
import re
import time
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any, Callable, Optional

from core._torchao_stub import (
    alias_torchao_fqn_to_config,
    hide_xformers_built_for_another_torch,
    install_torchao_windows_rocm_stub,
    install_xformers_windows_rocm_stub,
    is_stubbed,
    torch_is_rocm,
)
from core.inference.diffusion_families import _FAMILIES as _IMAGE_REGISTRY
from core.inference.diffusion_families import (
    detect_family,
    detect_family_for_pick,
    supported_family_names,
    trainable_family_names,
)
from core.inference.diffusion_torchao_patches import install_torchao_int_mm_patch
from core.inference.video_families import _FAMILIES as _VIDEO_REGISTRY
from core.inference.video_families import detect_video_family, supported_video_family_names
from utils.paths.path_utils import drop_appledouble_metadata, is_appledouble_metadata

from core.training.diffusion_samples import SAMPLE_FAMILIES, validate_sample_settings

# The trainers run in a spawned child that imports diffusers itself, so the inference-side install does not carry
# over. Both import this module first.
install_xformers_windows_rocm_stub()
hide_xformers_built_for_another_torch()
install_torchao_windows_rocm_stub()
alias_torchao_fqn_to_config()
# Same child: the DiT trainer's int8 base-weight quantisation goes through torchao.
install_torchao_int_mm_patch()

# Attention projections shared by SDXL and DiTs (diffusers/kohya); families may override.
DEFAULT_LORA_TARGETS: tuple[str, ...] = ("to_k", "to_q", "to_v", "to_out.0")

# piecewise_constant excluded: it needs a step_rules string the trainers never pass; accepting it would free GPU residents, then crash in the child.
_LR_SCHEDULERS: frozenset[str] = frozenset(
    {
        "linear",
        "cosine",
        "cosine_with_restarts",
        "polynomial",
        "constant",
        "constant_with_warmup",
    }
)

# fp32 RoPE/embedder overflow fp16 here. Keep in sync with the DiT trainer's specs.
_FORCE_BF16_FAMILIES: frozenset[str] = frozenset(
    {
        "qwen-image",
        "z-image",
        "krea-2",
        "flux.2-klein",
        "flux.2-dev",
        "ltx-2",
        "wan2.2-ti2v-5b",
        "minimax-h3",
    }
)

# ``VideoFamily.trainable``; every name in it MUST resolve through get_trainer, and a video base outside it is refused
# by name.
TRAINABLE_VIDEO_FAMILIES: frozenset[str] = frozenset(f.name for f in _VIDEO_REGISTRY if f.trainable)

# flow_shift defaults to auto to reproduce inference sigmas; dynamic-shift schedulers and MiniMax-H3 otherwise train unshifted.
AUTO_FLOW_SHIFT_FAMILIES: frozenset[str] = frozenset({"qwen-image", "ltx-2", "minimax-h3"})

# Video latents are allocated on the family's spatial compression grid, so a training resolution off that grid
# silently changes the latent geometry. LTX-2: 32x VAE; Wan2.2-TI2V-5B: 16x VAE x 2x2 patch.
_VIDEO_RESOLUTION_MULTIPLE = 32

_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".bmp"}
_CAPTION_EXTS = (".txt", ".caption")
# diffusers' canonical single-file LoRA name, so load_lora_weights(dir) finds it.
DEFAULT_LORA_FILENAME = "pytorch_lora_weights.safetensors"

# Rejected by name for a clear error instead of a mid-run crash.
_NON_TRAINABLE_RESIDUAL_TOKENS = frozenset({"sd3", "pixart", "sana", "lumina", "cogview"})
_NON_TRAINABLE_RESIDUAL_PHRASES = ("stable-diffusion-3", "hunyuan-dit")

EventCb = Callable[[dict[str, Any]], None]
# Falsy = keep going; truthy = stop (True, or a dict that may carry save=False to cancel without saving a partial adapter).
StopCb = Callable[[], Any]


def _all_trainable_family_names() -> tuple[str, ...]:
    """Kept separate so video checkpoints never route to the image pipeline; this view unions both."""
    video = tuple(n for n in supported_video_family_names() if n in TRAINABLE_VIDEO_FAMILIES)
    return tuple(trainable_family_names()) + video


def _trainable_family_spec(name: str) -> Any:
    """Searches both registries; detect_family alone misses video families, which callers would skip."""
    from core.inference.diffusion_families import detect_family

    key = str(name or "").strip().lower()
    fam = detect_family("", override = key)
    if fam is not None:
        return fam
    return detect_video_family("", override = key)


def _refuse_untrainable_video_family(name: str) -> None:
    """Refuses untrainable video families by name; otherwise they fall through to the SDXL trainer."""
    trainable = ", ".join(sorted(TRAINABLE_VIDEO_FAMILIES))
    raise ValueError(
        f"'{name}' is a video model Unsloth can't train yet. Video LoRA training currently "
        f"supports: {trainable}. {_trainable_hint()}"
    )


def _component_only_repos() -> dict[str, tuple[str, str, str]]:
    """Component-only repos from registry tables, not names; video prequant repos read apart from the image table; a registered base never appears."""
    from core.inference.diffusion_families import detect_family
    from core.inference.video_families import detect_video_family

    image_families = [detect_family("", override = n) for n in supported_family_names()]
    video_families = [detect_video_family("", override = n) for n in supported_video_family_names()]
    components: dict[str, tuple[str, str, str]] = {}
    bases: set[str] = set()
    for fam, is_video in [(f, False) for f in image_families] + [(f, True) for f in video_families]:
        if fam is None:
            continue
        for attr in ("base_repo", "deploy_base_repo"):
            repo = getattr(fam, attr, None)
            if repo:
                bases.add(str(repo).strip().lower())
        bases.update(str(r).strip().lower() for r in getattr(fam, "train_base_repos", ()) if r)
        # Image repos are full pipelines (bases); video repos are pre-quantized denoisers (components).
        for table in ("prequant_repos", "prequant_variant_repos"):
            for row in getattr(fam, table, ()) or ():
                if not row:
                    continue
                repo = str(row[-1]).strip().lower()
                if is_video:
                    components.setdefault(repo, (fam.name, "transformer", str(fam.base_repo)))
                else:
                    bases.add(repo)
        for row in getattr(fam, "te_prequant_repos", ()):
            components.setdefault(
                str(row[2]).strip().lower(), (fam.name, str(row[1]), str(fam.base_repo))
            )
        for row in getattr(fam, "te_prequant_variant_repos", ()):
            components.setdefault(str(row[3]).strip().lower(), (fam.name, str(row[2]), str(row[0])))
    return {repo: hit for repo, hit in components.items() if repo not in bases}


def _refuse_component_only_repo(base_model: str) -> None:
    """Refused in the preflight, before GPU residents are freed; a component repo cannot be a base."""
    hit = _component_only_repos().get(str(base_model or "").strip().lower())
    if hit is None:
        return
    family, component, base_repo = hit
    raise ValueError(
        f"'{base_model}' is the pre-cast {component} checkpoint for the '{family}' family, not a "
        f"full model: it ships no model_index.json and no pipeline, so it cannot be a training "
        f"base. Train from '{base_repo}' instead."
    )


def _trainable_hint() -> str:
    """A user-facing hint listing the families Unsloth can train today. Always names SDXL explicitly
    so the message is actionable even as more families become trainable."""
    names = ", ".join(_all_trainable_family_names()) or "sdxl"
    return (
        f"Trainable families right now: {names} "
        f"(for example the SDXL base stabilityai/stable-diffusion-xl-base-1.0). "
        f"Other families can load LoRAs but not train them yet."
    )


def _assert_family_pipeline_available(fam: Any) -> None:
    """Asserts the pipeline class exists before GPU residents are freed; probe family_probe_class, not fam.pipeline_class (generic on modular families)."""
    from core.inference.diffusion_families import (
        assert_pipeline_class_available,
        family_probe_class,
    )
    assert_pipeline_class_available(family_probe_class(fam), fam.name)


def training_pipeline_import_error(resolved_family: str) -> Optional[str]:
    """Strict, unlike inference: the child shares this interpreter, so a failed import is final; return the message so the route maps it to a 400."""
    from core.inference.diffusion_families import (
        assert_pipeline_class_available,
        family_probe_class,
    )

    # Video families are invisible to detect_family; returning None defers the strict gate to the child.
    fam = _trainable_family_spec(resolved_family)
    if fam is None:
        return None
    try:
        assert_pipeline_class_available(family_probe_class(fam), fam.name, strict = True)
    except ValueError as e:
        return str(e)
    return None


def resolve_trainable_family(base_model: str, model_family: Optional[str] = None) -> str:
    family = _resolve_trainable_family(base_model, model_family)
    from core.inference.video_families import assert_ltx_pick_supported

    assert_ltx_pick_supported(family, base_model)
    return family


def _resolve_trainable_family(base_model: str, model_family: Optional[str] = None) -> str:
    """Resolve the trainer family for a base model, or raise ValueError with a clear reason.
    Positive resolution, before anything is downloaded: a ``.gguf`` name can never be a training
    base; an explicit ``model_family`` must name a registry family, and that family must be
    trainable; otherwise the family is detected from the base-model name, and a KNOWN but
    non-trainable family is rejected; a name resolving to no registry family but matching a known
    non-trainable architecture (SD3 / PixArt / ...) is rejected; a resolved family whose pipeline
    class the installed diffusers lacks is rejected, so an environment too old for the pick fails
    here rather than in the child, after the GPU residents are gone; and an unclassifiable custom
    name/path falls through to the SDXL trainer (backwards compatible -- a wrong pick still fails
    cleanly later in from_pretrained). No pipeline assert on that last path: there is no family
    spec to read a class off, and SDXL's pipeline predates every diffusers in play."""
    name = str(base_model or "").strip().lower()
    # GGUF (.gguf or *-GGUF repo) is inference-only, so training refuses it; modular_model_index.json also counts as a local base.
    local = Path(base_model).expanduser() if base_model else None
    is_local_diffusers = bool(
        local
        and (
            (local / "model_index.json").is_file() or (local / "modular_model_index.json").is_file()
        )
    )
    if name.endswith(".gguf") or ("gguf" in name and not is_local_diffusers):
        raise ValueError(
            f"'{base_model}' is a GGUF checkpoint/repo, which can't be a training base "
            f"(training needs the full diffusers model). {_trainable_hint()}"
        )
    # A component checkpoint is never a base, whatever family the name matches; must precede every family branch, including an explicit model_family override.
    _refuse_component_only_repo(base_model)
    # Like component-only refusal: the family is trainable, but the loader cannot open this repo.
    _refuse_ltx23_training_base(base_model)
    # Before either branch: model_family="ltx-2" must not train a local LTX-2.5 pipeline.
    from core.inference.video_families import assert_local_pipeline_not_ltx25

    assert_local_pipeline_not_ltx25(base_model)
    if model_family and str(model_family).strip():
        key = str(model_family).strip().lower()
        fam = detect_family("", override = key)
        if fam is None:
            # Not an image family: it may still name a VIDEO family, which lives in its own registry.
            vid = detect_video_family("", override = key)
            if vid is not None:
                if vid.name not in TRAINABLE_VIDEO_FAMILIES:
                    _refuse_untrainable_video_family(vid.name)
                _assert_family_pipeline_available(vid)
                return vid.name
            known = ", ".join(supported_family_names() + supported_video_family_names())
            raise ValueError(f"Unknown model_family {model_family!r}. Known families: {known}.")
        if not fam.trainable:
            raise ValueError(f"'{fam.name}' models can't be trained yet. {_trainable_hint()}")
        _assert_family_pipeline_available(fam)
        return fam.name

    fam = detect_family_for_pick(base_model)
    if fam is not None:
        if not fam.trainable:
            raise ValueError(
                f"'{base_model}' looks like a {fam.name} model, which isn't trainable yet. "
                f"{_trainable_hint()}"
            )
        _assert_family_pipeline_available(fam)
        return fam.name

    # Checked here rather than first so an image repo the picker already claims keeps its existing route.
    vid = detect_video_family(base_model)
    if vid is None and is_local_diffusers:
        from core.inference.video_families import local_cosmos3_pipeline_family
        local_family = local_cosmos3_pipeline_family(base_model)
        vid = detect_video_family("", override = local_family) if local_family else None
    if vid is not None:
        if vid.name not in TRAINABLE_VIDEO_FAMILIES:
            _refuse_untrainable_video_family(vid.name)
        _assert_family_pipeline_available(vid)
        return vid.name

    condensed = re.sub(r"[^a-z0-9]+", "-", name)
    hit = next(
        (p for p in _NON_TRAINABLE_RESIDUAL_PHRASES if p in condensed),
        None,
    ) or next(
        (t for t in condensed.split("-") if t in _NON_TRAINABLE_RESIDUAL_TOKENS),
        None,
    )
    if hit:
        raise ValueError(
            f"'{base_model}' looks like a {hit} model, which isn't trainable. {_trainable_hint()}"
        )
    # Unknown custom name / local path: default to the SDXL trainer (unchanged behaviour).
    return "sdxl"


def repo_is_prequantized(base_model: str) -> bool:
    """Name heuristic: a bnb-4bit repo is already quantized, so it serves nf4 only, not dense precisions."""
    name = str(base_model or "").lower()
    return "bnb-4bit" in name or "-4bit" in name or "int4" in name or "nf4" in name


def _module_is_torchao_stub(module: Any) -> bool:
    """Detects the Windows-ROCm torchao stub via its _unsloth_stub sentinel; find_spec alone cannot tell."""
    if module is None:
        return False
    sentinel = getattr(module, "_unsloth_stub", None)
    if sentinel is None:
        return False
    try:
        from core._torchao_stub import _STUB_SENTINEL
    except Exception:  # noqa: BLE001 -- stub module absent -> nothing to compare against
        return False
    return sentinel is _STUB_SENTINEL


def has_functional_torchao() -> bool:
    """Needs a functional import, not find_spec: the ROCm stub passes find_spec yet quantizes nothing. Never raises."""
    try:
        import importlib

        quant = importlib.import_module("torchao.quantization")
        if _module_is_torchao_stub(quant):
            return False
        # The symbols the int8 path actually imports must exist on the real module.
        return hasattr(quant, "Int8WeightOnlyConfig") and hasattr(quant, "quantize_")
    except Exception:  # noqa: BLE001 -- torchao absent / broken build -> treat as unavailable
        return False


def train_precision_modes() -> tuple[list[str], str]:
    """(supported base_precision modes, recommended pick) for the current machine: nf4 always works;
    bf16/auto need a bf16-capable CUDA GPU (Ampere+); int8/mxfp8 additionally need a
    FUNCTIONAL torchao (their explicit paths import it with no fallback, and the Windows-ROCm
    stub only looks installed). fp8 needs sm89+ (torch's own _scaled_mm); mxfp8 needs the Blackwell tensor cores
    (sm100+) its cuBLAS kernels target. The dense modes all train in bf16 compute, which the DiT
    trainer requires, so a non-bf16 CUDA GPU (T4/V100/RTX 20xx) is offered only nf4 -- otherwise
    /info would advertise a start that evicts resident models and then fails the trainer's bf16
    guard. Never raises."""
    modes = ["nf4"]
    recommended = "nf4"
    try:
        import torch
        if flow_bf16_trainable():
            modes.append("bf16")
            # ROCm capability values are gfx versions, not the NVIDIA SM levels checked below.
            rocm = torch_is_rocm()
            torchao_ok = has_functional_torchao() and not rocm
            if torchao_ok:
                modes.append("int8")
            major, minor = torch.cuda.get_device_capability()
            if not rocm and (major, minor) >= (8, 9) and hasattr(torch, "float8_e4m3fn"):
                modes.append("fp8")
            if torchao_ok and (major, minor) >= (10, 0):
                modes.append("mxfp8")
            modes.append("auto")
            recommended = "auto"
    except Exception:  # noqa: BLE001 -- no torch / probe failure -> nf4 only
        pass
    return modes, recommended


def get_trainer(family: str) -> Callable[..., str]:
    """Return the training entrypoint for ``family``. Imports the trainer module lazily so this
    shared module stays free of the heavy trainer imports (and any import cycle)."""
    key = (family or "sdxl").strip().lower()
    if key == "sdxl":
        from core.training.diffusion_lora_trainer import run_diffusion_lora_training
        return run_diffusion_lora_training
    if key in _DIT_TRAIN_FAMILIES:
        from core.training.diffusion_dit_trainer import run_dit_lora_training
        return run_dit_lora_training
    # MiniMax-H3 denoises video and audio jointly on coupled schedules, so it fits no _FamilySpec seam.
    if key == "minimax-h3":
        from core.training.diffusion_h3_trainer import run_h3_lora_training
        return run_h3_lora_training
    raise ValueError(f"No trainer is registered for family {family!r}.")


# Train UI starting points, not hard limits; absent families use DiffusionLoraConfig defaults.
FAMILY_TRAIN_DEFAULTS: dict[str, dict[str, Any]] = {
    "sdxl": {"lora_rank": 16, "learning_rate": 1e-4, "resolution": 1024},
    # Plain "constant" ignores lr_warmup_steps, so warmup defaults must use a warmup-capable scheduler.
    "flux.1": {
        "lora_rank": 16,
        "learning_rate": 1e-4,
        "resolution": 512,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    "qwen-image": {
        "lora_rank": 16,
        "learning_rate": 5e-5,
        "resolution": 512,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    "z-image": {"lora_rank": 16, "learning_rate": 1e-4, "resolution": 768},
    # The Krea 2 authors' recommended starting point (their DreamBooth defaults): rank/alpha 32, lr 3e-4, 512px.
    "krea-2": {"lora_rank": 32, "learning_rate": 3e-4, "resolution": 512},
    # Upstream FLUX.2 DreamBooth uses rank 16 / lr 1e-4; uniform timestep draws need a warmup ramp.
    "flux.2-klein": {
        "lora_rank": 16,
        "learning_rate": 1e-4,
        "resolution": 512,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    "flux.2-dev": {
        "lora_rank": 16,
        "learning_rate": 1e-4,
        "resolution": 512,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    # Resolution must be a multiple of 32 (LTX-2 VAE spatial compression).
    "ltx-2": {
        "lora_rank": 32,
        "learning_rate": 1e-4,
        "resolution": 512,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    # DiffSynth-Studio's Wan recipe; 704 is TI2V-5B's native short edge.
    "wan2.2-ti2v-5b": {
        "lora_rank": 32,
        "learning_rate": 1e-4,
        "resolution": 704,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
    },
    # resolution is the canvas SHORT EDGE and 768 is what the released checkpoint generates on; rank 16 not 32 because
    # the adapter also serves the audio rows through one shared stack.
    "minimax-h3": {
        "lora_rank": 16,
        "learning_rate": 1e-4,
        "resolution": 768,
        "lr_scheduler": "constant_with_warmup",
        "lr_warmup_steps": 20,
        "train_batch_size": 1,
    },
}


def train_defaults(family: str) -> dict[str, Any]:
    """Recommended starting hyperparameters for ``family`` (empty if unknown)."""
    return dict(FAMILY_TRAIN_DEFAULTS.get((family or "").strip().lower(), {}))


# Display labels (the registries' ``label``) + a short VRAM/access note per trainable family, surfaced by the Train UI
# so users pick a base with realistic expectations.
_FAMILY_LABELS = {fam.name: fam.label for fam in (*_IMAGE_REGISTRY, *_VIDEO_REGISTRY) if fam.label}
# params is the transformer size (SDXL is not quoted that way); note is the rest.
_FAMILY_TRAIN_SPECS: dict[str, dict[str, Any]] = {
    "sdxl": {"params": "", "qlora_vram_gb": 12, "gated": False, "note": "The lightest option."},
    "flux.1": {"params": "12B", "qlora_vram_gb": 16, "gated": True, "note": ""},
    "qwen-image": {
        "params": "20B",
        "qlora_vram_gb": 24,
        "gated": False,
        "note": "The heaviest option.",
    },
    "z-image": {"params": "6B", "qlora_vram_gb": 12, "gated": False, "note": ""},
    "krea-2": {
        "params": "12B",
        "qlora_vram_gb": 18,
        "gated": False,
        "note": "Trains on Krea-2-Raw, runs on Turbo.",
    },
    "flux.2-klein": {"params": "4B", "qlora_vram_gb": 10, "gated": False, "note": ""},
    "flux.2-dev": {"params": "32B", "qlora_vram_gb": 28, "gated": True, "note": ""},
    # Run peak (34.8 GB on B200) includes the resident Gemma3-12B conditioner.
    "ltx-2": {
        "params": "19B",
        "qlora_vram_gb": 36,
        "gated": False,
        "note": "Video: trains a style LoRA on still images.",
    },
    # Measured on a B200 (nf4, 704px, rank 32): run peaks at 11.6 GB during the one-time UMT5-XXL encode.
    "wan2.2-ti2v-5b": {
        "params": "5B",
        "qlora_vram_gb": 12,
        "gated": False,
        "note": "Video: trains a style LoRA on still images.",
    },
    # Measured on a B200: the loop peaks near 44 GB, but a 20-step run peaked at 77.76 GB with the 63 GiB Qwen3-VL
    # conditioner resident, so 72 sizes users onto a card that OOMs later.
    "minimax-h3": {
        "params": "31B",
        "qlora_vram_gb": 80,
        "gated": False,
        "note": "Video with sound: trains on clips that have a soundtrack.",
    },
}
# Keys are canonical upstream ids; family_train_infos adds mirror aliases the client overlays.
_BASE_TRAIN_SPECS: dict[str, dict[str, Any]] = {
    "black-forest-labs/flux.2-klein-base-9b": {
        "params": "9B",
        # The bf16 text encoder alone is 16.4 GB, so leave room for VAE and runtime rather than the 4B floor.
        "qlora_vram_gb": 18,
    },
}
_GATED_NOTE = "Gated: needs its license and your HF token."


def _family_vram_note(name: str, overrides: Optional[dict[str, Any]] = None) -> str:
    """The one-line note, rebuilt from the spec for clients that predate the chip fields."""
    spec = _FAMILY_TRAIN_SPECS.get(name)
    if not spec:
        return ""
    spec = {**spec, **(overrides or {})}
    gb = spec["qlora_vram_gb"]
    head = f"{spec['params']}, QLoRA by default (~{gb} GB+)." if spec["params"] else f"~{gb} GB+."
    tail = [t for t in (_GATED_NOTE if spec["gated"] else "", spec["note"]) if t]
    return " ".join([head, *tail])


# Flow-matching DiT families (diffusion_dit_trainer) need bf16 on CUDA; SDXL has its own path.
_DIT_TRAIN_FAMILIES = frozenset(
    {
        "flux.1",
        "qwen-image",
        "z-image",
        "krea-2",
        "flux.2-klein",
        "flux.2-dev",
        "ltx-2",
        "wan2.2-ti2v-5b",
    }
)
# Kept separate so the DiT-specific levers (compile, the shared sigma table) do not follow.
_FLOW_TRAIN_FAMILIES = _DIT_TRAIN_FAMILIES | {"minimax-h3"}


def effective_mixed_precision(cfg: Any) -> str:
    """Precision the trainer actually runs in; pre-Ampere bf16 becomes fp16, so checkpoints record that."""
    import torch  # noqa: PLC0415 -- keep the import list light for the training subprocess

    requested = str(getattr(cfg, "mixed_precision", "") or "")
    if str(getattr(cfg, "resolved_family", "") or "").strip().lower() in _FLOW_TRAIN_FAMILIES:
        # Record the device-resolved precision, not the request, or identical resumes mismatch.
        return "bf16" if resolve_train_device() in ("cuda", "xpu") else "no"
    if not torch.cuda.is_available():
        return "no"
    if requested == "bf16" and not native_bf16_supported():
        return "fp16"
    return requested


def native_bf16_supported() -> bool:
    """Checks NVIDIA compute capability >= 8 (torch counts emulated bf16 pre-Ampere); ROCm by gfx arch. Never raises."""
    try:
        import torch

        if not torch.cuda.is_available():
            return False
        from core.inference.rocm_bf16 import is_rocm_torch, rocm_bf16_supported

        if is_rocm_torch(torch):
            return rocm_bf16_supported(torch)
        return torch.cuda.get_device_capability()[0] >= 8
    except Exception:  # noqa: BLE001 -- no torch / probe failure -> treat as unsupported
        return False


def flow_bf16_trainable() -> bool:
    """Whether the bf16-only flow trainers (DiT, MiniMax-H3; no fp16 path) may run on this GPU. ROCm targets
    without native bf16 (RDNA2-and-older / Vega) still run bf16 through fp32 emulation, slowly, so they stay
    admitted as before the arch gate; only pre-Ampere NVIDIA and ``UNSLOTH_STUDIO_ROCM_BF16=0`` are refused. Never raises."""
    if native_bf16_supported():
        return True
    try:
        import torch
        from core.inference.rocm_bf16 import rocm_bf16_forced_off

        if rocm_bf16_forced_off():
            return False
        return bool(
            torch.cuda.is_available() and torch_is_rocm() and torch.cuda.is_bf16_supported()
        )
    except Exception:  # noqa: BLE001 -- no torch / probe failure -> treat as unsupported
        return False


def resolve_train_device() -> str:
    """CUDA first, then XPU, else CPU; a probe that raises must fall through rather than kill the run."""
    import torch  # noqa: PLC0415 -- keep the import list light for the training subprocess

    def _probe(module) -> bool:
        try:
            fn = getattr(module, "is_available", None)
            return bool(fn()) if callable(fn) else False
        except Exception:  # noqa: BLE001 -- probe failure -> this accelerator is not usable
            return False

    if _probe(getattr(torch, "cuda", None)):
        return "cuda"
    if _probe(getattr(torch, "xpu", None)):
        return "xpu"
    return "cpu"


def xpu_native_bf16_probe() -> Optional[bool]:
    """Ask with including_emulation=False (default says True for every XPU); None means unknown, never False, which would refuse hosts. Never raises."""
    import torch  # noqa: PLC0415

    fn = getattr(getattr(torch, "xpu", None), "is_bf16_supported", None)
    if not callable(fn):
        return None
    try:
        return bool(fn(including_emulation = False)) or _xpu_is_known_bf16_part(torch)
    except TypeError:
        # A torch predating the including_emulation parameter: its answer is the only one there is.
        try:
            return bool(fn())
        except Exception:  # noqa: BLE001 -- unprobeable
            return None
    except Exception:  # noqa: BLE001 -- unprobeable
        return None


def _xpu_is_known_bf16_part(torch) -> bool:
    """Whether the current XPU is an Arc / Data Center part, read from its PCI id. Never raises.

    The SYCL runtime answers ``has_bfloat16_conversions`` through libocloc (the intel-ocloc
    package, which the torch-xpu wheels do not ship), so without it the strict probe is False on
    every device, BMG and PVC included; with it, True on every device. The PCI id does not depend
    on the install."""
    try:
        props = torch.xpu.get_device_properties()
        device_id = getattr(props, "device_id", None)
        if isinstance(device_id, int) and device_id > 0:
            from utils.hardware.hardware import _is_intel_xpu_pci_id
            return _is_intel_xpu_pci_id(device_id)
        # A torch without device_id: the marketing name is the only signal left.
        return bool(re.search(r"\bArc\b|Data Center GPU", str(getattr(props, "name", "") or "")))
    except Exception:  # noqa: BLE001 -- unprobeable keeps the strict answer
        return False


def native_bf16_supported_xpu() -> bool:
    """``xpu_native_bf16_probe`` collapsed for the trainer child, which runs ON the device: there an
    unprobeable capability is a refusal, matching ``native_bf16_supported`` on the CUDA side."""
    return xpu_native_bf16_probe() is True


def bf16_unsupported_reason(resolved_family: str) -> Optional[str]:
    """Covers every flow-matching trainer, not just DiT, so the route fails before evicting residents; CPU-only and SDXL exempt. Never raises."""
    if (resolved_family or "").strip().lower() not in _FLOW_TRAIN_FAMILIES:
        return None
    try:
        import torch
        if torch.cuda.is_available() and not flow_bf16_trainable():
            return (
                "This trainer requires a bfloat16-capable GPU (Ampere or newer); this CUDA "
                "device does not support bf16. Train the DiT families on a newer GPU."
            )
        # Reject an emulation-only XPU before eviction; an unprobeable one is left to the child.
        if resolve_train_device() == "xpu" and xpu_native_bf16_probe() is False:
            return (
                "This trainer requires a bfloat16-capable GPU; this XPU device does not "
                "support bf16 natively. Train the DiT families on a newer GPU."
            )
    except Exception:  # noqa: BLE001 -- torch probe failure must not block a start
        return None
    return None


def dit_accelerator_missing_reason(resolved_family: str) -> Optional[str]:
    """Reason a DiT family cannot train on this host at all, else None. Never raises. nf4 is not a
    CPU fallback: the 4-bit base load goes through diffusers' bitsandbytes quantizer, which needs
    the model on CUDA or XPU. Without this gate such a host accepts the default nf4 start, evicts
    the resident Images pipeline, downloads the text encoders, and only then dies in the child.
    Apple MPS is not enough: resolve_train_device trains there on the CPU, and the quantizer
    refuses a CPU device_map. SDXL keeps its own fp32-on-CPU path; MiniMax-H3 is covered too,
    since it loads its denoiser through the same quantizer."""
    if (resolved_family or "").strip().lower() not in _FLOW_TRAIN_FAMILIES:
        return None
    try:
        import torch
        def probe(owner: Any) -> bool:
            # Probe each accelerator separately: torch.mps.is_available() needs torch 2.5+.
            try:
                fn = getattr(owner, "is_available", None)
                return bool(fn()) if callable(fn) else False
            except Exception:  # noqa: BLE001
                return False

        if probe(torch.cuda) or probe(getattr(torch, "xpu", None)):
            return None
    except Exception:  # noqa: BLE001 -- probe failure must not block a start
        return None
    return (
        "Training the DiT families needs an NVIDIA, AMD or Intel GPU: even the 4-bit (nf4) base "
        "load requires CUDA, ROCm or XPU, and this host has none (Apple Silicon included). Train "
        "SDXL here, or use a GPU machine."
    )


def bitsandbytes_optimizer_supported() -> bool:
    """False only on Intel XPU, where bitsandbytes 8-bit updates route to Triton and assert
    (construction succeeds, so try/except misses it); keyed on get_device(), NOT
    torch.xpu.is_available()."""
    try:
        from utils.hardware import DeviceType, get_device
        return get_device() != DeviceType.XPU
    except Exception:  # noqa: BLE001 -- a probe failure must not block a start
        return True


def _is_bnb_8bit_optimizer_key(name: Optional[str]) -> bool:
    return isinstance(name, str) and name.startswith("bitsandbytes.") and "8bit" in name


def recorded_optimizer_class(cfg: Any, identity: Any) -> Optional[str]:
    """Optimizer class of the bundle being resumed, else None; never raises (restore_resume_state reports errors)."""
    if not getattr(cfg, "resume_from_checkpoint", None):
        return None
    try:
        from core.training.diffusion_checkpoint import preflight_resume, read_checkpoint
        path, _step = preflight_resume(
            cfg.resume_from_checkpoint, identity = identity, target_steps = cfg.train_steps
        )
        value = (read_checkpoint(path) or {}).get("optimizer_class")
    except Exception:  # noqa: BLE001
        return None
    return value if isinstance(value, str) else None


def resume_steps_left(cfg: Any, identity: Any) -> int:
    """Optimizer steps this process will run: the target minus the resumed bundle's step; the target when unknown."""
    if not getattr(cfg, "resume_from_checkpoint", None):
        return cfg.train_steps
    try:
        from core.training.diffusion_checkpoint import preflight_resume
        _path, step = preflight_resume(
            cfg.resume_from_checkpoint, identity = identity, target_steps = cfg.train_steps
        )
    except Exception:  # noqa: BLE001 -- restore_resume_state reports the real problem
        return cfg.train_steps
    return max(0, cfg.train_steps - int(step))


class TrainingPeakMemory:
    """Training-only peak: ``pause`` banks it before a preview round, ``resume`` resets after, so VAE decode is excluded."""

    def __init__(self, device: str):
        self.device = device
        self.banked = 0.0
        reset_training_peak_memory(device)

    def pause(self) -> None:
        self.banked = max(self.banked, training_peak_memory_gb(self.device))

    def resume(self) -> None:
        reset_training_peak_memory(self.device)

    def gb(self) -> float:
        return max(self.banked, training_peak_memory_gb(self.device))


def _accelerator_memory_module(device: str) -> Any:
    import torch

    module = getattr(torch, device, None) if device in ("cuda", "xpu") else None
    if module is None or not hasattr(module, "max_memory_allocated"):
        return None
    return module


def reset_training_peak_memory(device: str) -> None:
    """Start the reported peak at the loop: the load / encode peak is higher and not the training cost."""
    module = _accelerator_memory_module(device)
    if module is not None:
        try:
            module.reset_peak_memory_stats()
        except Exception:  # noqa: BLE001 -- reporting only
            pass


def training_peak_memory_gb(device: str) -> float:
    """Peak allocated GB since reset_training_peak_memory on CUDA / XPU; 0.0 where unmeasured (reported as None)."""
    module = _accelerator_memory_module(device)
    if module is None:
        return 0.0
    try:
        return round(module.max_memory_allocated() / 1e9, 2)
    except Exception:  # noqa: BLE001 -- reporting only
        return 0.0


GC_MODE_ENV = "UNSLOTH_DIFFUSION_GC_MODE"
GC_EVERY_N_ENV = "UNSLOTH_DIFFUSION_GC_EVERY_N"


def enable_diffusion_gradient_checkpointing(model: Any, mode: Optional[str] = None) -> str:
    """ "plain" checkpoints every block, "partial" every Nth; selective / CPU-offloaded were slower or diverged under regional compile."""
    mode = (mode or os.environ.get(GC_MODE_ENV, "") or "plain").strip().lower()
    every_n = 1
    if mode == "partial":
        try:
            every_n = max(2, int(os.environ.get(GC_EVERY_N_ENV, "") or 2))
        except ValueError:
            every_n = 2
    try:
        from unsloth_zoo.block_checkpointing import enable_block_gradient_checkpointing
    except ImportError:
        import functools

        import torch.utils.checkpoint as _ckpt

        model.enable_gradient_checkpointing(
            gradient_checkpointing_func = functools.partial(_ckpt.checkpoint, use_reentrant = False)
        )
        return "plain"
    enable_block_gradient_checkpointing(model, every_n_blocks = every_n)
    return "partial" if every_n > 1 else "plain"


def make_lora_optimizer(
    params: list,
    lr: float,
    resume_optimizer_class: Optional[str] = None,
) -> Any:
    """torch AdamW (AdamW8bit step() syncs per parameter); AdamW8bit only to resume its own bundle, never on XPU (dies at step())."""
    import torch

    if os.environ.get("UNSLOTH_DIFFUSION_FP32_OPTIM", "") in ("1", "true"):
        return torch.optim.AdamW(params, lr = lr)
    if _is_bnb_8bit_optimizer_key(resume_optimizer_class) and bitsandbytes_optimizer_supported():
        try:
            import bitsandbytes as bnb
            return bnb.optim.AdamW8bit(params, lr = lr)
        except Exception:  # noqa: BLE001 -- restore_resume_state then names the mismatch
            pass
    if torch.cuda.is_available():
        try:
            return torch.optim.AdamW(params, lr = lr, fused = True)
        except Exception:  # noqa: BLE001 -- fused unsupported on this build/device
            pass
    return torch.optim.AdamW(params, lr = lr)


def training_precision_preflight_error(resolved_family: str, base_precision: str) -> Optional[str]:
    """Reason the requested DiT precision cannot run on this host, else None -- checked by the start
    route BEFORE evicting resident GPU workloads (the trainer's own checks fire only in the
    child, after eviction). Every gate mirrors one in _resolve_base_precision, so a doomed run is
    rejected before teardown: the bf16-GPU requirement; no accelerator at all (which covers nf4
    too); the dense precisions needing CUDA; the torchao precisions against a ROCm build, which
    clears the stub test and hands the sm100 floor an AMD gfx version; explicit int8 needing a
    FUNCTIONAL torchao; explicit fp8/mxfp8 against the Windows-ROCm stub; explicit fp8 needing
    sm89+ and mxfp8 Blackwell. Add a gate there, add it here. Never raises."""
    reason = bf16_unsupported_reason(resolved_family)
    if reason:
        return reason
    # No accelerator at all: every DiT precision is out, nf4 included.
    reason = dit_accelerator_missing_reason(resolved_family)
    if reason:
        return reason
    fam = (resolved_family or "").strip().lower()
    mode = (base_precision or "").strip().lower()
    if fam in _FLOW_TRAIN_FAMILIES and mode in ("bf16", "int8", "fp8", "mxfp8"):
        # Dense precisions need CUDA; reject here so residents are not evicted first.
        try:
            import torch
            has_cuda = torch.cuda.is_available()
        except Exception:  # noqa: BLE001 -- no torch / probe failure -> treat as no CUDA
            has_cuda = False
        if not has_cuda:
            return (
                f"base_precision={mode!r} needs a CUDA GPU; this host has none. "
                "Use base_precision='nf4' or 'auto'."
            )
        # Reject before eviction; _resolve_base_precision repeats this in the child.
        if mode in ("int8", "fp8", "mxfp8") and torch_is_rocm():
            return (
                f"base_precision={mode!r} is a torchao NVIDIA tensor-core path (int8 sm_80+, fp8 "
                "sm_89+, mxfp8 sm_100+) and this is a ROCm/AMD GPU. Use 'nf4', 'bf16', or 'auto'."
            )
        if mode == "int8" and not has_functional_torchao():
            return (
                "base_precision='int8' needs a functional torchao install; this host's torchao is "
                "missing or the non-functional Windows-ROCm stub. Use 'nf4', 'bf16', or 'auto'."
            )
        # Mirrors the child's fp8/mxfp8 stub guard so a doomed run is refused before eviction. Not
        # has_functional_torchao(): that probes int8's symbols.
        if mode in ("fp8", "mxfp8") and is_stubbed("torchao"):
            return (
                f"base_precision={mode!r} is not available on this host: torchao is the "
                "non-functional Windows-ROCm stub. Use 'nf4', 'bf16', or 'auto'."
            )
        # mxfp8 needs sm100+, fp8 needs sm89+; checked here so a stale client fails before eviction.
        if mode == "fp8":
            try:
                import torch
                fp8_ok = torch.cuda.get_device_capability() >= (8, 9)
            except Exception:  # noqa: BLE001 -- probe failure -> treat as unsupported, fail fast
                fp8_ok = False
            if not fp8_ok:
                return (
                    "base_precision='fp8' needs an Ada, Hopper or Blackwell (sm89+) GPU; this GPU is "
                    "older. Use base_precision='bf16', 'int8', 'nf4', or 'auto'."
                )
        if mode == "mxfp8":
            try:
                import torch
                blackwell = torch.cuda.get_device_capability() >= (10, 0)
            except Exception:  # noqa: BLE001 -- probe failure -> treat as unsupported, fail fast
                blackwell = False
            if not blackwell:
                return (
                    "base_precision='mxfp8' needs a Blackwell (sm100+) GPU; this GPU is older. "
                    "Use base_precision='bf16', 'int8', 'nf4', or 'auto'."
                )
    return None


def _training_fetch_repo(base: str, token: Optional[str] = None) -> str:
    from core.inference.diffusion_families import (
        _is_local_path,
        mirror_repo,
        prefer_ungated_mirror,
        upstream_is_gated,
    )

    fetched = prefer_ungated_mirror(base, token)
    # Anonymous training ignores partial caches of gated upstreams.
    if (
        not token
        and upstream_is_gated(base)
        and not _is_local_path(base)
        and not os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip()
    ):
        fetched = mirror_repo(base) or fetched
    return fetched


def _training_mirror_access_specs(repo: str, note: str = "") -> dict[str, dict[str, Any]]:
    from core.inference.diffusion_families import mirror_repo, upstream_is_gated

    mirror = mirror_repo(repo)
    if not mirror or not upstream_is_gated(repo):
        return {}
    facts = {}
    for shown in (repo, mirror):
        fetched = _training_fetch_repo(shown)
        gated = upstream_is_gated(fetched)
        explanation = (
            f"Downloads from {fetched}. The original model license still applies."
            if not gated
            else ""
        )
        facts[shown] = {
            "gated": gated,
            "note": " ".join(part for part in (note, explanation) if part),
        }
    return facts


def family_train_infos() -> list[dict[str, Any]]:
    """Lists both registries; drops a family whose pipeline class is missing, since start refuses it."""
    from core.inference.diffusion_families import family_pipeline_available, mirror_repo
    from core.inference.diffusion_transformer_quant import _family_train_denied

    dit_modes, dit_recommended = train_precision_modes()
    infos: list[dict[str, Any]] = []
    for name in _all_trainable_family_names():
        fam = _trainable_family_spec(name)
        if fam is None or not family_pipeline_available(fam):
            continue
        # A video family carries no train_base_repos/deploy_base_repo: its own base repo is the one training base.
        repos = list(getattr(fam, "train_base_repos", ()) or ()) or [fam.base_repo]
        # Use _FLOW_TRAIN_FAMILIES: H3 also supports base_precision.
        is_dit = name in _FLOW_TRAIN_FAMILIES
        # Non-bf16 CUDA fails all DiT preflights, so offer no precision; drop schemes the bar holds back.
        dit_block = (
            bf16_unsupported_reason(name) or dit_accelerator_missing_reason(name)
            if is_dit
            else None
        )
        # H3 compiles under the auto rule; the panel control stays DiT / SDXL only.
        supports_compile = bool(not dit_block) and name in _DIT_TRAIN_FAMILIES
        if not is_dit or dit_block:
            fam_modes: list[str] = []
        else:
            fam_modes = [m for m in dit_modes if not _family_train_denied(name, m)]
        spec = _FAMILY_TRAIN_SPECS.get(name, {})
        deploy_bases: dict[str, str] = {}
        base_specs: dict[str, dict[str, Any]] = {}
        for repo in repos:
            base_spec = _BASE_TRAIN_SPECS.get(str(repo).strip().lower())
            if not base_spec:
                continue
            base_specs[repo] = dict(base_spec)
            repo_mirror = mirror_repo(repo)
            if repo_mirror:
                base_specs[repo_mirror] = dict(base_spec)
        for repo in repos:
            for shown, access in _training_mirror_access_specs(
                repo, str(spec.get("note", ""))
            ).items():
                base_specs[shown] = {**base_specs.get(shown, {}), **access}
        default_facts = base_specs.get(repos[0], {})
        for training_repo, inference_repo in getattr(fam, "deploy_base_repos", ()):
            deploy_bases[training_repo] = inference_repo
            # Mirror-id bases pair like vendor ids; return the inference mirror so Deploy stays ungated.
            training_mirror = mirror_repo(training_repo)
            if training_mirror:
                deploy_bases[training_mirror] = mirror_repo(inference_repo) or inference_repo
        infos.append(
            {
                "name": name,
                "label": _FAMILY_LABELS.get(name, name),
                "default_base": repos[0],
                "base_repos": repos,
                "defaults": train_defaults(name),
                "vram_note": dit_block or _family_vram_note(name, default_facts),
                # Dropped on a dit_block, since vram_note then carries the reason.
                "params": "" if dit_block else spec.get("params", ""),
                "qlora_vram_gb": None if dit_block else spec.get("qlora_vram_gb"),
                "gated": False
                if dit_block
                else bool(default_facts.get("gated", spec.get("gated", False))),
                "note": "" if dit_block else default_facts.get("note", spec.get("note", "")),
                "precision_modes": fam_modes,
                "recommended_precision": "nf4" if (not is_dit or dit_block) else dit_recommended,
                # Compile: SDXL and DiT trainers, except where the GPU lacks bf16 or the trainer cannot compile.
                "supports_compile": supports_compile or name == "sdxl",
                # save_steps is refused for checkpointless families, so hide the control.
                "supports_checkpoints": name not in CHECKPOINTLESS_FAMILIES,
                # sample_every is refused elsewhere, so the panel offers "Sample every" only where it runs.
                "supports_samples": name in SAMPLE_FAMILIES,
                "supports_bucketing": name not in UNBUCKETED_FAMILIES,
                # The images loader refuses video bases, so the panel offers no Deploy to Create for these.
                "is_video": name in TRAINABLE_VIDEO_FAMILIES,
                # A batch > 1 is REFUSED for a family whose forward covers one packed sequence, so leaving the control
                # unrestricted turns a reasonable 2 into a rejected Start with nothing to say why.
                "max_train_batch_size": 1 if name in SINGLE_SEQUENCE_FAMILIES else None,
                # Krea trains on Raw but previews adapters on Turbo; None elsewhere (and never for a video family).
                "deploy_base": getattr(fam, "deploy_base_repo", None),
                # Families with several train/deploy pairs cannot use the scalar above.
                "deploy_bases": deploy_bases,
                # Dropped on a dit_block so the hardware reason in vram_note is shown instead.
                "base_specs": {} if dit_block else base_specs,
            }
        )
    return infos


@dataclass
class DiffusionLoraConfig:
    """Everything a diffusion LoRA training run needs. Only ``base_model`` / ``data_dir`` /
    ``output_dir`` are required; the rest have sensible defaults."""

    base_model: str
    data_dir: str
    output_dir: str
    # Caption for images lacking their own; required when the dataset has no captions.jsonl or sidecars.
    instance_prompt: Optional[str] = None
    resolution: int = 1024
    train_steps: int = 500
    # 0 = disabled (train for train_steps). Above 0 it overrides train_steps with num_epochs full passes.
    num_epochs: int = 0
    learning_rate: float = 1e-4
    train_batch_size: int = 1
    gradient_accumulation_steps: int = 1
    lora_rank: int = 16
    lora_alpha: Optional[int] = None
    lora_dropout: float = 0.0
    lora_target_modules: tuple[str, ...] = DEFAULT_LORA_TARGETS
    seed: int = 42
    mixed_precision: str = "bf16"
    snr_gamma: Optional[float] = 5.0
    gradient_checkpointing: bool = True
    max_grad_norm: float = 1.0
    lr_scheduler: str = "constant"
    lr_warmup_steps: int = 0
    center_crop: bool = False
    # Off by default: flipping mirrors text, logos and one-sided features in half the samples.
    random_flip: bool = False
    bucketing: Optional[bool] = None
    caption_column: str = "text"
    adapter_name: str = "default"
    hf_token: Optional[str] = None
    # normalized() sets a byte-identical mirror to load; base_model stays canonical for resume.
    fetch_base_model: Optional[str] = None
    # cache_variants crop/flip draws are frozen per image; the per-step VAE sampling noise is preserved.
    cache_latents: bool = True
    cache_variants: int = 4
    # Latent stats and caption embeddings, keyed by hash; a warm cache skips VAE and text encoders.
    cond_cache_dir: Optional[str] = None
    # DiT LoRA EMA decay; 0.0 disables; otherwise a warmup-ramped EMA is exported under ema/.
    ema_decay: float = 0.0
    # Regional torch.compile of blocks: off, on, or auto (auto only for dense, non-bitsandbytes bases).
    compile_transformer: str = "auto"
    # TF32 matmuls + cudnn autotuning for the run. Near-lossless; disable for strict bit-reproducibility A/Bs.
    enable_tf32: bool = True
    # "nf4" | "bf16" | "int8" | "fp8" | "auto"; non-nf4 needs a dense base.
    base_precision: str = "nf4"
    # None: model's own schedule ("auto" for AUTO_FLOW_SHIFT_FAMILIES); a number is the effective shift on unshifted u.
    flow_shift: Optional[Any] = None
    # Per-sample chance of using an empty prompt instead of the caption (CFG dropout); 0.0 disables.
    cfg_dropout: float = 0.0
    # Per-sample loss weight by timestep: none is unweighted MSE, bell is Gaussian normalized to mean 1.
    weighting_scheme: str = "none"
    # How often to emit a progress event (in optimizer steps).
    log_every: int = 1
    # 0 writes no periodic checkpoints; stop-and-save writes one, so Resume stays available.
    save_steps: int = 0
    # How many checkpoint-<N> bundles to keep in the output dir; 0 keeps every one.
    save_total_limit: int = 2
    # 0 disables. Not part of the resume identity: previews never touch the training math.
    sample_every: int = 0
    # Empty uses the instance prompt, else the first caption.
    sample_prompts: tuple[str, ...] = ()
    # The run's output_dir, or one of its checkpoint-<N> directories; the start route resolves and validates it before
    # the trainer spawns.
    resume_from_checkpoint: Optional[str] = None
    # Family override; None detects from base_model; normalized() sets resolved_family to the trainer.
    model_family: Optional[str] = None
    resolved_family: str = "sdxl"

    def normalized(self) -> "DiffusionLoraConfig":
        """Returns a validated copy and raises ValueError on an untrainable request; coerces string and blank inputs from the Unsloth config path."""
        resolved_family = resolve_trainable_family(self.base_model, self.model_family)
        if self.train_steps < 1:
            raise ValueError("train_steps must be >= 1")
        if not 0 <= int(self.num_epochs) <= 1000:
            raise ValueError("num_epochs must be between 0 and 1000 (0 uses train_steps)")
        if self.train_batch_size < 1:
            raise ValueError("train_batch_size must be >= 1")
        if self.gradient_accumulation_steps < 1:
            raise ValueError("gradient_accumulation_steps must be >= 1")
        if self.lora_rank < 1:
            raise ValueError("lora_rank must be >= 1")
        if self.lora_alpha is not None and self.lora_alpha < 1:
            raise ValueError(
                "lora_alpha must be >= 1 (a zero/negative alpha scales the adapter to nothing)"
            )
        if self.resolution < 64 or self.resolution % 8 != 0:
            raise ValueError("resolution must be a multiple of 8 and >= 64")
        # Video VAEs compress 32x, so off-grid sizes silently change latent geometry; refuse before eviction.
        if (
            resolved_family in TRAINABLE_VIDEO_FAMILIES
            and self.resolution % _VIDEO_RESOLUTION_MULTIPLE != 0
        ):
            raise ValueError(
                f"'{resolved_family}' trains at a resolution that is a multiple of "
                f"{_VIDEO_RESOLUTION_MULTIPLE} (its VAE compresses space by that factor); "
                f"got {self.resolution}."
            )
        if self.mixed_precision not in ("bf16", "fp16", "no"):
            raise ValueError("mixed_precision must be one of bf16 / fp16 / no")
        # torch.manual_seed only accepts int64/uint64; catch wider values before eviction.
        if not -(2**63) <= int(self.seed) <= 2**64 - 1:
            raise ValueError("seed must fit in torch's 64-bit range")
        # Refuse fp16 for a bf16-only DiT family up front, before evicting resident models.
        if self.mixed_precision == "fp16" and resolved_family in _FORCE_BF16_FAMILIES:
            raise ValueError(
                f"'{resolved_family}' LoRA training requires bf16: fp16 overflows its fp32 "
                f"RoPE / embedder internals. Set mixed precision to bf16."
            )
        if str(self.lr_scheduler) not in _LR_SCHEDULERS:
            raise ValueError(
                f"lr_scheduler must be one of {', '.join(sorted(_LR_SCHEDULERS))}; "
                f"got {self.lr_scheduler!r}"
            )
        # Do not rewrite the scheduler: it is checkpoint identity, and rewriting it makes legacy (constant, warmup > 0) runs unresumable.
        try:
            lr_warmup_steps = int(self.lr_warmup_steps or 0)
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"lr_warmup_steps must be a whole number, got {self.lr_warmup_steps!r}"
            ) from exc
        if lr_warmup_steps < 0:
            raise ValueError("lr_warmup_steps must be >= 0")
        if not 1 <= int(self.cache_variants) <= 16:
            raise ValueError("cache_variants must be between 1 and 16")
        try:
            save_steps = int(self.save_steps or 0)
            save_total_limit = int(self.save_total_limit or 0)
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"save_steps / save_total_limit must be whole numbers, got "
                f"{self.save_steps!r} / {self.save_total_limit!r}"
            ) from exc
        if save_steps < 0:
            raise ValueError("save_steps must be >= 0 (0 disables periodic checkpoints)")
        if save_total_limit < 0:
            raise ValueError("save_total_limit must be >= 0 (0 keeps every checkpoint)")
        # A blank resume path means "fresh run", not the outputs root.
        resume_from_checkpoint = (
            str(self.resume_from_checkpoint).strip()
            if self.resume_from_checkpoint is not None
            else ""
        ) or None
        # H3 has no resume bundle, so accepting resume silently started fresh and overwrote the outputs.
        if resolved_family in CHECKPOINTLESS_FAMILIES:
            if resume_from_checkpoint:
                raise ValueError(
                    f"resume_from_checkpoint is not supported for {resolved_family}: its trainer "
                    f"writes no checkpoint bundle, so there is nothing to continue from and the "
                    f"run would silently start over and overwrite its output. Start a fresh run."
                )
            if save_steps:
                raise ValueError(
                    f"save_steps is not supported for {resolved_family}: its trainer writes no "
                    f"checkpoint bundle. Leave it at 0; the adapter is still saved at the end."
                )
        try:
            ema_decay = float(self.ema_decay or 0.0)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"ema_decay must be a number, got {self.ema_decay!r}") from exc
        # decay = 1.0 would freeze the shadow forever.
        if not 0.0 <= ema_decay < 1.0:
            raise ValueError("ema_decay must be in [0, 1); 0 disables the EMA adapter")
        sample_every, sample_prompts = validate_sample_settings(
            self.sample_every, self.sample_prompts, resolved_family
        )
        # A blank cond_cache_dir (the Unsloth default when unset) means "off", not cwd.
        cond_cache_dir = (
            str(self.cond_cache_dir).strip() if self.cond_cache_dir is not None else ""
        ) or None
        compile_transformer = str(self.compile_transformer or "auto").strip().lower()
        if compile_transformer not in ("off", "on", "auto"):
            raise ValueError("compile_transformer must be one of off / on / auto")
        base_precision = str(self.base_precision or "nf4").strip().lower()
        if base_precision not in ("nf4", "bf16", "int8", "fp8", "mxfp8", "auto"):
            raise ValueError("base_precision must be one of nf4 / bf16 / int8 / fp8 / mxfp8 / auto")
        # base_precision is DiT-only: dense-mode gates skip other families; mode-name check runs for all.
        if resolved_family != "sdxl" and base_precision in ("bf16", "int8", "fp8", "mxfp8"):
            if repo_is_prequantized(self.base_model):
                raise ValueError(
                    f"base_precision={base_precision!r} needs a dense base repo, but "
                    f"'{self.base_model}' is already bitsandbytes-quantized. Pick the "
                    f"family's dense (bf16) base repo for this mode, or use nf4/auto."
                )
            if self.mixed_precision != "bf16":
                raise ValueError(
                    f"base_precision={base_precision!r} trains in bf16 compute; set "
                    f"mixed_precision to bf16."
                )
            # H3 shares linears across modalities, so the measured fp8 module filter does not apply.
            if resolved_family == "minimax-h3" and base_precision in ("fp8", "mxfp8"):
                raise ValueError(
                    f"base_precision={base_precision!r} is not supported for minimax-h3: its "
                    f"packed sequence mixes video, audio and text through one set of linears, "
                    f"so the activation range fp8 was measured against does not apply. Use "
                    f"'nf4', 'int8', 'bf16', or 'auto'."
                )
            # Use the stricter _family_train_denied, not _family_denied (render-only schemes).
            from core.inference.diffusion_transformer_quant import _family_train_denied

            if _family_train_denied(resolved_family, base_precision):
                raise ValueError(
                    f"base_precision={base_precision!r} is not validated for training "
                    f"{resolved_family}. Use 'nf4', 'int8', 'bf16', or 'auto'."
                )
        flow_shift = self.flow_shift
        if flow_shift is None and resolved_family in AUTO_FLOW_SHIFT_FAMILIES:
            flow_shift = "auto"
        if isinstance(flow_shift, str):
            flow_shift = flow_shift.strip().lower()
            if flow_shift != "auto":
                try:
                    flow_shift = float(flow_shift)
                except ValueError as exc:
                    raise ValueError(
                        f"flow_shift must be a positive number or 'auto', got {self.flow_shift!r}"
                    ) from exc
        if flow_shift is not None and not isinstance(flow_shift, str):
            flow_shift = float(flow_shift)
            # JSON accepts 1e309 (inf), which would poison every sampled sigma.
            if not math.isfinite(flow_shift) or flow_shift <= 0:
                raise ValueError(
                    "flow_shift must be a finite number > 0 (1.0 disables the shift), or 'auto'"
                )
        try:
            cfg_dropout = float(self.cfg_dropout or 0.0)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"cfg_dropout must be a number, got {self.cfg_dropout!r}") from exc
        if not 0.0 <= cfg_dropout <= 1.0:
            raise ValueError("cfg_dropout must be between 0 and 1")
        weighting_scheme = str(self.weighting_scheme or "none").strip().lower()
        if weighting_scheme not in ("none", "bell"):
            raise ValueError("weighting_scheme must be one of none / bell")
        # Gamma <= 0 zeroes or inverts the min-SNR weight and silently trains a bad loss; None disables.
        if self.snr_gamma is not None and float(self.snr_gamma) <= 0:
            raise ValueError("snr_gamma must be > 0, or null to disable min-SNR weighting")
        # learning_rate can arrive as a string from the Unsloth config path.
        try:
            learning_rate = float(self.learning_rate)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"learning_rate must be a number, got {self.learning_rate!r}") from exc
        if learning_rate <= 0:
            raise ValueError("learning_rate must be > 0")
        alpha = self.lora_alpha if self.lora_alpha is not None else self.lora_rank
        targets = tuple(self.lora_target_modules) or DEFAULT_LORA_TARGETS
        # Resume with unset targets keeps the recorded ones, so changing a family default never strands old runs.
        if resume_from_checkpoint and resolved_family != "sdxl" and targets == DEFAULT_LORA_TARGETS:
            from core.training.diffusion_checkpoint import recorded_resume_targets
            targets = recorded_resume_targets(resume_from_checkpoint) or targets
        # A blank Hub token must load anonymously, not as an explicit empty credential.
        token = self.hf_token.strip() if isinstance(self.hf_token, str) else self.hf_token
        if resolved_family == "sdxl":
            fetch_base_model = self.base_model
        else:
            fetch_base_model = _training_fetch_repo(self.base_model, token or None)
        # Blank caption_column means "text", matching the start route's fingerprint.
        caption_column = str(self.caption_column or "").strip() or "text"
        bucketing = None if self.bucketing is None else _coerce_bool(self.bucketing)
        if resolved_family in UNBUCKETED_FAMILIES:
            bucketing = False
        elif bucketing is None and not resume_from_checkpoint:
            bucketing = True
        return replace(
            self,
            learning_rate = learning_rate,
            lr_warmup_steps = lr_warmup_steps,
            lora_alpha = alpha,
            lora_target_modules = targets,
            max_grad_norm = float(self.max_grad_norm),
            hf_token = token or None,
            fetch_base_model = fetch_base_model,
            caption_column = caption_column,
            num_epochs = int(self.num_epochs),
            cache_variants = int(self.cache_variants),
            bucketing = bucketing,
            save_steps = save_steps,
            save_total_limit = save_total_limit,
            sample_every = sample_every,
            sample_prompts = sample_prompts,
            resume_from_checkpoint = resume_from_checkpoint,
            cond_cache_dir = cond_cache_dir,
            ema_decay = ema_decay,
            compile_transformer = compile_transformer,
            base_precision = base_precision,
            flow_shift = flow_shift,
            cfg_dropout = cfg_dropout,
            weighting_scheme = weighting_scheme,
            resolved_family = resolved_family,
        )


def resolve_train_steps(
    cfg: "DiffusionLoraConfig",
    n_images: int,
    image_paths: Optional[list[str]] = None,
) -> int:
    """The effective optimizer-step count for a run. When ``cfg.num_epochs`` is set (> 0), one epoch
    is one full pass over the dataset in optimizer steps -- ceil(ceil(N / batch) / grad_accum) --
    so the run is ``num_epochs`` such passes, capped at 100000. Bucketed runs (``image_paths``)
    count batches per bucket: a bucket pads its last batch within itself. With ``num_epochs == 0`` the explicit ``cfg.train_steps`` is used unchanged."""
    if cfg.num_epochs > 0:
        batch = max(1, cfg.train_batch_size)
        batches = math.ceil(n_images / batch)
        canvases = plan_image_canvases(cfg, image_paths)[0] if image_paths is not None else None
        if canvases is not None:
            batches = sum(math.ceil(len(g) / batch) for g in bucket_groups(canvases).values())
        steps_per_epoch = max(1, math.ceil(batches / max(1, cfg.gradient_accumulation_steps)))
        return min(100000, cfg.num_epochs * steps_per_epoch)
    return cfg.train_steps


class PermutationBatchSampler:
    """Yields batch indices as consecutive slices of a reshuffled permutation of ``range(n)``, so
    every index is visited exactly once per cycle before any repeats -- an epoch-style full pass
    instead of the with-replacement draw that leaves part of a small dataset unseen at low step
    counts. When a cycle is exhausted the order is reshuffled from the run's own ``rng`` so the
    index stream stays seed-deterministic and each cycle differs. Both trainers share this so the
    SDXL ``_next_batch`` path and the DiT per-sample draw select indices the same way; step count
    and batch shapes are unchanged."""

    def __init__(self, n: int, rng: random.Random) -> None:
        if n <= 0:
            raise ValueError("PermutationBatchSampler needs at least one item")
        self._n = n
        self._rng = rng
        self._order: list[int] = []
        self._pos = 0

    def _reshuffle(self) -> None:
        self._order = list(range(self._n))
        self._rng.shuffle(self._order)
        self._pos = 0

    def next_batch(self, k: int) -> list[int]:
        # k may exceed n; the permutation refills across cycles so exactly k indices return.
        out: list[int] = []
        while len(out) < k:
            if self._pos >= len(self._order):
                self._reshuffle()
            take = min(k - len(out), len(self._order) - self._pos)
            out.extend(self._order[self._pos : self._pos + take])
            self._pos += take
        return out

    def state_dict(self) -> dict[str, Any]:
        """Stores the cycle order, not just the position: the rng alone cannot reproduce a cycle in
        progress."""
        return {"n": self._n, "order": list(self._order), "pos": int(self._pos)}

    def load_state_dict(self, state: Optional[dict[str, Any]]) -> bool:
        """True when restored; False for a different dataset size, since ignoring that silently reorders and skips images."""
        if not isinstance(state, dict) or int(state.get("n") or 0) != self._n:
            return False
        order = state.get("order")
        if not isinstance(order, (list, tuple)):
            return False
        try:
            restored = [int(i) for i in order]
        except (TypeError, ValueError):
            return False
        # A shortened or duplicate-carrying order is in range and plausible, so the cycle reshuffles early or serves
        # the same image twice with the RNG already past the original draw.
        if restored and sorted(restored) != list(range(self._n)):
            return False
        self._order = restored
        try:
            pos = int(state.get("pos") or 0)
        except (TypeError, ValueError):
            return False
        # A position outside 0..len(order) is a damaged manifest, and clamping it re-serves the permutation from the
        # top or ends the cycle early behind an already-restored RNG.
        if not 0 <= pos <= len(self._order):
            return False
        self._pos = pos
        return True


def discover_image_caption_pairs(
    data_dir: str | os.PathLike[str],
    *,
    instance_prompt: Optional[str] = None,
    caption_column: str = "text",
    verify_images: bool = False,
) -> list[tuple[str, str]]:
    """Caption priority: sidecar, then metadata row, then instance_prompt; uncaptioned images skipped; must match routes.training._image_record."""
    root = Path(data_dir).expanduser()
    if not root.is_dir():
        raise FileNotFoundError(f"data_dir is not a directory: {data_dir}")

    # The caption lookup resolves to the caption's own companion, which exists, so the pair reads as a real one.
    images = drop_appledouble_metadata(
        sorted(p for p in root.iterdir() if p.is_file() and p.suffix.lower() in _IMAGE_EXTS)
    )

    # 1. metadata.jsonl / captions.jsonl (either name accepted).
    meta_caption: dict[str, str] = {}
    for meta_name in ("metadata.jsonl", "captions.jsonl"):
        meta_path = root / meta_name
        if not meta_path.is_file():
            continue
        # Skip a bad upload (invalid UTF-8 or non-object JSON) so the instance_prompt fallback still applies.
        # split("\n"), not splitlines(): JSON keeps U+2028, U+2029 and U+0085 raw inside a string.
        try:
            meta_lines = meta_path.read_text(encoding = "utf-8").split("\n")
        except (OSError, UnicodeError):
            continue
        for line in meta_lines:
            line = line.strip()
            if not line:
                continue
            try:
                row = json.loads(line)
            except (json.JSONDecodeError, TypeError):
                continue
            if not isinstance(row, dict):
                continue
            key = row.get("file_name") or row.get("image") or row.get("file")
            value = row.get(caption_column)
            # A JSON null is "no caption", not the string "None".
            if key and value is not None:
                meta_caption[str(key)] = str(value)

    pairs: list[tuple[str, str]] = []
    for img in images:
        caption: Optional[str] = None
        sidecar_present = False
        # An EMPTY sidecar is a tombstone: suppresses the metadata caption.
        for ext in _CAPTION_EXTS:
            sidecar = img.with_suffix(ext)
            if sidecar.is_file():
                sidecar_present = True
                try:
                    caption = sidecar.read_text(encoding = "utf-8").strip()
                except (OSError, UnicodeError):
                    # An unreadable sidecar reads as the empty tombstone, so the instance_prompt fallback applies
                    # instead of a 500.
                    caption = ""
                break
        # Metadata keyed by basename or as_posix path (Windows-safe); a sidecar, even empty, wins.
        if not sidecar_present:
            caption = meta_caption.get(img.name) or meta_caption.get(
                img.relative_to(root).as_posix()
            )
        # 3. dreambooth instance prompt for any image still without a caption.
        if not caption and instance_prompt:
            caption = instance_prompt
        if caption:
            if verify_images:
                # Reject a corrupt image now, before the start route frees GPU models.
                try:
                    from PIL import Image
                    with Image.open(img) as _probe:
                        _probe.verify()
                except Exception as e:  # noqa: BLE001 -- corrupt/zero-byte/truncated file
                    raise ValueError(
                        f"Image cannot be decoded: {img.name} ({e}). Remove or replace the "
                        f"corrupt or zero-byte file before training."
                    ) from e
            pairs.append((str(img), caption))

    if not pairs:
        raise ValueError(
            "No captioned images found. Provide a metadata.jsonl / captions.jsonl, per-image "
            ".txt captions, or an instance prompt."
        )
    return pairs


# Shared config has save_steps/resume_from_checkpoint; loops without them must raise, not ignore.
CHECKPOINTLESS_FAMILIES: frozenset[str] = frozenset({"minimax-h3"})
UNBUCKETED_FAMILIES: frozenset[str] = frozenset({"minimax-h3"})

# Batch is pure replication: layout, rotary grid and timesteps come from one clip and its caption.
SINGLE_SEQUENCE_FAMILIES: frozenset[str] = frozenset({"minimax-h3"})

# Families loaded via ModularPipeline (modular_model_index.json, no model_index.json); the trainer and start route must share this set.
MODULAR_BASE_FAMILIES: frozenset[str] = frozenset({"minimax-h3"})

# MiniMax-H3 canvas multiple: a 16x VAE compression and a 2x patch.
_H3_CANVAS_MULTIPLE = 32


def h3_train_unsupported_reason(cfg: Any) -> Optional[str]:
    """Returns the reason this config cannot train MiniMax-H3, else None; never raises. Config-only, so the route can check before freeing residents."""
    if (getattr(cfg, "resolved_family", "") or "").strip().lower() != "minimax-h3":
        return None
    if cfg.mixed_precision != "bf16":
        return (
            "MiniMax-H3 LoRA training requires bf16: its checkpoint keeps the patch "
            "projections, the timestep MLP and the output heads in fp32 and fp16 overflows "
            "them. The loop hard-codes the bf16 weight dtype and autocast either way, so any "
            "other setting would be recorded and then not run. Set mixed precision to bf16."
        )
    if cfg.resolution % _H3_CANVAS_MULTIPLE:
        return (
            f"MiniMax-H3 trains on a canvas whose edges are multiples of {_H3_CANVAS_MULTIPLE} "
            f"(a 16x VAE compression and a 2x patch); got resolution {cfg.resolution}."
        )
    if float(getattr(cfg, "cfg_dropout", 0.0) or 0.0) > 0:
        return (
            "MiniMax-H3 is guidance-distilled: it has no unconditional branch and no negative "
            "prompt, so a classifier-free-guidance dropout trains a path the sampler never "
            "takes. Set cfg_dropout to 0."
        )
    if str(getattr(cfg, "weighting_scheme", "none") or "none") != "none":
        return (
            "MiniMax-H3 has no timestep-weighted loss yet: its two schedules put video and "
            "audio at different sigmas in the same step, so a single weight over 'the' "
            "timestep is ambiguous. Use weighting_scheme='none'."
        )
    # Different caption lengths mean different layouts; no mask to pad with.
    if cfg.train_batch_size != 1:
        return (
            "MiniMax-H3 trains at batch size 1: one forward covers one packed sequence, whose "
            "row layout is set by the clip's own geometry and its caption's length. Use "
            "gradient_accumulation_steps to raise the effective batch."
        )
    # No conditioning cache exists on this path, so accepting the directory would promise a saving that never happens.
    if str(getattr(cfg, "cond_cache_dir", "") or "").strip():
        return (
            "MiniMax-H3 has no persistent conditioning cache yet: each run loads the "
            "conditioner and recomputes its captions and latents, so cond_cache_dir would be "
            "recorded and never read. Leave it unset."
        )
    return None


# Normalised, not refused: several are request defaults, refusing would 422 every untouched request.
_H3_FIXED_RECIPE: dict[str, Any] = {
    "center_crop": True,
    "random_flip": False,
    "snr_gamma": None,
    "cache_latents": True,
    "cache_variants": 1,
    "bucketing": False,
}


def train_recipe_overrides(cfg: Any) -> dict[str, Any]:
    """The fields whose REQUESTED value this family's loop replaces, mapped to what it runs. Shared
    for the same reason ``h3_train_unsupported_reason`` is: the trainer applies these in the
    CHILD, while the run record is written by the PARENT from the config handed to
    ``service.start``. Normalising in the trainer alone therefore fixed what ran and left
    Previous Runs describing cropping, flipping and min-SNR weighting that never happened. The
    other flow-matching families drop only min-SNR; SDXL honours all of them."""
    family = (getattr(cfg, "resolved_family", "") or "").strip().lower()
    if family == "minimax-h3":
        return dict(_H3_FIXED_RECIPE)
    # Min-SNR is an SDXL (epsilon-prediction) weighting; the flow-matching loops never read it.
    if family and family != "sdxl":
        return {"snr_gamma": None}
    return {}


# LTX-2 is deliberately not here: it trains a style LoRA FROM still images, so it keeps the image discovery.
CLIP_TRAINED_FAMILIES: frozenset[str] = frozenset({"minimax-h3"})


def discover_training_pairs(
    resolved_family: str,
    data_dir: str | os.PathLike[str],
    *,
    instance_prompt: Optional[str] = None,
    caption_column: str = "text",
    verify_images: bool = False,
) -> list[tuple[str, str]]:
    """Uses the family's own discovery (clips for MiniMax-H3), so the preflight matches the trainer."""
    if str(resolved_family or "").strip().lower() in CLIP_TRAINED_FAMILIES:
        from core.training.diffusion_h3_clips import discover_clip_caption_pairs
        return discover_clip_caption_pairs(
            data_dir, instance_prompt = instance_prompt, caption_column = caption_column
        )
    return discover_image_caption_pairs(
        data_dir,
        instance_prompt = instance_prompt,
        caption_column = caption_column,
        verify_images = verify_images,
    )


def training_fetch_repo(cfg: Any) -> Optional[str]:
    """The repository the trainer downloads: DiT families load the resolved mirror, others the base model."""
    family = (getattr(cfg, "resolved_family", None) or "sdxl").strip().lower()
    if family in _DIT_TRAIN_FAMILIES:
        return getattr(cfg, "fetch_base_model", None) or cfg.base_model
    return cfg.base_model


def _emit(on_event: Optional[EventCb], type_: str, **kw: Any) -> None:
    if on_event is not None:
        on_event({"type": type_, "ts": time.time(), **kw})


def _plan_cache_variants(
    num_images: int,
    cache_variants: int,
    center_crop: bool,
    random_flip: bool,
    seed: int,
    crop_room: Optional[list[tuple[int, int]]] = None,
) -> list[list[tuple[float, float, bool]]]:
    """Seed-deterministic crop/flip plan for the latent cache: per image, up to ``cache_variants``
    draws of (u_left, u_top, flip) with the crop as unit fractions the loader maps onto its
    integer crop range. Uses its own rng stream so the training loop's draws are untouched.
    Center-crop / no-flip collapse duplicate variants, so callers encode each distinct variant
    exactly once. ``crop_room``: per-image (x, y) crop slack; an axis with none pins its fraction.
    Pure (no torch) for CPU unit tests."""
    crop_rng = random.Random(seed)
    plan: list[list[tuple[float, float, bool]]] = []
    for i in range(max(0, num_images)):
        variants: list[tuple[float, float, bool]] = []
        for _ in range(max(1, cache_variants)):
            u_left, u_top = crop_rng.random(), crop_rng.random()
            flip = bool(random_flip and crop_rng.random() < 0.5)
            if crop_room is not None:
                u_left = u_left if crop_room[i][0] > 0 else 0.5
                u_top = u_top if crop_room[i][1] > 0 else 0.5
            if center_crop:
                u_left = u_top = 0.5  # loader ignores the fractions for a center crop
            key = (u_left, u_top, flip)
            if key not in variants:
                variants.append(key)
        plan.append(variants)
    return plan


def resolve_bucketing(cfg: "DiffusionLoraConfig") -> "DiffusionLoraConfig":
    """Settle an unset ``bucketing``: the bundle's recorded value on a resume (pre-field runs stay square)."""
    if cfg.bucketing is not None:
        return cfg
    if not cfg.resume_from_checkpoint:
        return replace(cfg, bucketing = cfg.resolved_family not in UNBUCKETED_FAMILIES)
    from core.training.diffusion_checkpoint import recorded_bucketing

    return replace(cfg, bucketing = recorded_bucketing(cfg.resume_from_checkpoint))


def plan_image_canvases(
    cfg: "DiffusionLoraConfig", image_paths: list[str]
) -> tuple[Optional[list[tuple[int, int]]], Optional[list[tuple[int, int]]]]:
    """Per-image (w, h) canvas and (x, y) crop slack, or (None, None) when unbucketed. Headers only."""
    if not cfg.bucketing:
        return None, None
    from core.training.diffusion_train_extras import (
        bucket_resolutions,
        cover_resize_dims,
        nearest_bucket,
        oriented_image_size,
    )

    choices = bucket_resolutions(cfg.resolution)
    canvases, room = [], []
    for path in image_paths:
        w0, h0 = oriented_image_size(path)
        bw, bh = nearest_bucket(w0, h0, choices)
        rw, rh = cover_resize_dims(w0, h0, bw, bh)
        canvases.append((bw, bh))
        room.append((rw - bw, rh - bh))
    # All-square datasets keep the unbucketed sampler and cache keys, so existing caches stay warm.
    if all(c == (cfg.resolution, cfg.resolution) for c in canvases):
        return None, None
    return canvases, room


def bucket_groups(canvases: list[tuple[int, int]]) -> dict[tuple[int, int], list[int]]:
    groups: dict[tuple[int, int], list[int]] = {}
    for i, shape in enumerate(canvases):
        groups.setdefault(shape, []).append(i)
    return groups


# Fp32 posteriors per image and variant can exhaust pinned RAM; over budget, encode per step.
_LATENT_CACHE_BUDGET_BYTES = 4 * 1024**3  # 4 GiB

# Cache builders return this when over budget, so the VAE stays resident; None is a stop.
LATENT_CACHE_OVER_BUDGET: Any = object()


def _latent_cache_forced() -> bool:
    """The user explicitly forced the latent cache on, bypassing the size gate. The explicit opt-in
    counterpart to ``UNSLOTH_DIFFUSION_NO_LATENT_CACHE``; only the automatic default is
    size-gated, so an explicit choice is honoured verbatim in either direction."""
    return os.environ.get("UNSLOTH_DIFFUSION_FORCE_LATENT_CACHE", "") in ("1", "true")


def _latent_cache_over_budget(
    per_variant_bytes: int,
    total_variants: int,
    budget_bytes: Optional[int] = None,
) -> bool:
    """True when total_variants x per_variant_bytes exceeds the budget; per-variant bytes are measured from a real encoded latent."""
    if budget_bytes is None:
        budget_bytes = _LATENT_CACHE_BUDGET_BYTES
    return per_variant_bytes * max(0, total_variants) > budget_bytes


def _apply_perf_flags(
    cfg: "DiffusionLoraConfig",
    device: str,
    cudnn_benchmark: bool = False,
) -> dict:
    """cudnn autotune is for the SDXL U-Net only: it doubles peak VRAM and gains nothing for DiT."""
    from core.inference.diffusion_speed import snapshot_backend_flags

    snap: dict[str, Any] = {"flags": snapshot_backend_flags(), "matmul_precision": None}
    if device != "cuda":
        return snap
    try:
        import torch

        snap["matmul_precision"] = torch.get_float32_matmul_precision()
        if cfg.enable_tf32:
            torch.backends.cuda.matmul.allow_tf32 = True
            torch.backends.cudnn.allow_tf32 = True
            torch.set_float32_matmul_precision("high")
        else:
            # Strict-fp32 A/B mode: clear flags explicitly (cudnn TF32 defaults ON).
            torch.backends.cuda.matmul.allow_tf32 = False
            torch.backends.cudnn.allow_tf32 = False
            torch.set_float32_matmul_precision("highest")
        if cudnn_benchmark:
            torch.backends.cudnn.benchmark = True
        # cuDNN SDPA training is broken for FLUX shapes on torch 2.10 + cu130; pin flash/mem-eff.
        cuda_backends = getattr(torch.backends, "cuda", None)
        if cuda_backends is not None and hasattr(cuda_backends, "enable_cudnn_sdp"):
            try:
                snap["cudnn_sdp"] = bool(cuda_backends.cudnn_sdp_enabled())
            except Exception:  # noqa: BLE001 -- flag unreadable: skip the tweak entirely
                snap["cudnn_sdp"] = None
            if snap["cudnn_sdp"]:
                cuda_backends.enable_cudnn_sdp(False)
    except Exception:  # noqa: BLE001 -- perf flags are never fatal
        pass
    return snap


def _restore_perf_flags(snap: Optional[dict]) -> None:
    """Undo ``_apply_perf_flags`` (the trainer subprocess is disposable, but in-process callers --
    tests, notebooks -- must not inherit mutated globals)."""
    if not snap:
        return
    from core.inference.diffusion_speed import restore_backend_flags

    restore_backend_flags(snap.get("flags"))
    try:
        import torch

        if snap.get("matmul_precision"):
            torch.set_float32_matmul_precision(snap["matmul_precision"])
        # Restore cudnn SDPA state; None means the flag was unreadable at apply time and was left alone.
        cuda_backends = getattr(torch.backends, "cuda", None)
        if (
            snap.get("cudnn_sdp") is not None
            and cuda_backends is not None
            and hasattr(cuda_backends, "enable_cudnn_sdp")
        ):
            cuda_backends.enable_cudnn_sdp(bool(snap["cudnn_sdp"]))
    except Exception:  # noqa: BLE001 -- best-effort restore
        pass


# Independent of the inference allowlist. Exact lowercase; never add pickles or remote code.
_TRAIN_EXTRA_TRUSTED_REPOS = frozenset(
    {
        "black-forest-labs/flux.2-dev",
        "black-forest-labs/flux.2-klein-4b",
        "black-forest-labs/flux.2-klein-base-4b",
        "black-forest-labs/flux.2-klein-base-9b",
        # A video family, so the image-side inference allowlist never covered it; safetensors-only, no remote code.
        "lightricks/ltx-2",
        # MiniMax-H3's official base, for the same reason: safetensors-only, no remote code.
        "minimaxai/minimax-h3",
        "wan-ai/wan2.2-ti2v-5b-diffusers",
    }
)

# LTX-2.3 repos are single-file checkpoints the trainer cannot load; refuse before eviction.
_LTX23_TRAIN_UNSUPPORTED = ("lightricks/ltx-2.3", "lightricks/ltx-2.3-fp8")


def _refuse_ltx23_training_base(base_model: str) -> None:
    """Raise for an LTX-2.3 base: the family routing accepts it, the training loader cannot."""
    if str(base_model or "").strip().lower() not in _LTX23_TRAIN_UNSUPPORTED:
        return
    raise ValueError(
        f"'{base_model}' ships LTX-2.3 as single-file checkpoints with no diffusers layout, so it "
        f"cannot be a training base yet: the trainer loads a base with from_pretrained, while 2.3 "
        f"has to be assembled with from_single_file plus components from the 2.0 base. Train from "
        f"'Lightricks/LTX-2' instead."
    )


def _assert_trusted_base_model(base_model: str, *, allow_modular: bool = False) -> None:
    """Checked before from_pretrained so untrusted repos (possible pickle weights) are never fetched; allow_modular takes a MiniMax-H3 modular dir."""
    from core.inference.diffusion import _assert_local_base_is_pipeline, _is_trusted_diffusion_repo

    trusted = (
        _is_trusted_diffusion_repo(base_model)
        or str(base_model or "").strip().lower() in _TRAIN_EXTRA_TRUSTED_REPOS
    )
    if not trusted:
        raise ValueError(
            f"Refusing to train from untrusted base model '{base_model}'. Use a local path or "
            f"a trusted repo (an unsloth/* repo or an official base)."
        )
    # An existing LOCAL base is loaded as a full pipeline, which needs an index; reject a non-pipeline local dir
    # before /diffusion/start frees the GPU models.
    try:
        _assert_local_base_is_pipeline(base_model, allow_modular = allow_modular)
    except ValueError as e:
        shape = _single_file_shape(base_model)
        if shape is None:
            raise
        # Echo only the caller's own path; a file found inside would leak before authorization.
        what = "is a single-file checkpoint" if shape == "file" else "holds single-file checkpoints"
        raise ValueError(
            f"'{base_model}' {what}, which cannot be a training base yet: training loads the base "
            f"as a diffusers pipeline folder (one subfolder per component). Pick a base from the "
            f"list instead."
        ) from e


_SINGLE_FILE_SUFFIXES = (".safetensors", ".ckpt", ".gguf")
# LoRA weights, not a base: a trained Studio / diffusers LoRA folder holds pytorch_lora_weights.safetensors.
_LORA_WEIGHT_NAMES = ("pytorch_lora_weights.safetensors", "adapter_model.safetensors")
_NOT_A_CHECKPOINT_FOLDER = (
    "model_index.json",
    "modular_model_index.json",
    "config.json",
    "adapter_config.json",
)


def _single_file_shape(base_model: str) -> Optional[str]:
    """ "file" / "folder" when a local base is, or holds (an A1111 / ComfyUI models folder), a single-file
    checkpoint, else None. Wording only, never a verdict."""
    try:
        path = Path(str(base_model or "").strip()).expanduser()
        if path.is_file():
            return "file" if _is_checkpoint_name(path) else None
        if not path.is_dir() or any((path / m).exists() for m in _NOT_A_CHECKPOINT_FOLDER):
            return None
        with os.scandir(path) as entries:
            if any(_is_checkpoint_name(Path(e.path)) and e.is_file() for e in entries):
                return "folder"
    except OSError:
        pass
    return None


def _is_checkpoint_name(path: Path) -> bool:
    name = path.name.lower()
    return (
        name.endswith(_SINGLE_FILE_SUFFIXES)
        and name not in _LORA_WEIGHT_NAMES
        and not is_appledouble_metadata(path)
    )


# One writer and one reader for BOTH trainers, so an SDXL and a DiT run resume from the same bundle shape.
def trainable_state_dict(model: Any) -> dict[str, Any]:
    """Exactly the tensors the optimizer holds moments for, not the peft export, so resume is bit-exact."""
    return {name: p.detach() for name, p in model.named_parameters() if p.requires_grad}


def load_trainable_state_dict(model: Any, state: Optional[dict[str, Any]]) -> int:
    """A partial match raises: optimizer state is keyed by index, so moved names would load silently."""
    if not state:
        return 0
    import torch

    restored = 0
    trainable: set[str] = set()
    with torch.no_grad():
        for name, p in model.named_parameters():
            if not p.requires_grad:
                continue
            trainable.add(name)
            saved = state.get(name)
            if saved is None:
                continue
            if tuple(saved.shape) != tuple(p.shape):
                raise ValueError(
                    f"Checkpoint tensor '{name}' has shape {tuple(saved.shape)} but this run "
                    f"expects {tuple(p.shape)}; the LoRA configuration does not match."
                )
            p.copy_(saved.to(device = p.device, dtype = p.dtype))
            restored += 1
    # Check both directions: a strict-subset adapter must not pass.
    unsaved = sorted(trainable - set(state))
    unknown = sorted(set(state) - trainable)
    if unsaved or unknown:
        detail = []
        if unsaved:
            detail.append(f"{len(unsaved)} not in the checkpoint (e.g. {', '.join(unsaved[:3])})")
        if unknown:
            detail.append(f"{len(unknown)} not in this run (e.g. {', '.join(unknown[:3])})")
        raise ValueError(
            f"This run has {len(trainable)} trainable tensors and the checkpoint has "
            f"{len(state)}: {'; '.join(detail)}. The LoRA configuration does not match the one "
            "it was saved from."
        )
    return restored


def _json_safe_progress(progress: Optional[dict[str, Any]]) -> dict[str, Any]:
    """Drops NaN/inf progress values: json.dumps emits NaN/Infinity, which strict JSON readers reject."""
    out: dict[str, Any] = {}
    for key, value in (progress or {}).items():
        if isinstance(value, float) and not math.isfinite(value):
            continue
        out[key] = value
    return out


def write_resume_checkpoint(
    cfg: DiffusionLoraConfig,
    *,
    step: int,
    model: Any,
    optimizer: Any,
    lr_scheduler: Any,
    identity: Any,
    on_event: Optional[EventCb] = None,
    ema: Any = None,
    sampler: Any = None,
    rng_streams: Optional[dict[str, Any]] = None,
    progress: Optional[dict[str, Any]] = None,
    discard_existing: bool = False,
    preexisting: Optional[Any] = None,
) -> tuple[Optional[str], Optional[str]]:
    """Never raises: returns (path, error) instead of losing a healthy run; discard_existing on the first write so older bundles cannot outrank it."""
    from core.training.diffusion_checkpoint import capture_rng_state, save_checkpoint
    try:
        path = save_checkpoint(
            output_dir = cfg.output_dir,
            step = step,
            adapter_state = trainable_state_dict(model),
            identity = identity,
            target_steps = cfg.train_steps,
            optimizer = optimizer,
            lr_scheduler = lr_scheduler,
            ema_state = ema.state_dict() if ema is not None else None,
            ema_updates = int(getattr(ema, "updates", 0) or 0) if ema is not None else 0,
            rng = capture_rng_state(rng_streams),
            sampler_state = sampler.state_dict() if sampler is not None else None,
            progress = _json_safe_progress(progress),
            save_total_limit = int(cfg.save_total_limit or 0),
            discard_existing = discard_existing,
            # Identifies this bundle so a same-step shortcut skips only our own re-save, not another run's.
            source_checkpoint = getattr(cfg, "resume_from_checkpoint", None),
            # Bundles predating this run are never pruned to make room for its own; a branched resume used to delete them irreversibly.
            preexisting = preexisting,
        )
        # Reported per save: a later crash keeps resumable state; a failed write stays blocked.
        _emit(on_event, "checkpoint_saved", checkpoint_path = path, step = step)
        return path, None
    except Exception as exc:  # noqa: BLE001 -- reported, never fatal to the run
        message = f"Could not write a resume checkpoint at step {step}: {exc}"
        _emit(on_event, "checkpoint_failed", step = step, message = message)
        return None, message


def _reapply_lr_schedule(optimizer: Any, lr_scheduler: Any) -> None:
    """Recompute lr from the live schedule: scheduler resume restores only the position; LambdaLR only, since chainable schedulers would double-step."""
    try:
        import torch

        if not isinstance(lr_scheduler, torch.optim.lr_scheduler.LambdaLR):
            return
        values = [
            float(base * lmbda(lr_scheduler.last_epoch))
            for lmbda, base in zip(lr_scheduler.lr_lambdas, lr_scheduler.base_lrs)
        ]
        for group, value in zip(optimizer.param_groups, values):
            group["lr"] = value
        lr_scheduler._last_lr = values
    except Exception:  # noqa: BLE001 -- keeping the restored rate is a safe fallback
        pass


_OPTIMIZER_KERNEL_KEYS = ("fused", "foreach")


def restore_resume_state(
    cfg: DiffusionLoraConfig,
    *,
    model: Any,
    optimizer: Any,
    lr_scheduler: Any,
    identity: Any,
    on_event: Optional[EventCb] = None,
    ema: Any = None,
    sampler: Any = None,
    rng_streams: Optional[dict[str, Any]] = None,
) -> Any:
    """Re-runs the full preflight in the child rather than trusting the start route's check."""
    if not cfg.resume_from_checkpoint:
        return None
    from core.training.diffusion_checkpoint import (
        ResumeError,
        load_checkpoint,
        optimizer_key,
        preflight_resume,
        restore_rng_state,
    )

    path, step = preflight_resume(
        cfg.resume_from_checkpoint, identity = identity, target_steps = cfg.train_steps
    )
    ckpt = load_checkpoint(path)
    load_trainable_state_dict(model, ckpt.tensors("adapter"))
    optimizer_state = ckpt.torch_state("optimizer")
    if optimizer_state is not None:
        # Foreign moments (AdamW8bit vs torch AdamW) load cleanly, then the first step dies on a bare KeyError.
        saved_optimizer = ckpt.optimizer_class
        live_optimizer = optimizer_key(optimizer)
        if not saved_optimizer:
            # An optimizer file with no class beside it is a hand-edited or half-written bundle, and foreign moments
            # load cleanly then die on the first step, after the preflight evicted the residents.
            raise ResumeError(
                "This checkpoint does not record which optimizer wrote its state, so its "
                "moments cannot be safely restored. Resume from an earlier checkpoint, or "
                "start a new run."
            )
        if saved_optimizer != live_optimizer:
            raise ResumeError(
                f"This checkpoint's optimizer state was written by {saved_optimizer}, but this "
                f"machine builds {live_optimizer}. Install the same optimizer backend (or unset "
                f"UNSLOTH_DIFFUSION_FP32_OPTIM) to continue this run."
            )
        # Optimizer state is keyed by position, the adapter by name; verify the order matches.
        saved_names = ckpt.optimizer_param_names
        live_names = list(trainable_state_dict(model))
        if saved_names is not None and saved_names != live_names:
            raise ResumeError(
                "This checkpoint's optimizer state was written for a different parameter order "
                "than this build produces, so its moments cannot be matched to this run's "
                "tensors. Start a new run, or resume on the version that wrote it."
            )
        # Checkpoint lr wins (HF Trainer semantics); the fused/foreach kernel choice stays this host's.
        kernels = [
            {k: g[k] for k in _OPTIMIZER_KERNEL_KEYS if k in g} for g in optimizer.param_groups
        ]
        saved_groups = (
            optimizer_state.get("param_groups") if isinstance(optimizer_state, dict) else None
        )
        if isinstance(saved_groups, list) and len(saved_groups) == len(kernels):
            # torch places "step" by the SAVED fused flag: non-fused bundles keep it on CPU, which fused rejects.
            optimizer_state = {
                **optimizer_state,
                "param_groups": [{**g, **kept} for g, kept in zip(saved_groups, kernels)],
            }
        optimizer.load_state_dict(optimizer_state)
        for group, kept in zip(optimizer.param_groups, kernels):
            group.update(kept)
    elif optimizer is not None:
        # Every bundle this writer produces has an optimizer, so continuing without one restarts Adam's moments from
        # zero at step N while reporting a clean resume.
        raise ResumeError(
            "This checkpoint carries no optimizer state, so the run cannot be continued from "
            "it: the moments would restart from zero at the resumed step. Start a new run."
        )
    scheduler_state = ckpt.torch_state("scheduler")
    if scheduler_state is not None:
        lr_scheduler.load_state_dict(scheduler_state)
        _reapply_lr_schedule(optimizer, lr_scheduler)
    elif lr_scheduler is not None:
        # A fresh LambdaLR at step 0 would re-warm the learning rate the restored optimizer already moved past.
        raise ResumeError(
            "This checkpoint carries no learning-rate scheduler state, so the schedule would "
            "restart from step 0. Start a new run."
        )
    if sampler is not None and not sampler.load_state_dict(ckpt.sampler_state):
        # Every image checkpoint carries sampler state, so a missing or malformed one leaves a fresh sampler behind an
        # RNG restored past the saved permutation: images silently skipped or repeated.
        raise ResumeError(
            "This checkpoint's dataset sampler state is missing or unreadable, so the image "
            "order cannot be continued. Start a new run."
        )
    if ema is not None:
        ema_state = ckpt.tensors("ema")
        if ema_state:
            missing = ema.missing_from(ema_state)
            if missing:
                # load_state_dict silently keeps init values for unmatched EMA entries.
                named = ", ".join(missing[:3]) + ("..." if len(missing) > 3 else "")
                raise ResumeError(
                    f"This checkpoint's EMA state is missing or mis-shaped for {len(missing)} "
                    f"of this run's adapter tensors ({named}), so the averaged weights cannot "
                    f"be continued. Resume with EMA disabled, or start a new run."
                )
            ema.load_state_dict(ema_state, updates = ckpt.ema_updates)
        else:
            # EMA was built before the adapter restore, so its shadow holds init weights.
            ema.reseed_from(model)
    restore_rng_state(ckpt.rng_json, ckpt.torch_state("rng"), rng_streams)
    _emit(
        on_event,
        "resumed",
        checkpoint_path = str(path),
        step = step,
        total_steps = cfg.train_steps,
        # Identity, not path: another run can overwrite the same slot, so a path alone is not lineage.
        source_created_at = ckpt.manifest.get("created_at"),
    )
    return ckpt


def _publish_to_lora_catalog(
    lora_path: str,
    cfg: DiffusionLoraConfig,
    steps: Optional[int] = None,
) -> Optional[str]:
    """Video families are skipped: loras/diffusion is read only by the Images LoRA picker."""
    if detect_video_family("", override = cfg.resolved_family) is not None:
        return None
    try:
        import shutil

        from core.inference.diffusion_lora import loras_dir, sanitize_alias

        base = (
            cfg.adapter_name
            if cfg.adapter_name and cfg.adapter_name != "default"
            else Path(cfg.output_dir).name
        )
        alias = sanitize_alias(base)
        src_resolved = Path(lora_path).resolve()
        dest = loras_dir() / f"{alias}.safetensors"
        # A retrain with the same adapter name must not clobber a prior mirror: pick the next free numeric suffix.
        if dest.exists() and dest.resolve() != src_resolved:
            n = 2
            while True:
                candidate = loras_dir() / f"{alias}-{n}.safetensors"
                if not candidate.exists() or candidate.resolve() == src_resolved:
                    dest = candidate
                    break
                n += 1
        if src_resolved != dest.resolve():
            shutil.copy2(lora_path, dest)
        _write_lora_sidecar(dest.with_suffix(".json"), cfg, steps)
        return str(dest)
    except Exception:  # noqa: BLE001 -- the catalog mirror is best-effort, never fatal
        return None


def _write_lora_sidecar(
    sidecar_path: Path,
    cfg: DiffusionLoraConfig,
    steps: Optional[int] = None,
) -> None:
    """Records the step reached, not the configured train_steps, so a stopped run is not overstated."""
    meta = {
        "family": cfg.resolved_family,
        "families": [cfg.resolved_family],
        "base_model": cfg.base_model,
        "lora_rank": cfg.lora_rank,
        "lora_alpha": cfg.lora_alpha,
        "steps": int(steps) if steps is not None else cfg.train_steps,
        "resolution": cfg.resolution,
        "trigger_prompt": cfg.instance_prompt,
        "created_at": time.time(),
        "source": "studio-trained",
        # diffusion_lora.LORA_SIDECAR_KIND: marks the adapter as an image LoRA wherever it is copied.
        "kind": "diffusion-lora",
    }
    sidecar_path.write_text(json.dumps(meta, indent = 2), encoding = "utf-8")


# Maps generic Unsloth payload keys to DiffusionLoraConfig fields so one request shape drives both.
_CONFIG_ALIASES = {
    "model_name": "base_model",
    "max_steps": "train_steps",
    # Identity alias so the epochs override is threaded through explicitly.
    "num_epochs": "num_epochs",
    "batch_size": "train_batch_size",
    "lora_r": "lora_rank",
    "lr_scheduler_type": "lr_scheduler",
    "random_seed": "seed",
    "lr": "learning_rate",
}


def _coerce_gradient_checkpointing(value: Any) -> bool:
    """Unsloth sends gradient_checkpointing as a string ("none" / "true" / "unsloth"); the disable
    words are False, anything else truthy is True. A real bool passes through."""
    if isinstance(value, str):
        return value.strip().lower() not in ("", "none", "false", "0", "no", "off")
    return bool(value)


def _coerce_bool(value: Any) -> bool:
    """Coerce a flag that may arrive as a string through the generic Unsloth config path (e.g.
    "false" / "0" / "off"). A non-empty string like "false" is otherwise truthy, so an opt-out
    would silently no-op. A real bool passes through."""
    if isinstance(value, str):
        return value.strip().lower() not in ("", "none", "false", "0", "no", "off")
    return bool(value)


def _config_from_dict(config: dict) -> DiffusionLoraConfig:
    """Build a DiffusionLoraConfig from a plain dict. Unknown keys are ignored so a richer request
    payload (UI form) does not break construction; a small set of generic Unsloth training keys
    are aliased onto the diffusion field names, and string flags are coerced."""
    valid = DiffusionLoraConfig.__dataclass_fields__.keys()
    kwargs: dict[str, Any] = {}
    # Aliases first (lowest priority); a canonical key present in the payload overrides.
    for src, dst in _CONFIG_ALIASES.items():
        if src in config and config[src] is not None and dst in valid:
            kwargs[dst] = config[src]
    for k, v in config.items():
        if k in valid:
            kwargs[k] = v
    # max_steps 0 is the epoch-mode sentinel; normalized() rejects train_steps < 1 before resolve_train_steps applies num_epochs.
    try:
        _num_epochs = int(kwargs.get("num_epochs") or 0)
    except (TypeError, ValueError):
        _num_epochs = 0
    if _num_epochs > 0 and not kwargs.get("train_steps"):
        kwargs.pop("train_steps", None)
    if kwargs.get("lora_target_modules"):
        kwargs["lora_target_modules"] = tuple(kwargs["lora_target_modules"])
    if isinstance(kwargs.get("sample_prompts"), (list, tuple)):
        kwargs["sample_prompts"] = tuple(kwargs["sample_prompts"])
    if "gradient_checkpointing" in kwargs:
        kwargs["gradient_checkpointing"] = _coerce_gradient_checkpointing(
            kwargs["gradient_checkpointing"]
        )
    if kwargs.get("bucketing") is not None:
        kwargs["bucketing"] = _coerce_bool(kwargs["bucketing"])
    for flag in ("cache_latents", "enable_tf32"):
        if flag in kwargs:
            kwargs[flag] = _coerce_bool(kwargs[flag])
    return DiffusionLoraConfig(**kwargs)