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.

60.2 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

"""Pydantic schemas for Training API"""

import math
import re
from pathlib import Path, PureWindowsPath
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from typing import Annotated, Any, Optional, List, Dict, Literal, Union

from hub.schemas.inventory import ModelFormat
from utils.hf_dataset_options import (
    MAX_HF_DATASET_OPTION_LENGTH,
    valid_hf_dataset_config_name,
    valid_hf_dataset_split_name,
    valid_hf_dataset_split_instruction,
)
from utils.training_runs import normalize_project_name


# ASCII integer, optional single sign. Rejects "++512" and Unicode digits that pass str.isdigit().
_INT_RE = re.compile(r"[+-]?[0-9]+")
_HF_DATASET_ID_SEGMENT_RE = re.compile(r"[A-Za-z0-9_](?:[A-Za-z0-9._-]*[A-Za-z0-9_])?")
TRAINING_REQUEST_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:-]*$"


_MAX_BATCH_SIZE = 4096
_MAX_GRAD_ACCUM = 4096
_MAX_STEPS = 1_000_000
_MAX_EPOCHS = 1000
# 2M is a sanity cap; host RAM runs out long before this.
_MAX_SEQ_LENGTH = 2_000_000
_MAX_LR_VALUE = 1.0
_MAX_LORA_R = 16_384
_MAX_LORA_ALPHA = 32_768
_MIN_VISION_IMAGE_SIZE = 256
# 2048 is the highest most llms stay stable at
_MAX_VISION_IMAGE_SIZE = 2048
# Caps .skip(n) on streaming datasets so an absurd index cannot iterate effectively forever.
_MAX_DATASET_SLICE_INDEX = 1_000_000_000


class S3Config(BaseModel):
    """S3 bucket configuration for loading datasets from AWS S3"""

    model_config = ConfigDict(populate_by_name = True)

    bucket: str = Field(..., description = "S3 bucket name")
    region: str = Field("us-east-1", description = "AWS region")
    prefix: Optional[str] = Field(None, description = "Optional path prefix within bucket")
    access_key_id: Optional[str] = Field(
        None,
        alias = "accessKeyId",
        description = "AWS access key ID (optional if using IAM role)",
    )
    secret_access_key: Optional[str] = Field(
        None,
        alias = "secretAccessKey",
        description = "AWS secret access key (optional if using IAM role)",
    )
    use_iam_role: bool = Field(
        False,
        alias = "useIamRole",
        description = "Use IAM role credentials instead of access keys",
    )

    @model_validator(mode = "after")
    def _check_credentials(self) -> "S3Config":
        # Require either IAM role auth or a full key pair so credentials are never half-configured.
        if not self.use_iam_role and not (self.access_key_id and self.secret_access_key):
            raise ValueError(
                "s3_config requires either use_iam_role=True or both "
                "access_key_id and secret_access_key"
            )
        return self


def _parse_lr(v: Any) -> float:
    """Parse learning_rate as a positive float strictly below _MAX_LR_VALUE."""
    # mode="before" sees bools (not 1/0) for a precise error.
    if v is None:
        raise ValueError("learning_rate is required")
    if isinstance(v, bool):
        raise ValueError("learning_rate must be a number, not a bool")
    try:
        lr = float(v)
    except (TypeError, ValueError):
        raise ValueError(f"learning_rate must be parseable as float (got {v!r})")
    if not (lr > 0.0):
        raise ValueError(f"learning_rate must be > 0 (got {lr!r}); typical range is 1e-6 .. 1e-3")
    if lr >= _MAX_LR_VALUE:
        raise ValueError(
            f"learning_rate must be < 1.0 (got {lr!r}); values that large always diverge training"
        )
    return lr


def _resolve_inventory_handles(values):
    """Resume replays a referenced history payload, so the entries come back as handles."""
    if not isinstance(values, (list, tuple)):
        return values
    return [_resolve_inventory_handle(item) if isinstance(item, str) else item for item in values]


def _unquote_pasted_path(value):
    """Windows "Copy as path" quotes the path; quoted, it never exists and reads as an untrusted repo id."""
    if isinstance(value, str):
        text = value.strip()
        if len(text) >= 2 and text[0] == text[-1] and text[0] in "\"'":
            return text[1:-1]
    return value


def _resolve_inventory_handle(value: str) -> str:
    """Lazy: `models.inference` is large and the CLI imports this module without needing it."""
    try:
        from models.inference import resolve_inventory_handle
    except Exception:  # noqa: BLE001 -- a resolver that cannot import must not fail a run
        return value
    return resolve_inventory_handle(value)


# The strings trainer.normalize_gradient_checkpointing turns into False.
_CHECKPOINTING_OFF = ("false", "0", "no", "none", "off")


class DrafterTrainingConfig(BaseModel):
    """Optional speculative-decoding drafter trained after the fine-tune (omitted or disabled = off)."""

    enabled: bool = False
    strategy: Literal["auto", "mtp", "eagle3"] = "auto"
    data_source: Literal["dataset", "regenerate"] = "dataset"
    max_examples: int = Field(2000, ge = 16, le = 100000)
    epochs: float = Field(1.0, ge = 0.1, le = 20)
    learning_rate: Optional[float] = Field(None, gt = 0, le = 1.0)
    draft_steps: int = Field(3, ge = 1, le = 8)

    @field_validator("max_examples", "draft_steps", "epochs", mode = "before")
    @classmethod
    def _reject_booleans(cls, value: Any) -> Any:
        if isinstance(value, bool):
            raise ValueError("expected a number, not a boolean")
        return value


class TrainingStartRequest(BaseModel):
    """Request schema for starting training"""

    model_name: str = Field(
        ..., description = "Model identifier (e.g., 'unsloth/llama-3-8b-bnb-4bit')"
    )
    # The same identity the picker was shown; see `resolve_inventory_handle`.
    _resolve_the_handle = field_validator("model_name")(_resolve_inventory_handle)
    project_name: Optional[str] = Field(
        None,
        max_length = 80,
        description = "Optional user-defined project name appended to run folders and shown in history",
    )
    start_request_id: Optional[str] = Field(
        None,
        min_length = 1,
        max_length = 128,
        pattern = TRAINING_REQUEST_ID_PATTERN,
        description = "Opaque client-generated identifier used to reconcile an ambiguous start response",
    )
    training_type: Literal["LoRA/QLoRA", "Full Finetuning", "Continued Pretraining"] = Field(
        ...,
        description = "Training type: 'LoRA/QLoRA', 'Full Finetuning', or 'Continued Pretraining'",
    )
    hf_token: Optional[str] = Field(None, description = "HuggingFace token")
    load_in_4bit: bool = Field(True, description = "Load model in 4-bit quantization")
    max_seq_length: int = Field(2048, description = "Maximum sequence length")
    vision_image_size: Optional[int] = Field(
        None,
        description = "Optional maximum image side length for VLM training. Null uses model default.",
    )
    trust_remote_code: bool = Field(
        False,
        description = "Allow loading models with custom code (e.g. NVIDIA Nemotron). Only enable for repos you trust.",
    )
    approved_remote_code_fingerprint: Optional[str] = Field(
        None,
        description = "sha256 fingerprint from the remote-code scan, pinning user approval of this exact custom-code version.",
    )
    model_known_cached: bool = Field(
        False,
        description = "Whether the selected model is already present in the local HF cache",
    )
    model_local_path: Optional[str] = Field(
        None,
        description = "Local HF cache path for the selected model, when known",
    )
    model_format: Optional[ModelFormat] = Field(
        None,
        description = "On-disk format of the selected model, when known",
    )
    model_snapshot_path: Optional[str] = Field(
        None,
        description = "Server-verified model snapshot directory pinned for this run",
    )

    hf_dataset: Optional[str] = Field(None, description = "HuggingFace dataset identifier")
    dataset_known_cached: bool = Field(
        False,
        description = "Whether the selected HF dataset is already present in the local cache",
    )
    dataset_local_path: Optional[str] = Field(
        None,
        description = "Local HF cache path for the selected dataset, when known",
    )
    dataset_snapshot_path: Optional[str] = Field(
        None,
        description = "Server-verified dataset snapshot directory pinned for this run",
    )
    local_datasets: List[str] = Field(
        default_factory = list, description = "List of local dataset paths"
    )
    local_eval_datasets: List[str] = Field(
        default_factory = list, description = "List of local eval dataset paths"
    )
    # The history detail references these, and Resume replays that payload.
    _resolve_the_dataset_handles = field_validator("local_datasets", "local_eval_datasets")(
        _resolve_inventory_handles
    )
    format_type: str = Field(..., description = "Dataset format type")
    subset: Optional[str] = None
    train_split: Optional[str] = Field("train", description = "Training split name")
    eval_split: Optional[str] = Field(None, description = "Eval split name. None = auto-detect")
    dataset_streaming: bool = Field(
        False,
        description = "Whether to load the Hugging Face dataset in streaming mode",
    )
    eval_steps: float = Field(0.00, description = "Fraction of total steps between evals (0-1)")
    early_stopping_patience: int = Field(
        0,
        ge = 0,
        le = 1000,
        description = "Stop after this many evaluations without a lower eval loss and keep the best weights. 0 = off",
    )
    drafter: Optional[DrafterTrainingConfig] = Field(
        None,
        description = "Train a speculative-decoding drafter (MTP head or EAGLE-3) after the fine-tune",
    )
    dataset_slice_start: Optional[int] = Field(
        None,
        ge = 0,
        le = _MAX_DATASET_SLICE_INDEX,
        description = "Inclusive start row index for dataset slicing",
    )
    dataset_slice_end: Optional[int] = Field(
        None,
        ge = 0,
        le = _MAX_DATASET_SLICE_INDEX,
        description = "Inclusive end row index for dataset slicing",
    )

    @model_validator(mode = "before")
    @classmethod
    def _compat_split(cls, values: Any) -> Any:
        """Accept legacy 'split' field as alias for 'train_split'."""
        if isinstance(values, dict) and "split" in values:
            values.setdefault("train_split", values.pop("split"))
        return values

    @field_validator("project_name")
    @classmethod
    def _normalize_project_name(cls, value: Optional[str]) -> Optional[str]:
        return normalize_project_name(value)

    @field_validator("early_stopping_patience", mode = "before")
    @classmethod
    def _reject_boolean_patience(cls, value: Any) -> Any:
        if isinstance(value, bool):
            raise ValueError("early_stopping_patience must be a number, not a boolean")
        return value

    @field_validator("eval_steps", mode = "before")
    @classmethod
    def _normalize_eval_steps(cls, value: Any) -> Any:
        # float is not strict, so `"eval_steps": true` would arrive as 1.0, a cadence of every step.
        if isinstance(value, bool):
            raise ValueError("eval_steps must be a number, not a boolean")
        # JSON 1e309 coerces to inf; store as disabled so config_json has no `Infinity`.
        try:
            if not math.isfinite(float(value)):
                return 0.0
        except OverflowError:
            # float() refuses a JSON int too large to represent: same unusable cadence as inf.
            return 0.0
        except (TypeError, ValueError):
            pass
        return value

    # After-validators run in definition order; keep these order-independent.
    @model_validator(mode = "after")
    def _validate_dataset_slice(self) -> "TrainingStartRequest":
        # start == end is intentionally allowed (a deliberate single-row slice); the trainer warns.
        if (
            self.dataset_slice_start is not None
            and self.dataset_slice_end is not None
            and self.dataset_slice_end < self.dataset_slice_start
        ):
            raise ValueError(
                "dataset_slice_end must be greater than or equal to dataset_slice_start"
            )
        return self

    @field_validator("hf_dataset")
    @classmethod
    def _check_hf_dataset(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > 256:
            raise ValueError("hf_dataset is too long (max 256 chars)")
        if ".." in v:
            raise ValueError("hf_dataset must not contain '..'")
        if any(_HF_DATASET_ID_SEGMENT_RE.fullmatch(segment) is None for segment in v.split("/")):
            raise ValueError("hf_dataset contains invalid characters or path segments")
        return v

    @field_validator("subset")
    @classmethod
    def _check_subset(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > MAX_HF_DATASET_OPTION_LENGTH:
            raise ValueError(f"subset is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars)")
        if not valid_hf_dataset_config_name(v):
            raise ValueError("subset contains invalid characters")
        return v

    @field_validator(
        "model_local_path",
        "dataset_local_path",
        "model_snapshot_path",
        "dataset_snapshot_path",
    )
    @classmethod
    def _check_cache_local_path(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        # Resolve the handle first so checks below run on the path.
        v = _resolve_inventory_handle(v.strip())
        if not v:
            return None
        if len(v) > 4096:
            raise ValueError("local cache path is too long (max 4096 chars)")
        if "\x00" in v:
            raise ValueError("local cache path contains invalid characters")
        if ".." in Path(v).parts or ".." in PureWindowsPath(v).parts:
            raise ValueError("local cache path must not contain '..' segments")
        return v

    @field_validator("train_split", "eval_split")
    @classmethod
    def _check_split_name(cls, v: Optional[str]) -> Optional[str]:
        if v is None:
            return v
        v = v.strip()
        if not v:
            return None
        if len(v) > MAX_HF_DATASET_OPTION_LENGTH:
            raise ValueError(f"split name is too long (max {MAX_HF_DATASET_OPTION_LENGTH} chars)")
        if not valid_hf_dataset_split_instruction(v):
            raise ValueError("split name contains invalid characters")
        return v

    @field_validator("learning_rate", mode = "before")
    @classmethod
    def _check_learning_rate(cls, v):
        # Stringify because downstream call sites float() it themselves.
        lr = _parse_lr(v)
        return str(lr)

    @field_validator("batch_size")
    @classmethod
    def _check_batch_size(cls, v: int) -> int:
        if v is None:
            raise ValueError("batch_size is required")
        if v < 1 or v > _MAX_BATCH_SIZE:
            raise ValueError(f"batch_size must be in [1, {_MAX_BATCH_SIZE}] (got {v!r})")
        return v

    @field_validator("gradient_accumulation_steps")
    @classmethod
    def _check_grad_accum(cls, v: int) -> int:
        if v is None:
            return 1
        if v < 1 or v > _MAX_GRAD_ACCUM:
            raise ValueError(
                f"gradient_accumulation_steps must be in [1, {_MAX_GRAD_ACCUM}] (got {v!r})"
            )
        return v

    @field_validator("num_epochs")
    @classmethod
    def _check_num_epochs(cls, v: int) -> int:
        # 0 is the frontend's sentinel for "use max_steps instead".
        if v is None:
            return 1
        if v < 0 or v > _MAX_EPOCHS:
            raise ValueError(f"num_epochs must be in [0, {_MAX_EPOCHS}] (got {v!r})")
        return v

    @field_validator("max_steps")
    @classmethod
    def _check_max_steps(cls, v: Optional[int]) -> Optional[int]:
        # 0 is the frontend's sentinel for "use num_epochs instead".
        if v is None:
            return v
        if not isinstance(v, int) or v < 0 or v > _MAX_STEPS:
            raise ValueError(f"max_steps must be a non-negative int <= {_MAX_STEPS} (got {v!r})")
        return v

    @field_validator("max_seq_length")
    @classmethod
    def _check_max_seq_length(cls, v: int) -> int:
        if v is None or v < 1 or v > _MAX_SEQ_LENGTH:
            raise ValueError(f"max_seq_length must be in [1, {_MAX_SEQ_LENGTH}] (got {v!r})")
        return v

    @field_validator("vision_image_size", mode = "before")
    @classmethod
    def _check_vision_image_size(cls, v: Any) -> Optional[int]:
        # mode="before" sees True/False as bool (not 1/0) for a precise error.
        if v is None:
            return v
        if isinstance(v, bool):
            raise ValueError("vision_image_size must be an integer or null")
        if isinstance(v, int):
            coerced = v
        elif isinstance(v, str) and _INT_RE.fullmatch(v.strip()):
            coerced = int(v.strip())
        elif isinstance(v, float) and v.is_integer():
            coerced = int(v)
        else:
            # numpy ints / Integral subclasses, without a hard numpy import.
            try:
                import numbers
                if isinstance(v, numbers.Integral):
                    coerced = int(v)
                elif isinstance(v, numbers.Real) and float(v).is_integer():
                    coerced = int(v)
                else:
                    raise TypeError
            except Exception:
                raise ValueError("vision_image_size must be an integer or null")
        if coerced < _MIN_VISION_IMAGE_SIZE or coerced > _MAX_VISION_IMAGE_SIZE:
            raise ValueError(
                f"vision_image_size must be in [{_MIN_VISION_IMAGE_SIZE}, "
                f"{_MAX_VISION_IMAGE_SIZE}] (got {coerced!r})"
            )
        return coerced

    @field_validator("warmup_steps")
    @classmethod
    def _check_warmup_steps(cls, v: Optional[int]) -> Optional[int]:
        if v is None:
            return v
        if not isinstance(v, int) or v < 0 or v > _MAX_STEPS:
            raise ValueError(f"warmup_steps must be a non-negative int <= {_MAX_STEPS} (got {v!r})")
        return v

    @field_validator("warmup_ratio")
    @classmethod
    def _check_warmup_ratio(cls, v):
        if v is None:
            return v
        try:
            r = float(v)
        except (TypeError, ValueError):
            raise ValueError(f"warmup_ratio must be a number (got {v!r})")
        if not (0.0 <= r <= 1.0):
            raise ValueError(f"warmup_ratio must be in [0.0, 1.0] (got {r!r})")
        return r

    @field_validator("save_steps")
    @classmethod
    def _check_save_steps(cls, v: int) -> int:
        if v is None:
            return 100
        if v < 0 or v > _MAX_STEPS:
            raise ValueError(f"save_steps must be in [0, {_MAX_STEPS}] (got {v!r})")
        return v

    @field_validator("weight_decay")
    @classmethod
    def _check_weight_decay(cls, v: float) -> float:
        if v is None:
            return 0.0
        try:
            wd = float(v)
        except (TypeError, ValueError):
            raise ValueError(f"weight_decay must be a number (got {v!r})")
        if wd < 0 or wd > 10.0:
            raise ValueError(f"weight_decay must be in [0, 10] (got {wd!r}); typical 0..0.1")
        return wd

    @field_validator("lora_r")
    @classmethod
    def _check_lora_r(cls, v: int) -> int:
        if v is None:
            return 16
        if v < 1 or v > _MAX_LORA_R:
            raise ValueError(f"lora_r must be in [1, {_MAX_LORA_R}] (got {v!r})")
        return v

    @field_validator("lora_alpha")
    @classmethod
    def _check_lora_alpha(cls, v: int) -> int:
        if v is None:
            return 16
        if v < 1 or v > _MAX_LORA_ALPHA:
            raise ValueError(f"lora_alpha must be in [1, {_MAX_LORA_ALPHA}] (got {v!r})")
        return v

    @field_validator("lora_dropout")
    @classmethod
    def _check_lora_dropout(cls, v: float) -> float:
        if v is None:
            return 0.0
        try:
            d = float(v)
        except (TypeError, ValueError):
            raise ValueError(f"lora_dropout must be a number (got {v!r})")
        if not (0.0 <= d < 1.0):
            raise ValueError(f"lora_dropout must be in [0.0, 1.0) (got {d!r})")
        return d

    custom_format_mapping: Optional[Dict[str, Any]] = Field(
        None,
        description = (
            "User-provided column-to-role mapping, e.g. {'image': 'image', 'caption': 'text'} "
            "for VLM or {'instruction': 'user', 'output': 'assistant'} for LLM. "
            "Enhanced format includes __system_prompt, __user_template, "
            "__assistant_template, __label_mapping metadata keys."
        ),
    )
    num_epochs: int = Field(1, description = "Number of training epochs")
    learning_rate: str = Field("2e-4", description = "Learning rate")
    batch_size: int = Field(1, description = "Batch size")
    gradient_accumulation_steps: int = Field(1, description = "Gradient accumulation steps")
    warmup_steps: Optional[int] = Field(None, description = "Warmup steps")
    warmup_ratio: Optional[float] = Field(None, description = "Warmup ratio")
    max_steps: Optional[int] = Field(None, description = "Maximum training steps")
    save_steps: int = Field(100, description = "Steps between checkpoints")
    # NaN clears _check_weight_decay's 0..10 range check (every comparison with it is False), so it is refused here.
    weight_decay: float = Field(0.001, allow_inf_nan = False, description = "Weight decay")
    # Reject inf too: JSON 1e309 parses to inf, which passes ge=0 but never binds the clip.
    max_grad_norm: Optional[float] = Field(
        None,
        ge = 0,
        allow_inf_nan = False,
        description = (
            "Global gradient norm clipping threshold. Unset keeps the training "
            "backend's own default; 0 turns global-norm clipping off, which on "
            "MLX leaves per-parameter clipping in force unless max_grad_leaf_norm "
            "is also 0. Honored on MLX; the CUDA path trains with its own fixed "
            "thresholds."
        ),
    )
    max_grad_value: Optional[float] = Field(
        None,
        ge = 0,
        allow_inf_nan = False,
        description = (
            "MLX-only elementwise gradient value clipping threshold. "
            "If unset, MLX uses its runtime default."
        ),
    )
    max_grad_leaf_norm: Optional[float] = Field(
        None,
        ge = 0,
        allow_inf_nan = False,
        description = (
            "MLX-only proportional per-parameter gradient norm cap. "
            "Preserves each tensor's gradient direction without global norm "
            "clipping's memory overhead."
        ),
    )
    cast_norm_output_to_input_dtype: bool = Field(
        True,
        description = (
            "MLX-only: keep norm parameters in fp32 but cast norm outputs "
            "back to the incoming activation dtype."
        ),
    )
    # numpy's range (transformers.set_seed): out of it, the run only fails after the model loads.
    random_seed: int = Field(
        3407,
        ge = 0,
        le = 2**32 - 1,
        description = (
            "Random seed; matches the Unsloth backend / MLX worker default "
            "and unsloth's historical recommended value."
        ),
    )
    packing: bool = Field(True, description = "Enable sequence packing where supported")
    optim: str = Field("adamw_8bit", description = "Optimizer")
    lr_scheduler_type: str = Field("linear", description = "Learning rate scheduler type")
    embedding_learning_rate: Optional[float] = Field(
        None,
        gt = 0,
        lt = 1.0,
        description = "Separate learning rate for embedding matrices (CPT). "
        "Must be in (0, 1). Should be 2-10x smaller than the main learning rate.",
    )

    use_lora: bool = Field(True, description = "Use LoRA (derived from training_type)")
    lora_r: int = Field(16, description = "LoRA rank")
    lora_alpha: int = Field(16, description = "LoRA alpha")
    lora_dropout: float = Field(0.0, description = "LoRA dropout")
    target_modules: List[str] = Field(default_factory = list, description = "Target modules for LoRA")
    gradient_checkpointing: str = Field("", description = "Gradient checkpointing setting")
    offload_layers: Union[Literal["auto"], Annotated[int, Field(ge = 0, le = 1024)]] = Field(
        0,
        description = "Decoder layers kept in host RAM and streamed to the GPU during training "
        "(0 = off, 'auto' = as few as fit)",
    )
    offload_vram_gb: Optional[float] = Field(
        None,
        gt = 0,
        le = 4096,
        description = "VRAM this run may use, in GiB; offload_layers = 'auto' sizes to it",
    )
    offload_vram_gb_per_device: Optional[List[Optional[Annotated[float, Field(gt = 0, le = 4096)]]]] = (
        Field(
            None,
            max_length = 64,
            description = "Per-GPU VRAM budget in GiB, entry i for the GPU /api/system lists as index i "
            "(null = no cap); replaces offload_vram_gb when given",
        )
    )
    prefetch_depth: Union[Literal["auto"], Annotated[int, Field(ge = 1, le = 8)]] = Field(
        2,
        description = "Offloaded layers fetched ahead of the one running ('auto' = measured)",
    )
    use_rslora: bool = Field(False, description = "Use RSLoRA")
    use_loftq: bool = Field(False, description = "Use LoftQ")
    use_dora: bool = Field(False, description = "Use DoRA")
    train_on_completions: bool = Field(
        True, description = "Train on assistant completions where supported"
    )

    finetune_vision_layers: bool = Field(False, description = "Finetune vision layers")
    finetune_language_layers: bool = Field(True, description = "Finetune language layers")
    finetune_attention_modules: bool = Field(True, description = "Finetune attention modules")
    finetune_mlp_modules: bool = Field(True, description = "Finetune MLP modules")
    is_dataset_image: bool = Field(False, description = "Whether the dataset contains image data")
    is_dataset_audio: bool = Field(False, description = "Whether the dataset contains audio data")
    is_embedding: bool = Field(
        False, description = "Whether model is an embedding/sentence-transformer model"
    )
    is_decision: bool = Field(
        False,
        description = "Train a decision model: a Laya or Clef checkpoint, or an LLM with a new Clef head",
    )
    model_subfolder: Optional[str] = Field(
        None, description = "Checkpoint subfolder of a decision model repo"
    )
    decision_layout: Optional[Literal["laya", "clef", "llm"]] = Field(
        None,
        description = "Set by the server from the checkpoint files; a caller's value is replaced",
    )
    decision_head: Optional[Literal["clef", "d1"]] = Field(
        None,
        description = "What a language model trains into: a Clef head, or a d1 on MLX for LFM3-VL and LFM3-Omni, the default there",
    )

    enable_wandb: bool = Field(False, description = "Enable Weights & Biases logging")
    wandb_token: Optional[str] = Field(None, description = "W&B token")
    wandb_project: Optional[str] = Field(None, description = "W&B project name")
    enable_tensorboard: bool = Field(False, description = "Enable TensorBoard logging")
    tensorboard_dir: Optional[str] = Field(None, description = "TensorBoard directory")
    resume_from_checkpoint: Optional[str] = Field(
        None, description = "Saved training output directory to resume from"
    )
    # The history detail hands out a handle for the resumable directory; Resume sends it back.
    _resolve_the_resume_handle = field_validator("resume_from_checkpoint")(
        _resolve_inventory_handle
    )

    gpu_ids: Optional[List[int]] = Field(
        None,
        description = (
            "Physical GPU indices to use, for example [0, 1]. Omit or pass "
            "[] to use automatic selection. Explicit gpu_ids are unsupported "
            "when the parent visibility mask uses non-numeric or subdevice "
            "entries -- this includes CUDA_VISIBLE_DEVICES with MIG or "
            "unresolvable UUID entries on NVIDIA, and ZE_AFFINITY_MASK with subdevice tokens "
            "(e.g. '0.0,0.1') or FLAT-hierarchy (default) tile handles on "
            "Intel XPU."
        ),
    )

    s3_config: Optional[S3Config] = Field(
        None,
        description = 'S3 bucket configuration. Missing SDK installs on first use; preinstall offline support with: python -m pip install "unsloth[s3]"',
    )

    @field_validator("target_modules", mode = "before")
    @classmethod
    def _normalize_target_modules(cls, value: Any) -> Any:
        # Sanitized non-LoRA history stores the unused value as null; treat it as an omitted list.
        return [] if value is None else value

    @model_validator(mode = "after")
    def _default_training_objective_toggles(self) -> "TrainingStartRequest":
        # getattr: validate_assignment on a model_construct() instance lacks required fields.
        non_chat = getattr(self, "is_embedding", False) or getattr(self, "is_decision", False)
        if "packing" not in self.model_fields_set and non_chat:
            self.packing = False
        if "train_on_completions" not in self.model_fields_set and (
            non_chat
            or getattr(self, "dataset_streaming", False)
            or getattr(self, "training_type", None) == "Continued Pretraining"
            or getattr(self, "format_type", None) in ("raw", "raw_text")
        ):
            self.train_on_completions = False
        return self

    @model_validator(mode = "after")
    def _validate_streaming_splits(self) -> "TrainingStartRequest":
        # Streaming load_dataset rejects HF slice syntax ("Bad split").
        if self.dataset_streaming:
            for field_name, split_val in (
                ("train_split", self.train_split),
                ("eval_split", self.eval_split),
            ):
                if split_val is not None and not valid_hf_dataset_split_name(split_val):
                    raise ValueError(
                        f"dataset_streaming requires a plain split name in {field_name} "
                        f"(got {split_val!r}); use a name such as 'train' or 'validation'."
                    )
        return self

    @model_validator(mode = "after")
    def _check_steps_or_epochs(self) -> "TrainingStartRequest":
        # Each accepts 0 as "use the other"; both 0 means nothing to train.
        if (self.max_steps is None or self.max_steps == 0) and self.num_epochs == 0:
            raise ValueError("Either num_epochs or max_steps must be > 0; both cannot be 0.")
        return self

    @model_validator(mode = "after")
    def _check_offload_has_checkpointing(self) -> "TrainingStartRequest":
        # install_block_swap refuses swapped layers without checkpointing; say so before loading.
        if (
            self.offload_layers
            and self.training_type != "Full Finetuning"
            and self.gradient_checkpointing.strip().lower() in _CHECKPOINTING_OFF
        ):
            raise ValueError(
                "offload_layers needs gradient checkpointing: set gradient_checkpointing to "
                "'unsloth' or 'true', or offload_layers to 0."
            )
        return self

    @model_validator(mode = "after")
    def _validate_lora_variant_flags(self) -> "TrainingStartRequest":
        # Direct API, YAML or CLI callers bypass the frontend, so reject variant flag conflicts early.
        active = [
            name
            for name, enabled in (
                ("use_rslora", self.use_rslora),
                ("use_loftq", self.use_loftq),
                ("use_dora", self.use_dora),
            )
            if enabled
        ]
        if len(active) > 1:
            raise ValueError(
                f"Only one LoRA variant may be enabled at a time; got {active}. "
                "use_rslora, use_loftq, and use_dora are mutually exclusive."
            )
        # getattr: model_construct() leaves required fields unset and this still runs.
        if getattr(self, "training_type", None) == "Full Finetuning" and active:
            raise ValueError(
                f"{active[0]} requires an adapter method (LoRA/QLoRA or "
                "Continued Pretraining); it has no effect under Full Finetuning."
            )
        return self

    @model_validator(mode = "after")
    def _validate_drafter(self) -> "TrainingStartRequest":
        drafter = getattr(self, "drafter", None)
        if drafter is None or not drafter.enabled:
            return self
        if getattr(self, "is_embedding", False) or getattr(self, "is_decision", False):
            raise ValueError("drafter training is only available for text generation models.")
        if getattr(self, "training_type", None) == "Continued Pretraining":
            raise ValueError("drafter training is not available for continued pretraining.")
        return self


class TrainingJobResponse(BaseModel):
    """Immediate response when training is initiated"""

    job_id: str = Field(..., description = "Unique training job identifier")
    status: Literal["pending", "queued", "error"] = Field(..., description = "Initial job status")
    message: str = Field(..., description = "Human-readable status message")
    error: Optional[str] = Field(None, description = "Error details if status is 'error'")
    error_code: Optional[str] = Field(None, description = "Stable error code if status is 'error'")


class TokenPreviewRequest(BaseModel):
    """How a training run would tokenize and mask a few dataset rows, or ``text`` when given. Only
    the model's tokenizer is read, never its weights."""

    model_name: str = Field(..., min_length = 1)
    model_type: Optional[str] = None
    load_in_4bit: bool = True
    dataset_name: Optional[str] = None
    subset: Optional[str] = None
    train_split: Optional[str] = None
    dataset_local_path: Optional[str] = None
    dataset_known_cached: bool = False
    format_type: str = "auto"
    custom_format_mapping: Optional[Dict[str, Any]] = None
    train_on_completions: bool = True
    is_cpt: bool = False
    max_seq_length: int = Field(2048, ge = 1, le = 1_048_576)
    num_samples: int = Field(3, ge = 1, le = 8)
    seed: int = 0
    text: Optional[str] = Field(None, max_length = 200_000)
    # The dataset's format from an earlier preview, so typed text gets the template and markers it would.
    final_format: Optional[str] = None

    _resolve_the_handles = field_validator("model_name", "dataset_name")(_resolve_inventory_handle)


class TrainingStartRequestStatus(BaseModel):
    start_request_id: str
    job_id: str
    state: Literal["pending", "accepted", "rejected"]
    message: str
    error: Optional[str] = None
    error_code: Optional[str] = None


class TrainingStatus(BaseModel):
    """Current training job status - works for streaming or polling"""

    job_id: str = Field(..., description = "Training job identifier")
    start_request_id: Optional[str] = Field(
        None, description = "Client-generated identifier for the current training start request"
    )
    start_request_state: Optional[Literal["pending", "accepted", "rejected"]] = Field(
        None, description = "Lifecycle state of the current training start request"
    )
    phase: Literal[
        "idle",
        "loading_model",
        "loading_dataset",
        "configuring",
        "training",
        "training_drafter",
        "finalizing",
        "completed",
        "error",
        "stopped",
    ] = Field(..., description = "Current phase of training pipeline")
    is_training_running: bool = Field(..., description = "True if training loop is actively running")
    eval_enabled: bool = Field(
        False,
        description = "True if evaluation dataset is configured for this training run",
    )
    message: str = Field(..., description = "Human-readable status message")
    error: Optional[str] = Field(None, description = "Error details if phase is 'error'")
    warnings: List[str] = Field(
        default_factory = list,
        description = "Non-fatal warnings retained for the current training run",
    )
    details: Optional[dict] = Field(
        None, description = "Phase-specific info, e.g. {'model_size': '8B'}"
    )
    metric_history: Optional[dict] = Field(
        None,
        description = "Full metric history arrays for chart recovery after SSE reconnection. "
        "Keys: 'steps', 'loss', 'lr', 'grad_norm', 'grad_norm_steps' — each a list of numeric values.",
    )


class TrainingProgress(BaseModel):
    """Training progress metrics - for streaming or polling"""

    job_id: str = Field(..., description = "Training job identifier")
    step: int = Field(..., description = "Current training step")
    total_steps: int = Field(..., description = "Total training steps")
    loss: Optional[float] = Field(None, description = "Current loss value")
    learning_rate: Optional[float] = Field(None, description = "Current learning rate")
    progress_percent: float = Field(..., description = "Progress percentage (0.0 to 100.0)")
    epoch: Optional[float] = Field(None, description = "Current epoch")
    elapsed_seconds: Optional[float] = Field(
        None, description = "Time elapsed since training started"
    )
    eta_seconds: Optional[float] = Field(None, description = "Estimated time remaining")
    session_start_step: Optional[int] = Field(
        None, description = "Step this session started from (non-zero on a resumed run)"
    )
    grad_norm: Optional[float] = Field(
        None, description = "L2 norm of gradients, computed before gradient clipping"
    )
    num_tokens: Optional[int] = Field(None, description = "Total number of tokens processed so far")
    eval_loss: Optional[float] = Field(
        None, description = "Eval loss from the most recent evaluation step"
    )


class TrainingRunSummary(BaseModel):
    """Summary of a training run for list views."""

    id: str
    status: Literal["running", "completed", "stopped", "error"]
    model_name: str
    project_name: Optional[str] = None
    dataset_name: str
    display_name: Optional[str] = None
    started_at: str
    ended_at: Optional[str] = None
    total_steps: Optional[int] = None
    final_step: Optional[int] = None
    final_loss: Optional[float] = None
    output_dir: Optional[str] = None
    duration_seconds: Optional[float] = None
    error_message: Optional[str] = None
    loss_sparkline: Optional[List[float]] = None
    can_resume: bool = False
    # Why resume is unavailable when the reason is the recorded resource provenance rather than the checkpoint itself.
    resume_blocked_reason: Optional[str] = None
    resumed_later: bool = False
    artifacts_available: bool = False
    has_preview_model: bool = False
    preview_ref: Optional[str] = None
    # HMAC capability token for the `/p/{preview_ref}` share link, appended as `?k=`; None when not previewable.
    preview_sig: Optional[str] = None


class TrainingRunUpdateRequest(BaseModel):
    """Mutable fields on a training run."""

    model_config = ConfigDict(extra = "forbid")

    display_name: Optional[str] = Field(None, max_length = 120)


class TrainingRunListResponse(BaseModel):
    """Response for listing training runs."""

    runs: List[TrainingRunSummary]
    total: int


class TrainingRunMetrics(BaseModel):
    """Metrics arrays for a training run, using paired step arrays per metric."""

    step_history: List[int] = Field(default_factory = list)
    loss_history: List[float] = Field(default_factory = list)
    loss_step_history: List[int] = Field(default_factory = list)
    lr_history: List[float] = Field(default_factory = list)
    lr_step_history: List[int] = Field(default_factory = list)
    grad_norm_history: List[float] = Field(default_factory = list)
    grad_norm_step_history: List[int] = Field(default_factory = list)
    eval_loss_history: List[float] = Field(default_factory = list)
    eval_step_history: List[int] = Field(default_factory = list)
    final_epoch: Optional[float] = None
    final_num_tokens: Optional[int] = None


class TrainingRunDetailResponse(BaseModel):
    """Response for a single training run with config and metrics."""

    run: TrainingRunSummary
    config: dict
    metrics: TrainingRunMetrics


class TrainingRunDeleteResponse(BaseModel):
    """Response for deleting a training run."""

    status: str
    message: str
    artifacts_deleted: bool = False
    artifacts_kept_reason: Optional[Literal["shared_output_dir", "purge_failed"]] = None


class DiffusionTrainingStartRequest(BaseModel):
    """Request to start a diffusion (SDXL) LoRA training job.

    Field names mirror ``core.training.diffusion_lora_trainer.DiffusionLoraConfig`` so the
    service can pass ``model_dump()`` straight through. Only the paths are required; the
    rest carry the trainer's defaults.
    """

    model_config = ConfigDict(protected_namespaces = ())

    base_model: str = Field(..., description = "HF repo id or local path to a trainable base")
    # Unresolved, family detection and `_assert_trusted_base_model` read `ref:...` as a Hub id.
    _unquote_the_base = field_validator("base_model", mode = "before")(_unquote_pasted_path)
    _resolve_the_base_handle = field_validator("base_model")(_resolve_inventory_handle)
    data_dir: str = Field(..., description = "Folder of training images (+ captions)")
    output_dir: str = Field(..., description = "Directory to write the LoRA .safetensors into")
    # Resume replays the stored config, whose `output_dir` answers as a handle.
    _resolve_the_output_handle = field_validator("output_dir")(_resolve_inventory_handle)
    model_family: Optional[str] = Field(
        None,
        description = "Explicit trainer family (sdxl / flux.1 / ...); omitted = detect from base_model",
    )
    instance_prompt: Optional[str] = Field(
        None, description = "Dreambooth caption applied to images without their own caption"
    )
    resolution: int = Field(
        1024, ge = 64, le = 2048, description = "Square training resolution (multiple of 8)"
    )
    train_steps: int = Field(500, ge = 1, le = 100000)
    num_epochs: int = Field(
        0,
        ge = 0,
        le = 1000,
        description = (
            "0 = use train_steps; > 0 overrides train_steps with epochs x "
            "ceil(N / (batch x grad_accum)) optimizer steps over the N-image dataset"
        ),
    )
    # Upper bound too: JSON 1e309 becomes inf and passes gt-only; values >= 1.0 diverge, and an inf rate would evict residents.
    learning_rate: float = Field(1e-4, gt = 0, lt = 1.0)
    train_batch_size: int = Field(1, ge = 1, le = 64)
    gradient_accumulation_steps: int = Field(1, ge = 1, le = 256)
    lora_rank: int = Field(16, ge = 1, le = 320)
    lora_alpha: Optional[int] = Field(None, ge = 1, le = 640, description = "Defaults to lora_rank")
    # lt 1: dropout p=1.0 zeroes the LoRA branch and saves an untrained adapter.
    lora_dropout: float = Field(0.0, ge = 0.0, lt = 1.0)
    # Mirrors DiffusionLoraConfig knobs so set values are not silently dropped; defaults are SDXL's.
    lora_target_modules: List[str] = Field(
        default_factory = lambda: ["to_k", "to_q", "to_v", "to_out.0"],
        description = "U-Net modules to attach LoRA to",
    )
    # Finite: inf max_grad_norm means unclipped training.
    max_grad_norm: float = Field(
        1.0,
        ge = 0,
        allow_inf_nan = False,
        description = "Gradient clipping max-norm; 0 disables clipping",
    )
    # Bounded to what torch.manual_seed accepts: an out-of-range value passes preflight, evicts residents, then dies in the trainer.
    seed: int = Field(42, ge = -(2**63), le = 2**64 - 1)
    mixed_precision: Literal["bf16", "fp16", "no"] = Field("bf16")
    # Finite: inf gamma collapses min-SNR weights to 1.0.
    snr_gamma: Optional[float] = Field(
        5.0,
        gt = 0,
        allow_inf_nan = False,
        description = "Min-SNR loss weighting (SDXL only; flow-matching families ignore it); null disables",
    )
    gradient_checkpointing: bool = Field(True)
    lr_scheduler: Literal[
        "linear",
        "cosine",
        "cosine_with_restarts",
        "polynomial",
        "constant",
        "constant_with_warmup",
    ] = Field("constant")
    lr_warmup_steps: int = Field(0, ge = 0)
    center_crop: bool = Field(False)
    # Opt-in: mirroring teaches text, logos and one-sided features in both orientations.
    random_flip: bool = Field(
        False, description = "Randomly mirror training images left-right (augmentation)"
    )
    bucketing: Optional[bool] = Field(
        None,
        description = (
            "Aspect-ratio buckets: train each image on the same-area canvas nearest its aspect "
            "ratio instead of a square crop. null means on for a new run and, on a resume, what "
            "the checkpoint recorded (square for a run from before buckets existed). MiniMax-H3 "
            "always trains unbucketed."
        ),
    )
    caption_column: str = Field("text")
    hf_token: Optional[str] = Field(None)
    cache_latents: bool = Field(
        True, description = "Precompute VAE latents once and free the VAE for the run"
    )
    cache_variants: int = Field(
        4, ge = 1, le = 16, description = "Frozen crop/flip variants per image in the latent cache"
    )
    cond_cache_dir: Optional[str] = Field(
        None,
        description = (
            "Directory for the PERSISTENT conditioning cache (latents + text embeddings), reused "
            "across runs: a rerun whose images, captions and resolution are unchanged skips "
            "loading the VAE and the multi-GB text encoders entirely. Unsloth-relative names are "
            "resolved under the Unsloth outputs root and absolute paths must stay inside it. "
            "null or blank keeps the in-memory cache, which is rebuilt every run."
        ),
    )
    compile_transformer: Literal["off", "on", "auto"] = Field(
        "auto", description = "Regional torch.compile of the transformer blocks"
    )
    enable_tf32: bool = Field(
        True, description = "TF32 matmuls + cudnn autotuning (near-lossless speedup)"
    )
    base_precision: Literal["nf4", "bf16", "int8", "fp8", "mxfp8", "auto"] = Field(
        "nf4",
        description = (
            "DiT base transformer precision: nf4 QLoRA (memory floor, default), bf16 dense, "
            "int8 torchao weight-only, fp8 float8 training compute (Ada/Hopper/Blackwell), "
            "mxfp8 block-scaled float8 compute (Blackwell, best at high resolution/batch), "
            "or auto (pick by free VRAM + GPU class). Dense modes need a non-prequant base."
        ),
    )
    # DiT-only lever: undeclared, model_dump() silently dropped it. Defaults match DiffusionLoraConfig.
    ema_decay: float = Field(
        0.0, ge = 0.0, lt = 1.0, description = "EMA of the LoRA weights; 0 disables it"
    )
    cfg_dropout: float = Field(
        0.0, ge = 0.0, le = 1.0, description = "Chance of dropping the caption to an empty prompt"
    )
    weighting_scheme: Literal["none", "bell"] = Field(
        "none",
        description = (
            "Per-sample loss weighting over the drawn timestep: none (unweighted MSE) or bell "
            "(Gaussian bell centered mid-schedule). Timesteps are always logit-normal sampled."
        ),
    )
    flow_shift: Optional[Union[float, Literal["auto"]]] = Field(
        None,
        description = (
            "Flow-matching timestep shift, as the effective shift on the unshifted schedule "
            "(musubi / kohya discrete_flow_shift; 1.0 trains unshifted). null uses the family "
            "default: auto for qwen-image, ltx-2 and minimax-h3, otherwise the model's own "
            "scheduler shift (3.0 for Z-Image-Turbo, 6.0 for Z-Image)."
        ),
    )
    save_steps: int = Field(
        0,
        ge = 0,
        le = 100000,
        description = (
            "Write a resumable checkpoint every N optimizer steps. 0 (the default) writes no "
            "periodic checkpoints; a stop-and-save always writes one, so Resume stays available "
            "either way."
        ),
    )
    save_total_limit: int = Field(
        2, ge = 0, le = 100, description = "How many checkpoints to keep; 0 keeps every one"
    )
    sample_every: int = Field(
        0,
        ge = 0,
        le = 100000,
        description = (
            "Render fixed-seed preview images every N optimizer steps (plus a step-0 baseline and "
            "the final step). 0 (the default) renders none. Image families only."
        ),
    )
    sample_prompts: List[str] = Field(
        default_factory = list,
        max_length = 4,
        description = (
            "Preview prompts, one image each. Empty uses the instance prompt, else the first caption."
        ),
    )
    resume_from_checkpoint: Optional[str] = Field(
        None,
        description = (
            "Continue a previous run: its output_dir (the newest complete checkpoint inside it "
            "is used) or one explicit checkpoint-<N> directory. Must resolve inside the Unsloth "
            "outputs root, and must match this run's family, base model, dataset, LoRA "
            "configuration and precision. train_steps is then the TARGET TOTAL, so resuming a "
            "checkpoint at step 11 with train_steps=500 trains steps 12..500."
        ),
    )
    # Diffusion Resume replays `checkpoint_path` or the output dir; both answer as references.
    _resolve_the_resume_handle = field_validator("resume_from_checkpoint")(
        _resolve_inventory_handle
    )
    resumed_from_job_id: Optional[str] = Field(
        None,
        pattern = r"^[0-9a-f]{32}$",
        description = "The run this one continues, recorded in the history for lineage only",
    )


class DiffusionTrainingStopRequest(BaseModel):
    """Optional body for stopping a diffusion training job. ``save`` mirrors the LLM
    trainer's stop: True (default) exports the partial adapter, False cancels without
    leaving one behind."""

    save: bool = Field(True)


class DiffusionTrainingStartResponse(BaseModel):
    """Response for starting a diffusion training job."""

    job_id: str
    status: str


class DiffusionMetricHistory(BaseModel):
    """Paired step-indexed history arrays for the live training charts. Every series but
    ``loss`` may hold nulls so the sparse ones still align with ``steps`` by index."""

    steps: List[int] = Field(default_factory = list)
    loss: List[float] = Field(default_factory = list)
    lr: List[Optional[float]] = Field(default_factory = list)
    grad_norm: List[Optional[float]] = Field(default_factory = list)
    # Null for all families but MiniMax-H3; the chart uses that to decide whether to draw split curves.
    video_loss: List[Optional[float]] = Field(default_factory = list)
    audio_loss: List[Optional[float]] = Field(default_factory = list)


class DiffusionSampleImage(BaseModel):
    """One preview image; ``path`` is relative to the run's output_dir."""

    step: int
    path: str
    prompt: str = ""
    seed: Optional[int] = None


class DiffusionModelLoadProgress(BaseModel):
    done: int = Field(ge = 0)
    total: int = Field(gt = 0)
    unit: Literal["tensors", "components", "shards"]
    label: str


class DiffusionTrainingPreparation(BaseModel):
    stage: Optional[str] = None
    done: Optional[int] = None
    total: Optional[int] = None


class DiffusionTrainingDownloadProgress(BaseModel):
    bytes_done: int = Field(default = 0, ge = 0)
    bytes_total: int = Field(default = 0, ge = 0)
    label: str = "Model files"
    scope: str = "active_files"


class DiffusionTrainingStatusResponse(BaseModel):
    """A snapshot of the current diffusion training job (or idle)."""

    active: bool
    job_id: Optional[str] = None
    status: str
    message: str = ""
    step: int = 0
    total_steps: int = 0
    loss: Optional[float] = None
    avg_loss: Optional[float] = None
    learning_rate: Optional[float] = None
    # Total pre-clip gradient norm from the last optimizer step (health signal the UI charts).
    grad_norm: Optional[float] = None
    # The combined loss can hold steady while one modality degrades, so these are reported apart.
    video_loss: Optional[float] = None
    audio_loss: Optional[float] = None
    num_images: Optional[int] = None
    in_model_load: bool = False
    preparation: Optional[DiffusionTrainingPreparation] = None
    model_load_stage: Optional[Literal["conditioning", "transformer", "quantizing"]] = None
    model_load_progress: Optional[DiffusionModelLoadProgress] = None
    download_progress: Optional[DiffusionTrainingDownloadProgress] = None
    output_dir: Optional[str] = None
    lora_path: Optional[str] = None
    # The second, EMA-averaged adapter written in the run's ema subdir when ema_decay was enabled.
    ema_path: Optional[str] = None
    # Catalog mirror path plus the family and base model, so the UI can deploy the adapter.
    catalog_path: Optional[str] = None
    family: Optional[str] = None
    base_model: Optional[str] = None
    # Live throughput + peak VRAM (from the trainer's progress events).
    samples_per_second: Optional[float] = None
    peak_memory_gb: Optional[float] = None
    # Newest bundle and step, why it could not be written (Resume tooltip), and where a resume started.
    checkpoint_path: Optional[str] = None
    checkpoint_step: Optional[int] = None
    resume_blocked_reason: Optional[str] = None
    resumed_from_step: Optional[int] = None
    started_at: Optional[float] = None
    updated_at: Optional[float] = None
    # Bounded step/loss/lr history for the live loss + LR charts.
    metric_history: Optional[DiffusionMetricHistory] = None
    samples: List[DiffusionSampleImage] = Field(default_factory = list)


class DiffusionTrainingRunSummary(BaseModel):
    """One persisted diffusion training run (terminal), as listed in the Train tab's
    previous-runs history. The heavy payload (config + metric logs) lives in the detail."""

    job_id: str
    status: str
    message: str = ""
    adapter: Optional[str] = None
    family: Optional[str] = None
    base_model: Optional[str] = None
    step: int = 0
    total_steps: int = 0
    avg_loss: Optional[float] = None
    # Whether this run left an adapter on disk (full completion or stop-and-save).
    saved: bool = False
    catalog_path: Optional[str] = None
    instance_prompt: Optional[str] = None
    started_at: Optional[float] = None
    ended_at: Optional[float] = None
    # The run's adapter directory, which is also what a Resume replays as resume_from_checkpoint.
    output_dir: Optional[str] = None
    # Re-derived from disk at read time, so deleting checkpoints removes the action.
    can_resume: bool = False
    checkpoint_step: Optional[int] = None
    # The exact bundle a resume would continue, not whatever is newest in a folder two runs share.
    checkpoint_path: Optional[str] = None
    resume_blocked_reason: Optional[str] = None
    # Lineage: the run this one continued, and the step it picked up from.
    resumed_from_job_id: Optional[str] = None
    resumed_from_step: Optional[int] = None


class DiffusionTrainingRunDetail(DiffusionTrainingRunSummary):
    """The full persisted record: summary + scrubbed start config + metric logs."""

    loss: Optional[float] = None
    samples_per_second: Optional[float] = None
    peak_memory_gb: Optional[float] = None
    num_images: Optional[int] = None
    lora_path: Optional[str] = None
    ema_path: Optional[str] = None
    config: Optional[dict] = None
    metric_history: Optional[DiffusionMetricHistory] = None
    samples: List[DiffusionSampleImage] = Field(default_factory = list)


class DiffusionTrainingRunsResponse(BaseModel):
    runs: List[DiffusionTrainingRunSummary] = Field(default_factory = list)


class DiffusionDatasetSummary(BaseModel):
    """One dataset folder under the Unsloth datasets root: images, clips, or both."""

    name: str
    path: str
    image_count: int
    # Clips for video-trained families; default 0 keeps older payloads and image-only callers valid.
    clip_count: int = 0
    caption_count: int


class DiffusionTrainableFamily(BaseModel):
    """A base-model family the diffusion trainer supports, with UI-facing metadata."""

    name: str
    label: str
    default_base: str
    base_repos: List[str] = Field(default_factory = list)
    defaults: dict = Field(default_factory = dict)
    vram_note: str = ""
    # vram_note's facts as fields. Empty when this host cannot train the family.
    params: str = ""
    qlora_vram_gb: Optional[int] = None
    gated: bool = False
    note: str = ""
    # base_precision modes this machine supports; empty means no selector, e.g. SDXL.
    precision_modes: List[str] = Field(default_factory = list)
    recommended_precision: str = "nf4"
    supports_compile: bool = False
    # save_steps is refused for checkpointless families; True keeps old payloads.
    supports_checkpoints: bool = True
    supports_samples: bool = False
    supports_bucketing: bool = True
    is_video: bool = False
    # 1 for a family whose forward covers one packed sequence: a value above the cap is refused rather
    # than clamped, and declaring it here is what stops Pydantic dropping it from the response.
    max_train_batch_size: Optional[int] = None
    # LoRA previews on this repo, not the training base (Krea trains on Raw, runs on Turbo).
    deploy_base: Optional[str] = None
    # maps each training base, including public mirrors, to its inference base.
    deploy_bases: Dict[str, str] = Field(default_factory = dict)
    # overlays checkpoint-specific parameter and VRAM guidance on family defaults.
    base_specs: Dict[str, dict] = Field(default_factory = dict)


class DiffusionTrainingInfoResponse(BaseModel):
    """lists paths, usable datasets, and UI-facing trainable families for this Unsloth instance."""

    datasets_root: str
    outputs_root: str
    datasets: List[DiffusionDatasetSummary]
    # includes every occupied folder name, even captions-only folders.
    dataset_names: List[str] = Field(default_factory = list)
    # occupied, unlisted folders that this upload form may safely continue.
    continuation_dataset_names: List[str] = Field(default_factory = list)
    families: List[DiffusionTrainableFamily] = Field(default_factory = list)


class DiffusionDatasetUploadResponse(BaseModel):
    """counts cover the whole folder after the upload, including earlier uploads."""

    name: str
    path: str
    image_count: int
    clip_count: int = 0
    caption_count: int
    uploaded: int


class DiffusionDatasetImageRecord(BaseModel):
    """One image in a training dataset folder, with its resolved caption. ``caption`` is
    null when no caption exists from any source; ``caption_source`` records where the
    shown caption came from (``metadata`` beats a per-image ``sidecar``; ``none`` when
    uncaptioned) so the labeling UI can highlight images that still need a caption."""

    filename: str
    caption: Optional[str] = None
    caption_source: Literal["sidecar", "metadata", "none"] = "none"
    # Clips are listed but have no pixel dimensions and the labeling grid skips them; default is image.
    kind: Literal["image", "clip"] = "image"
    width: int
    height: int
    size_bytes: int


class DiffusionDatasetImagesResponse(BaseModel):
    """Every item in a dataset folder (including uncaptioned ones), for the labeling grid."""

    name: str
    path: str
    images: List[DiffusionDatasetImageRecord]


class DiffusionCaptionUpdateRequest(BaseModel):
    """Write (or, when blank, clear) the per-image ``.txt`` caption sidecar."""

    caption: str = ""


class DiffusionDatasetExample(BaseModel):
    """A curated, one-click-importable example image dataset. ``image_cap`` bounds how many
    images are materialized; ``license`` is shown verbatim so users see the terms before
    importing; ``suggested_trigger`` seeds the trigger prompt for uncaptioned subject sets."""

    id: str
    label: str
    repo: str
    description: str
    license: str
    image_cap: int
    suggested_trigger: Optional[str] = None


class DiffusionDatasetExamplesResponse(BaseModel):
    """The curated example-dataset registry the Train tab offers for one-click import."""

    examples: List[DiffusionDatasetExample]


class DiffusionDatasetImportRequest(BaseModel):
    """Import a curated example (``id``) into a dataset folder (``name``; defaults to the
    example id)."""

    id: str
    name: Optional[str] = None


class DiffusionDatasetImportResponse(BaseModel):
    """Result of a one-click example import: folder counts plus provenance so the UI can
    show what was fetched and under what license."""

    name: str
    path: str
    image_count: int
    clip_count: int = 0
    caption_count: int
    imported: int
    license: str
    source_repo: str