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.

51.1 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

"""Pure sd-cli argv builder for stable-diffusion.cpp; no torch, diffusers or subprocess imports, so
tests need no GPU, binary, or model files"""

from __future__ import annotations

import functools
import os
import re
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass, field
from typing import Optional

from core.inference.diffusion_memory import (
    OFFLOAD_GROUP,
    OFFLOAD_MODEL,
    OFFLOAD_NONE,
    OFFLOAD_SEQUENTIAL,
)

# Text-encoder flags per family, in supply order; keyed by DiffusionFamily.name, not sd.cpp.
_TE_FLAGS_BY_FAMILY: dict[str, tuple[str, ...]] = {
    "z-image": ("--llm",),
    "flux.2-klein": ("--llm",),
    "flux.2-dev": ("--llm",),
    "qwen-image": ("--qwen2vl",),
    "qwen-image-edit": ("--qwen2vl",),
    "qwen-image-layered": ("--qwen2vl",),
    # 2.1 conditions on Qwen3-VL via --llm; --qwen2vl also enables Qwen2-VL's vision, the wrong
    # door.
    "qwen-image-2.1": ("--llm",),
    # Qwen3-VL-4B through --llm, as qwen-image-2.1.
    "flux.3-klein": ("--llm",),
    "flux.3-klein-base": ("--llm",),
    "krea-2": ("--llm",),
    "flux.1": ("--clip_l", "--t5xxl"),
    "flux.1-kontext": ("--clip_l", "--t5xxl"),
}


def text_encoder_flags_for_family(family_name: str) -> tuple[str, ...]:
    """sd-cli text-encoder flags for ``family_name`` (empty if unknown)."""
    return _TE_FLAGS_BY_FAMILY.get(family_name, ())


# sd-cli image-gen mode (older txt2img); img2img is the same mode with --init-img.
DEFAULT_MODE = "img_gen"


@dataclass(frozen = True)
class SdCppModelFiles:
    """Resolved on-disk paths for one checkpoint's components. ``diffusion_model`` is required; the
    rest are optional (a bundled single-file checkpoint still builds). None fields are omitted."""

    diffusion_model: str
    vae: Optional[str] = None
    audio_vae: Optional[str] = None
    clip_l: Optional[str] = None
    clip_g: Optional[str] = None
    t5xxl: Optional[str] = None
    llm: Optional[str] = None
    llm_vision: Optional[str] = None
    qwen2vl: Optional[str] = None
    tokenizer: Optional[str] = None


@dataclass(frozen = True)
class SdCppGenParams:
    """Generation parameters, mapped 1:1 onto sd-cli's sampling flags.

    Image-conditioning fields cover the img_gen variants: ``init_img`` + ``strength`` = img2img,
    + ``mask`` = inpaint, ``ref_images`` = FLUX Kontext / Qwen-Image-Edit editing. ``lora_dir`` is
    the LoRA directory; individual LoRAs are ``<lora:name:weight>`` tags in ``prompt``.
    """

    prompt: str
    negative_prompt: Optional[str] = None
    # None: unset, so image runs let sd.cpp derive size; plain txt2img defaults to 1024x1024.
    width: Optional[int] = None
    height: Optional[int] = None
    steps: Optional[int] = None
    cfg_scale: Optional[float] = None
    guidance: Optional[float] = None
    seed: Optional[int] = None
    sampling_method: Optional[str] = None
    scheduler: Optional[str] = None
    batch_count: int = 1
    init_img: Optional[str] = None
    strength: Optional[float] = None
    mask: Optional[str] = None
    ref_images: tuple[str, ...] = ()
    lora_dir: Optional[str] = None
    lora_apply_mode: Optional[str] = None
    # Qwen-Image-Layered layer count; sd.cpp returns layers + 1 images (first = input reconstruction). None = its default 3.
    qwen_image_layers: Optional[int] = None


@dataclass(frozen = True)
class SdCppVideoGenParams:
    """Video generation parameters for sd-cli's ``vid_gen`` mode.

    Keyframes and Ref2VA references use separate denoiser partitions. Reference videos are
    frame directories, and their WAV soundtracks are paired by index.
    """

    prompt: str
    width: int
    height: int
    num_frames: int
    fps: int = 24
    steps: Optional[int] = None
    cfg_scale: float = 1.0
    seed: Optional[int] = None
    init_img: Optional[str] = None
    end_img: Optional[str] = None
    ref_images: tuple[str, ...] = ()
    ref_videos: tuple[str, ...] = ()
    ref_video_audios: tuple[str, ...] = ()
    ref_audios: tuple[str, ...] = ()
    # sd.cpp exposes only the video schedule shift.
    flow_shift: Optional[float] = None


@dataclass(frozen = True)
class SdCppUpscaleParams:
    """Inputs for sd-cli's ESRGAN upscale mode (a separate run mode)."""

    input_image: str
    upscale_model: str
    repeats: int = 1
    tile_size: Optional[int] = None


# Fork patch (ggml-patches/0001): quantized matmuls with >= N rows use BF16 dequant + cuBLAS instead of int8 MMQ.
# Q8_0 only (Z-Image Turbo vs BF16, B200: LPIPS 0.0148 -> 0.0052); k-quants are weight-error bound. Ada/Ampere/Orin keep MMQ (2x faster).
# Read from the diffusion GGUF only (A100, Q8_0 DiT + Q4_K_M encoder: 1.57x); the env is process-wide, but prompt rows
# stay below it. Drop the env once the pin carries fork patch 0016, the build's own Q8_0-only default.
QUANT_CUBLAS_ENV = "GGML_CUDA_QUANT_CUBLAS_MIN_BATCH"
QUANT_CUBLAS_WEIGHT_TYPES = frozenset({"Q8_0"})
_UNQUANTIZED_GGUF_TYPES = frozenset({"F32", "F16", "BF16", "F64", "I8", "I16", "I32", "I64"})


def quant_cublas_min_batch(cuda_cc: tuple[int, int]) -> Optional[int]:
    """Rows from which ``cuda_cc`` takes the BF16 cuBLAS route, or None to keep MMQ."""
    major, minor = int(cuda_cc[0]), int(cuda_cc[1])
    if (major, minor) == (8, 0) or major in (9, 10):
        return 1024
    if major == 12:
        return 4096
    return None


def gguf_quantized_weight_types(path: Optional[str]) -> Optional[frozenset[str]]:
    """Quantized tensor types in the GGUF at ``path``, or None if unreadable. Reads only the mmapped tensor table."""
    if not path or not str(path).lower().endswith(".gguf"):
        return None
    try:
        from gguf import GGUFReader
        reader = GGUFReader(str(path), "r")
        return frozenset(t.tensor_type.name for t in reader.tensors) - _UNQUANTIZED_GGUF_TYPES
    except Exception:  # noqa: BLE001 -- unknown keeps the build's default (MMQ)
        return None


def quant_cublas_env(
    cuda_ccs: Sequence[tuple[int, int]],
    environ: Optional[dict] = None,
    weight_types: Optional[frozenset[str]] = None,
) -> dict[str, str]:
    """Set only if every card sd.cpp may pick agrees and the diffusion GGUF is all Q8_0; a user value wins."""
    import os

    environ = os.environ if environ is None else environ
    if QUANT_CUBLAS_ENV in environ or not cuda_ccs:
        return {}
    if not weight_types or not weight_types <= QUANT_CUBLAS_WEIGHT_TYPES:
        return {}
    rows = {quant_cublas_min_batch(cc) for cc in cuda_ccs}
    if len(rows) != 1 or None in rows:
        return {}
    return {QUANT_CUBLAS_ENV: str(rows.pop())}


# Native speed profiles. default/max: --diffusion-fa + --diffusion-conv-direct (exact); Metal/Vulkan/ROCm get fa only.
NATIVE_SPEED_OFF = "off"
NATIVE_SPEED_DEFAULT = "default"
NATIVE_SPEED_MAX = "max"
NATIVE_SPEED_MODES = (NATIVE_SPEED_OFF, NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX)


def native_speed_flags(
    speed_mode: Optional[str],
    backend_args: Optional[Sequence[str]] = None,
    accelerator: Optional[str] = None,
    binary: Optional[str] = None,
) -> list[str]:
    """sd-cli speed flags for a native speed mode (empty for off / None). Separate from offload:
    ``--diffusion-fa`` is a win in its own right. De-duplicated against offload at the call site.
    ``backend_args``: the other argv flags (``--backend`` picks the device); ``accelerator``: build class or None.
    ``binary``: on builds listing ``--conv-direct`` (master-963+) a rejected direct conv is sent as ``--conv-direct off``,
    since an omitted flag means auto there (direct conv on for HIP MMA / Vulkan regardless of this policy)."""
    mode = (speed_mode or NATIVE_SPEED_OFF).strip().lower()
    if mode in ("", NATIVE_SPEED_OFF):
        return []
    if mode in (NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX):
        args = backend_args or ()
        if not conv_direct_wanted(args, accelerator):
            user_set = any(f in _CONV_DIRECT_FLAGS for f in args)
            if not user_set and binary and sd_cpp_supports_conv_direct_mode(binary):
                return ["--diffusion-fa", "--conv-direct", "off"]
            return ["--diffusion-fa"]
        return ["--diffusion-fa", "--diffusion-conv-direct"]
    raise ValueError(f"native speed_mode must be one of {NATIVE_SPEED_MODES}, got '{speed_mode}'")


# Flags that already decide direct conv; a user-supplied one wins over the policy.
_CONV_DIRECT_FLAGS = ("--conv-direct", "--diffusion-conv-direct", "--vae-conv-direct")
_VALUED_SPEED_FLAGS = ("--conv-direct",)


def speed_flags_without(speed: Sequence[str], offload: Sequence[str]) -> list[str]:
    """``speed`` minus flags already in ``offload``, keeping a valued flag and its value together."""
    out: list[str] = []
    i = 0
    while i < len(speed):
        flag = speed[i]
        width = 2 if flag in _VALUED_SPEED_FLAGS and i + 1 < len(speed) else 1
        if flag not in offload:
            out += list(speed[i : i + width])
        i += width
    return out


def sd_cpp_supports_conv_direct_mode(binary: str) -> bool:
    """True when ``binary --help`` lists ``--conv-direct``. Fails closed (older builds reject the unknown flag)."""
    import os

    try:
        st = os.stat(binary)
    except OSError:
        return False
    return _conv_direct_in_help(str(binary), st.st_size, st.st_mtime_ns)


@functools.lru_cache(maxsize = 16)
def _conv_direct_in_help(binary: str, size: int, mtime_ns: int) -> bool:
    import re

    from core.inference.sd_cpp_backend import _sd_cpp_probe_output

    text = _sd_cpp_probe_output(binary, "--help")
    return text is not None and re.search(r"(?<![\w-])--conv-direct\b", text) is not None


# Direct conv loses to im2col here: Vulkan (sd.cpp #2137, 10.9 -> 73.4 s) and HIP (#2085; gfx1151 never faster).
_CONV_DIRECT_SLOW_BACKENDS = ("vulkan", "rocm", "hip")


def conv_direct_wanted(backend_args: Sequence[str] = (), accelerator: Optional[str] = None) -> bool:
    """``UNSLOTH_SD_CPP_CONV_DIRECT`` = 1/0 forces it (Metal too); else off on Metal, and a ``--backend diffusion=``
    pin beats ``accelerator``."""
    import os

    forced = (os.environ.get("UNSLOTH_SD_CPP_CONV_DIRECT") or "").strip().lower()
    if forced in ("1", "on", "true", "yes"):
        return True
    if forced in ("0", "off", "false", "no"):
        return False
    if _runs_on_apple_metal(backend_args):
        return False
    args = list(backend_args)
    target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
    name = (target or accelerator or "").strip().lower().rstrip("0123456789")
    return name not in _CONV_DIRECT_SLOW_BACKENDS


def _diffusion_backend(specs: Sequence[str]) -> Optional[str]:
    """The backend the diffusion module gets from ``--backend`` specs: ``diffusion=`` beats a bare default; None = auto-fit."""
    explicit = default = None
    for spec in specs:
        for part in str(spec).split(","):
            key, sep, value = part.strip().partition("=")
            if not sep:
                default = key or default
            elif key.strip().lower() == "diffusion":
                explicit = value.strip()
    return explicit or default


def _runs_on_apple_metal(backend_args: Sequence[str] = ()) -> bool:
    """True when sd.cpp runs diffusion on Apple Metal (an explicit --backend decides, else Apple
    Silicon not paravirtual); direct conv stays off since CONV_2D trips the GPU watchdog."""
    import sys

    if sys.platform != "darwin":
        return False
    args = list(backend_args)
    target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
    if target is not None:
        return target.lower() != "cpu"
    return apple_silicon_machine() and not metal_is_paravirtual()


@functools.lru_cache(maxsize = 1)
def apple_silicon_machine() -> bool:
    """True on an Apple Silicon Mac, including an x86_64 Python under Rosetta (``hw.optional.arm64``, as install.sh)."""
    import platform
    import sys

    if sys.platform != "darwin":
        return False
    if platform.machine().lower() in ("arm64", "aarch64"):
        return True
    try:
        import ctypes
        import ctypes.util

        libc = ctypes.CDLL(ctypes.util.find_library("c"))
        value = ctypes.c_int(0)
        size = ctypes.c_size_t(ctypes.sizeof(value))
        if (
            libc.sysctlbyname(
                b"hw.optional.arm64", ctypes.byref(value), ctypes.byref(size), None, 0
            )
            == 0
        ):
            return value.value == 1
    except Exception:  # noqa: BLE001 -- no answer means an Intel Mac
        pass
    return False


def forces_cpu_backend(device: Optional[str]) -> bool:
    """True when an sd.cpp run on resolved ``device`` is placed on the CPU backend (a paravirtual Mac GPU)."""
    return device == "mps" and metal_is_paravirtual()


# Kill switch for the Metal text-encoder placement below (1/true keeps the encoder on Metal).
_METAL_TE_ON_GPU_ENV = "UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU"


@functools.lru_cache(maxsize = 1)
def metal_is_paravirtual() -> bool:
    """True when this Mac's Metal device is Apple's paravirtual GPU (a macOS VM). Reuses the llama.cpp probe."""
    import sys

    if sys.platform != "darwin":
        return False
    try:
        from core.inference.llama_cpp import _metal_device_is_paravirtual
    except Exception:  # noqa: BLE001 -- no probe means no evidence of a VM
        return False
    try:
        return bool(_metal_device_is_paravirtual())
    except Exception:  # noqa: BLE001
        return False


def metal_text_encoder_flags() -> list[str]:
    """Placement flags for sd.cpp on Apple Metal, else nothing.

    A paravirtual GPU gets ``--backend cpu``: the bundled ggml segfaults there on CPU-fallback buffers. Otherwise the
    text encoder stays on the CPU (``--clip-on-cpu``) since ggml-metal can abort an LLM encoder;
    ``UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU=1`` keeps it on Metal."""
    import os
    import sys

    if sys.platform != "darwin":
        return []
    if metal_is_paravirtual():
        return list(CPU_BACKEND_FLAGS)
    if os.environ.get(_METAL_TE_ON_GPU_ENV, "").strip().lower() in ("1", "true", "yes", "on"):
        return []
    return ["--clip-on-cpu"]


def metal_placement_flags(offload: Sequence[str]) -> list[str]:
    """``metal_text_encoder_flags()`` minus what ``offload`` already says.

    ``--backend cpu`` is a flag pair: per-item filtering would leave a dangling ``cpu``, so an explicit pin drops it."""
    flags = metal_text_encoder_flags()
    if flags == list(CPU_BACKEND_FLAGS):
        return [] if "--backend" in offload else flags
    return [f for f in flags if f not in offload]


# 1 / 0 forces sd.cpp's --mmap on / off; unset decides from the installed build (``mmap_flags``).
SD_CPP_MMAP_ENV = "UNSLOTH_DIFFUSION_SD_CPP_MMAP"
# Help text of builds whose --mmap still repacks CPU weights (older ones run them unrepacked: slower, other pixels).
CPU_MMAP_REPACK_HELP = "weights the CPU repacks are still loaded"
# leejet/stable-diffusion.cpp#2037 (master-907) maps mmapped weights through Metal device buffers. Older builds accept
# --mmap but hand Metal a CPU buffer it cannot address, so the flag is only safe from this build on.
METAL_MMAP_MIN_BUILD = 907
_INSTALL_RECORD = ".unsloth-sd-cpp-install.json"


# MOSS-Image negative-branch skip, matching diffusion_moss_image.reference_uncond_skip: SFT skips nothing; Base skips
# block 22 while sigma-percent is in 0 .. 0.5 (shift 5: steps 0-12 of 25). Builds without these --extra-sample-args keys
# ignore them and keep sd.cpp's default (block 22 every step); UNSLOTH_MOSS_REFERENCE_SKIP=0 sends nothing.
MOSS_REFERENCE_SKIP_ENV = "UNSLOTH_MOSS_REFERENCE_SKIP"
MOSS_BASE_UNCOND_SKIP_END = 0.5


def moss_is_base_checkpoint(*identities: Optional[str]) -> bool:
    """True when any repo id / folder / filename spells MOSS-Image-Base (separators folded); else the SFT default."""
    for identity in identities:
        folded = "".join(c for c in str(identity or "").lower() if c.isalnum())
        if "mossimagebase" in folded:
            return True
    return False


def moss_uncond_skip_sample_args(*identities: Optional[str]) -> Optional[str]:
    """sd.cpp ``extra_sample_args`` for a MOSS-Image checkpoint, or None for the binary's every-step default."""
    if (os.environ.get(MOSS_REFERENCE_SKIP_ENV) or "").strip().lower() in (
        "0",
        "off",
        "false",
        "no",
    ):
        return None
    if moss_is_base_checkpoint(*identities):
        return f"moss_uncond_skip_start=0,moss_uncond_skip_end={MOSS_BASE_UNCOND_SKIP_END:g}"
    return "moss_uncond_skip=false"


def sd_cpp_build_number(tag: Optional[str]) -> Optional[int]:
    """``N`` of a ``master-N-<sha>[-u<sha>]`` release tag, else None."""
    import re

    m = re.match(r"^master-(\d+)(?:-|$)", str(tag or "").strip())
    return int(m.group(1)) if m else None


@functools.lru_cache(maxsize = 8)
def _installed_sd_cpp_tag(binary: str) -> Optional[str]:
    """The release tag Studio's installer recorded next to ``binary`` (the binary sits at or a few levels under the
    install root). None for a binary the installer did not place (``SD_CLI_PATH``, PATH, a source build)."""
    import json
    from pathlib import Path

    try:
        path = Path(binary).resolve()
    except Exception:  # noqa: BLE001
        return None
    for parent in list(path.parents)[:3]:
        try:
            with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:
                rec = json.load(f)
        except (OSError, ValueError):
            continue
        tag = rec.get("tag") if isinstance(rec, dict) else None
        return tag if isinstance(tag, str) and tag else None
    return None


def mac_mmap_flags(binary: Optional[str], extra_args: Optional[Sequence[str]] = None) -> list[str]:
    """``["--mmap"]`` on macOS when ``binary`` maps weights correctly on Metal, else nothing.

    With it, GGUF / safetensors weights stay clean file-backed pages (Metal wraps them in place, the CPU backend reads
    them in place) instead of a second anonymous copy, which on unified memory is the copy that swaps: upstream measured
    a Qwen-Image 2.1 Q4_K_M peak footprint of 10.2 -> 1.4 GB on an M1 Pro, pixel-identical. Fails closed on a build it
    cannot date; ``UNSLOTH_DIFFUSION_SD_CPP_MMAP`` = 1 / 0 forces it either way."""
    import os
    import sys

    if sys.platform != "darwin" or "--mmap" in (extra_args or ()):
        return []
    forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()
    if forced in ("0", "false", "no", "off"):
        return []
    if forced in ("1", "true", "yes", "on"):
        return ["--mmap"]
    build = sd_cpp_build_number(_installed_sd_cpp_tag(str(binary))) if binary else None
    return ["--mmap"] if build is not None and build >= METAL_MMAP_MIN_BUILD else []


@functools.lru_cache(maxsize = 8)
def _installed_sd_cpp_accelerator(binary: str) -> Optional[str]:
    """The accelerator class (``cpu`` / ``cuda`` / ``vulkan`` / ...) Studio's installer recorded next to ``binary``."""
    import json
    from pathlib import Path

    try:
        path = Path(binary).resolve()
    except Exception:  # noqa: BLE001
        return None
    for parent in list(path.parents)[:3]:
        try:
            with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:
                rec = json.load(f)
        except (OSError, ValueError):
            continue
        accel = rec.get("accelerator") if isinstance(rec, dict) else None
        return accel if isinstance(accel, str) and accel else None
    return None


def sd_cpp_mmap_keeps_cpu_repack(binary: str) -> bool:
    """True when ``binary --help`` says its --mmap still repacks CPU weights. Fails closed."""
    try:
        st = os.stat(binary)
    except OSError:
        return False
    return _cpu_mmap_repack_in_help(str(binary), st.st_size, st.st_mtime_ns)


@functools.lru_cache(maxsize = 16)
def _cpu_mmap_repack_in_help(binary: str, size: int, mtime_ns: int) -> bool:
    from core.inference.sd_cpp_backend import _sd_cpp_probe_output
    text = _sd_cpp_probe_output(binary, "--help")
    return text is not None and CPU_MMAP_REPACK_HELP in text


def mmap_flags(
    binary: Optional[str],
    extra_args: Optional[Sequence[str]] = None,
    backend_args: Optional[Sequence[str]] = None,
) -> list[str]:
    """``--mmap`` on macOS Metal-mmap builds and on CPU renders whose --mmap still repacks CPU weights (keeps
    unrepacked weights file-backed: ~4.6 GB vs 13.3 GB anonymous, pixel-identical). GPU renders are left alone."""
    import sys

    if sys.platform == "darwin":
        return mac_mmap_flags(binary, extra_args)
    if "--mmap" in (extra_args or ()):
        return []
    forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()
    if forced in ("0", "false", "no", "off"):
        return []
    if forced in ("1", "true", "yes", "on"):
        return ["--mmap"]
    if not binary:
        return []
    args = [*(backend_args or ()), *(extra_args or ())]
    target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
    on_cpu = (
        target.lower() == "cpu"
        if target is not None
        else _installed_sd_cpp_accelerator(str(binary)) == "cpu"
    )
    return ["--mmap"] if on_cpu and sd_cpp_mmap_keeps_cpu_repack(str(binary)) else []


# Everything on the CPU backend. sd.cpp prefers GPU -> integrated GPU -> CPU and only `--backend` changes which
# backend EXECUTES the graph (`--offload-to-cpu` moves parameters, not compute), so this is the one flag that removes
# ggml-metal entirely.
CPU_BACKEND_FLAGS: tuple[str, ...] = ("--backend", "cpu")

# Negative --max-vram auto-detects free VRAM per device; segments on its own.
GRAPH_CUT_VRAM_FLAGS: tuple[str, ...] = ("--max-vram", "-1")
# Upstream honours --stream-layers only under --offload-to-cpu (diffusion params on CPU); otherwise it warns and ignores the flag.
GRAPH_CUT_STREAM_FLAGS: tuple[str, ...] = ("--stream-layers",)
# The full set, for callers that already offload to CPU.
GRAPH_CUT_AUTO_FLAGS: tuple[str, ...] = GRAPH_CUT_VRAM_FLAGS + GRAPH_CUT_STREAM_FLAGS

# The committed "-1" is a placeholder (live server signatures compare on it); a launch swaps it for an explicit GiB
# budget read before the spawn, so the 2 GiB reserve also covers the child's own CUDA context and cuBLAS workspaces.
# Other negative values (UMA pinned-weight reserve) are applied by sd.cpp itself and never replaced.
GRAPH_CUT_BUDGET_RESERVE_BYTES = 2 << 30
GRAPH_CUT_MIN_BUDGET_BYTES = 1 << 30
GRAPH_CUT_RETRY_SCALE = 0.75
GRAPH_CUT_EXPLICIT_BUDGET_ENV = "UNSLOTH_SD_CPP_EXPLICIT_VRAM_BUDGET"


def explicit_vram_budget_enabled(env: Optional[dict] = None) -> bool:
    """Kill switch: ``UNSLOTH_SD_CPP_EXPLICIT_VRAM_BUDGET=0`` keeps sd.cpp's own "-1" free-VRAM reading."""
    import os

    environ = os.environ if env is None else env
    return str(environ.get(GRAPH_CUT_EXPLICIT_BUDGET_ENV, "")).strip().lower() not in (
        "0",
        "false",
        "no",
        "off",
    )


def graph_cut_budget_gib(
    free_bytes: Optional[int],
    *,
    reserve_bytes: int = GRAPH_CUT_BUDGET_RESERVE_BYTES,
    scale: float = 1.0,
) -> Optional[float]:
    """``--max-vram`` GiB for ``free_bytes`` free, or None (keep "-1"). Rounded DOWN so it never exceeds the plan."""
    if free_bytes is None:
        return None
    budget = (int(free_bytes) - int(reserve_bytes)) * float(scale)
    if budget < GRAPH_CUT_MIN_BUDGET_BYTES:
        return None
    return int(budget / float(1 << 30) * 100) / 100.0


def _format_gib(value: float) -> str:
    return f"{value:.2f}"


def max_vram_value(flags: Sequence[str]) -> Optional[str]:
    items = list(flags)
    for i, flag in enumerate(items):
        if flag == "--max-vram":
            return items[i + 1] if i + 1 < len(items) else None
    return None


def max_vram_is_auto(value: Optional[str]) -> bool:
    if value is None or "=" in value or "," in value:
        return False
    try:
        return float(value) < 0
    except ValueError:
        return False


def max_vram_is_placeholder(value: Optional[str]) -> bool:
    """Only the committed ``-1``; a computed UMA reserve (``-17.05``) is sd.cpp's to apply, not a placeholder."""
    if not max_vram_is_auto(value):
        return False
    return float(value) == float(GRAPH_CUT_VRAM_FLAGS[1])  # type: ignore[arg-type]


def with_max_vram_budget(
    flags: Sequence[str], budget: "Optional[float | dict[str, float]]"
) -> list[str]:
    """Replace only the ``-1`` placeholder (dict -> ``cuda0=6.25,cuda1=12.50``), never a user or UMA-fit value."""
    out = list(flags)
    if not budget:
        return out
    for i, flag in enumerate(out):
        if flag != "--max-vram" or i + 1 >= len(out) or not max_vram_is_placeholder(out[i + 1]):
            continue
        if isinstance(budget, dict):
            out[i + 1] = ",".join(f"{name}={_format_gib(gib)}" for name, gib in budget.items())
        else:
            out[i + 1] = _format_gib(float(budget))
    return out


def explicit_max_vram_gib(flags: Sequence[str]) -> "Optional[float | dict[str, float]]":
    value = max_vram_value(flags)
    if value is None or max_vram_is_auto(value):
        return None
    try:
        if "=" in value:
            out: dict[str, float] = {}
            for part in value.split(","):
                name, _, gib = part.partition("=")
                out[name.strip()] = float(gib)
            return out
        gib = float(value)
    except ValueError:
        return None
    return gib if gib > 0 else None


def scaled_vram_budget(
    budget: "float | dict[str, float]", scale: float
) -> "Optional[float | dict[str, float]]":
    """``budget * scale`` per device, or None once any device falls below ``GRAPH_CUT_MIN_BUDGET_BYTES``."""
    floor_gib = GRAPH_CUT_MIN_BUDGET_BYTES / float(1 << 30)

    def one(gib: float) -> Optional[float]:
        value = int(float(gib) * float(scale) * 100) / 100.0
        return value if value >= floor_gib else None

    if isinstance(budget, dict):
        out = {name: one(gib) for name, gib in budget.items()}
        if not out or any(v is None for v in out.values()):
            return None
        return out  # type: ignore[return-value]
    return one(float(budget))


# Not the model manager's "cannot make enough memory available": completed renders print it too.
_DEVICE_OOM_MARKERS: tuple[str, ...] = (
    "erroroutofdevicememory",
    "out_of_device_memory",
    "cudaerrormemoryallocation",
    "hiperroroutofmemory",
    "failed to allocate cuda",
    "failed to allocate rocm",
    "failed to allocate vulkan",
    "failed to allocate metal",
    "failed during workspace capacity check",
    "failed during workspace allocation",
    "failed during allocated capacity check",
)
# Bare "out of memory" counts only beside a device API name; host OOM is not cured by a smaller VRAM budget.
_DEVICE_OOM_CONTEXT: tuple[str, ...] = ("cuda", "hip", "rocm", "vulkan", "metal", "ggml_backend")
_HOST_OOM_MARKERS: tuple[str, ...] = (
    "host malloc",
    "host memory",
    "out_of_host_memory",
    "bad_alloc",
    "cannot allocate memory",
)


def is_device_oom_text(text: Optional[str]) -> bool:
    if not text:
        return False
    for line in str(text).lower().splitlines():
        if any(marker in line for marker in _HOST_OOM_MARKERS):
            continue
        if any(marker in line for marker in _DEVICE_OOM_MARKERS):
            return True
        if "out of memory" in line and any(word in line for word in _DEVICE_OOM_CONTEXT):
            return True
    return False


# sd.cpp ``fail_segment`` capacity-check stages (ggml_runner.cpp); "workspace allocation" is an allocator failure.
_SEGMENT_REFUSAL_MARKERS: tuple[str, ...] = (
    "failed during weight preparation",
    "failed during workspace capacity check",
    "failed during allocated capacity check",
)
# Allocator failures on the host RAM that weight preparation stages into, as well as on the device.
_ALLOCATION_FAILURE_MARKERS: tuple[str, ...] = (
    *_HOST_OOM_MARKERS,
    "erroroutofhostmemory",
    "failed to allocate",
    "backend buffer failed",
)
# sd.cpp fills free-512 MiB with cached weights, so each phase needs memory the last one released; half leaves it
# unclaimed when the driver reports the release late (Windows may defer destroying allocations).
IMAGE_VRAM_RETRY_SCALE = 0.5


def is_vram_refusal_text(text: Optional[str]) -> bool:
    """sd.cpp's model manager declined a segment for VRAM, and no allocation failed outright (that keeps its error)."""
    lines = str(text or "").lower().splitlines()
    if not any(marker in line for line in lines for marker in _SEGMENT_REFUSAL_MARKERS):
        return False
    return not any(
        "failed during" not in line
        and (
            is_device_oom_text(line)
            or any(marker in line for marker in _ALLOCATION_FAILURE_MARKERS)
        )
        for line in lines
    )


def image_vram_retry_budget(
    planned_free_mib: Optional[Mapping[str, int]], render_devices: Iterable[str] = ()
) -> Optional[str]:
    """``--max-vram`` for the image retry: half of each planned card's free VRAM (``CUDA0=..,CUDA1=..`` for several),
    skipping cards under the floor. None if none qualifies or a ``render_devices`` card does not."""
    planned = dict(planned_free_mib or {})
    budgets: dict[str, float] = {}
    for name, mib in planned.items():
        gib = graph_cut_budget_gib(int(mib) << 20, reserve_bytes = 0, scale = IMAGE_VRAM_RETRY_SCALE)
        if gib is not None:
            budgets[name] = gib
    if not budgets:
        return None
    known = {name.lower() for name in budgets}
    if any(str(device).lower() not in known for device in render_devices):
        return None
    if len(planned) == 1:
        return _format_gib(next(iter(budgets.values())))
    return ",".join(f"{name}={_format_gib(gib)}" for name, gib in budgets.items())


def device_backend_flags(
    device_name: Optional[str],
    offload: Optional[list[str]] = None,
    *,
    te_device: Optional[str] = None,
    vae_device: Optional[str] = None,
) -> list[str]:
    """Pins only modules the offload policy left on GPU, else sd.cpp uses ordinal 0 on mixed boxes; a later device flag would undo --clip-on-cpu."""
    if not device_name:
        return []
    flags = offload or []
    te = "cpu" if "--clip-on-cpu" in flags else (te_device or device_name)
    vae = "cpu" if "--vae-on-cpu" in flags else (vae_device or device_name)
    return ["--backend", f"diffusion={device_name},te={te},vae={vae}"]


def without_device_backend_flags(flags: Sequence[str]) -> list[str]:
    """Strips every --backend pair: sd.cpp concatenates repeats, so a CPU restart needs the pin gone; status and recipe read empty flags as no offload.
    A two-card block split's ``--auto-fit`` / ``--max-vram`` belong to its pin and go with it."""
    items = list(flags)
    split = any(
        f == "--backend" and i + 1 < len(items) and "&" in str(items[i + 1])
        for i, f in enumerate(items)
    )
    paired = ("--backend", "--auto-fit", "--max-vram") if split else ("--backend",)
    out: list[str] = []
    skip = False
    for flag in items:
        if skip:
            skip = False
            continue
        if flag in paired:
            skip = True
            continue
        out.append(flag)
    return out


# ggml-metal GGML_ABORTs on an unsupported op, killing sd-server mid-generation.
_GGML_UNSUPPORTED_OP_MARKERS = ("unsupported op", "ggml_abort")


def is_ggml_unsupported_op_abort(message: str) -> bool:
    """Only this abort signature is retried on CPU; OOM kills, real bugs, and corrupt checkpoints
    are not."""
    text = (message or "").lower()
    return all(marker in text for marker in _GGML_UNSUPPORTED_OP_MARKERS)


def offload_flags(
    policy: str,
    *,
    vae_tiling: bool = False,
    diffusion_fa: bool = False,
    vae_on_cpu: bool = True,
) -> list[str]:
    """vae_on_cpu=False drops only --vae-on-cpu, for families whose VAE cannot run on the CPU path."""
    flags: list[str] = []
    fa = diffusion_fa
    tile = vae_tiling
    if policy in (OFFLOAD_GROUP, OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
        flags.append("--offload-to-cpu")
        fa = True
    if policy in (OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
        flags.append("--clip-on-cpu")
        if vae_on_cpu:
            flags.append("--vae-on-cpu")
        tile = True
    if fa:
        flags.append("--diffusion-fa")
    if tile:
        flags.append("--vae-tiling")
    # Stable order, de-duplicated (a forced flag can coincide with a policy one).
    seen: set[str] = set()
    out: list[str] = []
    for f in flags:
        if f not in seen:
            seen.add(f)
            out.append(f)
    return out


# sd-cli's own <lora:NAME:W> pattern; it loads an absolute NAME from anywhere, whatever --lora-model-dir says.
_LORA_TAG_RE = re.compile(r"<lora:([^:>]+):([^>]+)>")


def strip_lora_tags(prompt: str) -> str:
    """Removes every tag sd-cli would parse, to a fixed point so a split tag cannot reassemble, plus any dangling
    ``<lora:`` that could pair with a tag appended after it."""
    out, prev = prompt, None
    while prev != out:
        prev = out
        out = _LORA_TAG_RE.sub("", out).replace("<lora:", "")
    if out == prompt:
        return prompt
    return re.sub(r"[ \t]{2,}", " ", out).strip()


def build_sd_cpp_command(
    binary: str,
    files: SdCppModelFiles,
    params: SdCppGenParams,
    *,
    output_path: str,
    offload: Optional[list[str]] = None,
    threads: Optional[int] = None,
    verbose: bool = False,
    extra_args: Optional[list[str]] = None,
) -> list[str]:
    """``extra_args`` go last because sd.cpp's parser is last-wins, so a user can override any flag."""
    if not files.diffusion_model:
        raise ValueError("diffusion_model path is required")
    if not (params.prompt or "").strip():
        raise ValueError("prompt is required")
    # A --mask without --init-img is invalid (inpaint needs a source image), so reject it here.
    if params.mask and not params.init_img:
        raise ValueError("init_img is required when mask is set (inpaint needs a source image)")

    cmd: list[str] = [binary, "--mode", DEFAULT_MODE, "--diffusion-model", files.diffusion_model]
    for flag, value in (
        ("--vae", files.vae),
        ("--clip_l", files.clip_l),
        ("--clip_g", files.clip_g),
        ("--t5xxl", files.t5xxl),
        ("--llm", files.llm),
        ("--llm_vision", files.llm_vision),
        ("--qwen2vl", files.qwen2vl),
        ("--tokenizer", files.tokenizer),
    ):
        if value:
            cmd += [flag, value]

    # Tags are only honoured against a lora_dir the caller filled with validated adapters.
    prompt = params.prompt if params.lora_dir else strip_lora_tags(params.prompt)
    cmd += ["--prompt", prompt]
    if params.negative_prompt:
        cmd += ["--negative-prompt", params.negative_prompt]
    if params.init_img:
        cmd += ["--init-img", params.init_img]
    if params.strength is not None:
        cmd += ["--strength", _fmt_float(params.strength)]
    if params.mask:
        cmd += ["--mask", params.mask]
    for ref in params.ref_images:
        cmd += ["--ref-image", ref]
    if params.qwen_image_layers is not None:
        cmd += ["--qwen-image-layers", str(int(params.qwen_image_layers))]
    # LoRA: the directory to scan; individual LoRAs are <lora:name:w> tags in prompt.
    if params.lora_dir:
        cmd += ["--lora-model-dir", params.lora_dir]
    if params.lora_apply_mode:
        cmd += ["--lora-apply-mode", params.lora_apply_mode]
    # Unset dims are omitted for image-conditioned runs so sd.cpp derives size; txt2img defaults to 1024.
    if params.width is not None or params.height is not None:
        w = int(params.width) if params.width is not None else 1024
        h = int(params.height) if params.height is not None else 1024
        cmd += ["--width", str(w), "--height", str(h)]
    elif not (params.init_img or params.ref_images):
        cmd += ["--width", "1024", "--height", "1024"]
    if params.steps is not None:
        cmd += ["--steps", str(int(params.steps))]
    if params.cfg_scale is not None:
        cmd += ["--cfg-scale", _fmt_float(params.cfg_scale)]
    if params.guidance is not None:
        cmd += ["--guidance", _fmt_float(params.guidance)]
    if params.sampling_method:
        cmd += ["--sampling-method", str(params.sampling_method)]
    if params.scheduler:
        cmd += ["--scheduler", str(params.scheduler)]
    if params.seed is not None:
        cmd += ["--seed", str(int(params.seed))]
    if params.batch_count and params.batch_count != 1:
        # The runner collects only --output, so a CLI batch drops images; use the server API.
        raise ValueError(
            "sd-cli runs are single-image; use the sdcpp server API for batch generation."
        )

    cmd += ["--output", output_path]
    if threads is not None:
        cmd += ["--threads", str(int(threads))]
    offload = list(offload or [])
    if offload:
        cmd += offload
    cmd += metal_placement_flags(offload)
    cmd += mmap_flags(binary, extra_args, offload)
    if verbose:
        cmd += ["-v"]
    if extra_args:
        cmd += list(extra_args)
    return cmd


def build_sd_cpp_video_command(
    binary: str,
    files: SdCppModelFiles,
    params: SdCppVideoGenParams,
    *,
    output_path: str,
    offload: Optional[list[str]] = None,
    threads: Optional[int] = None,
    verbose: bool = False,
    extra_args: Optional[list[str]] = None,
) -> list[str]:
    """Build one MiniMax-H3 audio-video ``sd-cli`` command (text-only, or keyframe-conditioned)."""
    if not files.diffusion_model:
        raise ValueError("diffusion_model path is required")
    if not files.vae:
        raise ValueError("MiniMax-H3 video generation requires a video VAE")
    if not files.llm:
        raise ValueError("MiniMax-H3 video generation requires its Qwen3-VL text encoder")
    if not (params.prompt or "").strip():
        raise ValueError("prompt is required")
    if params.width <= 0 or params.height <= 0 or params.num_frames <= 0:
        raise ValueError("width, height, and num_frames must be positive")

    cmd = [
        binary,
        "--mode",
        "vid_gen",
        "--diffusion-model",
        files.diffusion_model,
        "--vae",
        files.vae,
    ]
    if files.audio_vae:
        cmd += ["--audio-vae", files.audio_vae]
    cmd += ["--llm", files.llm]
    if files.llm_vision:
        cmd += ["--llm_vision", files.llm_vision]
    if files.tokenizer:
        cmd += ["--tokenizer", files.tokenizer]
    # Reject incompatible partitions before loading the model.
    if (params.init_img or params.end_img) and (
        params.ref_images or params.ref_videos or params.ref_audios
    ):
        raise ValueError(
            "MiniMax-H3 keyframes and references cannot be combined: they run against "
            "different denoiser partitions."
        )
    if len(params.ref_video_audios) > len(params.ref_videos):
        raise ValueError("each reference video soundtrack needs a reference video to pair with")
    if params.init_img:
        cmd += ["--init-img", params.init_img]
    if params.end_img:
        cmd += ["--end-img", params.end_img]
    for ref in params.ref_images:
        cmd += ["--ref-image", ref]
    for ref in params.ref_videos:
        cmd += ["--ref-video", ref]
    for ref in params.ref_video_audios:
        cmd += ["--ref-video-audio", ref]
    for ref in params.ref_audios:
        cmd += ["--ref-audio", ref]
    cmd += [
        "--prompt",
        # Video has no LoRA selection, so no prompt tag is legitimate.
        strip_lora_tags(params.prompt),
        "--cfg-scale",
        _fmt_float(params.cfg_scale),
        "--width",
        str(int(params.width)),
        "--height",
        str(int(params.height)),
        "--rng",
        "cpu",
        "--fps",
        str(int(params.fps)),
        "--video-frames",
        str(int(params.num_frames)),
    ]
    if params.steps is not None:
        cmd += ["--steps", str(int(params.steps))]
    if params.flow_shift is not None:
        cmd += ["--flow-shift", _fmt_float(params.flow_shift)]
    if params.seed is not None:
        cmd += ["--seed", str(int(params.seed))]
    cmd += ["--output", output_path]
    if threads is not None:
        cmd += ["--threads", str(int(threads))]
    offload = list(offload or [])
    if offload:
        cmd += offload
    cmd += metal_placement_flags(offload)
    cmd += mmap_flags(binary, extra_args, offload)
    if verbose:
        cmd.append("-v")
    if extra_args:
        cmd += list(extra_args)
    return cmd


def build_sd_cpp_upscale_command(
    binary: str,
    params: SdCppUpscaleParams,
    *,
    output_path: str,
    verbose: bool = False,
    extra_args: Optional[list[str]] = None,
) -> list[str]:
    """Build the ``sd-cli --mode upscale`` argv (ESRGAN). A distinct run mode: input image + ESRGAN
    model, no prompt or text encoders. ``repeats`` runs the upscaler N times (each a fixed scale)."""
    if not params.input_image:
        raise ValueError("input_image is required for upscale")
    if not params.upscale_model:
        raise ValueError("upscale_model is required for upscale")
    # Reject repeats below 1 explicitly: a truthiness guard would swallow repeats=0 into sd-cli's one-pass default.
    if params.repeats < 1:
        raise ValueError("repeats must be >= 1 for upscale")
    cmd: list[str] = [
        binary,
        "--mode",
        "upscale",
        "--init-img",
        params.input_image,
        "--upscale-model",
        params.upscale_model,
    ]
    if params.repeats != 1:
        cmd += ["--upscale-repeats", str(int(params.repeats))]
    if params.tile_size is not None:
        cmd += ["--upscale-tile-size", str(int(params.tile_size))]
    cmd += ["--output", output_path]
    # Same paravirtual-GPU CPU placement as generation; an explicit --backend in extra_args wins.
    if metal_is_paravirtual() and "--backend" not in (extra_args or ()):
        cmd += list(CPU_BACKEND_FLAGS)
    if verbose:
        cmd += ["-v"]
    if extra_args:
        cmd += list(extra_args)
    return cmd


def build_sd_cpp_server_command(
    binary: str,
    files: SdCppModelFiles,
    *,
    host: str,
    port: int,
    vae_format: Optional[str] = None,
    offload: Optional[list[str]] = None,
    native_speed: Optional[str] = None,
    threads: Optional[int] = None,
    scratch_dir: Optional[str] = None,
    verbose: bool = False,
    extra_args: Optional[list[str]] = None,
    accelerator: Optional[str] = None,
) -> list[str]:
    """Those dir flags all point at ``scratch_dir``, which must exist: sd-server fails on a missing dir."""
    if not files.diffusion_model:
        raise ValueError("diffusion_model path is required")

    cmd: list[str] = [binary, "--diffusion-model", files.diffusion_model]
    for flag, value in (
        ("--vae", files.vae),
        # Without it a resident H3 vid_gen server renders a silent clip.
        ("--audio-vae", files.audio_vae),
        ("--clip_l", files.clip_l),
        ("--clip_g", files.clip_g),
        ("--t5xxl", files.t5xxl),
        ("--llm", files.llm),
        ("--llm_vision", files.llm_vision),
        ("--qwen2vl", files.qwen2vl),
        ("--tokenizer", files.tokenizer),
    ):
        if value:
            cmd += [flag, value]
    if vae_format:
        cmd += ["--vae-format", vae_format]
    cmd += ["--listen-ip", str(host), "--listen-port", str(int(port))]
    if scratch_dir:
        cmd += [
            "--lora-model-dir",
            scratch_dir,
            "--hires-upscalers-dir",
            scratch_dir,
            "--embd-dir",
            scratch_dir,
        ]
    if threads is not None:
        cmd += ["--threads", str(int(threads))]

    offload = list(offload or [])
    if offload:
        cmd += offload
    # De-dup speed flags against offload (may already include --diffusion-fa).
    placement = metal_placement_flags(offload)
    backend_args = [*offload, *placement, *(extra_args or ())]
    cmd += speed_flags_without(
        native_speed_flags(native_speed, backend_args, accelerator, binary), offload
    )
    cmd += placement
    cmd += mmap_flags(binary, extra_args, offload)
    if verbose:
        cmd += ["-v"]
    if extra_args:
        cmd += list(extra_args)
    return cmd


def build_img_gen_request(
    *,
    prompt: str,
    negative_prompt: Optional[str] = None,
    width: int = 1024,
    height: int = 1024,
    steps: Optional[int] = None,
    seed: Optional[int] = None,
    batch_count: int = 1,
    sample_method: Optional[str] = None,
    scheduler: Optional[str] = None,
    flow_shift: Optional[float] = None,
    cfg_scale: Optional[float] = None,
    distilled_guidance: Optional[float] = None,
    output_format: str = "png",
    lora: Optional[list[dict]] = None,
    ref_images: Optional[list[str]] = None,
    qwen_image_layers: Optional[int] = None,
    custom_sigmas: Optional[list[float]] = None,
    hires: Optional[dict] = None,
    extra_sample_args: Optional[str] = None,
) -> dict:
    """Guidance is split: FLUX distilled values go to distilled_guidance, real CFG scales to txt_cfg."""
    if not str(prompt).strip():
        raise ValueError("prompt is required")

    guidance: dict = {}
    if cfg_scale is not None:
        guidance["txt_cfg"] = float(cfg_scale)
    if distilled_guidance is not None:
        guidance["distilled_guidance"] = float(distilled_guidance)

    sample_params: dict = {}
    if steps is not None:
        sample_params["sample_steps"] = int(steps)
    if sample_method:
        sample_params["sample_method"] = str(sample_method)
    if scheduler:
        sample_params["scheduler"] = str(scheduler)
    if flow_shift is not None:
        sample_params["flow_shift"] = float(flow_shift)
    if custom_sigmas:
        # Same key the server's sample_params parser reads for sd-cli's --sigmas.
        sample_params["custom_sigmas"] = [float(s) for s in custom_sigmas]
    if guidance:
        sample_params["guidance"] = guidance
    if extra_sample_args:
        sample_params["extra_sample_args"] = str(extra_sample_args)

    req: dict = {
        "prompt": prompt,
        "negative_prompt": negative_prompt or "",
        "width": int(width),
        "height": int(height),
        "batch_count": max(1, int(batch_count)),
        "output_format": output_format,
    }
    if seed is not None:
        req["seed"] = int(seed)
    if sample_params:
        req["sample_params"] = sample_params
    # The server resolves lora paths against --lora-model-dir; prompt tags unsupported there.
    if lora:
        req["lora"] = lora
    # Base64 PNGs in model order; no init_image/strength/mask: this is reference conditioning, not img2img.
    if ref_images:
        req["ref_images"] = list(ref_images)
    if qwen_image_layers is not None:
        req["qwen_image_layers"] = int(qwen_image_layers)
    if hires:
        req["hires"] = dict(hires)
    return req


def sd_cli_output_paths(output_path: str, num_results: int) -> list[str]:
    """The files one ``sd-cli`` image run writes for ``--output output_path``: the path itself for a
    single result, else ``<stem>_<i><ext>`` from 0 (``examples/cli/main.cpp`` ``save_results``).
    A layered generation is the multi-result case: layers + 1 images from one run."""
    if num_results <= 1:
        return [output_path]
    stem, dot, ext = output_path.rpartition(".")
    if not dot or "/" in ext or "\\" in ext:
        stem, ext = output_path, "png"
    return [f"{stem}_{i}.{ext}" for i in range(num_results)]


H3_SERVER_REFS_ENV = "UNSLOTH_H3_SERVER_REFS"
# sd-cli's --ref-video reader (examples/cli/main.cpp load_images_from_dir): these extensions, byte-ordered names.
_SD_CLI_FRAME_EXTS = (".jpg", ".jpeg", ".png", ".bmp", ".webp")


# "0" = no family --scheduler / flow-shift variants (sd.cpp default schedule).
FAMILY_SCHEDULER_ENV = "UNSLOTH_SD_CPP_FAMILY_SCHEDULER"


def family_scheduler_enabled() -> bool:
    value = os.environ.get(FAMILY_SCHEDULER_ENV, "").strip().lower()
    return value not in ("0", "false", "no", "off")


def h3_server_refs_enabled() -> bool:
    value = os.environ.get(H3_SERVER_REFS_ENV, "").strip().lower()
    return value not in ("0", "false", "no", "off")


def h3_reference_media_keys(params: "SdCppVideoGenParams") -> tuple[str, ...]:
    keys = []
    if params.ref_videos:
        keys.append("ref_videos")
    if params.ref_video_audios:
        keys.append("ref_video_audios")
    if params.ref_audios:
        keys.append("ref_audios")
    return tuple(keys)


def h3_server_eligible(params: "SdCppVideoGenParams", *, server_refs: bool = False) -> bool:
    return server_refs or not h3_reference_media_keys(params)


def sd_cli_frame_files(directory: str) -> list[str]:
    entries = [
        entry
        for entry in os.scandir(directory)
        if entry.is_file() and os.path.splitext(entry.name)[1].lower() in _SD_CLI_FRAME_EXTS
    ]
    entries.sort(key = lambda entry: entry.name.encode("utf-8", "surrogateescape"))
    return [entry.path for entry in entries]


def build_vid_gen_request(
    params: "SdCppVideoGenParams",
    *,
    images_b64: Optional[dict[str, str]] = None,
    ref_images_b64: Optional[list[str]] = None,
    output_compression: int = 90,
    ref_videos_b64: Optional[list[list[str]]] = None,
    ref_video_audios_b64: Optional[list[str]] = None,
    ref_audios_b64: Optional[list[str]] = None,
) -> dict:
    """POST body equal to build_sd_cpp_video_command (same pixels per seed); writes AVI, which needs no WebM build; --rng cpu is a server flag passed at spawn."""
    if not (params.prompt or "").strip():
        raise ValueError("prompt is required")
    if params.width <= 0 or params.height <= 0 or params.num_frames <= 0:
        raise ValueError("width, height, and num_frames must be positive")
    inline_refs = {
        "ref_videos": ref_videos_b64,
        "ref_video_audios": ref_video_audios_b64,
        "ref_audios": ref_audios_b64,
    }
    for key in h3_reference_media_keys(params):
        if len(inline_refs[key] or ()) != len(getattr(params, key)):
            raise ValueError(f"{key} must be sent inline to the sd-server vid_gen API")
    if len(params.ref_video_audios) > len(params.ref_videos):
        raise ValueError("each reference video soundtrack needs a reference video to pair with")
    images = dict(images_b64 or {})
    if (images.get("init_image") or images.get("end_image")) and (
        ref_images_b64 or h3_reference_media_keys(params)
    ):
        raise ValueError(
            "MiniMax-H3 keyframes and references cannot be combined: they run against "
            "different denoiser partitions."
        )
    sample_params: dict = {"guidance": {"txt_cfg": float(params.cfg_scale)}}
    if params.steps is not None:
        sample_params["sample_steps"] = int(params.steps)
    if params.flow_shift is not None:
        sample_params["flow_shift"] = float(params.flow_shift)
    req: dict = {
        "prompt": params.prompt,
        "width": int(params.width),
        "height": int(params.height),
        "video_frames": int(params.num_frames),
        "fps": int(params.fps),
        "sample_params": sample_params,
        "output_format": "avi",
        "output_compression": int(output_compression),
    }
    if params.seed is not None:
        req["seed"] = int(params.seed)
    for key in ("init_image", "end_image"):
        if images.get(key):
            req[key] = images[key]
    if ref_images_b64:
        req["ref_images"] = list(ref_images_b64)
    for key in h3_reference_media_keys(params):
        req[key] = [list(item) if key == "ref_videos" else item for item in inline_refs[key]]
    return req


def _fmt_float(value: float) -> str:
    """Compact float -> str: drop a trailing ``.0`` (``1.0`` -> ``1``) to keep logged commands tidy."""
    f = float(value)
    return str(int(f)) if f.is_integer() else repr(f)