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.

358 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 the Inference API."""

from __future__ import annotations

import re
import time
import uuid
from collections import deque
from typing import Annotated, Any, Dict, Literal, Optional, List, Union

from pydantic import (
    BaseModel,
    ConfigDict,
    Discriminator,
    Field,
    PrivateAttr,
    StrictFloat,
    StrictInt,
    Tag,
    field_validator,
    model_serializer,
    model_validator,
)

from core.inference.audio_workflows import status_audio_workflows
from core.inference.diffusion_conditioning import MAX_REQUEST_SIDE
from core.inference.llama_server_args import (
    BATCH_MAX,
    BATCH_MIN,
    CACHE_RAM_MAX_MIB,
    CTX_CHECKPOINTS_MAX,
    PARALLEL_MAX,
    PARALLEL_MIN,
)
from core.inference.runtime_context import MAX_REQUESTABLE_CONTEXT
from utils.upload_limits import VIDEO_INPUT_REFERENCE_JSON_MAX_BYTES
from core.inference.video_families import MAX_VIDEO_NUM_FRAMES
from picker.schemas import MAX_CHAT_TEMPLATE_BYTES
from models.providers import ProviderReasoningConfig, normalize_provider_extra_headers
from utils.reasoning_budget import validate_reasoning_budget_message

# A 24 MB reference audio as a base64 data URL, with room for its header.
_VIDEO_REFERENCE_AUDIO_MAX_CHARS = ((24 * 1024 * 1024 + 2) // 3) * 4 + 64 * 1024


def resolve_inventory_handle(value: str) -> str:
    """Turn a `ref:...` inventory identity back into the path it stands for. A reference this
    process did not issue is left as it arrived. Decides nothing about authorization."""
    if not isinstance(value, str) or not value.startswith("ref:"):
        return value
    try:
        from hub.utils.host_paths import note_resolved_handle, resolve_host_path_reference
    except Exception:  # noqa: BLE001 -- a resolver that cannot import must not fail loads
        return value
    resolved = resolve_host_path_reference(value)
    if not resolved:
        return value
    # Remembered for this request so the ANSWER carries the handle, not the path.
    note_resolved_handle(value, resolved)
    return resolved


MlxOffload = Optional[Union[Literal["auto", "off"], float]]


def _mlx_offload_amount(value: Any) -> Any:
    """``None`` (the default, as ``"auto"``), ``"auto"``, ``"off"``, or the fraction to read from
    disk, in (0, 1]."""
    if value is None or value in ("auto", "off"):
        return value
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 < value <= 1:
        raise ValueError("must be 'auto', 'off' or the fraction to keep on disk, in (0, 1]")
    return float(value)


class LoadRequest(BaseModel):
    """Request to load a model for inference"""

    engine_parallelism: Literal["tensor", "pipeline", "data"] = "tensor"
    engine_precision: Literal["auto", "bf16", "fp16", "int4", "int8", "fp8"] = "auto"
    engine_kv_cache_dtype: Literal["auto", "fp8"] = Field(
        "auto",
        description = "Managed engine KV cache dtype; 'fp8' halves KV cache memory (vLLM --kv-cache-dtype).",
    )
    engine_seed: Optional[int] = Field(
        None, ge = 0, le = 2**31 - 1, description = "Managed engine seed (vLLM --seed)."
    )
    engine_gpu_memory_utilization: Optional[float] = Field(
        None,
        ge = 0.05,
        le = 0.99,
        description = "Upper bound on the share of each selected GPU the managed engine may claim "
        "(vLLM --gpu-memory-utilization). Unset lets Unsloth size it from free memory.",
    )
    engine: Literal["auto", "vllm", "sglang"] = Field(
        "auto",
        description = "Inference engine to use. 'auto' selects Unsloth's default backend; "
        "'vllm' and 'sglang' require an installed optional engine.",
    )
    model_path: str = Field(..., description = "Model identifier or local path")
    _gguf_companion_roots: tuple[str, ...] = PrivateAttr(default = ())
    # `()` also means "do not widen", so this marks unset vs explicitly empty.
    _gguf_companion_roots_set: bool = PrivateAttr(default = False)
    # Auto-switch only: the owner-override alias, so the managed path-flag check reads the same row.
    _override_alias_id: Optional[str] = PrivateAttr(default = None)
    # The catalog id a load by path should keep advertising (Open WebUI /models/load).
    _advertised_id: Optional[str] = PrivateAttr(default = None)
    load_request_id: Optional[str] = Field(
        None,
        min_length = 1,
        max_length = 128,
        pattern = r"^[A-Za-z0-9][A-Za-z0-9._:-]*$",
        description = "Opaque client attempt ID for scoped in-flight cancellation",
    )

    force_reload: bool = Field(
        False,
        description = "Start a fresh runtime even when the active settings already match",
    )
    alongside: bool = Field(
        False,
        description = "Keep the loaded model and serve this one next to it",
    )
    force_alongside: bool = Field(
        False,
        description = "Load alongside even when it only partly fits the free GPU memory",
    )
    native_path_lease: Optional[str] = Field(
        None, description = "Frontend-visible signed native path grant"
    )
    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated models")
    max_seq_length: int = Field(
        0,
        ge = 0,
        le = MAX_REQUESTABLE_CONTEXT,
        description = (
            "Maximum sequence length. Send 0 to let a backend that sizes its own window "
            "(llama.cpp or MLX) choose the context itself."
        ),
    )
    max_seq_length_auto_derived: bool = Field(
        False,
        description = "max_seq_length is the previous load's fitted context, not a user choice",
    )
    load_in_4bit: bool = Field(True, description = "Load model in 4-bit quantization")
    is_lora: bool = Field(False, description = "Whether this is a LoRA adapter")
    gguf_variant: Optional[str] = Field(
        None, description = "GGUF quantization variant (e.g. 'Q4_K_M')"
    )
    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.",
    )
    chat_template_override: Optional[str] = Field(
        None,
        description = "Custom Jinja2 chat template to use instead of the model's default",
    )

    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)

    @field_validator("chat_template_override")
    @classmethod
    def normalize_blank_chat_template_override(cls, value: Optional[str]) -> Optional[str]:
        if value is None:
            return None
        # Char count is a lower bound on UTF-8 bytes: cheap early reject.
        if len(value) > MAX_CHAT_TEMPLATE_BYTES:
            raise ValueError(f"Chat template exceeds the {MAX_CHAT_TEMPLATE_BYTES}-byte limit.")
        if value.strip() == "":
            return None
        if len(value.encode("utf-8")) > MAX_CHAT_TEMPLATE_BYTES:
            raise ValueError(f"Chat template exceeds the {MAX_CHAT_TEMPLATE_BYTES}-byte limit.")
        return value

    cache_type_kv: Optional[str] = Field(
        None,
        description = (
            "KV cache data type for both K and V "
            "(e.g. 'f16', 'bf16', 'q8_0', 'q4_0', 'q4_1', 'q5_0', 'q5_1', 'iq4_nl', 'f32')"
        ),
    )
    mlx_kv_quant: Optional[str] = Field(
        None,
        description = (
            "MLX KV cache quantization: 'auto' for an unquantized cache, '8'/'6'/'5'/'4'/'3'/'2' "
            "for an mx.quantize width, or 'tq-4'/'tq-3.5'/'tq-3'/'tq-2' for TurboQuant. MLX names a "
            "width rather than a llama.cpp dtype, so this is separate from cache_type_kv. Ignored "
            "by non-MLX backends; a model whose cache layout cannot be quantized reports the reason "
            "instead of applying it."
        ),
    )
    mlx_kv_bits: Optional[float] = Field(
        None, description = "Superseded by mlx_kv_quant; read only when mlx_kv_quant is omitted."
    )

    @model_validator(mode = "after")
    def derive_mlx_kv_quant(self):
        """A bare width only ever meant mx.quantize; null is how a client spells Auto."""

        if "mlx_kv_quant" not in self.model_fields_set and self.mlx_kv_bits is not None:
            from core.inference.mlx_inference import encode_mlx_kv_quant
            self.mlx_kv_quant = encode_mlx_kv_quant(self.mlx_kv_bits)
        return self

    mlx_int8_prefill: bool = Field(
        False,
        description = (
            "Experimental, MLX only: run quantized projections with int8 activations on Apple "
            "neural accelerators for faster prompt processing. Lossy: outputs change and "
            "accuracy drops. Applied only when the model supports it; the status reports the "
            "reason otherwise."
        ),
    )
    mlx_ane_prefill: bool = Field(
        False,
        description = (
            "Experimental, MLX only: run part of each MLP on the Apple Neural Engine alongside the "
            "GPU for faster prompt processing. Lossy: the Neural Engine uses int8 weights, so "
            "outputs change slightly. Applied only when the model supports it and the split is "
            "measured faster here; the status reports the reason otherwise."
        ),
    )
    mlx_fast_verify: bool = Field(
        False,
        description = (
            "Experimental, MLX only: verify a drafter's tokens on faster kernels during speculative "
            "decoding. Changes decode output slightly against plain greedy decoding, repeatably. "
            "Applied only when the load attaches a drafter and the model supports it; the status "
            "reports the reason otherwise. Decided at load: changing it reloads the model."
        ),
    )
    mlx_ple_offload: MlxOffload = Field(
        None,
        description = (
            "MLX only: the fraction of the per-layer embedding (PLE) tables read from the "
            "checkpoint on disk instead of held in memory, 'off', or 'auto' (also null): read "
            "from disk only when the load would otherwise leave less than half the memory past "
            "the weights for context. Applied only to a model with PLE tables; the status "
            "reports the reason otherwise."
        ),
    )
    mlx_expert_offload: MlxOffload = Field(
        None,
        description = (
            "MLX only: the fraction of each MoE layer's routed experts read from the checkpoint "
            "on disk on demand instead of held in memory, 'off', or 'auto' (also null): as "
            "mlx_ple_offload, after the PLE tables. Slower decode; applied only to quantized "
            "routed experts."
        ),
    )
    _mlx_offload_amounts = field_validator("mlx_ple_offload", "mlx_expert_offload", mode = "before")(
        _mlx_offload_amount
    )

    gpu_ids: Optional[List[int]] = Field(
        None,
        description = (
            "GPU placement pool, for example [0, 1]. Omit or pass [] to use "
            "automatic selection. CUDA/ROCm values are physical GPU indices; "
            "Vulkan values are ggml device ordinals. Explicit selection is not "
            "supported on XPU, and physical IDs are unsupported when the parent "
            "visibility mask uses "
            "non-numeric or subdevice entries, including CUDA_VISIBLE_DEVICES "
            "with MIG or unresolvable UUID entries and ZE_AFFINITY_MASK with subdevice tokens "
            "(for example '0.0,0.1') or FLAT-hierarchy tile handles. For GGUF "
            "models the fitter may pin the smallest subset of this pool that fits."
        ),
    )
    speculative_type: Optional[str] = Field(
        None,
        description = (
            "Speculative decoding mode for GGUF models. Canonical values: "
            "'auto' (platform-aware: DSpark when the model ships a sidecar, "
            "else DFlash when it ships one, else MTP on MTP GGUFs, ngram-mod "
            "fallback for sub-3B), "
            "'mtp' (force draft-mtp only on both GPU and CPU), "
            "'dspark' (force a draft-dspark sidecar), "
            "'dflash' (force a draft-dflash sidecar), "
            "'ngram' (force ngram-mod only), 'mtp+ngram' (force "
            "ngram-mod+draft-mtp chain on both platforms), 'off' (disabled). "
            "Legacy values 'default' (-> auto), 'draft-mtp' (-> mtp), "
            "'draft-dspark' (-> dspark), 'draft-dflash' (-> dflash), "
            "'ngram-mod' (-> ngram), and 'ngram-simple' (kept as-is) are "
            "still accepted. MLX models read 'auto', 'mtp', 'dflash', 'dspark', 'eagle3', "
            "'ngram' and 'off'; every drafter kind also copies repeated text (n-gram), "
            "so 'mtp+ngram' reads as 'mtp'. On MLX, 'auto' attaches the first "
            "cached drafter (an MTP head or assistant, then DFlash2, DFlash, DSpark, EAGLE-3) that "
            "costs no context, on loads served through mlx-vlm. Ignored for other non-GGUF models."
        ),
    )
    spec_draft_n_max: Optional[int] = Field(
        None,
        ge = 1,
        le = 16,
        description = (
            "Max draft tokens per step for MTP, DSpark or DFlash speculative "
            "decoding (--spec-draft-n-max). Defaults to 2 on GPU and 3 on "
            "CPU/Mac when unset (upstream-bench sweet spot for dense Qwen3.6 "
            "MTP quants, and the measured sweet spot for DFlash too). Only "
            "applied when speculative_type resolves to 'mtp', 'mtp+ngram', "
            "'dspark' or 'dflash'. On MLX, up to the drafter's trained depth (3 for "
            "MTP heads and assistants) every step drafts exactly this many (or takes an "
            "n-gram copy expected to yield more), even when "
            "plain decoding would be faster; above it, or for n-gram copies alone, it "
            "is a ceiling and the controller decides when to draft."
        ),
    )
    spec_draft_model: Optional[str] = Field(
        None,
        max_length = 1024,
        description = (
            "MLX only: a companion drafter (DFlash, DFlash2, DSpark, EAGLE-3 or Gemma "
            "assistant) to speculate with, as a local directory or an already-cached "
            "repo id; never downloaded. Tried before the model's own MTP head and the "
            "cached companions discovery would pick."
        ),
    )
    n_parallel: Optional[int] = Field(
        None,
        ge = PARALLEL_MIN,
        le = PARALLEL_MAX,
        description = (
            f"Replies this load may decode at once ({PARALLEL_MIN}..{PARALLEL_MAX}). "
            "For GGUF these are llama-server's --parallel slots, and the VRAM "
            "fitter may launch fewer to keep the model fully on GPU; omit for the "
            "server-wide default set at launch. Elsewhere it is a ceiling, not a promise: "
            "a runtime that decodes replies together commits its memory to this width and "
            "spends it on both the replies to one turn and the concurrent chats joining a "
            "batch already decoding, while one that does not answers every reply on its "
            "own whatever this says. The load reply's parallel_slots is what it came to."
        ),
    )
    n_batch: Optional[int] = Field(
        None,
        ge = BATCH_MIN,
        le = BATCH_MAX,
        description = (
            "Logical prompt batch size for llama-server (--batch-size) for "
            f"this load ({BATCH_MIN}..{BATCH_MAX}). Omit for the llama.cpp "
            "default (2048). Ignored for non-GGUF models."
        ),
    )
    n_ubatch: Optional[int] = Field(
        None,
        ge = BATCH_MIN,
        le = BATCH_MAX,
        description = (
            "Physical prompt micro-batch size for llama-server (--ubatch-size) "
            f"for this load ({BATCH_MIN}..{BATCH_MAX}). Omit for the llama.cpp "
            "default (512), raised to a projector's own per-image ceiling when "
            "its images would abort the server at 512: 1120 for Gemma 4, and "
            "2048 for a projector whose family cannot be read. Every other "
            "vision model keeps the 512 default. "
            "llama.cpp caps it at the batch size. Larger values speed up prompt "
            "processing at the cost of compute-buffer VRAM. Ignored for "
            "non-GGUF models."
        ),
    )
    load_mode: Optional[Literal["auto", "none", "mmap", "mlock", "mmap+mlock", "dio"]] = Field(
        None,
        description = (
            "How llama-server reads the weights off disk (--load-mode). 'auto' "
            "memory-maps unless a device cannot, 'mmap' forces the mapping, "
            "'mlock' keeps the model in RAM rather than letting it swap or "
            "compress, 'mmap+mlock' does both, 'dio' uses DirectIO where "
            "available and 'none' asks for no special mode. Omit for the "
            "llama.cpp default. The Model Memory settings own host placement, so "
            "'Keep model in GPU memory' replaces this with mmap+mlock and "
            "'Don't reserve system RAM' drops a mode that would hold a full host "
            "copy. Ignored for non-GGUF models."
        ),
    )
    spec_draft_cache_type: Optional[str] = Field(
        None,
        description = (
            "KV cache dtype for the DRAFT model's context "
            "(--spec-draft-type-k / --spec-draft-type-v), for example 'q8_0'. "
            "Separate from cache_type_kv, which is the target model's. Only "
            "reaches the command line when the load attaches a separate draft "
            "model; omit for the llama.cpp default (f16). Ignored for non-GGUF "
            "models."
        ),
    )
    ctx_checkpoints: Optional[int] = Field(
        None,
        ge = 0,
        le = CTX_CHECKPOINTS_MAX,
        description = (
            "Context checkpoints kept per slot (--ctx-checkpoints), which let a "
            "sliding-window model rewind instead of re-processing the prompt. "
            "Omit for the llama.cpp default (32); 0 disables them. "
            "Each costs host memory, and a model without a sliding window "
            "ignores it. Ignored for non-GGUF models."
        ),
    )
    cache_ram: Optional[int] = Field(
        None,
        ge = -1,
        le = CACHE_RAM_MAX_MIB,
        description = (
            "Host memory in MiB llama-server may spend caching prompt state it "
            "has evicted from a slot (--cache-ram). Omit for the llama.cpp "
            "default (8192); 0 disables the cache and -1 lifts the limit. "
            "Ignored for non-GGUF models."
        ),
    )
    tensor_parallel: bool = Field(
        False,
        description = (
            "Split the model across GPUs by tensor (--split-mode tensor) "
            "instead of by layer for GGUF models. Only affects multi-GPU "
            "setups, where it can make generation significantly faster. "
            "No effect on a single GPU. Ignored for non-GGUF models."
        ),
    )
    disable_vision: bool = Field(
        False,
        description = (
            "Load a vision-capable GGUF without its multimodal projector, as a "
            "text-only model. Frees the VRAM the projector would hold, at the cost "
            "of image input, which is off for the session; text generation is "
            "unaffected. Ignored for models with no vision projector, and for "
            "non-GGUF models."
        ),
    )
    audio_device: Optional[Literal["auto", "cpu", "gpu"]] = Field(
        None,
        description = (
            "Native audio (TTS / music) models only: where to hold the weights. "
            "'cpu' keeps them in CPU RAM rather than the GPU -- slower generation, "
            "but it leaves VRAM for other models and runs checkpoints too large for "
            "the card. 'gpu' prefers the accelerator; 'auto' (default) detects. "
            "Ignored for every non-audio model, and for GGUF audio: llama.cpp "
            "placement comes from gpu_memory_mode and gpu_layers, which are decided "
            "before anything can know a GGUF is audio. Send gpu_memory_mode='manual' "
            "with gpu_layers=0 and speculative_type='off' to hold a GGUF TTS in RAM."
        ),
    )
    gpu_memory_mode: Literal["auto", "manual"] = Field(
        "auto",
        description = (
            "GPU memory strategy for GGUF models. 'auto' (default): Unsloth "
            "selects GPUs and caps context to fit VRAM. 'manual': you own the "
            "offload. Leave gpu_layers at -1 (Auto) to hand memory management to "
            "llama.cpp's --fit (no device masking, no context auto-reduce, no "
            "gpu-layer/tensor-split planning); set gpu_layers >= 0 to pin layers "
            "and n_cpu_moe yourself (--fit off), with tensor_parallel still "
            "applying (split by free VRAM unless tensor_split is set, no planner). "
            "Ignored for non-GGUF."
        ),
    )
    gpu_layers: int = Field(
        -1,
        ge = -1,
        description = (
            "Manual mode only: number of layers to offload to the GPU "
            "(--gpu-layers, with --fit off). A value >= the model's layer count "
            "offloads all of them. -1 = Auto: hand layer + context sizing to "
            "llama.cpp's --fit. Ignored unless gpu_memory_mode is 'manual'."
        ),
    )
    cpu_fallback: bool = Field(
        False,
        description = (
            "Replay a previously recovered automatic Vulkan load in its managed CPU-only "
            "runtime. Used when restoring that model after a failed switch."
        ),
    )
    n_cpu_moe: int = Field(
        0,
        ge = 0,
        description = (
            "Manual mode only: keep the first N MoE expert layers on the CPU "
            "(--n-cpu-moe) to save VRAM on MoE models. 0 = none, N = number of "
            "MoE layers offloaded (the backend offsets past any leading dense "
            "layers). Ignored unless gpu_memory_mode is 'manual' with gpu_layers >= 0."
        ),
    )
    tensor_split: Optional[List[float]] = Field(
        None,
        description = (
            "Relative share of the model per GPU (--tensor-split), in the order of "
            "the GPUs in use, e.g. [2, 1] for 2:1. Omit it to let llama.cpp use its "
            "default, which splits by free VRAM. Values are relative, so [1, 1] "
            "forces an even split and [3, 1] and [75, 25] mean the same thing. "
            "In manual mode (gpu_layers >= 0) the list is passed through as-is. In "
            "auto mode it applies only with tensor_parallel, and only when the "
            "placement planner did not size the split itself; a ratio that does not "
            "fit the planner's per-GPU budget is dropped rather than forwarded. "
            "Ignored entirely when gpu_memory_mode is 'manual' with gpu_layers < 0."
        ),
    )

    @field_validator(
        "n_batch", "n_ubatch", "ctx_checkpoints", "cache_ram", "reasoning_budget", mode = "before"
    )
    @classmethod
    def _no_booleans(cls, value: Any) -> Any:
        # bool is an int: `true` would launch --batch-size 1 and llama-server aborts (500 not 422).
        # Kept off the annotation: an Annotated BeforeValidator leaks Field bounds into OpenAPI.
        if isinstance(value, bool):
            raise ValueError("Expected a number, got a boolean.")
        return value

    @field_validator("tensor_split")
    @classmethod
    def _reject_degenerate_tensor_split(cls, value: Optional[List[float]]) -> Optional[List[float]]:
        # Bad splits are dropped at launch but compared raw in reload dedupe (reload loop).
        if not value:
            return value
        import math

        if any((not math.isfinite(v)) or v < 0 for v in value):
            raise ValueError("tensor_split entries must be finite and non-negative")
        if sum(value) <= 0:
            raise ValueError("tensor_split must have a positive total")
        return value

    llama_extra_args: Optional[List[str]] = Field(
        None,
        description = (
            "Extra arguments forwarded verbatim to llama-server for GGUF models. "
            "One token per list entry, e.g. ['--top-k', '20', '--seed', '42']. "
            "Unsloth-managed flags (model identity, port, context length, GPU placement, "
            "auth, UI/server mode) are rejected. Ignored for non-GGUF models."
        ),
    )
    reasoning_budget: int = Field(
        -1,
        ge = -1,
        le = 2_147_483_647,
        description = "llama-server reasoning token budget (-1 = model/default behavior).",
    )
    reasoning_budget_message: str = Field(
        "",
        description = "Message emitted by llama-server when the reasoning budget is exhausted.",
    )

    @field_validator("reasoning_budget_message")
    @classmethod
    def _validate_reasoning_budget_message(cls, value: str) -> str:
        return validate_reasoning_budget_message(value)

    force_cancel_active: bool = Field(
        False,
        description = (
            "Stop chats still generating instead of refusing with 409. A load "
            "replaces the llama-server every open conversation decodes on."
        ),
    )


class UnloadRequest(BaseModel):
    """Request to unload a model"""

    model_path: str = Field(..., description = "Model identifier to unload")
    cancel_load_request_id: Optional[str] = Field(
        None,
        min_length = 1,
        max_length = 128,
        pattern = r"^[A-Za-z0-9][A-Za-z0-9._:-]*$",
        description = ("Cancel only this in-flight load attempt; never unload a resident model"),
    )
    force_cancel_active: bool = Field(
        False,
        description = (
            "Stop chats still generating instead of refusing with 409. An "
            "unload takes away the llama-server they are decoding on."
        ),
    )
    # Unresolved handle matches no resident model and falsely reports success.
    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class SearchImagesLookupRequest(BaseModel):
    subjects: list[str] = Field(
        ...,
        min_length = 1,
        max_length = 5,
        description = "Specific things to fetch one picture each for.",
    )


def validate_stt_context_length(value: Any) -> int:
    """A zero selects Auto; fixed lengths are multiples of 256, since llama-server pads n_ctx to that."""
    if type(value) is not int or (value != 0 and not (1024 <= value <= 65536 and value % 256 == 0)):
        raise ValueError(
            "Voice context length must be 0 (Auto) or a multiple of 256 from 1024 to 65536."
        )
    return value


class SttContextSettings(BaseModel):
    context_length: int = Field(
        0,
        ge = 0,
        le = 65536,
        description = (
            "Qwen3-ASR on llama.cpp only: 0 (Auto) sizes context for the recording; "
            "a multiple of 256 from 1024 to 65536 fixes the context limit. Ignored by other STT engines."
        ),
    )

    _validate_context_length = field_validator("context_length", mode = "before")(
        validate_stt_context_length
    )


class TranscribeRequest(SttContextSettings):
    """Speech-to-text request for the dictation STT sidecar."""

    audio: str = Field(..., description = "Base64-encoded audio (any common format)")
    model: Optional[str] = Field(None, description = "STT model id; defaults server-side")
    language: Optional[str] = Field(None, description = "BCP-47 language, or 'auto'/None to detect")
    fast: bool = Field(
        False,
        description = "Use low-latency single-candidate decoding for dictation",
    )
    engine: Optional[str] = Field(
        None,
        description = "STT engine: 'transformers' (default), 'gguf' (whisper.cpp), 'mtmd' (llama.cpp) "
        "or 'audiocpp' (audio.cpp)",
    )
    device: Optional[Literal["auto", "cpu", "gpu"]] = Field(
        None,
        description = (
            "Where to hold the model: 'cpu' keeps it in CPU RAM, 'gpu' prefers the "
            "accelerator, 'auto' (default) detects. Applies when this request has to "
            "load the model; a resident model on another device is reloaded to honour it."
        ),
    )


class SttLoadRequest(SttContextSettings):
    """Warm the STT sidecar with a model without transcribing."""

    model: Optional[str] = Field(None, description = "STT model id; defaults server-side")
    engine: Optional[str] = Field(
        None,
        description = "STT engine: 'transformers' (default), 'gguf' (whisper.cpp), 'mtmd' (llama.cpp) "
        "or 'audiocpp' (audio.cpp)",
    )
    device: Optional[Literal["auto", "cpu", "gpu"]] = Field(
        None,
        description = (
            "Where to hold the model: 'cpu' keeps it in CPU RAM rather than the GPU, "
            "'gpu' prefers the accelerator, 'auto' (default) detects."
        ),
    )
    gguf_variant: Optional[str] = Field(
        None,
        description = (
            "Variant of an audio GGUF dictation model (engine 'audiocpp'): a quant or a named "
            "sub-variant such as 'tiny'. Omitted picks the model's default."
        ),
    )
    download_id: Optional[str] = Field(
        None,
        description = "Opaque identity of the download attempt being cancelled",
    )

    @model_validator(mode = "after")
    def _fold_audio_gguf_variant(self):
        # The audio.cpp sidecar takes ``id:variant``, so every route must build the same string.
        engine = (self.engine or "").strip().lower()
        model = (self.model or "").strip()
        variant = (self.gguf_variant or "").strip()
        if (
            variant
            and model
            and ":" not in model
            and (
                engine in ("audiocpp", "audio_cpp", "audio.cpp")
                or model.lower().startswith(("audio-cpp/", "audiocpp-"))
            )
        ):
            self.model = f"{model}:{variant}"
        return self


class ValidateModelRequest(BaseModel):
    """Check whether an identifier resolves to a ModelConfig; does NOT load weights."""

    engine_parallelism: Literal["tensor", "pipeline", "data"] = "tensor"
    engine_precision: Literal["auto", "bf16", "fp16", "int4", "int8", "fp8"] = "auto"
    engine_kv_cache_dtype: Literal["auto", "fp8"] = Field(
        "auto",
        description = "Managed engine KV cache dtype; 'fp8' halves KV cache memory (vLLM --kv-cache-dtype).",
    )
    engine_seed: Optional[int] = Field(
        None, ge = 0, le = 2**31 - 1, description = "Managed engine seed (vLLM --seed)."
    )
    engine_gpu_memory_utilization: Optional[float] = Field(
        None,
        ge = 0.05,
        le = 0.99,
        description = "Upper bound on the share of each selected GPU the managed engine may claim "
        "(vLLM --gpu-memory-utilization). Unset lets Unsloth size it from free memory.",
    )
    engine: Literal["auto", "vllm", "sglang"] = "auto"
    model_path: str = Field(..., description = "Model identifier or local path")
    # The same inventory handle the picker was shown; see `resolve_inventory_handle`.
    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)
    native_path_lease: Optional[str] = Field(
        None, description = "Frontend-visible signed native path grant"
    )
    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated models")
    llama_extra_args: Optional[List[str]] = Field(
        None,
        description = (
            "Pass-through llama-server args the follow-up /load will send. Sized with, "
            "not validated here: a --ctx-size or cache override changes the memory this "
            "preflight estimates, so omitting it would approve a different command from "
            "the one that runs."
        ),
    )
    gguf_variant: Optional[str] = Field(
        None, description = "GGUF quantization variant (e.g. 'Q4_K_M')"
    )
    # Intended load settings so the coexistence check matches the follow-up /load.
    max_seq_length: int = Field(0, ge = 0, le = MAX_REQUESTABLE_CONTEXT)
    load_in_4bit: bool = Field(True)
    cache_type_kv: Optional[str] = Field(None)
    tensor_parallel: bool = Field(False)
    # Follow-up /load opens no projector when set, so do not charge for one.
    disable_vision: bool = Field(False)
    gpu_ids: Optional[List[int]] = Field(None)
    # Sized with too: preflighting a CPU load would refuse one that takes no VRAM.
    audio_device: Optional[Literal["auto", "cpu", "gpu"]] = Field(
        None,
        description = (
            "Native audio placement intended for the follow-up load. 'cpu' skips "
            "the GPU-memory preflight, which that load would not use."
        ),
    )
    gpu_memory_mode: Literal["auto", "manual"] = Field(
        "auto",
        description = (
            "GGUF GPU-memory strategy intended for the follow-up load. Manual "
            "placement bypasses the training coexistence estimate: Auto layers "
            "delegate fitting to llama.cpp, while explicit layers are user-owned."
        ),
    )
    gpu_layers: int = Field(
        -1,
        ge = -1,
        description = (
            "Layer count intended for the follow-up load, so the coexistence estimate "
            "sizes like /load. Only 0 changes the verdict: a zero-layer DiffusionGemma "
            "split places no layers on any device, so it cannot compete with training "
            "for VRAM. -1 (Auto) keeps the previous behaviour for callers that omit it."
        ),
    )
    tensor_split: Optional[List[float]] = Field(
        None,
        description = (
            "Per-GPU share (--tensor-split) intended for the follow-up load. Manual "
            "mode promotes an explicit -ts from llama_extra_args into this field "
            "before stripping the raw flag, so the preflight strips exactly the "
            "tokens /load strips and judges the command /load will run (#11330). "
            "No sizing here reads the ratio itself: _guard_chat_load_against_training "
            "and _estimate_gguf_required_gb budget per device, not per share."
        ),
    )
    n_parallel: Optional[int] = Field(
        None,
        ge = PARALLEL_MIN,
        le = PARALLEL_MAX,
        description = (
            "Parallel decode slots intended for the follow-up load, so the "
            "coexistence estimate sizes the KV cache like /load. Omit for the "
            "server-wide --parallel default."
        ),
    )
    n_batch: Optional[int] = Field(
        None,
        ge = BATCH_MIN,
        le = BATCH_MAX,
        description = (
            "Batch size (--batch-size) intended for the follow-up load, so the "
            "coexistence estimate sizes the compute buffer like /load."
        ),
    )
    n_ubatch: Optional[int] = Field(
        None,
        ge = BATCH_MIN,
        le = BATCH_MAX,
        description = (
            "Micro-batch size (--ubatch-size) intended for the follow-up load, "
            "so the coexistence estimate sizes the compute buffer like /load."
        ),
    )
    speculative_type: Optional[str] = Field(
        None,
        description = (
            "Speculative mode intended for the follow-up load. The estimate is "
            "mode-dependent -- the drafter it charges differs by kind, and a "
            "DSpark sidecar is ~11 GB -- so omitting it makes this preflight "
            "disagree with /load in both directions."
        ),
    )
    spec_draft_n_max: Optional[int] = Field(
        None,
        ge = 1,
        le = 16,
        description = "Draft depth intended for the follow-up load; sizes the draft KV.",
    )
    spec_draft_cache_type: Optional[str] = Field(
        None,
        description = (
            "Draft KV cache dtype intended for the follow-up load. Sent so this "
            "preflight strips the same inherited draft-cache flags /load would, "
            "and so approves the command the load actually runs. The coexistence "
            "estimate prices the drafter's weights but not its KV, so the value "
            "itself does not move the number."
        ),
    )
    ctx_checkpoints: Optional[int] = Field(
        None,
        ge = 0,
        le = CTX_CHECKPOINTS_MAX,
        description = (
            "Checkpoints (--ctx-checkpoints) intended for the follow-up load, so "
            "the coexistence estimate sizes the SWA cache like /load. Each one is "
            "a per-slot snapshot that scales with the slot's context, so a load "
            "asking for them needs materially more memory than one that does not."
        ),
    )
    reasoning_budget: int = Field(-1, ge = -1, le = 2_147_483_647)
    reasoning_budget_message: str = ""

    @field_validator("reasoning_budget_message")
    @classmethod
    def _validate_reasoning_budget_message(cls, value: str) -> str:
        return validate_reasoning_budget_message(value)

    include_context_length: bool = Field(
        False,
        description = "Also read the native context length from the local GGUF header. "
        "Opt-in so the normal load preflight doesn't pay for a cache scan it doesn't need.",
    )
    include_chat_template: bool = Field(
        False,
        description = "Also read the embedded chat template from the local GGUF header, so a "
        "native (picked / drag-drop) file's default template can be shown before it is loaded. "
        "Opt-in and, like include_context_length, a metadata-only probe that skips the training "
        "guard. Only the leased file's own embedded template is read, never sibling sidecars.",
    )

    _no_booleans = field_validator(
        "n_batch", "n_ubatch", "ctx_checkpoints", "reasoning_budget", mode = "before"
    )(LoadRequest._no_booleans.__func__)

    _reject_degenerate_tensor_split = field_validator("tensor_split")(
        LoadRequest._reject_degenerate_tensor_split.__func__
    )


class ManagedEngineOffer(BaseModel):
    """Optional engines that can run a checkpoint the Default engine cannot."""

    quantization: str = Field(..., description = "quant_method from the checkpoint's config.json")
    engines: List[Literal["vllm", "sglang"]] = Field(
        ..., description = "Engines this host can run, in the order to offer them"
    )


class TransformersUpgradeInfo(BaseModel):
    """A model architecture no installed transformers ships, but a newer release does."""

    model_type: str = Field(
        ..., description = "config.json model_type unknown to every installed transformers"
    )
    pypi_version: Optional[str] = Field(
        None, description = "Latest transformers release on PyPI at check time"
    )
    supported_in_pypi: bool = Field(
        False,
        description = "True if the latest PyPI release ships this model_type; Unsloth can "
        "install it into a persistent sidecar after user consent.",
    )
    supported_in_main: bool = Field(
        False,
        description = "True if transformers GitHub main ships this model_type; with main_version "
        "set, Unsloth can install main into the persistent sidecar after user consent.",
    )
    main_version: Optional[str] = Field(
        None, description = "transformers main __version__ (a .devN string) at check time"
    )

    @property
    def installable(self) -> bool:
        """The consent dialog can install it: the PyPI release, else transformers main."""
        return bool(
            (self.supported_in_pypi and self.pypi_version)
            or (self.supported_in_main and self.main_version)
        )


class TransformersUpgradeCheckRequest(BaseModel):
    """Ask whether loading a model needs a newer transformers than any installed overlay."""

    model_name: str = Field(
        ...,
        min_length = 1,
        max_length = 1024,
        description = "Model identifier, local path or checkpoint directory to check.",
    )
    hf_token: Optional[str] = Field(
        None, description = "HuggingFace token, so gated repos resolve their config.json"
    )
    # Cache pin: a pinned snapshot's config.json can name a different architecture.
    prefer_local_cache: bool = Field(
        False,
        description = "Inspect the cached snapshot rather than the Hub repo, when one is pinned.",
    )
    model_local_path: Optional[str] = Field(
        None,
        max_length = 4096,
        description = "Cache directory the caller selected for this model, if any.",
    )
    model_snapshot_path: Optional[str] = Field(
        None,
        max_length = 4096,
        description = "Exact snapshot the load is pinned to; takes precedence over "
        "model_local_path, as it does for the remote-code scan.",
    )
    model_snapshot_repo_id: Optional[str] = Field(
        None,
        max_length = 1024,
        description = "Repository the pinned snapshot belongs to, when it differs from model_name.",
    )
    resume_run_id: Optional[str] = Field(
        None,
        max_length = 128,
        description = "Run this check precedes a resume of. Lets the answer say whether "
        "installing would strand that checkpoint's exact 4-bit resume.",
    )

    # This route swallows a failed lookup, so training would die at model load.
    _resolve_the_handle = field_validator(
        "model_name", "model_local_path", "model_snapshot_path", "model_snapshot_repo_id"
    )(resolve_inventory_handle)


class TransformersUpgradeCheckResponse(BaseModel):
    """Upgrade + quantization preflight for a load that does not run /validate.

    /validate answers this for a chat load as part of a much larger check (GGUF
    placement, VRAM coexistence, security review). Training needs the same two answers
    on their own, before starting a worker that would die at model load with an
    unrecognized-architecture error.
    """

    model_name: str = Field(..., description = "The identifier that was checked")
    requires_transformers_upgrade: bool = Field(
        False,
        description = "True when the architecture is unknown to every installed transformers "
        "but a newer transformers ships it; the caller should raise the install consent "
        "dialog before starting the load.",
    )
    transformers_upgrade: Optional[TransformersUpgradeInfo] = Field(
        None,
        description = "Details for the consent dialog; set only when "
        "requires_transformers_upgrade is true.",
    )
    requires_trust_remote_code: bool = Field(
        False,
        description = "Whether the model can load on the CURRENT transformers through its own "
        "repo code, so a declined (or unavailable) install still has a path forward.",
    )
    latest_tier_active: bool = Field(
        False,
        description = "Whether the latest-transformers sidecar already routes this model.",
    )
    forces_16bit: bool = Field(
        False,
        description = "Whether a run started now would load 16-bit rather than bnb 4-bit: true "
        "when the latest sidecar already routes the model, and when an install-only upgrade "
        "would put it there. Lets the UI state the real precision before the run starts.",
    )
    install_breaks_exact_resume: bool = Field(
        False,
        description = "Set only for a resume_run_id: installing the offered release would "
        "activate the latest sidecar, which permanently refuses that checkpoint's attested "
        "4-bit model load mode. The caller must not offer the install when the run can "
        "start without it.",
    )


class ValidateModelResponse(BaseModel):
    """Result of model validation.

    valid == True means from_identifier() succeeded and GGUF/LoRA/vision flags are available.
    """

    valid: bool = Field(..., description = "Whether the model identifier looks valid")
    message: str = Field(..., description = "Human-readable validation message")
    identifier: Optional[str] = Field(None, description = "Resolved model identifier")
    resident: bool = Field(
        False,
        description = (
            "Whether the weights this identifier names are the ones already loaded. Decided "
            "from the files, so an Ollama tag answers for whichever of its spellings loaded it."
        ),
    )
    display_name: Optional[str] = Field(None, description = "Display name derived from identifier")
    is_gguf: bool = Field(False, description = "Whether this is a GGUF model (llama.cpp)")
    is_diffusion: bool = Field(
        False, description = "Whether this is a block-diffusion model (DiffusionGemma)"
    )
    diffusion_unknown: bool = Field(
        False,
        description = "Whether the diffusion check came back inconclusive: the GGUF is not "
        "downloaded yet (or its header is unreadable) and its name does not carry the "
        "DiffusionGemma family, so is_diffusion == False here means 'not known to be "
        "diffusion', NOT 'known to be an ordinary GGUF'. Callers that choose a GPU-layer "
        "split before the load must treat this as possibly-diffusion.",
    )
    is_lora: bool = Field(False, description = "Whether this is a LoRA adapter")
    is_vision: bool = Field(False, description = "Whether this is a vision-capable model")
    requires_trust_remote_code: bool = Field(
        False,
        description = "Whether the model defaults require trust_remote_code to be enabled for loading.",
    )
    requires_security_review: bool = Field(
        False,
        description = "Whether Hugging Face's security scan flagged unsafe files (e.g. a "
        "malicious pickle), so the load is hard-blocked pending review.",
    )
    context_length: Optional[int] = Field(
        None,
        description = "Native training context length, read from the GGUF header when the file "
        "is already downloaded locally; None for non-GGUF, gated, or not-yet-downloaded models.",
    )
    layer_count: Optional[int] = Field(
        None,
        description = "Total layer count (GGUF block_count), the manual gpu-layers ceiling, read "
        "from the header alongside context_length; None when not read.",
    )
    moe_layer_count: Optional[int] = Field(
        None,
        description = "MoE expert-layer count (the manual --n-cpu-moe ceiling), read from the GGUF "
        "header alongside context_length; 0 for dense models, None when not read.",
    )
    chat_template: Optional[str] = Field(
        None,
        description = "Embedded GGUF chat template, read from the header when include_chat_template "
        "is set (native lease-backed picks); None for non-GGUF, over-cap, or not-read templates.",
    )
    requires_transformers_upgrade: bool = Field(
        False,
        description = "True when the model's architecture is unknown to every installed "
        "transformers but a newer transformers ships it; the UI should offer the "
        "install-transformers consent dialog (a PyPI release, else transformers main).",
    )
    transformers_upgrade: Optional[TransformersUpgradeInfo] = Field(
        None,
        description = "Details for the transformers-upgrade dialog; set only when "
        "requires_transformers_upgrade is true.",
    )
    mlx_loads_base_model: Optional[str] = Field(
        None,
        description = "On an MLX host, the full-precision repo that will be downloaded and "
        "loaded in place of the requested unsloth bnb-4bit repo (or of a LoRA's bnb base), "
        "because MLX cannot read bitsandbytes weights. None when the pick loads as asked.",
    )
    managed_engine_offer: Optional[ManagedEngineOffer] = Field(
        None,
        description = "Set when the Default engine cannot run this checkpoint's quantization "
        "but an optional engine can on this host; the UI offers to load it there.",
    )


class EstimateMemoryRequest(BaseModel):
    """Settings a Load-Model panel is about to submit, priced before it submits them.

    Every field mirrors the load request it previews, so the estimate answers for the
    command that would actually run. No model is loaded and no tensor data is read: a
    GGUF is priced from its header, an MLX repo from safetensors headers and the shapes
    of a graph that is built and never evaluated.
    """

    model_path: str = Field(..., description = "Model identifier or local path")
    gguf_variant: Optional[str] = Field(
        None, description = "GGUF quantization to price (e.g. Q4_K_M); the picked variant."
    )
    hf_token: Optional[str] = Field(None, description = "Token for gated repositories")
    native_path_lease: Optional[str] = Field(
        None,
        description = "Lease for a picked / drag-dropped .gguf, as /validate takes one.",
    )
    n_ctx: Optional[int] = Field(
        None,
        ge = 0,
        description = "Context length to price (--ctx-size). 0 or omitted prices the "
        "model's native context, which is what an Auto load asks for.",
    )
    load_in_4bit: bool = Field(
        True,
        description = "Quantize an unquantized checkpoint to 4 bits on load, as "
        "/load does by default. Priced because it is the difference between a "
        "checkpoint's shards and what those shards go resident as. A checkpoint "
        "carrying its own quantization is priced at its shards, and asking for 4 "
        "bits on top can make it unsizable, because the real load refuses that.",
    )
    cache_type_kv: Optional[str] = Field(
        None,
        description = "KV cache dtype to price. The biggest lever on this estimate at "
        "long contexts, so omitting it prices a load nobody asked for.",
    )
    n_parallel: Optional[int] = Field(
        None,
        ge = PARALLEL_MIN,
        le = PARALLEL_MAX,
        description = "Serving slots (--parallel); scales both the cache and the buffers.",
    )
    n_batch: Optional[int] = Field(None, ge = BATCH_MIN, le = BATCH_MAX)
    n_ubatch: Optional[int] = Field(None, ge = BATCH_MIN, le = BATCH_MAX)
    ctx_checkpoints: Optional[int] = Field(None, ge = 0, le = CTX_CHECKPOINTS_MAX)
    speculative_type: Optional[str] = Field(
        None, description = "Speculative mode; decides which drafter's weights are charged."
    )
    spec_draft_model: Optional[str] = Field(
        None,
        max_length = 1024,
        description = "MLX companion drafter intended for the follow-up load, as on /load.",
    )
    spec_draft_n_max: Optional[int] = Field(
        None,
        ge = 1,
        le = 16,
        description = "Draft depth. Sizes the drafter's rollback state, so it moves the "
        "estimate for every mode that loads a separate drafter.",
    )
    spec_draft_cache_type: Optional[str] = Field(
        None,
        description = "Draft KV cache dtype. The drafter keeps its own cache, and at a "
        "long context that is GB, not a rounding error.",
    )
    tensor_parallel: bool = Field(False, description = "Whether tensor mode is requested")
    disable_vision: bool = Field(
        False, description = "Vision off, so an image projector's bytes are not charged."
    )
    gpu_memory_mode: Optional[str] = Field(
        None, description = "'auto' or 'manual'; manual splits the weights by gpu_layers."
    )
    gpu_layers: Optional[int] = Field(
        None, ge = 0, description = "Layers pinned to the GPU under manual placement."
    )
    n_cpu_moe: Optional[int] = Field(
        None,
        ge = 0,
        description = "Expert layers held on the CPU (--n-cpu-moe). Not priced; echoed "
        "back so the panel can say the GPU figure reads high.",
    )
    selected_gpu_ids: Optional[List[int]] = Field(
        None,
        description = "GPUs the load is pinned to. Tensor mode replicates its compute "
        "buffers per device, so the pinned count changes the footprint.",
    )
    llama_extra_args: Optional[List[str]] = Field(
        None,
        description = "Pass-through llama-server flags. Read, not just carried: -c, "
        "-nkvo, --swa-full and the cache-type flags all move this estimate.",
    )

    max_seq_length: Optional[int] = Field(
        None,
        ge = 0,
        le = 1048576,
        description = "Context an MLX load would open at. Separate from n_ctx because "
        "the two backends take the length from different fields -- /load reads n_ctx "
        "for GGUF and max_seq_length for everything else -- and pricing one from the "
        "other quotes a context the load will not use.",
    )
    mlx_kv_quant: Optional[str] = Field(
        None,
        description = "MLX KV cache quantization in /load's vocabulary ('auto', '8', 'tq-4', ...). "
        "A TurboQuant choice is priced at full width, as the load fits it.",
    )
    mlx_kv_bits: Optional[int] = Field(
        None,
        description = "Superseded by mlx_kv_quant; read only when mlx_kv_quant is omitted. Not derived "
        "from cache_type_kv: that is llama.cpp's setting, it survives in the config of "
        "a model that never used it, and reading it here would quantize an estimate "
        "for a load whose cache stays full width.",
    )
    mlx_ple_offload: MlxOffload = Field(None, description = "As /load's mlx_ple_offload.")
    mlx_expert_offload: MlxOffload = Field(None, description = "As /load's mlx_expert_offload.")
    _mlx_offload_amounts = field_validator("mlx_ple_offload", "mlx_expert_offload", mode = "before")(
        _mlx_offload_amount
    )

    _no_booleans = field_validator(
        "n_batch", "n_ubatch", "ctx_checkpoints", "n_ctx", "max_seq_length", mode = "before"
    )(LoadRequest._no_booleans.__func__)
    # Unresolved, the handle reads as a Hub id and the panel is told the estimate is unavailable.
    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class Int8PrefillAvailabilityRequest(BaseModel):
    """A model whose run settings may offer MLX int8 prefill."""

    model_path: str = Field(..., description = "Model identifier or local path")
    hf_token: Optional[str] = Field(None, description = "Token for gated repositories")

    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class Int8PrefillAvailabilityResponse(BaseModel):
    """Whether a load of this model could run MLX int8 prefill, judged from its downloaded files."""

    available: bool
    reason: Optional[str] = Field(
        None,
        description = "Cause when available is false: 'not_downloaded', 'unsupported_model', "
        "'unsupported_zoo', or unsloth_zoo's own reason ('nax_unavailable', "
        "'no_eligible_projections', 'probe_failed').",
    )


class AnePrefillAvailabilityRequest(BaseModel):
    """A model whose run settings may offer MLX Neural Engine prefill."""

    model_path: str = Field(..., description = "Model identifier or local path")
    hf_token: Optional[str] = Field(None, description = "Token for gated repositories")

    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class AnePrefillAvailabilityResponse(BaseModel):
    """Whether a load of this model could run MLX Neural Engine prefill, judged from its downloaded files."""

    available: bool
    reason: Optional[str] = Field(
        None,
        description = "Cause when available is false: 'not_downloaded', 'unsupported_model', "
        "'unsupported_zoo', 'probe_failed', or unsloth_zoo's own reason ('no_neural_engine', "
        "'no_eligible_mlps').",
    )


class FastVerifyAvailabilityRequest(BaseModel):
    """A model whose run settings may offer MLX Fast Verify."""

    model_path: str = Field(..., description = "Model identifier or local path")
    hf_token: Optional[str] = Field(None, description = "Token for gated repositories")

    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class FastVerifyAvailabilityResponse(BaseModel):
    """Whether a load of this model could run MLX Fast Verify, judged from its downloaded files."""

    available: bool
    reason: Optional[str] = Field(
        None,
        description = "Cause when available is false: 'not_downloaded', 'unsupported_model', "
        "'unsupported_zoo', or unsloth_zoo's own reason ('no_lane_kernel', "
        "'no_eligible_projections', 'probe_failed').",
    )


class MlxDraftersRequest(BaseModel):
    model_path: str = Field(..., description = "Model identifier or local path of the target")

    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)


class MlxDrafter(BaseModel):
    repo_id: str = Field(..., description = "Cached Hugging Face repo, usable as spec_draft_model")
    kind: str = Field(..., description = "'mtp', 'dflash', 'dspark' or 'eagle3'")
    named: bool = Field(
        True,
        description = "Whether the repo is named for this model. False: it fits the model's "
        "architecture only (another generation or a fine-tune), so Auto does not use it.",
    )


class MlxDraftersResponse(BaseModel):
    """Cached drafters an MLX load of the target could name: those named for it first, in Auto's order."""

    drafters: list[MlxDrafter] = Field(default_factory = list)


class MlxOffloadEstimate(BaseModel):
    """What an MLX load reads from disk instead of holding in memory, "auto" decided."""

    ple: Optional[float] = Field(
        None, description = "Fraction of the PLE tables read from disk; null for none"
    )
    experts: Optional[float] = Field(
        None, description = "Fraction of the routed experts read from disk; null for none"
    )
    offloadable: list[Literal["ple", "experts"]] = Field(
        default_factory = list, description = "What the load can read from disk at all"
    )


class EstimateMemoryResponse(BaseModel):
    """Itemized memory an inference load would occupy, or why it could not be sized."""

    available: bool = Field(..., description = "Whether a breakdown could be produced at all.")
    reason: Optional[str] = Field(
        None,
        description = "Cause when available is false: 'not_gguf', 'not_downloaded', "
        "'unsupported_source' or 'unsizable'.",
    )
    weights_bytes: int = Field(
        0,
        description = "Resident weights, projector and drafter. The size of the files "
        "for a GGUF load; for MLX, what those files go resident AS, which is smaller "
        "wherever the load casts or quantizes them.",
    )
    kv_bytes: int = Field(0, description = "KV cache at the requested context and slots")
    kv_checkpoint_bytes: int = Field(
        0,
        description = "Context checkpoints in host RAM: included in kv_bytes and total_bytes, "
        "excluded from gpu_bytes.",
    )
    compute_bytes: int = Field(0, description = "Compute / graph buffers, flat plus context-linear")
    drafter_runtime_bytes: int = Field(
        0,
        description = "A separate drafter's own KV cache and rollback state, on top of "
        "its file in weights_bytes. Included in total_bytes, and in gpu_bytes unless the "
        "drafter is CPU-pinned. Reported separately so the itemization accounts for it.",
    )
    drafter_runtime_gpu_bytes: int = Field(
        0,
        description = "The share of drafter_runtime_bytes that lands on the GPU. Not a "
        "placement flag, because the term is not placed as one piece: under MTP the "
        "target-side verification state follows the TARGET cache (so --no-kv-offload "
        "moves it) while the draft cache follows the drafter (so --spec-draft-ngl 0 "
        "moves that instead), and the two can go different ways in the same load.",
    )
    projector_runtime_bytes: int = Field(
        0,
        description = "The vision encoder's buffers, about 0.4x the projector file on top "
        "of it. Included in total_bytes, and in gpu_bytes unless --no-mmproj-offload "
        "keeps the projector in host RAM.",
    )
    drafter_kv_unsized: bool = Field(
        False,
        description = "True when a drafter is charged whose cache could not be sized: "
        "--spec-draft-hf names a repository whose header is not on this disk. Its weights "
        "are in weights_bytes but its context-scaled cache is missing, so total_bytes is a "
        "lower bound.",
    )
    adapters_unsized: bool = Field(
        False,
        description = "True when a pass-through --lora / --lora-scaled / --control-vector / "
        "--control-vector-scaled names a file that could not be stat'd. llama.cpp loads every "
        "one of them into resident tensors on top of the base model, so those bytes are "
        "missing from total_bytes and it is a lower bound.",
    )
    total_bytes: int = Field(0, description = "Weights + KV + compute, wherever they land")
    gpu_bytes: int = Field(
        0, description = "The share of total_bytes that lands on the GPU under this offload"
    )
    kv_estimable: bool = Field(
        True,
        description = "False when the GGUF header lacks the attention dims needed to "
        "size the cache. kv_bytes is then 0 meaning UNKNOWN and total_bytes is a lower "
        "bound; rendering it as a confident total is what this flag exists to prevent.",
    )
    kv_on_gpu: bool = Field(
        True, description = "False under --no-kv-offload, which moves the cache to host RAM"
    )
    n_ctx: int = Field(0, description = "Context length the estimate actually priced")
    context_fitted: Optional[int] = Field(
        None,
        description = "The window MLX would fit to this machine's memory for a load that "
        "names no Context Length, which is then what n_ctx prices. Null when the load names "
        "one, when the machine holds the model's own window, or when the footprint of the "
        "load cannot be described.",
    )
    context_is_pinned: bool = Field(
        True,
        description = "False only when the loader will shrink n_ctx to fit, so the "
        "context-linear share of gpu_bytes is an upper bound rather than a reservation.",
    )
    gpu_floor_bytes: Optional[int] = Field(
        None,
        description = "gpu_bytes at the shortest context the loader's fit settles for; "
        "past it the launch offloads layers instead. Set only when context_is_pinned is false.",
    )
    floor_can_offload: bool = Field(
        False,
        description = "Whether a load still over the card at the floor moves layers to the "
        "CPU. False when the layer count is fixed or the fitter is off, where it may fail.",
    )
    cache_type_kv: Optional[str] = Field(
        None, description = "KV dtype the estimate priced, after flags and fallbacks resolve"
    )
    n_parallel: int = Field(1, description = "Slots the estimate priced, after the launch clamps")
    layer_count: Optional[int] = Field(None, description = "GGUF block_count, when readable")
    gpu_layers: Optional[int] = Field(
        None, description = "Layers charged to the GPU; null under automatic placement"
    )
    moe_offload_unmodelled: bool = Field(
        False,
        description = "True when --n-cpu-moe is set: experts move per-tensor, not "
        "per-block, so the GPU/host split above ignores it and reads high.",
    )
    lookup_table_bytes: int = Field(
        0,
        description = "Lookup-only tables (per-layer embeddings / Engram) in the model "
        "file. Never in gpu_bytes; excluded from weights_bytes and total_bytes when "
        "lookup_table_on_disk is true.",
    )
    lookup_table_on_disk: bool = Field(
        False,
        description = "True when llama.cpp streams those tables from disk (its default "
        "lazy mode), so only the rows in use are paged in.",
    )
    mlx_offload: Optional[MlxOffloadEstimate] = Field(
        None,
        description = "MLX: what the load reads from disk instead of memory, priced in "
        "weights_bytes; null when not MLX.",
    )


class MemoryEstimate(BaseModel):
    """The canonical answer to "what would this load occupy".

    Unsloth grew two routes that answer this -- ``POST /inference/estimate-memory``
    for the Load Model panel and ``GET /models/kv-cache-estimate`` for the Hub
    memory bar. They share the ``_gguf_memory_breakdown`` planner, so their
    arithmetic already agrees; this is the shared CONTRACT, so their vocabulary
    agrees too. Both legacy routes are projections of this model and keep their
    own shapes exactly.

    The one thing this model deliberately does not have is a field called
    ``weights_bytes``. That name means different things on the two legacy routes
    -- every resident file on one, the quant file alone on the other -- and it is
    the same type on both, so nothing catches a caller reading the wrong one.
    It is replaced here by two fields that each say which they are, and it is
    absent rather than redefined so that no future reader can pick it up and
    guess. See ``core/inference/memory_contract.py`` for the projections.
    """

    available: bool = Field(..., description = "Whether a breakdown could be produced at all.")
    reason: Optional[str] = Field(
        None,
        description = "Cause when available is false: 'not_gguf', 'not_downloaded', "
        "'unsupported_source' or 'unsizable'.",
    )

    quant_file_bytes: int = Field(
        0,
        description = "The selected GGUF quant file ALONE, as it sits on disk. This is "
        "the figure a download size or a weights segment should be drawn from, because "
        "it is the number the user already saw beside the model.",
    )
    resident_files_bytes: int = Field(
        0,
        description = "Every file this launch makes resident: the quant file PLUS "
        "whichever projector and drafter it opens. Always >= quant_file_bytes. This is "
        "the figure an itemized footprint should be drawn from.",
    )

    kv_bytes: int = Field(0, description = "KV cache at the requested context and slots")
    kv_checkpoint_bytes: int = Field(
        0, description = "The host-RAM part of kv_bytes: per-slot context checkpoints"
    )
    compute_bytes: int = Field(0, description = "Compute / graph buffers, flat plus context-linear")
    drafter_runtime_bytes: int = Field(
        0, description = "A separate drafter's own KV cache and rollback state"
    )
    drafter_runtime_gpu_bytes: int = Field(
        0, description = "The share of drafter_runtime_bytes that lands on the GPU"
    )
    projector_runtime_bytes: int = Field(
        0, description = "The vision encoder's buffers, on top of the projector file"
    )
    drafter_kv_unsized: bool = Field(
        False, description = "A charged drafter's cache could not be sized, so totals are a floor"
    )
    adapters_unsized: bool = Field(
        False, description = "A pass-through adapter could not be stat'd, so totals are a floor"
    )

    total_bytes: int = Field(0, description = "Weights + KV + compute, wherever they land")
    gpu_bytes: Optional[int] = Field(
        None,
        description = "The share of total_bytes that lands on the GPU. Optional because "
        "None and 0 are DIFFERENT answers here: None is 'the planner did not run', while "
        "0 is 'this launch puts nothing on the card', which inherited placement such as "
        "LLAMA_ARG_DEVICE=none really does produce. Collapsing the two sends a caller "
        "back to summing segments and drawing VRAM pressure for a load that touches no "
        "card at all.",
    )
    gpu_floor_bytes: Optional[int] = Field(
        None,
        description = "gpu_bytes at the shortest context the route prices: the Hub's 256, "
        "which leaves what no context reduction frees (drafter weights, flat compute "
        "buffers, recurrent rollback state), and the Load Model panel's loader fit floor, "
        "past which the launch offloads layers instead. None when it was not computed.",
    )
    floor_can_offload: bool = Field(
        False,
        description = "Whether a load still over the card at the floor moves layers to the "
        "CPU rather than keep a placement llama.cpp's fitter refuses to change.",
    )

    kv_estimable: bool = Field(True, description = "False when the header could not size the cache")
    kv_on_gpu: bool = Field(True, description = "Whether the target cache sits on the GPU")
    n_ctx: int = Field(0, description = "Context length the estimate actually priced")
    native_context: Optional[int] = Field(
        None, description = "The model's own trained context length, when readable"
    )
    cache_type_kv: Optional[str] = Field(
        None,
        description = (
            "KV cache width the estimate priced, in the vocabulary of whichever backend "
            "would load it: llama.cpp spellings such as f16 or q8_0 for a GGUF load, and "
            "a dtype abbreviation or an N-bit width for an MLX one. An MLX cache whose "
            "entries do not all end up at one width names each of them, the one carrying "
            "the most of the cache first, as in bf16/4-bit"
        ),
    )
    n_parallel: int = Field(1, description = "Slots the estimate priced, after the launch clamps")
    layer_count: Optional[int] = Field(None, description = "GGUF block_count, when readable")
    gpu_layers: Optional[int] = Field(None, description = "Layers placed on the GPU, when known")
    moe_offload_unmodelled: bool = Field(
        False, description = "--n-cpu-moe is set, so the GPU figure reads high"
    )
    lookup_table_bytes: int = Field(
        0, description = "Lookup-only tables in the model file, never charged to the GPU"
    )
    lookup_table_on_disk: bool = Field(
        False, description = "Those tables are streamed from disk, not resident"
    )
    mlx_offload: Optional[MlxOffloadEstimate] = Field(
        None, description = "MLX: what the load reads from disk; null when not MLX"
    )
    context_fitted: Optional[int] = Field(
        None,
        description = "The window MLX would fit to this machine's memory for a load that "
        "names no Context Length, and which n_ctx then prices. Null wherever the served "
        "window was not chosen for this machine.",
    )
    context_is_pinned: bool = Field(
        True,
        description = "False only when the loader is free to shrink the context. A caller "
        "that softens its verdict for an auto-fitted row has to stop softening here.",
    )
    inherited_device_pin: bool = Field(
        False,
        description = "An inherited LLAMA_ARG_DEVICE confines the launch to the cards it "
        "names, so a budget aggregated over the visible inventory describes a pool the "
        "launch will not open.",
    )
    spec_unpriced: bool = Field(
        False, description = "A speculative term was charged that could not be sized"
    )


class InstallLatestTransformersRequest(BaseModel):
    """Consented request to install the latest transformers release into a sidecar."""

    version: str = Field(
        ...,
        min_length = 1,
        max_length = 64,
        description = "Exact transformers version to install; must match the current "
        "latest PyPI release reported by /validate.",
    )
    force_cancel_active: bool = Field(
        False,
        description = (
            "Stop chats still generating instead of refusing with 409. The install "
            "is a step of the model swap that raised the same prompt, so a client "
            "that already got consent for that swap can carry it through here."
        ),
    )


class InstallLatestTransformersResponse(BaseModel):
    """Result of the consented latest-transformers sidecar install."""

    success: bool = Field(..., description = "Whether the sidecar was provisioned")
    version: str = Field(..., description = "The requested transformers version")
    message: str = Field(..., description = "Human-readable result")
    model_unloaded: bool = Field(
        False,
        description = "Whether the active chat model was unloaded before the swap "
        "(reported even on failure, so the client can restore its state)",
    )
    latest_version: Optional[str] = Field(
        None,
        description = "On a version-mismatch failure: the release that superseded "
        "the requested one, so the client can retry with it",
    )
    latest_main_version: Optional[str] = Field(
        None, description = "On a version-mismatch failure: transformers main's current version"
    )


class GenerateRequest(BaseModel):
    """Request for text generation (legacy /generate/stream endpoint)"""

    messages: List[dict] = Field(..., description = "Chat messages in OpenAI format")
    system_prompt: str = Field("", description = "System prompt")
    temperature: float = Field(0.6, ge = 0.0, le = 2.0, description = "Sampling temperature")
    top_p: float = Field(0.95, ge = 0.0, le = 1.0, description = "Top-p sampling")
    top_k: int = Field(20, ge = -1, le = 100, description = "Top-k sampling")
    min_p: float = Field(0.0, ge = 0.0, le = 1.0, description = "Min-p sampling")
    max_new_tokens: int = Field(2048, ge = 1, le = 4096, description = "Maximum tokens to generate")
    repetition_penalty: float = Field(1.0, ge = 1.0, le = 2.0, description = "Repetition penalty")
    presence_penalty: float = Field(0.0, ge = 0.0, le = 2.0, description = "Presence penalty")
    image_base64: Optional[str] = Field(None, description = "Base64 encoded image for vision models")


class MlxOffloadPart(BaseModel):
    applied: Optional[float] = Field(None, description = "Fraction read from disk; null for none")
    requested: Optional[Union[str, float]] = Field(None, description = "As the load asked for it")
    reason: Optional[str] = Field(None, description = "Why a requested offload is not applied")


class MlxOffloadStatus(BaseModel):
    """The PLE tables and routed experts an MLX load reads from disk instead of memory."""

    ple: MlxOffloadPart
    experts: MlxOffloadPart
    disk_bytes: Optional[int] = Field(
        None, description = "Weight bytes the loaded model reads from the checkpoint on demand"
    )


class _InferenceRuntimeFields(BaseModel):
    """Runtime fields shared by load and status responses."""

    engine_parallelism: Literal["tensor", "pipeline", "data"] = "tensor"
    engine_precision: Literal["auto", "bf16", "fp16", "int4", "int8", "fp8"] = "auto"
    engine_kv_cache_dtype: Literal["auto", "fp8"] = "auto"
    engine_seed: Optional[int] = None
    engine_gpu_memory_utilization: Optional[float] = None
    engine: Literal["auto", "vllm", "sglang"] = Field(
        "auto",
        description = "Active inference engine. 'auto' denotes Unsloth's default backend; "
        "'vllm' and 'sglang' denote optional managed engines.",
    )

    is_vision: bool = Field(False, description = "Whether model is a vision model")
    is_diffusion: bool = Field(
        False, description = "Whether model is a block-diffusion model (DiffusionGemma)"
    )
    diffusion_requested_ngl: Optional[int] = Field(
        None,
        description = "GPU-layer count the diffusion runner was ASKED for, when that differs "
        "from what it applied: an unsloth_zoo shim without --ngl drops the split and runs "
        "Auto, so gpu_layers reports -1 while this reports the standing request. None for "
        "non-diffusion models and whenever the ask and the applied split agree.",
    )
    is_audio: bool = Field(False, description = "Whether model is a TTS audio model")
    audio_type: Optional[str] = Field(
        None,
        description = "Audio codec or native generation architecture.",
    )
    has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")
    speaks: bool = Field(
        False, description = "Whether model can answer a spoken question in its own voice"
    )
    audio_family: Optional[str] = Field(
        None, description = "Loader family of an audio GGUF model (e.g. kokoro_tts, minimax_music3)."
    )
    audio_options: Optional[List[Dict[str, Any]]] = Field(
        None,
        description = (
            "Request options an audio GGUF model accepts: {name, type (bool|int|float|string|enum), "
            "description, default, min, max, values, required}. Send chosen values as audio_options."
        ),
    )
    audio_workflows: Optional[List[str]] = Field(
        None,
        description = (
            "Audio page workflows (speak, clone, music, transcribe) the loaded model serves; [] "
            "for a model that is not an audio model. Derived from is_audio and audio_type when "
            "not given."
        ),
    )
    audio_reference_text: Optional[Literal["required", "optional", "unused"]] = Field(
        None,
        description = (
            "For a model that clones: whether a request needs the reference clip's transcript. "
            "None for a model that does not clone."
        ),
    )
    audio_required_inputs: Optional[List[str]] = Field(
        None,
        description = (
            "Request fields the model refuses to run without (Maya1: ['instruct'], a voice "
            "description sent as instructions)."
        ),
    )
    audio_request_inputs: Optional[List[str]] = Field(
        None,
        description = "instruct/instruction/language fields a strict audio.cpp model reads, else None.",
    )
    audio_device_fallback: Optional[Literal["cpu"]] = Field(
        None,
        description = "'cpu' when the audio.cpp model could not start on the GPU and runs on the CPU.",
    )
    audio_music: Optional[Dict[str, Any]] = Field(
        None,
        description = (
            "Music studio capabilities of an audio.cpp music model: {modes: [{id: song|sfx|edit, "
            "...}]} with lyrics, description, instrumental, section_case, duration and "
            "variations for song and sfx, and actions, max_ranges and max_source_s for edit. "
            "None for a model the Music studio does not drive (and native MiniMax)."
        ),
    )
    audio_options_by_workflow: Optional[Dict[str, List[Dict[str, Any]]]] = Field(
        None, description = "Options per Audio workflow where they differ from audio_options."
    )
    audio_workflow_tasks: Optional[Dict[str, str]] = Field(
        None, description = "audio.cpp server task per workflow, e.g. {'convert:singing': 'svc'}."
    )
    audio_server_task: Optional[str] = Field(
        None, description = "audio.cpp server task the running server was started with."
    )
    audio_convert: Optional[Dict[str, Any]] = Field(
        None, description = "What the model offers on Convert; None when it does not convert."
    )
    audio_convert_route: Optional[str] = Field(
        None, description = "Seed-VC route the running server was started with."
    )
    audio_clone: Optional[Dict[str, Any]] = Field(
        None,
        description = "Clone rules (transcript, emotion clip, voice description); None when it does not clone.",
    )

    @model_validator(mode = "after")
    def derive_audio_workflows(self):
        if self.audio_workflows is None:
            self.audio_workflows = status_audio_workflows(self.is_audio, self.audio_type)
        return self

    has_video_input: bool = Field(
        False,
        description = (
            "Whether llama-server accepts video input for this model, from its /props "
            "modalities. False unless the mmproj, the build and ffmpeg all support it."
        ),
    )
    requires_trust_remote_code: bool = Field(
        False,
        description = "Whether the model defaults require trust_remote_code to be enabled for loading.",
    )
    context_length: Optional[int] = Field(
        None, description = "Runtime context length in tokens for the loaded model"
    )
    max_context_length: Optional[int] = Field(
        None,
        description = (
            "The ceiling to show for this model: llama.cpp estimates what the machine can "
            "hold, while MLX reports the model's own window. Neither reserves memory, and "
            "an explicit request above it is still honored."
        ),
    )
    native_context_length: Optional[int] = Field(
        None,
        description = "Model's native context length, from GGUF metadata or the MLX model config",
    )
    context_length_enforced: Optional[bool] = Field(
        None,
        description = (
            "Whether context_length bounds the runtime's KV cache for a reply decoded on "
            "its own. True confirmed, false confirmed unbounded, null the backend does not "
            "answer. MLX builds a cache to check, since a model with its own make_cache "
            "ignores the requested size. Replies decoded together are answered for by "
            "context_unbounded_when_batched, not by this."
        ),
    )
    context_unbounded_when_batched: bool = Field(
        False,
        description = (
            "Whether replies this load decodes together escape the window this reports. "
            "mlx-vlm's batch generator takes no window control, so a vision load able to "
            "run either batch reports true; everything else, llama.cpp included, reports "
            "false. Which batch a given reply gets is a per-request question this cannot "
            "settle, so it errs towards not promising a window. Both fields describe the "
            "load as it was loaded and neither changes afterwards, so a client combines "
            "them with parallel_slots to decide what to tell a user: a load reporting true "
            "and more than one slot cannot promise a window. That is the load's answer, not "
            "the reply's -- a load whose release keeps no batch open decodes a plain chat "
            "bounded while still reporting true -- so read it as the weaker claim it is."
        ),
    )
    context_length_fitted: Optional[int] = Field(
        None,
        description = (
            "The window MLX fitted to this machine's memory, where that is shorter than the "
            "model's own and no Context Length was requested. Null means context_length was not "
            "chosen for this machine: a pin, or the model's own window."
        ),
    )
    mlx_context_budget: Optional[int] = Field(
        None,
        description = (
            "Token limit enforced per request rather than by the KV cache, set where a "
            "requested cache width took the cache and context_length could not bound it. "
            "A request over it is refused; null where context_length bounds the cache itself."
        ),
    )
    supports_reasoning: bool = Field(
        False,
        description = "Whether model supports thinking/reasoning mode (enable_thinking or reasoning_effort)",
    )
    reasoning_style: Literal["enable_thinking", "reasoning_effort", "enable_thinking_effort"] = (
        Field(
            "enable_thinking",
            description = "Reasoning control style: 'enable_thinking' (boolean), 'reasoning_effort' (low|medium|high), or 'enable_thinking_effort' (on/off gate plus an effort level, e.g. GLM-5.2 high|max)",
        )
    )
    reasoning_effort_levels: List[str] = Field(
        default_factory = list,
        description = "Discrete reasoning_effort levels the template offers when reasoning_style is 'enable_thinking_effort' (e.g. ['high', 'max']); empty otherwise",
    )
    reasoning_always_on: bool = Field(
        False,
        description = "Whether reasoning is always on (hardcoded <think> tags, not toggleable)",
    )
    reasoning_budget: int = Field(-1, description = "Effective llama-server reasoning token budget.")
    reasoning_budget_message: str = Field(
        "", description = "Effective llama-server reasoning-budget exhaustion message."
    )
    # Echo what the load asked for: the effective pair folds in LLAMA_ARG_THINK_BUDGET* env, which
    # a client cannot reproduce, so comparing against it reloads forever.
    requested_reasoning_budget: int = Field(
        -1, description = "Reasoning token budget this load requested, before the environment."
    )
    requested_reasoning_budget_message: str = Field(
        "", description = "Reasoning-budget message this load requested, before the environment."
    )
    supports_preserve_thinking: bool = Field(
        False,
        description = "Whether the template understands the optional preserve_thinking kwarg",
    )
    preserve_thinking_default: bool = Field(
        False,
        description = "Default preserve_thinking value resolved for the active model family",
    )
    supports_tools: bool = Field(
        False,
        description = "Whether model supports tool calling (web search, etc.)",
    )
    cache_type_kv: Optional[str] = Field(
        None,
        description = (
            "KV cache data type for K and V "
            "(e.g. 'f16', 'bf16', 'q8_0', 'q4_0', 'q4_1', 'q5_0', 'q5_1', 'iq4_nl', 'f32')"
        ),
    )
    is_mlx: bool = Field(False, description = "Whether the active model is served by the MLX backend")
    is_npu: bool = Field(
        False,
        description = "Whether the active model runs on the AMD Ryzen AI NPU (FastFlowLM through Lemonade)",
    )
    mlx_kv_quant: Optional[str] = Field(
        None, description = "MLX KV cache quantization actually applied, in mlx_kv_quant's vocabulary"
    )
    mlx_kv_quant_requested: Optional[str] = Field(
        None,
        description = (
            "MLX KV cache quantization the load asked for. Differs from mlx_kv_quant when the model "
            "could not honor it, which is exactly when the reason matters."
        ),
    )
    mlx_kv_bits: Optional[float] = Field(
        None, description = "mlx_kv_quant as a bare width, kept for clients reading the older field"
    )
    mlx_kv_bits_requested: Optional[float] = Field(
        None, description = "mlx_kv_quant_requested as a bare width, kept for the same reason"
    )
    chat_template_override: Optional[str] = Field(
        None,
        description = "Chat template override this model was loaded with. llama.cpp reports what it applied; MLX reports what was requested, since a refusal applies nothing and the reason accompanies it",
    )
    chat_template_override_reason: Optional[str] = Field(
        None,
        description = (
            "Why a requested chat template override was not applied: the "
            "runtime supplies the template as code, the model ships a named "
            "set rather than one template, it renders without a template, or "
            "the override could not render a conversation."
        ),
    )
    mlx_kv_quant_eligibility: Optional[str] = Field(
        None,
        description = (
            "Whether this model's KV cache could be quantized: full, partial, "
            "none or refused. Describes eligibility, not the exact set of "
            "converted layers, which the runtime decides."
        ),
    )
    mlx_kv_quant_reason: Optional[str] = Field(
        None,
        description = (
            "Why KV quantization was not applied in full: the model's cache "
            "layout, or the layers it could not cover when eligibility is partial"
        ),
    )
    mlx_kv_quant_note: Optional[str] = Field(
        None, description = "Caveat that applies when KV quantization is active"
    )
    mlx_int8_prefill: Optional[bool] = Field(
        None, description = "Whether MLX int8 prefill is active for the loaded model"
    )
    mlx_int8_prefill_requested: Optional[bool] = Field(
        None, description = "Whether the load asked for MLX int8 prefill"
    )
    mlx_int8_prefill_reason: Optional[str] = Field(
        None,
        description = "Why requested int8 prefill is not active, as unsloth_zoo reports it "
        "(for example nax_unavailable or no_eligible_projections)",
    )
    mlx_ane_prefill: Optional[bool] = Field(
        None, description = "Whether MLX Neural Engine prefill is active for the loaded model"
    )
    mlx_ane_prefill_requested: Optional[bool] = Field(
        None, description = "Whether the load asked for MLX Neural Engine prefill"
    )
    mlx_ane_prefill_reason: Optional[str] = Field(
        None,
        description = "Why requested Neural Engine prefill is not active, as unsloth_zoo reports it "
        "(for example no_neural_engine, no_eligible_mlps, no_gain, not_enough_memory or released)",
    )
    mlx_fast_verify: Optional[bool] = Field(
        None, description = "Whether MLX Fast Verify is active for the loaded model"
    )
    mlx_fast_verify_requested: Optional[bool] = Field(
        None, description = "Whether the load asked for MLX Fast Verify"
    )
    mlx_fast_verify_reason: Optional[str] = Field(
        None,
        description = "Why requested Fast Verify is not active: no_drafter, unsupported_zoo, or unsloth_zoo's reason",
    )
    mlx_offload: Optional[MlxOffloadStatus] = Field(None, description = "MLX: weights read from disk")
    chat_template: Optional[str] = Field(
        None,
        description = "Jinja2 chat template string (from GGUF metadata or tokenizer)",
    )
    speculative_type: Optional[str] = Field(
        None,
        description = (
            "Canonical UI-facing requested speculative decoding mode "
            "('auto' / 'mtp' / 'dspark' / 'ngram' / 'mtp+ngram' / 'off' / "
            "'ngram-simple'), round-tripped from the original LoadRequest "
            "via _canonicalize_spec_mode. None when no model is loaded."
        ),
    )
    spec_draft_n_max: Optional[int] = Field(
        None,
        description = (
            "Active --spec-draft-n-max for MTP or DSpark speculative decoding, or "
            "None when the platform default is in effect."
        ),
    )
    spec_draft_model: Optional[str] = Field(
        None,
        description = "The companion drafter an MLX load was asked for; None elsewhere.",
    )
    spec_drafter_kind: Optional[str] = Field(
        None,
        description = (
            "Which drafter the resolution was about: 'mtp', 'dspark' or "
            "'dflash' ('eagle3' or 'ngram' too on MLX, where 'mtp' also names a Gemma "
            "assistant). Needed "
            "because Auto resolves the kind itself, so speculative_type still "
            "reads 'auto', and a fallback leaves the engaged type at 'default': "
            "neither still says which file the UI should tell the user to fix."
        ),
    )
    spec_fallback_reason: Optional[str] = Field(
        None,
        description = (
            "Why a speculative drafter was disabled despite being requested. "
            "'binary_no_mtp' / 'binary_outdated' -> a newer prebuilt would "
            "re-enable it (show the update affordance); 'runtime_error' -> the "
            "current build could not run it; 'drafter_not_found' -> the model's "
            "separate MTP or DSpark drafter could not be resolved; "
            "'drafter_no_vram' -> an Auto-mode fit downgrade: the model pins on "
            "GPU but the drafter's reserve does not, and Auto keeps the context "
            "rather than shrink it; select the drafter in Settings to force it. "
            "'mla_mtp_disabled' -> "
            "an Auto-mode policy downgrade: the model is MLA (GLM-5.2 et al.) "
            "whose llama.cpp MTP path runs slower than no speculation, so Auto "
            "used ngram-mod or spec-off instead -- updating won't help; choose "
            "MTP in Settings (or set UNSLOTH_MLA_MTP_ENABLED=1) to force it. "
            "'mtp_partial_offload' -> an Auto-mode policy downgrade: the model "
            "has an embedded Hybrid Mamba MTP head and the placement offloads "
            "only part of it, where the recurrent rollback copies cost more "
            "layers than the drafting wins back -- updating won't help; choose "
            "MTP in Settings to force it. "
            "MLX loads report 'drafter_not_found' (no drafter of the requested kind "
            "is cached), 'drafter_incompatible' (the named or found drafter does not "
            "fit this model), 'drafter_no_memory' (a drafter whose weights and cache "
            "leave no context that fits was passed over; a chosen mode still attaches "
            "one that fits by spending the prompt cache's share of memory), 'kv_quant' (KV "
            "cache quantization is on) or "
            "'runtime_error' (the installed MLX packages cannot speculate, or cannot "
            "load this model the way speculation needs), also when a later drafter "
            "or n-gram copies stood in for the one asked for. Under auto an MLX load "
            "reports no refusal; it reports 'auto_context_cost' (a found drafter would "
            "shrink the fitted context) or the drafter codes above for a named or "
            "unbuildable drafter. "
            "None when the requested strategy engaged or was not requested."
        ),
    )
    tensor_parallel: bool = Field(
        False,
        description = "Whether tensor-parallel split (--split-mode tensor) is active.",
    )
    disable_vision: bool = Field(
        False,
        description = (
            "Whether the load ran with the vision projector deliberately left "
            "unloaded. Echoes the request, so the Advanced Settings switch can "
            "reseed from it even on a GGUF that never had a projector."
        ),
    )
    vision_disabled_by_user: bool = Field(
        False,
        description = (
            "Whether image input is off because the user asked, rather than because "
            "the model has no usable mmproj. The two look identical to a client "
            "otherwise and need different guidance, so this stays False for a model "
            "that never had a projector to switch off."
        ),
    )
    gpu_memory_mode: Literal["auto", "manual"] = Field(
        "auto",
        description = "Active GPU memory strategy ('auto' or 'manual').",
    )
    gpu_layers: int = Field(
        -1,
        description = "Manual mode: requested --gpu-layers value (-1 = Auto/--fit, or when not manual).",
    )
    offloaded_layers: Optional[int] = Field(
        None,
        description = (
            "Layers llama.cpp actually placed on a GPU, when it reported the count. "
            "In Auto mode the placement is llama.cpp's own (--fit on), so this is the "
            "only account of what happened; gpu_layers above is the REQUEST."
        ),
    )
    offload_total_layers: Optional[int] = Field(
        None,
        description = "Total layers in the model, alongside offloaded_layers.",
    )
    overflow_layers: Optional[int] = Field(
        None,
        description = (
            "Layers with MoE expert weights that llama.cpp's --fit left in system memory: their "
            "routed experts, or part of the FFN for the first partial layer on a device. "
            "offloaded_layers still counts them as on the GPU, so a spill shows only here. Every "
            "MoE layer when expert_cache_mib is set. None when --fit did not run."
        ),
    )
    expert_cache_mib: Optional[float] = Field(
        None,
        description = (
            "--moe-cache-mib auto: every routed expert is in system memory and this many MiB of "
            "the most used ones are cached on the GPU. None when no MoE cache is in use."
        ),
    )
    gpu_weights_mib: Optional[float] = Field(
        None,
        description = "MiB of model weights llama.cpp placed in GPU buffers, from its load log.",
    )
    host_weights_mib: Optional[float] = Field(
        None,
        description = (
            "MiB of model weights in system memory (CPU, memory-mapped or pinned host buffers). "
            "Token embeddings stay here even when every layer is on the GPU."
        ),
    )
    gpu_backend_unavailable: bool = Field(
        False,
        description = (
            "Unsloth detected a GPU for this load but llama.cpp's own device table "
            "reported none, meaning its GPU backend did not initialise. Separates a "
            "backend failure from a fit that placed no layers; both log 0/M."
        ),
    )
    offload_overridden: bool = Field(
        False,
        description = (
            "Whether the user's own llama-server extras pinned the layer split. "
            "Auto mode respects an inherited -ngl instead of stripping it, so a "
            "deliberate placement can arrive with gpu_memory_mode still 'auto'."
        ),
    )
    cpu_fallback_reason: Optional[
        Literal["vulkan_startup_crash", "vulkan_startup_stall", "vulkan_no_device"]
    ] = Field(
        None,
        description = (
            "Why an automatic GGUF load was downgraded to CPU. "
            "'vulkan_startup_crash' means a managed, auto-selected Vulkan launch "
            "hard-crashed and the same launch became healthy with GPU devices disabled. "
            "'vulkan_startup_stall' means that launch stopped making startup progress. "
            "'vulkan_no_device' means the Vulkan probe found no usable device, so the "
            "load started on CPU without initialising the Vulkan runtime."
        ),
    )

    mmproj_fallback_reason: Optional[
        Literal["cpu_offload", "projector_incompatible", "projector_startup_failure"]
    ] = Field(
        None,
        description = (
            "How an automatic GGUF multimodal-projector recovery changed the load. "
            "'cpu_offload' keeps vision with the projector on CPU; "
            "'projector_incompatible' and 'projector_startup_failure' mean the "
            "model recovered text-only."
        ),
    )
    n_cpu_moe: int = Field(
        0,
        description = "Manual mode: MoE expert layers pinned to CPU (--n-cpu-moe); 0 = none.",
    )
    tensor_split: Optional[List[float]] = Field(
        None,
        description = "Relative model share per GPU (--tensor-split) used by the active load; None = default (split by free VRAM).",
    )
    n_layers: Optional[int] = Field(
        None,
        description = "Model's layer count (GGUF block_count), for the manual gpu-layers ceiling.",
    )
    n_moe_layers: int = Field(
        0,
        description = "Model's MoE expert-layer count (the n_cpu_moe ceiling); 0 if not an MoE model.",
    )
    gpu_ids: Optional[List[int]] = Field(
        None,
        description = "Effective GPU indices the model is using after fit-time narrowing, or None for automatic selection.",
    )
    requested_gpu_ids: Optional[List[int]] = Field(
        None,
        description = (
            "GPU placement pool requested by the user before fit-time narrowing, "
            "or None for automatic selection."
        ),
    )
    requested_parallel_slots: Optional[int] = Field(
        None,
        description = (
            "Replies the load was invoked with (per-load n_parallel, else the "
            "default; for GGUF, the server-wide --parallel set at launch). None "
            "for the diffusion runner, which ignores --parallel."
        ),
    )
    parallel_slots: Optional[int] = Field(
        None,
        description = (
            "Replies the loaded model is configured to decode at once. Not what any "
            "one reply is running under: a batch already decoding keeps the width it "
            "opened at until it drains, since resizing it would drop the replies "
            "inside it, and a request submitted before a change carries the width it "
            "was submitted with. For "
            "GGUF these are llama-server's --parallel slots after any fit-time "
            "reduction; elsewhere it is 1 when the runtime has no batched "
            "generation, or its settings rule it out. None for the diffusion "
            "runner, which ignores --parallel, and when the runtime did not say."
        ),
    )
    requested_n_batch: Optional[int] = Field(
        None,
        description = (
            "Batch size (--batch-size) the load was invoked with, or None when "
            "the load left it at the llama.cpp default (or to extra args / env)."
        ),
    )
    requested_n_ubatch: Optional[int] = Field(
        None,
        description = (
            "Micro-batch size (--ubatch-size) the load was invoked with, or None "
            "when the load left it at the llama.cpp default (or to extra args / env)."
        ),
    )
    requested_load_mode: Optional[str] = Field(
        None,
        description = (
            "Load mode (--load-mode) the load was invoked with, or None when the "
            "load left it at the llama.cpp default. This is what was REQUESTED: "
            "the Model Memory settings can replace it, and what they emit is "
            "reported by the model-memory settings route instead."
        ),
    )
    requested_spec_draft_cache_type: Optional[str] = Field(
        None,
        description = (
            "Draft KV cache dtype the load was invoked with, or None when the "
            "load left it at the llama.cpp default (or attached no drafter)."
        ),
    )
    requested_ctx_checkpoints: Optional[int] = Field(
        None,
        description = (
            "Checkpoints (--ctx-checkpoints) the load was invoked with, or None "
            "when the load left it at the llama.cpp default."
        ),
    )
    requested_cache_ram: Optional[int] = Field(
        None,
        description = (
            "Host prompt cache size in MiB (--cache-ram) the load was invoked "
            "with, or None when the load left it at the llama.cpp default."
        ),
    )
    requested_llama_extra_args: Optional[List[str]] = Field(
        None,
        description = (
            "Pass-through llama-server arguments the running load was INVOKED "
            "with, or None for a non-GGUF load and for a load that passed none. "
            "Published so a client that attached to an already-running server "
            "(a fresh tab, or another browser) knows what it is running: without "
            "it, a rollback after a failed switch restores the previous model "
            "without the arguments it had."
        ),
    )


class EvictedSlot(BaseModel):
    """A model a load unloaded to make room."""

    kind: Literal["chat", "audio", "image", "video"] = Field(
        ..., description = "chat, audio (a native or audio.cpp audio model), image or video"
    )
    model: str = Field(..., description = "Public model id, as /api/inference/status prints it")


class LoadResponse(_InferenceRuntimeFields):
    """Response after loading a model"""

    status: str = Field(..., description = "Load status")
    model: str = Field(..., description = "Model identifier")
    display_name: str = Field(..., description = "Display name of the model")
    is_lora: bool = Field(False, description = "Whether model is a LoRA adapter")
    is_gguf: bool = Field(False, description = "Whether model is a GGUF model (llama.cpp)")
    is_local_model: bool = Field(
        False, description = "Whether the loaded model came from a local filesystem path"
    )
    inference: dict = Field(
        ..., description = "Inference parameters (temperature, top_p, top_k, min_p)"
    )
    memory_warning: Optional[str] = Field(
        None,
        description = "Non-blocking advisory about this load, or null. Set when the "
        "weights do not fit in free VRAM plus available system RAM, so llama.cpp pages "
        "them in from disk and generation will be slow, or when the requested GGUF quant "
        "did not fit on disk and a smaller one was loaded. The model still loaded.",
    )
    carveout_advice: Optional[dict] = Field(
        None,
        description = "Non-blocking advisory, or null: this machine's integrated GPU has "
        "less memory dedicated to it than this model's weights need, so they run from "
        "shared system memory and generation is slower than it could be. Carries "
        "current_gb, needed_gb, suggested_gb, machine_gb, host_left_gb and a prose "
        "message. Null once the user has dismissed it at this allocation, and on every "
        "load where enlarging the allocation would not help. The model still loaded.",
    )
    evicted: list[str] = Field(
        default_factory = list,
        description = "Models unloaded to make room for this one: chat models loaded alongside, "
        "the replaced chat model, and any image or video model this load freed.",
    )
    evicted_slots: list[EvictedSlot] = Field(
        default_factory = list,
        description = "The same models as evicted, each with its kind and public model id.",
    )


class UnloadResponse(BaseModel):
    """Response after unloading a model"""

    status: str = Field(..., description = "Unload status")
    model: str = Field(..., description = "Model identifier that was unloaded")


class LoadProgressResponse(BaseModel):
    """Progress of the active GGUF load, sampled on demand.

    Drives a real progress bar during the post-download warmup (mmap + CUDA upload)
    instead of a spinner that freezes for minutes on large MoE models.
    """

    phase: Optional[str] = Field(
        None,
        description = (
            "Load phase: 'mmap' (weights paging into RAM via mmap), "
            "'ready' (llama-server reported healthy), or null when no "
            "load is in flight."
        ),
    )
    bytes_loaded: int = Field(
        0,
        description = (
            "Bytes of the model already resident in the llama-server process (VmRSS on Linux)."
        ),
    )
    bytes_total: int = Field(
        0,
        description = "Total bytes across all GGUF shards for the active model.",
    )
    fraction: float = Field(0.0, description = "bytes_loaded / bytes_total, clamped to 0..1.")


class LlamaFlagCatalogResponse(BaseModel):
    """Every llama-server flag THIS build documents, for validating pass-through args.

    Read from the installed binary's ``--help`` rather than a list bundled with
    Unsloth: a custom or newer llama.cpp is exactly the case where a bundled list
    would reject a flag that works, or accept one that does not exist.
    """

    flags: dict[str, str] = Field(
        default_factory = dict,
        description = "Flag name -> its help text, e.g. {'--top-k': 'top-k sampling ...'}",
    )
    managed: list[str] = Field(
        default_factory = list,
        description = "Flags Unsloth Studio owns; validate_extra_args rejects these outright",
    )
    switch_flags: list[str] = Field(
        default_factory = list,
        description = (
            "Flags this build documents as taking no value, so an editor can tell "
            "'--verbose foo' (which llama-server refuses) from '--numa distribute'"
        ),
    )
    max_bytes: int = Field(
        0,
        description = (
            "Size limit validate_extra_args applies on THIS host; smaller on Windows, "
            "where the whole command line shares one 32767-character budget"
        ),
    )
    windows_command_budget: int = Field(
        0,
        description = (
            "Characters the quoted command may take on Windows, or 0 elsewhere. An "
            "editor mirrors it because the quoting can double a backslash-heavy value."
        ),
    )
    default_parallel_slots: int = Field(
        1,
        description = (
            "Serving slots a load gets when it names none, the server-wide "
            "--parallel. An editor needs it to judge a pass-through --batch-size: "
            "llama-server aborts on a batch below the slots it serves, and with the "
            "Slots field blank this is the number the launch will use."
        ),
    )
    parallel_slots_clamped: bool = Field(
        False,
        description = (
            "True when this build serves ONE slot however many are asked for, because "
            "it has no --kv-unified and load_model falls back. The default above is "
            "already effective, but an EXPLICIT Slots value is not: without this an "
            "editor sizes its batch floor from a count the launch will not use, and "
            "refuses a --batch-size the backend accepts."
        ),
    )
    probe_ok: bool = Field(
        False,
        description = (
            "False when --help could not be read. `flags` is then empty and callers "
            "must not report a flag as unknown, only as unverified."
        ),
    )


class InferenceStatusResponse(_InferenceRuntimeFields):
    """Current inference backend status"""

    resident_mib: Optional[int] = Field(
        None,
        description = "Best-effort memory the resident model holds, in MiB; null when unknown.",
    )
    resident_on_gpu: Optional[bool] = Field(
        None,
        description = "True when resident_mib is model buffers on the GPUs /api/system reports, false for a CPU-only llama.cpp build, null when unknown (Vulkan or SYCL buffers are not parsed).",
    )
    active_model: Optional[str] = Field(
        None, description = "Currently active model display identifier"
    )
    model_identifier: Optional[str] = Field(
        None,
        description = "Loadable identifier for the active model.",
    )
    is_gguf: bool = Field(False, description = "Whether the active model is a GGUF model (llama.cpp)")
    is_local_model: bool = Field(
        False, description = "Whether the active model came from a local filesystem path"
    )
    gguf_variant: Optional[str] = Field(None, description = "GGUF quantization variant (e.g. Q4_K_M)")
    memory_warning: Optional[str] = Field(
        None,
        description = "Non-blocking advisory about the active load, or null: the "
        "memory_warning its load response carried, kept while that model is running.",
    )
    loading: List[str] = Field(default_factory = list, description = "Models currently being loaded")
    loaded: List[str] = Field(default_factory = list, description = "Models currently loaded")
    multi_model_mode: Optional[Literal["off", "fit", "always"]] = Field(
        None,
        description = "Keep multiple models loaded: off, fit (When they fit) or always.",
    )
    serving: List[str] = Field(
        default_factory = list,
        description = "Models answering requests: the active one and each kept alongside. "
        "Unlike loaded, leaves out a model only held in memory behind the active one.",
    )
    serving_checkpoints: List[str] = Field(
        default_factory = list,
        description = "The checkpoint id each serving entry is loaded from, in the same order: "
        "the path of a local model, else the same id. Load, select and unload by this one.",
    )
    inference: Optional[Dict[str, Any]] = Field(
        None, description = "Recommended inference parameters for the active model"
    )
    requested_context_length: Optional[int] = Field(
        None,
        description = (
            "The context length the active load was invoked with: 0 means the load asked "
            "the backend to choose, and null means the serving backend records no request "
            "at all. Both local backends size their own window, so context_length reports "
            "only what was resolved and cannot say whether anyone chose it; this is what "
            "lets a client restore the user's choice after a reload."
        ),
    )
    load_in_4bit: Optional[bool] = Field(
        None,
        description = (
            "The 4-bit setting the active non-GGUF load was REQUESTED with, not the "
            "value it resolved to: LoRA and the latest-transformers tier rewrite it, so "
            "only the requested value can be compared against a later request. None for "
            "GGUF, which does not use it."
        ),
    )
    llama_cpp_supports_mtp: bool = Field(
        True,
        description = (
            "Whether llama.cpp supports MTP (--spec-type mtp/draft-mtp). "
            "False -> recommend `unsloth studio update`."
        ),
    )
    spec_fallback_binary_changed: Optional[bool] = Field(
        None,
        description = (
            "For a 'binary_no_mtp' / 'binary_outdated' stand-down only: whether a "
            "different llama-server is installed than the live one launched from, "
            "which is the necessary condition in "
            "LlamaCppBackend.spec_binary_fallback_can_retry. False -> an identical "
            "/load cannot repair the drafter and dedupes, so a client need not "
            "reload for it. None for every other reason, and on a backend too old "
            "to report it."
        ),
    )
    spec_probe_retry_pending: Optional[bool] = Field(
        None,
        description = (
            "The capability probe has started answering since a launch it degraded, so "
            "an identical /load is rejected once to re-derive the runtime "
            "(_runtime_matches_intent's _capability_probe_inconclusive arm). No "
            "speculative mode gates it. None on a backend too old to report it."
        ),
    )
    spec_dflash_retry_pending: Optional[bool] = Field(
        None,
        description = (
            "A DFlash sidecar fetch failed retryably, which under Auto records no "
            "spec_fallback_reason at all, so an identical /load is rejected to fetch "
            "again. Applies to the 'auto' and 'dflash' modes. None on a backend too old "
            "to report it."
        ),
    )
    spec_dspark_sidecar_absent: Optional[bool] = Field(
        None,
        description = (
            "The DSpark drafter is absent rather than transiently unfetchable, which is "
            "the permanent state of every repo but one. _runtime_matches_intent excludes "
            "it from the drafter_not_found retry arm, so an identical /load dedupes and a "
            "client need not reload for it. None on a backend too old to report it."
        ),
    )
    tensor_parallel_dropped_by_arch_gate: Optional[bool] = Field(
        None,
        description = (
            "The GPU architecture gate normalized a tensor-parallel request to layer "
            "mode, so tensor_parallel reads false while the request that produced it was "
            "true. _runtime_matches_intent accepts the same true request against this "
            "runtime. None on a backend too old to report it."
        ),
    )
    gpu_placement_paravirtual: Optional[bool] = Field(
        None,
        description = (
            "Metal is a virtualised Apple GPU, so paravirtual_normalized_request rewrites "
            "every GGUF request to manual / zero layers / no split / no MoE before the "
            "duplicate-load comparators run. Placement cannot tell two requests apart "
            "here. None on a backend too old to report it."
        ),
    )
    audio_probe_pending: bool = Field(
        False,
        description = (
            "The post-launch audio probe did not finish and has to be retried. The route "
            "refuses its own already-loaded answer while this is true so load_model can "
            "re-probe, and nothing else does, so a client must not skip /load for it."
        ),
    )
    diffusion_split_supported: Optional[bool] = Field(
        None,
        description = (
            "A diffusion launch right now would honour --ngl. _runtime_matches_intent "
            "rejects an otherwise identical request once this is true and gpu_layers "
            "differs from diffusion_requested_ngl, so a split an older shim dropped can "
            "be applied. None off a diffusion runner, and on a backend too old to report "
            "it."
        ),
    )
    llama_cpp_prebuilt_stale: bool = Field(
        False,
        description = (
            "Installed llama.cpp prebuilt is >=3 days behind the latest "
            "release. True -> show `unsloth studio update` banner."
        ),
    )
    llama_cpp_installed_tag: Optional[str] = Field(
        None,
        description = "Installed llama.cpp tag, or None if unknown.",
    )
    llama_cpp_latest_tag: Optional[str] = Field(
        None,
        description = "Latest published llama.cpp tag, or None if GitHub unreachable.",
    )


class TextContentPart(BaseModel):
    """Text content part in a multimodal message."""

    type: Literal["text"]
    text: str


class ImageUrl(BaseModel):
    """Image URL object — supports data URIs and remote URLs."""

    url: str = Field(..., description = "data:image/png;base64,... or https://...")
    detail: Optional[Literal["auto", "low", "high", "original"]] = "auto"


class ImageContentPart(BaseModel):
    """Image content part in a multimodal message."""

    type: Literal["image_url"]
    image_url: ImageUrl


class VideoUrl(BaseModel):
    """Video URL object: an inline data URI. Remote URLs are not fetched."""

    url: str = Field(..., description = "data:video/mp4;base64,... (inline only)")


class VideoContentPart(BaseModel):
    """Video content part for llama-server or a custom OpenAI-compatible connection."""

    type: Literal["video_url"]
    video_url: VideoUrl


class InputDocumentContentPart(BaseModel):
    """Document (PDF / file) content part in a multimodal message.

    Unsloth-normalised shape (file_data or file_url, plus optional filename/media_type).
    Mapped onto Anthropic ``document`` / OpenAI ``input_file`` for vision providers;
    dropped for non-vision providers.
    """

    type: Literal["input_document"]
    file_data: Optional[str] = Field(
        None,
        description = "data:<media_type>;base64,<DATA> URI for inline payloads. Either file_data or file_url must be set; otherwise the part is dropped.",
    )
    file_url: Optional[str] = Field(
        None,
        description = "Remote URL pointing to the document (https://...).",
    )
    filename: Optional[str] = Field(
        None,
        description = "Display filename, forwarded to providers as `title`/`filename`.",
    )
    media_type: Optional[str] = Field(
        None,
        description = 'Override the media type sniffed from the data URI (e.g. "application/pdf").',
    )


class OpenAIReasoningContentPart(BaseModel):
    """OpenAI Responses reasoning item paired with a tool output.

    Reasoning models may require this replayed before an ``image_generation_call``
    id. OpenAI-only; routes strip it for other providers before proxying.
    """

    type: Literal["reasoning"]
    id: str = Field(..., description = "OpenAI reasoning output item id.")
    summary: list[dict[str, Any]] = Field(default_factory = list)
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None


class ImageGenerationCallContentPart(BaseModel):
    """OpenAI Responses image_generation call reference.

    Prior ``image_generation_call`` items let follow-up prompts edit a generated
    image without resending the payload. The frontend forwards it as a synthetic
    assistant part; ``external_provider`` maps it back to a top-level input item.
    """

    type: Literal["image_generation_call"]
    id: str = Field(..., description = "OpenAI image_generation_call output item id.")
    response_id: Optional[str] = Field(
        None,
        description = "OpenAI Responses response id to use as previous_response_id for follow-up edits.",
    )


class CompactionContentPart(BaseModel):
    """round-trip Anthropic summaries and opaque OpenAI Responses compaction state."""

    type: Literal["compaction"]
    content: Optional[str] = Field(
        None,
        description = "Anthropic-produced summary of the compacted-away conversation prefix.",
    )
    encrypted_content: Optional[str] = Field(
        None,
        description = "OpenAI Responses compaction item, opaque.",
    )


class InputAudio(BaseModel):
    data: str = Field(
        ..., min_length = 1, description = "Base64-encoded audio, without a data: prefix."
    )
    format: Optional[str] = Field(
        None, description = 'Declared container, e.g. "wav"; the decoder sniffs it anyway.'
    )


class InputAudioContentPart(BaseModel):
    type: Literal["input_audio"]
    input_audio: InputAudio


class UnknownContentPart(BaseModel):
    type: str

    model_config = {"extra": "allow"}


_KNOWN_CONTENT_PART_TAGS = frozenset(
    {
        "text",
        "image_url",
        "video_url",
        "input_audio",
        "input_document",
        "reasoning",
        "image_generation_call",
        "compaction",
    }
)


def _content_part_discriminator(v):
    tag = v.get("type") if isinstance(v, dict) else getattr(v, "type", None)
    # An unhashable tag would raise TypeError out of validation as a 500.
    if not isinstance(tag, str):
        return None
    return tag if tag in _KNOWN_CONTENT_PART_TAGS else "unknown"


ContentPart = Annotated[
    Union[
        Annotated[TextContentPart, Tag("text")],
        Annotated[ImageContentPart, Tag("image_url")],
        Annotated[VideoContentPart, Tag("video_url")],
        Annotated[InputAudioContentPart, Tag("input_audio")],
        Annotated[InputDocumentContentPart, Tag("input_document")],
        Annotated[OpenAIReasoningContentPart, Tag("reasoning")],
        Annotated[ImageGenerationCallContentPart, Tag("image_generation_call")],
        Annotated[CompactionContentPart, Tag("compaction")],
        Annotated[UnknownContentPart, Tag("unknown")],
    ],
    Discriminator(_content_part_discriminator),
]
"""Union type for multimodal content parts, discriminated by the 'type' field."""


class ChatMessage(BaseModel):
    """Single message in a chat conversation.

    ``content`` is a string or list of multimodal parts. Assistant messages with
    only ``tool_calls`` may set ``content=None``. Missing ``tool_call_id`` on
    ``role="tool"`` is resolved at the ``ChatCompletionRequest`` layer.
    """

    role: Literal["system", "user", "assistant", "tool", "developer"] = Field(
        ..., description = "Message role"
    )
    content: Optional[Union[str, list[ContentPart]]] = Field(
        None, description = "Message content (string or multimodal parts)"
    )
    reasoning_content: Optional[str] = Field(
        None,
        description = (
            "Assistant reasoning from an earlier turn, replayed to local chat templates "
            "that consume the OpenAI-compatible reasoning_content field."
        ),
    )
    tool_call_id: Optional[str] = Field(
        None,
        description = "OpenAI tool-result messages: id of the tool call this result belongs to.",
    )
    tool_calls: Optional[list[dict]] = Field(
        None,
        description = "OpenAI assistant messages: structured tool calls the model decided to make.",
    )
    name: Optional[str] = Field(
        None,
        description = "Participant name, or the tool name on tool-result messages.",
    )
    extra_content: Optional[dict] = Field(
        None,
        description = (
            "Provider-specific extra fields the translator may read. "
            "Gemini reads `extra_content.google.thought_signature` "
            "from assistant messages to replay text-part signatures."
        ),
    )

    @field_validator("reasoning_content", mode = "before")
    @classmethod
    def _ignore_non_string_reasoning(cls, value):
        # Gateways may send structured reasoning; do not turn it into a validation error.
        return value if isinstance(value, str) else None

    @model_validator(mode = "after")
    def _validate_role_shape(self) -> "ChatMessage":
        if self.tool_calls is not None and self.role != "assistant":
            raise ValueError('"tool_calls" is only valid on role="assistant" messages.')
        if self.tool_call_id is not None and self.role != "tool":
            raise ValueError('"tool_call_id" is only valid on role="tool" messages.')
        # llama-server puts the marker in any turn carrying it, so off a user turn it is template-dependent.
        if (
            self.role != "user"
            and isinstance(self.content, list)
            and any(isinstance(part, VideoContentPart) for part in self.content)
        ):
            raise ValueError(f'"video_url" parts are not valid on role="{self.role}" messages.')

        if self.role == "tool":
            # OpenAI accepts empty tool results; normalize to "" instead of a 400.
            if self.content is None or self.content == []:
                self.content = ""
        elif self.role == "assistant":
            # Post-Stop sentinel: collapse content="" / [] to None.
            if (self.content == "" or self.content == []) and not self.tool_calls:
                self.content = None
        else:  # "user" | "system"
            if self.content is None or self.content == []:
                raise ValueError(f'role="{self.role}" messages require "content".')
        return self


class ThinkingConfig(BaseModel):
    """Anthropic-compatible thinking/reasoning configuration.
    Use type='disabled' to turn off thinking, or type='enabled' to turn it on.
    Only type is read; extra fields (e.g. budget_tokens) are ignored, since
    Unsloth sets provider thinking budgets itself.
    """

    type: Literal["disabled", "enabled"] = "disabled"


def resolve_thinking_onto_enable_thinking(request):
    """Map Anthropic-style ``thinking`` onto the internal ``enable_thinking``. ``enable_thinking`` wins
    when both are given. Shared with counting, which must resolve the reasoning preamble exactly as
    the completion does."""
    if request.thinking is not None and request.enable_thinking is None:
        # Derived, not an x-unsloth override: kept out of model_fields_set so precedence ranks it below nested controls; covers explicit null.
        object.__setattr__(request, "enable_thinking", request.thinking.type == "enabled")
        request.model_fields_set.discard("enable_thinking")
    return request


class ReasoningControlsRequest(BaseModel):
    """The reasoning controls a request may carry, resolved the way a completion does.

    ChatCompletionRequest shares the resolution above rather than inheriting: pydantic
    orders inherited fields ahead of a subclass's own, reordering its OpenAPI properties
    and validation errors.
    """

    enable_thinking: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Enable/disable thinking/reasoning mode for supported models",
    )
    reasoning_effort: Optional[
        Literal["none", "minimal", "low", "medium", "high", "max", "xhigh"]
    ] = Field(
        None,
        description = "[x-unsloth] Reasoning effort level ('none'|'minimal'|'low'|'medium'|'high'|'max'|'xhigh'). OpenAI `/v1/responses` accepts model-dependent subsets; Anthropic adaptive thinking uses `max` as the top tier on Claude 4.6 Opus/Sonnet (inbound `xhigh` is mapped to `max`) and `xhigh` on Claude 4.7 Opus; local Harmony/gpt-oss templates support low|medium|high.",
    )
    preserve_thinking: Optional[bool] = Field(
        None,
        description = "[x-unsloth] When true, keep historical <think> blocks from past assistant turns in the prompt (Qwen3.6 templates). Independent of enable_thinking / reasoning_effort.",
    )
    thinking: Optional[ThinkingConfig] = Field(
        None,
        description = "[Anthropic-compatible] Thinking configuration. "
        "Use {type: 'disabled'} to disable thinking, {type: 'enabled'} to enable.",
    )

    @model_validator(mode = "after")
    def _map_thinking_to_enable_thinking(self):
        return resolve_thinking_onto_enable_thinking(self)


# Plain string, not Literal: unknown modes degrade to ask instead of a 422; None stays unset at the request boundary.
_KNOWN_PERMISSION_MODES = ("ask", "auto", "off", "full")


def _normalize_permission_mode(value: Any) -> Any:
    if value is None:
        return None
    if value not in _KNOWN_PERMISSION_MODES:
        return "ask"
    return value


def _normalize_sandbox_level(value: Any) -> Any:
    # Unlike permission_mode, an unknown level is a 422: degrading it either way would guess at
    # the isolation the user picked. Absent or null is "high", today's behaviour.
    if value is None:
        return "high"
    if isinstance(value, str):
        return value.strip().lower()
    return value


_SANDBOX_LEVEL_DESCRIPTION = (
    "[x-unsloth] Sandbox level for the Python and Terminal tools. 'high' (default) runs them "
    "in the OS sandbox when it works and on software safeguards otherwise. 'low' runs them on "
    "software safeguards only, so on a streaming UI chat 'off' still asks before their "
    "high-risk calls; elsewhere 'off' never prompts, as before. Full access overrides both. "
    "Case-insensitive; any other value is rejected."
)


class SandboxAttachment(BaseModel):
    sha256: str = Field(..., pattern = r"^[0-9a-f]{64}$")
    name: str = Field(..., max_length = 1024)


class ChatCompletionRequest(BaseModel):
    """OpenAI-compatible chat completion request.

    Non-OpenAI extension fields are marked with 'x-unsloth'."""

    model_config = {"extra": "allow"}
    # "off" with the client's own confirm_tool_calls=false: no prompt at all, even without OS isolation.
    _off_confirm_opt_out: bool = PrivateAttr(default = False)
    # Anthropic web_search allowed/blocked domains; server-side only, never a request field.
    _website_policy: Optional[dict] = PrivateAttr(default = None)

    model: str = Field(
        "default",
        description = "Model identifier (informational; the active model is used)",
    )
    messages: list[ChatMessage] = Field(..., description = "Conversation messages")
    stream: bool = Field(
        False,
        description = (
            "Whether to stream the response via SSE. Default matches OpenAI's "
            "spec (`false`); opt into streaming by sending `stream: true`."
        ),
    )
    temperature: float = Field(0.6, ge = 0.0, le = 2.0)
    top_p: float = Field(0.95, ge = 0.0, le = 1.0)
    max_tokens: Optional[int] = Field(
        None, ge = 1, description = "Maximum tokens to generate (None = until EOS)"
    )
    # Matches OpenAI's [-2, 2] range; negative values boost repetition where the backend applies them.
    presence_penalty: float = Field(
        0.0,
        ge = -2.0,
        le = 2.0,
        description = (
            "Presence penalty: charges a token once if it appears. MLX scores the completion"
            " only; llama-server also counts the prompt, within its own window."
        ),
    )
    frequency_penalty: float = Field(
        0.0,
        ge = -2.0,
        le = 2.0,
        description = (
            "Frequency penalty: charges a token per occurrence. MLX scores the completion"
            " only; llama-server also counts the prompt, within its own window."
        ),
    )
    # Token ids are not range-checked; MLX does not either, so a stray id is dropped at the processors.
    logit_bias: Optional[Dict[int, Annotated[float, Field(ge = -100.0, le = 100.0)]]] = Field(
        None,
        description = "Additive per-token logit bias keyed by token id, each in [-100, 100]. Ids past the model's logit width are ignored.",
    )
    stop: Optional[Union[str, list[str]]] = Field(
        None,
        description = "OpenAI stop sequences: a single string or list of strings at which generation halts.",
    )
    # Declared, not left to model_extra, so the schema documents it and a backend can refuse it by name.
    response_format: Optional[Dict[str, Any]] = Field(
        None,
        description = (
            'Guided decoding contract, typically `{"type": "json_object"}` or'
            ' a `json_schema`. `{"type": "text"}` names the default and'
            " constrains nothing. Anything else needs a grammar engine, and a"
            " backend without one rejects the request rather than answering text"
            " that ignores the contract."
        ),
    )
    tools: Optional[list[dict]] = Field(
        None,
        description = (
            "OpenAI function-tool definitions. When provided without `enable_tools=true`, "
            "Unsloth forwards the tools to the backend so the model returns structured "
            "tool_calls for the client to execute (standard OpenAI function calling)."
        ),
    )
    tool_choice: Optional[Union[str, dict]] = Field(
        None,
        description = (
            "OpenAI tool choice: 'auto' | 'required' | 'none' | "
            "{'type': 'function', 'function': {'name': ...}}"
        ),
    )
    max_completion_tokens: Optional[int] = Field(
        None,
        ge = 1,
        description = "OpenAI upper bound on generated tokens (supersedes the deprecated max_tokens).",
    )
    n: Optional[int] = Field(
        None,
        ge = 1,
        le = 128,
        description = "Number of chat completion choices to generate.",
    )
    logprobs: Optional[bool] = Field(
        None, description = "Whether to return log probabilities of the output tokens."
    )
    top_logprobs: Optional[int] = Field(
        None,
        ge = 0,
        le = 20,
        description = "Number of most likely tokens (0-20) to return per position; requires logprobs=true.",
    )
    parallel_tool_calls: Optional[bool] = Field(
        None, description = "Whether to enable parallel function calling during tool use."
    )
    seed: Optional[int] = Field(
        None,
        ge = -(2**63),
        le = 2**64 - 1,
        description = "Best-effort deterministic sampling seed.",
    )
    stream_options: Optional[dict] = Field(
        None,
        description = 'Streaming options, e.g. {"include_usage": true} to emit a final usage chunk.',
    )

    top_k: int = Field(20, ge = -1, le = 100, description = "[x-unsloth] Top-k sampling")
    min_p: float = Field(0.01, ge = 0.0, le = 1.0, description = "[x-unsloth] Min-p sampling threshold")
    repetition_penalty: float = Field(
        1.0, ge = 1.0, le = 2.0, description = "[x-unsloth] Repetition penalty"
    )
    image_base64: Optional[str] = Field(
        None, description = "[x-unsloth] Base64-encoded image for vision models"
    )
    audio_base64: Optional[str] = Field(
        None,
        description = "[x-unsloth] Base64-encoded audio (wav/mp3/ogg/flac/m4a) for audio-input models",
    )
    modalities: Optional[List[Literal["text", "audio"]]] = Field(
        None,
        description = (
            'Output modalities, as OpenAI\'s. ["text", "audio"] asks a model that speaks (status '
            "speaks) to answer the spoken question in audio_base64 in its own voice as well: the "
            "reply text, then message.audio / delta.audio {data: base64 wav, format: wav, "
            "sample_rate}. The model samples the reply its own way, so sampling settings do not "
            "apply and stop sequences are refused; max_tokens and usage count speech frames as "
            "well as text tokens; a streamed reply arrives whole, as one text delta and one audio delta."
        ),
    )
    extra_audio_base64: Optional[List[str]] = Field(
        None,
        description = (
            "[x-unsloth] Further recordings after audio_base64, in order, for models that take "
            "several clips in one message. Size and duration caps apply to all clips together."
        ),
    )
    audio_instructions: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] Scene or music-description instructions for native audio models. "
            "MiniMax Music 3 requires this alongside lyrics."
        ),
    )
    audio_language: Optional[str] = Field(
        None,
        description = "[x-unsloth] Target-language hint for native audio models that support it.",
    )
    audio_options: Optional[Dict[str, Any]] = Field(
        None,
        description = (
            "[x-unsloth] Per-model request options ({name: value}) for audio GGUF models, as listed "
            "in the loaded model's audio_options. Unknown names are dropped."
        ),
    )
    video_base64: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] Base64-encoded video (mp4/mov/webm/mkv/avi) for video-input "
            "models: a GGUF served by llama-server, or an MLX model whose processor reads video."
        ),
    )
    use_adapter: Optional[Union[bool, str]] = Field(
        None,
        description = (
            "[x-unsloth] Adapter control for compare mode. "
            "null = no change (default), "
            "false = disable adapters (base model), "
            "true = enable the current adapter, "
            "string = enable a specific adapter by name."
        ),
    )
    enable_thinking: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Enable/disable thinking/reasoning mode for supported models",
    )
    continue_final_message: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Continue the trailing assistant message instead of starting a new "
            "turn: the prompt ends mid-response so the model resumes token-exactly from "
            "where it stopped. Requires the last message to have role 'assistant'."
        ),
    )
    reasoning_effort: Optional[
        Literal["none", "minimal", "low", "medium", "high", "max", "xhigh"]
    ] = Field(
        None,
        description = "[x-unsloth] Reasoning effort level ('none'|'minimal'|'low'|'medium'|'high'|'max'|'xhigh'). OpenAI `/v1/responses` accepts model-dependent subsets; Anthropic adaptive thinking uses `max` as the top tier on Claude 4.6 Opus/Sonnet (inbound `xhigh` is mapped to `max`) and `xhigh` on Claude 4.7 Opus; local Harmony/gpt-oss templates support low|medium|high.",
    )
    preserve_thinking: Optional[bool] = Field(
        None,
        description = "[x-unsloth] When true, keep historical <think> blocks from past assistant turns in the prompt (Qwen3.6 templates). Independent of enable_thinking / reasoning_effort.",
    )
    thinking: Optional[ThinkingConfig] = Field(
        None,
        description = "[Anthropic-compatible] Thinking configuration. "
        "Use {type: 'disabled'} to disable thinking, {type: 'enabled'} to enable.",
    )
    enable_tools: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Enable tool calling for supported models",
    )
    enabled_tools: Optional[list[str]] = Field(
        None,
        description = (
            "[x-unsloth] List of enabled tool names. Local GGUF/safetensors models "
            "accept ['web_search', 'python', 'terminal', 'edit_file', 'render_html']. External "
            "providers accept ['web_search', 'web_fetch', 'code_execution'] for "
            "Anthropic and ['web_search', 'code_execution', 'image_generation'] for "
            "OpenAI Responses. If None, all local tools are enabled and no "
            "server-side tools are forwarded."
        ),
    )
    mcp_enabled: Optional[bool] = Field(
        None,
        description = "[x-unsloth] When true, append tools from every enabled MCP server to this request's tool list.",
    )
    mcp_image: Optional[str] = Field(
        None,
        max_length = 15 * 1024 * 1024,
        description = (
            "[x-unsloth] PNG, JPEG or WebP data URL that MCP tools with a mapped image field can "
            "receive after the user approves each call. Never shown to the model."
        ),
    )
    deep_research_armed: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Offer the deep_research handoff tool for this turn. Set when the "
            "composer has Deep Research armed; the model decides whether to use it."
        ),
    )
    confirm_tool_calls: Optional[bool] = Field(
        None,
        description = "[x-unsloth] When true, pause before each tool call and wait for the user to allow/deny it via POST /api/inference/tool-confirm.",
    )
    bypass_permissions: Optional[bool] = Field(
        False,
        description = "[x-unsloth] Bypass Permissions: when true, skip the tool-call confirmation gate AND disable the python/terminal execution sandbox (safety checks, command blocklist, resource limits). edit_file is likewise unconfined: an absolute path resolves as written and edits the real file there, instead of being held to the conversation's working directory. Secret env vars are still stripped. Takes precedence over confirm_tool_calls. Refused (400) for API keys and keyless API access unless the server sets UNSLOTH_STUDIO_ALLOW_API_FULL_ACCESS=1.",
    )
    permission_mode: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] Permission level for local tool calls. 'ask' pauses every "
            "call for approval; 'ask'/'auto' enable the confirmation gate on their "
            "own (needs a streaming request to deliver prompts). 'auto' ('Approve for "
            "me') only pauses calls detected as high risk (credential reads, privilege "
            "escalation, destructive/persistence, network exfil); ordinary calls run "
            "immediately, and the sandbox stays on. 'full' is equivalent to "
            "bypass_permissions=true (no confirmation, no sandbox). Unset defaults to "
            "'auto' for the per-call gate; a non-streaming request without an explicit "
            "mode cannot prompt and runs the loop. An unrecognized value (e.g. from a "
            "newer client) is treated as 'ask'."
        ),
    )
    sandbox_level: Literal["high", "low"] = Field(
        "high",
        description = _SANDBOX_LEVEL_DESCRIPTION,
    )
    auto_heal_tool_calls: Optional[bool] = Field(
        True,
        description = "[x-unsloth] Auto-detect and fix malformed tool calls from model output.",
    )
    nudge_tool_calls: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Opt-in tool-call recovery: when a model stalls with a short "
            "plan instead of calling an available tool, or passthrough healing cannot "
            "repair a malformed call, retry with a short nudge. Default off; "
            "UNSLOTH_TOOL_CALL_NUDGE=1 flips the process default."
        ),
    )
    deduplicate_tool_calls: Optional[bool] = Field(
        True,
        description = (
            "[x-unsloth] When false, a tool call identical to one that already "
            "succeeded in this response runs again instead of being answered "
            "with a duplicate notice. Default on."
        ),
    )
    context_overflow: Optional[Literal["error", "truncate_middle", "truncate_oldest"]] = Field(
        None,
        description = (
            "[x-unsloth] Local GGUF context-overflow behavior. 'error' (default) "
            "returns a 400 with code=context_length_exceeded. 'truncate_middle' is "
            "limited to client-tool or response_format passthrough and retries after "
            "keeping the first and recent turns. 'truncate_oldest' provides a rolling "
            "window for plain and Unsloth-tool chats by dropping complete oldest turns. "
            "Both truncation policies preserve system messages and tool-call groups. "
            "MLX models honor 'truncate_oldest' only, as do external providers "
            "given a compaction_threshold."
        ),
    )
    context_policy: Optional[Literal["checkpoint", "rolling"]] = Field(
        None,
        description = (
            "[x-unsloth] How a local GGUF or MLX chat compacts once context_overflow is "
            "truncate_oldest. 'checkpoint' resets to the latest turn plus standing "
            "instructions (Unsloth default). 'rolling' drops oldest complete turns. "
            "Unset uses UNSLOTH_CONTEXT_POLICY. On MLX only Unsloth-tool chats start a "
            "reset."
        ),
    )
    compaction_headroom_ratio: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 0.9,
        description = (
            "[x-unsloth] Extra share of the prompt budget to drop when a rolling "
            "compaction fires, so the boundary can stay put for a stretch of turns. "
            "A checkpoint reset leaves the same share free when it keeps the tool calls "
            "of the turn in progress. 0.25 is the process default "
            "(ROLLING_COMPACTION_HEADROOM_RATIO). Unset keeps the process default."
        ),
    )
    compact_context: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Compact now (Unsloth's /compact). A local GGUF or MLX chat starts "
            "a checkpoint on this request even when it still fits: older turns are "
            "archived and searchable, and the model keeps the newest turn plus standing "
            "instructions until the chat outgrows the window again. Needs "
            "context_overflow=truncate_oldest and a saved thread; otherwise ignored."
        ),
    )
    studio_tool_history: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] The replayed tool calls were produced by Unsloth's local "
            "tool loop rather than by an OpenAI-compatible client tool contract."
        ),
    )
    max_tool_calls_per_message: Optional[int] = Field(
        25,
        ge = 0,
        description = "[x-unsloth] Maximum number of tool call iterations per message (0 = disabled, 9999 = unlimited).",
    )
    tool_call_timeout: Optional[int] = Field(
        300,
        ge = 1,
        description = "[x-unsloth] Timeout in seconds for each tool call execution (9999 = no limit).",
    )
    run_tools_locally: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Execute the selected tools on the Unsloth host instead of "
            "asking the provider to run its own hosted builtins. Only meaningful "
            "for providers that ship hosted tools of the same name (OpenAI, "
            "Gemini, Kimi, OpenRouter), where 'web_search' alone is ambiguous: "
            "the same request means hosted search to a client written before "
            "Unsloth ran tools for external providers. Omitted keeps the hosted "
            "behaviour, so an older client is unaffected."
        ),
    )
    session_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Session/thread ID for scoping tool execution sandbox.",
    )
    sandbox_attachments: Optional[list[SandboxAttachment]] = Field(
        None,
        max_length = 64,
        description = (
            "[x-unsloth] Chat attachment originals (hashes from POST /api/chat/attachment-originals) "
            "to copy into the session sandbox before the tool loop, when the python tool is enabled."
        ),
    )
    thread_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Conversation ID for scoping stateful tool sessions (e.g. stdio MCP); stays per-thread where session_id may be shared project-wide.",
    )
    user_message_id: Optional[str] = Field(
        None,
        max_length = 256,
        description = (
            "[x-unsloth] The user message this turn answers. With thread_id it keys the chat's file "
            "history, so /rewind can put back what this turn's tool calls changed."
        ),
    )
    rag_scope: Optional[dict] = Field(
        None,
        description = (
            "[x-unsloth] Hidden RAG retrieval scope for the search_knowledge_base "
            "tool: {kb_id?, thread_id?, default_top_k?, mode?, autoinject?, "
            "autoinject_min_score?}. Candidate pools and the RRF constant come from "
            "server config. The model never sees this; the server resolves which "
            "documents to search."
        ),
    )
    cancel_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Per-request cancellation token. Frontend sends a fresh UUID per run so /inference/cancel matches one specific generation.",
    )

    provider_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Saved provider config ID. Its stored key is used when encrypted_api_key is omitted.",
    )
    provider_api_type: Literal["chat_completions", "responses"] = "chat_completions"
    provider_reasoning_config: Optional[ProviderReasoningConfig] = Field(
        None,
        description = "[x-unsloth] Explicit Custom reasoning dialect; saved provider configuration takes precedence.",
    )
    provider_type: Optional[str] = Field(
        None,
        description = "[x-unsloth] Provider type (e.g. 'openai', 'mistral'). Used if provider_id is not set.",
    )
    external_model: Optional[str] = Field(
        None,
        description = "[x-unsloth] Model ID at the external provider.",
    )
    encrypted_api_key: Optional[str] = Field(
        None,
        description = "[x-unsloth] RSA-encrypted, base64-encoded API key for the external provider.",
    )
    provider_base_url: Optional[str] = Field(
        None,
        description = "[x-unsloth] Override base URL for the external provider.",
    )
    extra_headers: Optional[dict[str, str]] = Field(
        None,
        description = (
            "[x-unsloth] Extra request headers when the request carries an API key. "
            "Saved connections send these from the stored record instead, so an "
            "explicit key cannot bind saved metadata."
        ),
    )

    @field_validator("extra_headers", mode = "before")
    @classmethod
    def _validate_chat_extra_headers(cls, value: Any) -> Any:
        if value is None:
            return None
        return normalize_provider_extra_headers(value)

    enable_prompt_caching: Optional[Union[bool, str]] = Field(
        None,
        description = (
            "[x-unsloth] Opt in to provider-side prompt caching. On Anthropic, "
            "boolean true attaches cache_control={type:ephemeral} to the system "
            "block so the static prefix is reused across turns. On OpenAI cloud, "
            "caching is automatic for prompts >=1024 tokens and the boolean is "
            "informational. On Gemini, pass a string cache resource name such "
            "as `cachedContents/abc123` to attach `cachedContent` on the native "
            "request (boolean true is a no-op on Gemini because creating the "
            "cache requires a separate POST /cachedContents call). On OpenRouter, "
            "boolean true adds a top-level cache_control for anthropic/ models. "
            "Ignored for every other provider. Treated as enabled when omitted."
        ),
    )

    @field_validator("enable_prompt_caching", mode = "before")
    @classmethod
    def _coerce_enable_prompt_caching(cls, value: Any) -> Any:
        """Coerce JSON bool strings back to bool. Widening to Union[bool, str] for
        Gemini cache names would let `"false"` read as truthy, so canonical bool
        literals are coerced to keep explicit opt-outs working."""
        if isinstance(value, str):
            lowered = value.strip().lower()
            # Pydantic v1 bool table; anything else stays a string (Gemini cachedContent path).
            if lowered in ("true", "t", "1", "yes", "y", "on"):
                return True
            if lowered in ("false", "f", "0", "no", "n", "off"):
                return False
        return value

    prompt_cache_ttl: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] Anthropic cache_control TTL, also used for Claude on "
            "OpenRouter. Defaults to the 5-minute "
            "ephemeral pool when omitted. Pass `1h` to write into the 1-hour "
            "pool instead -- 1h writes are billed at 2x base input vs 1.25x "
            "for 5m, but reads stay at 0.1x for both, so 1h pays off the "
            "moment a single extra read lands more than 5 minutes after the "
            "write. Only `5m` and `1h` are forwarded; any other value is "
            "silently ignored downstream so a stale frontend can't make the "
            "API 422 on the request. No-op on every other provider."
        ),
    )
    compaction_threshold: Optional[int] = Field(
        None,
        ge = 1,
        le = 2_000_000,
        description = (
            "[x-unsloth] Server-side context compaction trigger, in tokens. "
            "Per-provider routing:\n"
            "  - Anthropic (Opus 4.6+, Sonnet 4.6, Mythos preview): attaches "
            "the `compact_20260112` edit and the `compact-2026-01-12` beta "
            "header. The upstream floor is 50k; `_stream_anthropic` clamps "
            "lower values up.\n"
            "  - OpenAI cloud (api.openai.com) and Azure OpenAI Foundry "
            "(*.openai.azure.com, *.services.ai.azure.com): attaches "
            "`context_management:[{type:'compaction', compact_threshold:N}]` "
            "to /v1/responses. A deployment that answers `compact_threshold "
            "is not enabled` is retried without it.\n"
            "Both cap the trigger at 200k.\n"
            "Every other provider and model ignores it unless context_overflow "
            "is truncate_oldest, in which case Unsloth drops the oldest turns "
            "so the prompt and the reply fit within it before forwarding. "
            "Per-provider floors are enforced in the corresponding stream helpers."
        ),
    )
    context_window: Optional[int] = Field(
        None,
        ge = 1,
        description = (
            "[x-unsloth] The external model's context window, in tokens. When "
            "Unsloth drops the oldest turns for a compaction_threshold, the prompt "
            "also leaves room for max_tokens within it, and max_tokens is lowered "
            "if it would leave the prompt less than half of the window. With "
            "context_overflow=truncate_oldest and no compaction_threshold, three "
            "quarters of this window is used as the threshold; when this field is "
            "also omitted, a vLLM, llama.cpp or Custom connection uses the window "
            "its server reports on /models."
        ),
    )
    openai_code_exec_container_id: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] OpenAI shell-tool container id from the prior response "
            "in the same chat thread. When set and `code_execution` is in "
            "`enabled_tools`, the next /v1/responses call uses "
            "environment.type='container_reference' so filesystem state "
            "persists across turns. Unset → environment.type='container_auto' "
            "and OpenAI creates a fresh container. Only meaningful for the "
            "OpenAI cloud + gpt-5.5 family path; ignored otherwise."
        ),
    )
    anthropic_code_exec_container_id: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] Anthropic code_execution container id from the prior "
            "response in the same chat thread. When set and `code_execution` "
            "is in `enabled_tools`, the next /v1/messages call carries a "
            "top-level `container` field so the model sees filesystem state "
            "from earlier turns. Unset → Anthropic auto-creates a fresh "
            "container. Stale ids surface a 4xx with a `container_expired` / "
            "`container_not_found` hint; the backend emits a synthetic "
            "`container_invalidated` _toolEvent so the next turn falls back "
            "to auto-create."
        ),
    )
    fast_mode: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Anthropic fast-mode toggle. On Claude Opus 4.6 / "
            "4.7 adds the `fast-mode-2026-02-01` beta header and sends "
            "`speed: 'fast'` for higher OTPS at premium pricing. Silently "
            "ignored on every other model + provider. See "
            "https://platform.claude.com/docs/en/build-with-claude/fast-mode"
        ),
    )

    @model_validator(mode = "after")
    def _resolve_missing_tool_call_ids(self) -> "ChatCompletionRequest":
        """Fill missing tool_call_id by walking back to the preceding assistant. OpenAI / Anthropic
        passthrough require the result id to match the assistant's tool_calls[].id. Prefer
        function.name match, else first unconsumed tool_call; synth a random id only if none exists.
        A user turn breaks the lookup."""
        # One forward pass with an index instead of an O(n^2) backward rescan.
        messages = self.messages
        # The first pass only feeds the second; when every tool_call_id is present there is nothing to do.
        for msg in messages:
            if msg.role == "tool" and not msg.tool_call_id:
                break
        else:
            return self

        # Pre-mark explicit ids so a missing-id sibling can't steal a claimed one.
        consumed: set[tuple[int, int]] = set()

        # Newest assistant call per explicit str id; within one assistant the first index wins.
        latest_by_id: dict = {}
        for asst_idx, msg in enumerate(messages):
            role = msg.role
            if role == "user":
                latest_by_id.clear()
            elif role == "assistant":
                if not msg.tool_calls:
                    continue
                here: set = set()
                for tc_idx, tc in enumerate(msg.tool_calls):
                    if not isinstance(tc, dict):
                        continue
                    tc_id = tc.get("id")
                    if isinstance(tc_id, str) and tc_id not in here:
                        here.add(tc_id)
                        latest_by_id[tc_id] = (asst_idx, tc_idx)
            elif role == "tool" and msg.tool_call_id:
                claimed = latest_by_id.get(msg.tool_call_id)
                if claimed is not None:
                    consumed.add(claimed)

        # Oldest first so the nearest is on top; a drained assistant never refills.
        stack: list = []
        for asst_idx, msg in enumerate(messages):
            role = msg.role
            if role == "user":
                stack.clear()
                continue
            if role == "assistant":
                if not msg.tool_calls:
                    continue
                in_order: deque = deque()
                by_name: dict = {}
                for tc_idx, tc in enumerate(msg.tool_calls):
                    if (asst_idx, tc_idx) in consumed or not isinstance(tc, dict):
                        continue
                    if not tc.get("id"):
                        continue
                    function = tc.get("function")
                    function_name = function.get("name") if isinstance(function, dict) else None
                    in_order.append(tc_idx)
                    # ``name`` is a ``str``, so only a ``str`` function name can match it.
                    if isinstance(function_name, str):
                        by_name.setdefault(function_name, deque()).append(tc_idx)
                if in_order:
                    stack.append((asst_idx, msg.tool_calls, in_order, by_name))
                continue
            if role != "tool" or msg.tool_call_id:
                continue
            picked = None
            while stack:
                frame_idx, tool_calls, in_order, by_name = stack[-1]
                while in_order and (frame_idx, in_order[0]) in consumed:
                    in_order.popleft()
                if not in_order:
                    stack.pop()
                    continue
                # Match by name anywhere in this assistant, else take its first remaining call.
                chosen = None
                if msg.name:
                    named = by_name.get(msg.name)
                    if named is not None:
                        while named and (frame_idx, named[0]) in consumed:
                            named.popleft()
                        if named:
                            chosen = named.popleft()
                if chosen is None:
                    chosen = in_order.popleft()
                consumed.add((frame_idx, chosen))
                picked = tool_calls[chosen].get("id")
                break
            if picked is None:
                import secrets as _secrets
                picked = f"call_{_secrets.token_hex(8)}"
            msg.tool_call_id = picked
        return self

    @model_validator(mode = "after")
    def _promote_extra_audio(self) -> "ChatCompletionRequest":
        """Keep ``audio_base64`` the first clip whenever any clip is attached.

        Every capability, size and routing check keys on that field, so a request carrying
        only ``extra_audio_base64`` must not slip past them as audio-free.
        """
        extra = [clip for clip in self.extra_audio_base64 or [] if clip]
        if not self.audio_base64 and extra:
            self.audio_base64 = extra.pop(0)
        self.extra_audio_base64 = extra or None
        return self

    @model_validator(mode = "after")
    def _map_thinking_to_enable_thinking(self) -> "ChatCompletionRequest":
        return resolve_thinking_onto_enable_thinking(self)

    @field_validator("sandbox_level", mode = "before")
    @classmethod
    def _coerce_sandbox_level(cls, value: Any) -> Any:
        return _normalize_sandbox_level(value)

    @field_validator("permission_mode", mode = "before")
    @classmethod
    def _coerce_permission_mode(cls, value: Any) -> Any:
        # Unknown mode degrades to 'ask' instead of a 422.
        return _normalize_permission_mode(value)

    @model_validator(mode = "after")
    def _fold_full_permission_into_bypass(self) -> "ChatCompletionRequest":
        """permission_mode='full' is the documented equivalent of
        bypass_permissions=true, so fold it in before any route guard reads
        the flag (else a full request would trip the confirm-gate rejections)."""
        if self.permission_mode == "full":
            self.bypass_permissions = True
        elif self.bypass_permissions:
            # Legacy bypass callers map onto Full access (mirrors the tool loop).
            self.permission_mode = "full"
        elif self.permission_mode == "off":
            self._off_confirm_opt_out = (
                "confirm_tool_calls" in self.model_fields_set and self.confirm_tool_calls is False
            )
            # "Off" never prompts, so route guards must see confirm disabled.
            self.confirm_tool_calls = False
        elif (
            self.permission_mode is None
            and self.confirm_tool_calls is True
            and not (self.provider_id or self.provider_type)
        ):
            # Explicit confirm_tool_calls=True with no mode means "ask", not the weaker "auto" default.
            self.permission_mode = "ask"
        elif (
            self.permission_mode == "ask"
            and self.confirm_tool_calls is None
            and not (self.provider_id or self.provider_type)
            and (self.enable_tools is True or bool(self.mcp_enabled))
        ):
            # Self-enable only if the flag is unset and the Unsloth tool loop is requested, not for passthrough or external providers; auto stays unfolded.
            self.confirm_tool_calls = True
        return self


class ChatCountTokensRequest(ReasoningControlsRequest):
    """Count prompt tokens for a local chat without generating."""

    model_config = {"extra": "allow"}

    model: str = Field(
        "default",
        description = "Model identifier (informational; the active model is used)",
    )
    messages: list[ChatMessage] = Field(
        ...,
        description = "Conversation messages in OpenAI chat form",
    )
    max_tokens: Optional[int] = Field(None, ge = 1)
    context_overflow: Optional[Literal["error", "truncate_middle", "truncate_oldest"]] = None
    context_policy: Optional[Literal["checkpoint", "rolling"]] = None
    compaction_headroom_ratio: Optional[float] = Field(None, ge = 0.0, le = 0.9)
    tools: Optional[list[dict]] = Field(
        None,
        description = "Optional OpenAI tool definitions included in the prompt",
    )
    enable_tools: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Enable tool calling for supported models",
    )
    enabled_tools: Optional[list[str]] = Field(
        None,
        description = "[x-unsloth] List of enabled built-in tool names",
    )
    mcp_enabled: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Append tools from every enabled MCP server",
    )
    deep_research_armed: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Offer the deep_research handoff tool. Its schema is in the prompt "
            "whenever the composer armed research, so the count carries it too."
        ),
    )
    thread_id: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] The thread being counted. A thread with a conversation archive puts "
            "search_conversation and its compaction nudge in the prompt, so the count needs "
            "the same id the completion sends to price them."
        ),
    )
    session_id: Optional[str] = Field(
        None,
        description = (
            "[x-unsloth] The tool session the completion sends. A project's chosen working "
            "folder adds a sentence to the tool nudge, so the count needs it to price that."
        ),
    )
    rag_scope: Optional[dict] = Field(
        None,
        description = "[x-unsloth] Hidden RAG retrieval scope for search_knowledge_base",
    )
    auto_heal_tool_calls: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Strip leaked tool-call markup from replayed history",
    )
    studio_tool_history: Optional[bool] = Field(
        None,
        description = (
            "[x-unsloth] Mirrors ChatCompletionRequest: the replayed tool calls came from "
            "Unsloth's local tool loop, so _takes_tool_passthrough routes the count the way "
            "it routes the completion. Declared rather than left to extra='allow', which "
            "coerces nothing and would read the string 'false' as a claim of ownership."
        ),
    )
    permission_mode: Optional[str] = Field(
        None,
        description = "[x-unsloth] Permission level the completion would send. 'full' swaps the "
        "python/terminal descriptions for the unsandboxed pair and adds a sentence to the tool "
        "nudge; 'ask' holds the tool loop's first-pass retrieval behind its confirmation gate, so "
        "a pending turn under a retrieval scope is countable. A count that omits this prices a "
        "prompt the completion will not send, or declines one it could have priced.",
    )
    sandbox_level: Literal["high", "low"] = Field(
        "high",
        description = _SANDBOX_LEVEL_DESCRIPTION,
    )
    bypass_permissions: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Equivalent of permission_mode='full'. Declared explicitly (not "
        "left to extra='allow') so an omitted flag reads as None instead of raising AttributeError.",
    )

    confirm_tool_calls: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Whether the completion's tool loop would gate each call. "
        "Declared so it is typed and folded into permission_mode as it is on a completion.",
    )
    max_tool_calls_per_message: Optional[int] = Field(
        None,
        ge = 0,
        description = "[x-unsloth] Tool-call budget the completion would send. Zero suppresses the "
        "tool loop, so a count that never sees it prices a catalog the relay does not render.",
    )

    @field_validator("sandbox_level", mode = "before")
    @classmethod
    def _coerce_sandbox_level(cls, value: Any) -> Any:
        return _normalize_sandbox_level(value)

    @field_validator("permission_mode", mode = "before")
    @classmethod
    def _coerce_permission_mode(cls, value: Any) -> Any:
        return _normalize_permission_mode(value)

    # Uses the completion path's own function, not a copy, so counts render replayed tool history alike.
    _resolve_missing_tool_call_ids = model_validator(mode = "after")(
        ChatCompletionRequest._resolve_missing_tool_call_ids
    )

    @model_validator(mode = "after")
    def _fold_full_permission_into_bypass(self) -> "ChatCountTokensRequest":
        """Mirrors ChatCompletionRequest: the prompt builders read only the
        bypass flag, so 'full' has to reach them the same way here."""
        if self.permission_mode == "full":
            self.bypass_permissions = True
        elif self.bypass_permissions:
            self.permission_mode = "full"
        elif self.permission_mode is None and self.confirm_tool_calls is True:
            # confirm_tool_calls=true maps to permission_mode 'ask', which the loop's retrieval gate keys on.
            self.permission_mode = "ask"
        return self


class ToolConfirmRequest(BaseModel):
    session_id: Optional[str] = None
    approval_id: Optional[str] = None
    decision: Literal["allow", "deny"] = "deny"
    permission_mode: Optional[Literal["full"]] = None

    @model_validator(mode = "after")
    def _check_full_access_upgrade(self):
        if self.permission_mode == "full" and (self.decision != "allow" or not self.session_id):
            raise ValueError("A Full access upgrade requires Allow and the exact chat session")
        return self


class BrowserActionResultRequest(BaseModel):
    """What the chat tab's browser did for one ``browser_action`` (``state.browser_actions``)."""

    session_id: Optional[str] = None
    action_id: str = Field(min_length = 1, max_length = 64)
    result: dict[str, Any]


class ToolApprovalStatusRequest(BaseModel):
    """Ask whether one approval is still waiting. Takes the id rather than listing them, so a
    caller can only ask about an approval it already holds and cannot enumerate anyone else's."""

    session_id: Optional[str] = None
    approval_id: Optional[str] = None


class OpenAIContainerRequest(BaseModel):
    """Shared body for the OpenAI container endpoints (list / create / delete).

    Carries a saved provider ID or one-time encrypted API key plus base URL so
    the route can proxy to the user's account.
    """

    provider_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Saved OpenAI provider config whose stored key may be used.",
    )
    encrypted_api_key: Optional[str] = Field(
        None,
        description = "[x-unsloth] Optional RSA-encrypted OpenAI API key override.",
    )
    provider_base_url: Optional[str] = Field(
        None,
        description = "[x-unsloth] OpenAI base URL. Only api.openai.com is supported; non-cloud bases are rejected with 400.",
    )


class CreateOpenAIContainerBody(OpenAIContainerRequest):
    name: str = Field(
        ...,
        min_length = 1,
        max_length = 256,
        description = "Human-readable container name. Surfaces in the picker UI.",
    )
    ttl_minutes: int = Field(
        20,
        ge = 1,
        le = 20,
        description = (
            "Idle-timeout TTL the new container will inherit (anchor="
            "last_active_at). OpenAI hard-caps this at 20 minutes and "
            "rejects larger values with integer_above_max_value."
        ),
    )


class DeleteOpenAIContainerBody(OpenAIContainerRequest):
    container_id: str = Field(
        ...,
        description = "OpenAI container id (cntr_...) to delete.",
    )


class OpenAIContainerSummary(BaseModel):
    """One row from GET /v1/containers, reshaped for the UI."""

    id: str
    name: Optional[str] = None
    created_at: Optional[int] = None
    last_active_at: Optional[int] = None
    expires_after_minutes: Optional[int] = None
    status: Optional[str] = None


class ListOpenAIContainersResponse(BaseModel):
    containers: list[OpenAIContainerSummary]


class ChoiceDelta(BaseModel):
    """Delta content for a streaming chunk."""

    role: Optional[str] = None
    content: Optional[str] = None
    reasoning_content: Optional[str] = None
    tool_calls: Optional[list[dict]] = None
    audio: Optional[dict] = None


OpenAIFinishReason = Literal["stop", "length", "tool_calls", "content_filter", "function_call"]


class ChunkChoice(BaseModel):
    """A single choice in a streaming chunk."""

    index: int = 0
    delta: ChoiceDelta
    finish_reason: Optional[OpenAIFinishReason] = None
    logprobs: Optional[dict] = None


class ChatCompletionChunk(BaseModel):
    """A single SSE chunk in OpenAI streaming format."""

    id: str = Field(default_factory = lambda: f"chatcmpl-{uuid.uuid4().hex[:12]}")
    object: Literal["chat.completion.chunk"] = "chat.completion.chunk"
    created: int = Field(default_factory = lambda: int(time.time()))
    model: str = "default"
    choices: list[ChunkChoice]
    usage: Optional[CompletionUsage] = None
    timings: Optional[dict] = None
    context_truncated: Optional[dict] = None


class CompletionMessage(BaseModel):
    """The assistant's complete response message."""

    role: Literal["assistant"] = "assistant"
    # ``None`` on a pure tool-call turn (OpenAI content=null); string otherwise.
    content: Optional[str] = None
    refusal: Optional[str] = None
    reasoning_content: Optional[str] = None
    tool_calls: Optional[list[dict]] = None
    audio: Optional[dict] = None


class CompletionChoice(BaseModel):
    """A single choice in a non-streaming response."""

    index: int = 0
    message: CompletionMessage
    finish_reason: OpenAIFinishReason = "stop"
    logprobs: Optional[dict] = None


class CompletionUsage(BaseModel):
    """Token usage statistics (approximate)."""

    prompt_tokens: int = 0
    completion_tokens: int = 0
    total_tokens: int = 0
    # Studio tool loops: final pass's prompt + completion (total_tokens sums every pass's completion).
    context_tokens: Optional[int] = None
    prompt_tokens_details: Optional[dict] = Field(
        default_factory = lambda: {"cached_tokens": 0, "audio_tokens": 0}
    )
    completion_tokens_details: Optional[dict] = Field(
        default_factory = lambda: {
            "reasoning_tokens": 0,
            "audio_tokens": 0,
            "accepted_prediction_tokens": 0,
            "rejected_prediction_tokens": 0,
        }
    )

    @model_serializer(mode = "wrap")
    def _omit_unset_context_tokens(self, handler):
        # Only tool loops set it; elsewhere the OpenAI usage object stays byte-identical.
        data = handler(self)
        if isinstance(data, dict) and data.get("context_tokens") is None:
            data.pop("context_tokens", None)
        return data


class ChatCompletion(BaseModel):
    """Non-streaming chat completion response."""

    id: str = Field(default_factory = lambda: f"chatcmpl-{uuid.uuid4().hex[:12]}")
    object: Literal["chat.completion"] = "chat.completion"
    created: int = Field(default_factory = lambda: int(time.time()))
    model: str = "default"
    choices: list[CompletionChoice]
    usage: CompletionUsage = Field(default_factory = CompletionUsage)
    system_fingerprint: Optional[str] = None


class ResponsesInputTextPart(BaseModel):
    """Text content part in a Responses API message (type=input_text)."""

    type: Literal["input_text"]
    text: str


class ResponsesInputImagePart(BaseModel):
    """Image content part in a Responses API message (type=input_image)."""

    type: Literal["input_image"]
    image_url: str = Field(..., description = "data:image/png;base64,... or https://...")
    detail: Optional[Literal["auto", "low", "high", "original"]] = "auto"


class ResponsesOutputTextPart(BaseModel):
    """Assistant ``output_text`` content part replayed on subsequent turns.

    Clients looping on a stateless Responses endpoint round-trip prior assistant
    messages as ``output_text`` parts; we keep the text and ignore the
    annotations/logprobs when flattening into Chat Completions.
    """

    type: Literal["output_text"]
    text: str
    annotations: Optional[list] = None
    logprobs: Optional[list] = None

    model_config = {"extra": "allow"}


class ResponsesUnknownContentPart(BaseModel):
    """Catch-all for unmodelled content-part types.

    Keeps validation green for newer part types (e.g. ``input_audio``) so an unrelated turn
    is never answered with a 422 schema dump. Normalisation then refuses the part by name,
    the way ``UnknownContentPart`` is refused on the Chat Completions side: landing here
    means the part was understood well enough to say what it is, not that it can be served.
    """

    type: str

    model_config = {"extra": "allow"}


ResponsesContentPart = Union[
    ResponsesInputTextPart,
    ResponsesInputImagePart,
    ResponsesOutputTextPart,
    ResponsesUnknownContentPart,
]


class ResponsesInputMessage(BaseModel):
    """A single message in the Responses API input array."""

    type: Optional[Literal["message"]] = None
    role: Literal["system", "user", "assistant", "developer"]
    content: Union[str, list[ResponsesContentPart]]

    # Codex requires its `phase` field round-tripped on assistant messages.
    model_config = {"extra": "allow"}


class ResponsesFunctionCallInputItem(BaseModel):
    """A prior assistant function_call replayed in a multi-turn Responses input.

    Tool calls are top-level input items (not nested), correlated by ``call_id``.
    """

    type: Literal["function_call"]
    id: Optional[str] = Field(None, description = "Item id assigned by the server (e.g. fc_...)")
    call_id: str = Field(
        ...,
        description = "Correlation id matching a function_call_output on the next turn.",
    )
    name: str
    namespace: Optional[str] = None
    arguments: str = Field(..., description = "JSON string of the arguments the model produced.")
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None


class ResponsesFunctionCallOutputInputItem(BaseModel):
    """A tool result supplied by the client for a prior function_call.

    Replaces Chat Completions' ``role="tool"`` message. Correlated to its
    originating call by ``call_id``.
    """

    type: Literal["function_call_output"]
    id: Optional[str] = None
    call_id: str
    output: Union[str, list] = Field(
        ..., description = "String or content-array result of the tool call."
    )
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None


class ResponsesCustomToolCallInputItem(BaseModel):
    """A prior assistant custom_tool_call replayed by a Responses client."""

    type: Literal["custom_tool_call"]
    id: Optional[str] = None
    call_id: str
    name: str
    input: str = Field(..., description = "Raw freeform input the model produced.")
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None


class ResponsesCustomToolCallOutputInputItem(BaseModel):
    """A client result for a prior custom_tool_call."""

    type: Literal["custom_tool_call_output"]
    id: Optional[str] = None
    call_id: str
    output: Union[str, list]
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None


class ResponsesUnknownInputItem(BaseModel):
    """Catch-all for unmodelled Responses input item types.

    Covers ``reasoning`` items and future types, so unrelated turns don't 422.
    Normalisation replays reasoning text, refuses ``item_reference``, drops the rest.
    """

    type: str

    model_config = {"extra": "allow"}


def _responses_input_item_discriminator(v: Any) -> str:
    """Explicit discriminator, since pydantic smart-union misreports errors when a strict Literal misses."""
    if isinstance(v, dict):
        t = v.get("type")
        r = v.get("role")
    else:
        t = getattr(v, "type", None)
        r = getattr(v, "role", None)
    if t == "function_call":
        return "function_call"
    if t == "function_call_output":
        return "function_call_output"
    if t == "custom_tool_call":
        return "custom_tool_call"
    if t == "custom_tool_call_output":
        return "custom_tool_call_output"
    if r is not None or t == "message":
        return "message"
    return "unknown"


ResponsesInputItem = Annotated[
    Union[
        Annotated[ResponsesInputMessage, Tag("message")],
        Annotated[ResponsesFunctionCallInputItem, Tag("function_call")],
        Annotated[ResponsesFunctionCallOutputInputItem, Tag("function_call_output")],
        Annotated[ResponsesCustomToolCallInputItem, Tag("custom_tool_call")],
        Annotated[ResponsesCustomToolCallOutputInputItem, Tag("custom_tool_call_output")],
        Annotated[ResponsesUnknownInputItem, Tag("unknown")],
    ],
    Discriminator(_responses_input_item_discriminator),
]


class ResponsesFunctionTool(BaseModel):
    """Flat function-tool definition for the Responses API request.

    Unlike Chat Completions (nested under a ``"function"`` key), this uses a flat
    shape with ``type``/``name``/``description``/``parameters``/``strict`` at top level.
    """

    type: Literal["function"]
    name: str
    description: Optional[str] = None
    parameters: Optional[dict] = None
    strict: Optional[bool] = None


class ResponsesRequest(BaseModel):
    """OpenAI Responses API request."""

    model: str = Field("default", description = "Model identifier")
    input: Union[str, list[ResponsesInputItem]] = Field(
        default = [],
        description = "Input text or list of messages / function_call / function_call_output items",
    )
    instructions: Optional[str] = Field(None, description = "System / developer instructions")
    temperature: Optional[float] = Field(None, ge = 0.0, le = 2.0)
    top_p: Optional[float] = Field(None, ge = 0.0, le = 1.0)
    seed: Optional[int] = Field(
        None,
        ge = -(2**63),
        le = 2**64 - 1,
        description = "[x-unsloth] Best-effort deterministic sampling seed.",
    )
    max_output_tokens: Optional[int] = Field(None, ge = 1)
    stream: bool = Field(False, description = "Whether to stream the response via SSE")

    # Plain dict list so built-in tool shapes round-trip without validation errors.
    tools: Optional[list[dict]] = Field(
        None,
        description = (
            "Responses-shape tool definitions. Function tools and Codex's "
            "custom `apply_patch` are translated to the Chat Completions nested "
            "shape before being forwarded to llama-server; other tool types "
            "(built-in web_search, file_search, mcp, ...) are accepted for SDK "
            "compatibility but ignored on the llama-server passthrough."
        ),
    )
    tool_choice: Optional[Any] = Field(
        None,
        description = (
            "'auto' | 'required' | 'none' | {'type': 'function', 'name': ...} — "
            "the Responses-shape forcing object is translated to the Chat "
            "Completions nested shape internally."
        ),
    )
    parallel_tool_calls: Optional[bool] = None

    previous_response_id: Optional[str] = None
    store: Optional[bool] = None
    metadata: Optional[dict] = None
    truncation: Optional[Any] = None
    user: Optional[str] = None
    text: Optional[Any] = None
    reasoning: Optional[Any] = None

    model_config = {"extra": "allow"}


class ResponsesOutputTextContent(BaseModel):
    """A text content block inside an output message."""

    type: Literal["output_text"] = "output_text"
    text: str
    annotations: list = Field(default_factory = list)


class ResponsesOutputMessage(BaseModel):
    """An output message in the Responses API response."""

    type: Literal["message"] = "message"
    id: str = Field(default_factory = lambda: f"msg_{uuid.uuid4().hex[:12]}")
    status: Literal["completed", "in_progress", "incomplete"] = "completed"
    role: Literal["assistant"] = "assistant"
    content: list[ResponsesOutputTextContent] = Field(default_factory = list)


class ResponsesOutputReasoningContent(BaseModel):
    """A reasoning text content block inside a reasoning output item."""

    type: Literal["reasoning_text"] = "reasoning_text"
    text: str


class ResponsesOutputReasoning(BaseModel):
    """A top-level reasoning output item in the Responses API response."""

    type: Literal["reasoning"] = "reasoning"
    id: str = Field(default_factory = lambda: f"rs_{uuid.uuid4().hex[:12]}")
    status: Literal["completed", "in_progress", "incomplete"] = "completed"
    summary: list = Field(default_factory = list)
    content: Optional[list[ResponsesOutputReasoningContent]] = None


class ResponsesOutputFunctionCall(BaseModel):
    """A function-call output item in the Responses API response.

    Each tool call is its own top-level ``output`` item, correlated via ``call_id``.
    """

    type: Literal["function_call"] = "function_call"
    id: str = Field(default_factory = lambda: f"fc_{uuid.uuid4().hex[:12]}")
    call_id: str
    name: str
    namespace: Optional[str] = None
    arguments: str = Field(..., description = "JSON string of the arguments the model produced.")
    status: Literal["completed", "in_progress", "incomplete"] = "completed"

    @model_serializer(mode = "wrap")
    def _omit_unset_namespace(self, handler):
        data = handler(self)
        if isinstance(data, dict) and data.get("namespace") is None:
            data.pop("namespace", None)
        return data


class ResponsesOutputCustomToolCall(BaseModel):
    """A freeform custom-tool call returned by the Responses API."""

    type: Literal["custom_tool_call"] = "custom_tool_call"
    id: str = Field(default_factory = lambda: f"ctc_{uuid.uuid4().hex[:12]}")
    call_id: str
    name: str
    input: str
    status: Literal["completed", "in_progress", "incomplete"] = "completed"


ResponsesOutputItem = Union[
    ResponsesOutputMessage,
    ResponsesOutputReasoning,
    ResponsesOutputFunctionCall,
    ResponsesOutputCustomToolCall,
]


class ResponsesUsage(BaseModel):
    """Token usage for a Responses API response (input_tokens, not prompt_tokens)."""

    input_tokens: int = 0
    output_tokens: int = 0
    total_tokens: int = 0
    # {"cached_tokens": n}: prompt tokens the server reused from its cache, when it said.
    input_tokens_details: Optional[dict[str, int]] = None


class ResponsesResponse(BaseModel):
    """Top-level Responses API response object."""

    id: str = Field(default_factory = lambda: f"resp_{uuid.uuid4().hex[:12]}")
    object: Literal["response"] = "response"
    created_at: int = Field(default_factory = lambda: int(time.time()))
    status: Literal["completed", "in_progress", "incomplete", "failed"] = "completed"
    model: str = "default"
    output: list[ResponsesOutputItem] = Field(default_factory = list)
    usage: ResponsesUsage = Field(default_factory = ResponsesUsage)
    error: Optional[Any] = None
    incomplete_details: Optional[Any] = None
    instructions: Optional[str] = None
    metadata: dict = Field(default_factory = dict)
    temperature: Optional[float] = None
    top_p: Optional[float] = None
    max_output_tokens: Optional[int] = None
    previous_response_id: Optional[str] = None
    text: Optional[Any] = None
    tool_choice: Optional[Any] = None
    tools: list = Field(default_factory = list)
    truncation: Optional[Any] = None


class AnthropicTextBlock(BaseModel):
    type: Literal["text"]
    text: str


class AnthropicImageSource(BaseModel):
    type: Literal["base64", "url"]
    media_type: Optional[str] = None
    data: Optional[str] = None
    url: Optional[str] = None


class AnthropicImageBlock(BaseModel):
    type: Literal["image"]
    source: AnthropicImageSource


class AnthropicToolUseBlock(BaseModel):
    type: Literal["tool_use"]
    id: str
    name: str
    input: dict


class AnthropicToolResultBlock(BaseModel):
    type: Literal["tool_result"]
    tool_use_id: str
    content: Union[str, list] = ""
    is_error: Optional[bool] = None

    @field_validator("content", mode = "before")
    @classmethod
    def _coerce_null_content(cls, v):
        # Null tool result content would 400 on the str|list union.
        return "" if v is None else v


# Unknown block types are accepted; the converter renders them if it can, else drops them.
_KNOWN_ANTHROPIC_BLOCK_TYPES = frozenset(
    {"text", "image", "tool_use", "tool_result", "thinking", "redacted_thinking"}
)
# The converter drops thinking blocks from user content, which would lose the turn.
_USER_ANTHROPIC_BLOCK_TYPES = frozenset(
    {"text", "image", "tool_use", "tool_result", "search_result", "document"}
)


class AnthropicUnknownBlock(BaseModel):
    type: str
    model_config = {"extra": "allow"}

    @field_validator("type")
    @classmethod
    def _only_unknown_types(cls, v):
        # Known types go to their typed models so a malformed one still fails; this only catches the rest.
        if v in _KNOWN_ANTHROPIC_BLOCK_TYPES:
            raise ValueError("known block type handled by its typed model")
        return v


class AnthropicThinkingBlock(BaseModel):
    # Clients replay thinking blocks with tool results, so accept them; conversion then drops them.
    type: Literal["thinking"]
    thinking: str = ""
    signature: str = ""
    model_config = {"extra": "allow"}


class AnthropicRedactedThinkingBlock(BaseModel):
    type: Literal["redacted_thinking"]
    data: str = ""
    model_config = {"extra": "allow"}


AnthropicContentBlock = Union[
    AnthropicTextBlock,
    AnthropicImageBlock,
    AnthropicToolUseBlock,
    AnthropicToolResultBlock,
    AnthropicThinkingBlock,
    AnthropicRedactedThinkingBlock,
    AnthropicUnknownBlock,
]


def _anthropic_content_to_system_text(content: Any) -> str:
    """Convert misplaced system message content into Anthropic system text."""
    if content is None:  # null content must not become the literal "None"
        return ""
    if isinstance(content, str):
        return content
    if isinstance(content, list):
        parts: list[str] = []
        for block in content:
            if isinstance(block, dict) and block.get("type") == "text":
                text = block.get("text")
                if isinstance(text, str):
                    parts.append(text)
                    continue
            if block is not None:
                parts.append(str(block))
        return "\n\n".join(part for part in parts if part)
    return str(content)


def _merge_anthropic_system(system: Any, additions: list[str]) -> Any:
    if not additions:
        return system

    addition_blocks = [{"type": "text", "text": text} for text in additions if text.strip()]
    if not addition_blocks:
        return system

    if system is None:
        return addition_blocks[0]["text"] if len(addition_blocks) == 1 else addition_blocks
    if isinstance(system, str):
        return "\n\n".join([system, *[block["text"] for block in addition_blocks]])
    if isinstance(system, list):
        return [*system, *addition_blocks]
    return system


def _block_type(block: Any) -> Any:
    return block.get("type") if isinstance(block, dict) else getattr(block, "type", None)


def _system_note(text: str) -> str:
    if text.lstrip().startswith("<system-reminder>"):
        return text
    return f"<system-reminder>\n{text}\n</system-reminder>"


def _as_blocks(content: Any) -> Optional[list]:
    if isinstance(content, str):
        return [{"type": "text", "text": content}] if content else []
    return list(content) if isinstance(content, list) else None


def _with_user_note(message: dict, note: str, *, first: bool) -> Optional[dict]:
    """Copy of a user turn with a text block added; None for malformed content, left for validation to reject."""
    blocks = _as_blocks(message.get("content"))
    if blocks is None:
        return None
    block = {"type": "text", "text": note}
    if blocks and all(_block_type(b) == "tool_result" for b in blocks):
        # As a text block it would start a new user query (templates drop the reasoning before it); MCP image envelopes stay last.
        index = 0 if first else len(blocks) - 1
        result = blocks[index] if isinstance(blocks[index], dict) else blocks[index].model_dump()
        inner = result.get("content")
        inner = [] if inner is None else _as_blocks(inner)
        if inner is None:
            return None
        blocks[index] = {**result, "content": [block, *inner]}
        return {**message, "content": blocks}
    return {**message, "content": [block, *blocks] if first else [*blocks, block]}


_CLAUDE_STYLE_REMINDER_SUFFIX = (
    " output style is active. Remember to follow the specific guidelines for this style."
)


def _is_repeated_claude_style_reminder(text: str, retained_system: list[str]) -> bool:
    """Drop an exact standalone style reminder already retained; never dedupe other user or tool text."""
    if not text.endswith(_CLAUDE_STYLE_REMINDER_SUFFIX):
        return False
    style = text[: -len(_CLAUDE_STYLE_REMINDER_SUFFIX)]
    if not style or "\n" in style or "\r" in style:
        return False
    heading = f"# Output Style: {style}"
    return any(heading in part.splitlines() for part in retained_system) and any(
        text in part.split("\n\n") for part in retained_system
    )


class AnthropicMessage(BaseModel):
    role: Literal["user", "assistant"]
    content: Union[str, list[AnthropicContentBlock]]

    @model_validator(mode = "before")
    @classmethod
    def _normalize_content(cls, data):
        # Assistant: null content becomes empty. User: stay strict, rejecting null and unconvertible blocks so no input is silently dropped.
        if not isinstance(data, dict):
            return data
        content = data.get("content")
        if data.get("role") == "assistant":
            # Only an explicit null; a missing key still 400s.
            if "content" in data and content is None:
                return {**data, "content": ""}
            return data
        if isinstance(content, list):
            for block in content:
                btype = (
                    block.get("type") if isinstance(block, dict) else getattr(block, "type", None)
                )
                # True if auto-load may run; guards keep invalid requests from loading. Reads configured setting, not effective TTL: residency stops unloads, not reloads.
                if not isinstance(btype, str) or btype not in _USER_ANTHROPIC_BLOCK_TYPES:
                    raise ValueError(f"unsupported content block type {btype!r} in a user message")
                # Unreadable documents degrade to a note only inside a tool result.
                if btype == "document":
                    source = (
                        block.get("source")
                        if isinstance(block, dict)
                        else getattr(block, "source", None)
                    )
                    stype = source.get("type") if isinstance(source, dict) else None
                    if stype not in ("text", "content"):
                        raise ValueError(
                            f"unsupported document source type {stype!r}: only text and content "
                            "documents can be read"
                        )
        return data


class AnthropicTool(BaseModel):
    # User-defined tools carry input_schema; server and Anthropic-schema client tools use type/name.
    type: Optional[str] = None
    name: Optional[str] = None
    description: Optional[str] = None
    input_schema: Optional[dict] = None
    model_config = {"extra": "allow"}


class AnthropicThinkingConfig(BaseModel):
    # str, not Literal: Claude Code sends adaptive tiers; only "disabled" means off.
    type: str = "enabled"
    # Forwarded to llama-server as thinking_budget_tokens when thinking is on.
    budget_tokens: Optional[int] = None
    model_config = {"extra": "allow"}


_ANTHROPIC_EFFORT_LEVELS = frozenset({"none", "minimal", "low", "medium", "high", "max", "xhigh"})


class AnthropicMessagesRequest(BaseModel):
    model: str = "default"
    max_tokens: Optional[int] = None
    messages: list[AnthropicMessage]
    system: Optional[Union[str, list]] = None
    tools: Optional[list[AnthropicTool]] = None
    tool_choice: Optional[Any] = None
    stream: bool = False
    temperature: Optional[float] = None
    top_p: Optional[float] = None
    top_k: Optional[int] = None
    seed: Optional[int] = Field(
        None,
        ge = -(2**63),
        le = 2**64 - 1,
        description = "[x-unsloth] Best-effort deterministic sampling seed.",
    )
    stop_sequences: Optional[list[str]] = None
    metadata: Optional[dict] = None
    # [x-unsloth] extensions mirroring the OpenAI endpoint convenience fields
    min_p: Optional[float] = Field(
        None, ge = 0.0, le = 1.0, description = "[x-unsloth] Min-p sampling threshold"
    )
    repetition_penalty: Optional[float] = Field(
        None, ge = 1.0, le = 2.0, description = "[x-unsloth] Repetition penalty"
    )
    presence_penalty: Optional[float] = Field(
        None, ge = 0.0, le = 2.0, description = "[x-unsloth] Presence penalty"
    )
    enable_tools: Optional[bool] = None
    enabled_tools: Optional[list[str]] = None
    thinking: Optional[AnthropicThinkingConfig] = None
    # These win over `thinking` when both are present.
    enable_thinking: Optional[bool] = None
    reasoning_effort: Optional[
        Literal["none", "minimal", "low", "medium", "high", "max", "xhigh"]
    ] = None
    preserve_thinking: Optional[bool] = None
    # Claude Code sends the effort tier here, never in reasoning_effort.
    output_config: Optional[dict] = None
    session_id: Optional[str] = None
    thread_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Conversation ID for scoping stateful tool sessions (e.g. stdio MCP); stays per-thread where session_id may be shared project-wide.",
    )
    cancel_id: Optional[str] = None
    bypass_permissions: Optional[bool] = Field(
        False,
        description = "[x-unsloth] Bypass Permissions: when true, disable the python/terminal execution sandbox (safety checks, command blocklist, resource limits) for server-side tool calls. Secret env vars are still stripped. Declared explicitly (not relied on via extra='allow') so omitted requests default to False instead of raising AttributeError.",
    )
    permission_mode: Optional[str] = Field(
        None,
        description = "[x-unsloth] Permission level for local tool calls: 'ask' pauses every call, 'auto' ('Approve for me') only pauses calls detected as high risk, 'off' ('Run automatically') never pauses while Python and Terminal run in the OS sandbox and otherwise pauses their high-risk calls in a streaming UI chat, 'full' equals bypass_permissions=true. Unset defaults to 'auto' for the per-call gate; a non-streaming request without an explicit mode runs the loop. An unrecognized value (e.g. from a newer client) is treated as 'ask'. Declared explicitly so omitted requests default to None instead of raising AttributeError.",
    )
    sandbox_level: Literal["high", "low"] = Field(
        "high",
        description = _SANDBOX_LEVEL_DESCRIPTION,
    )
    auto_heal_tool_calls: Optional[bool] = Field(
        True,
        description = "[x-unsloth] Auto-detect and fix malformed tool calls from model output (mirrors the Chat Completions field; applies to the client-tool passthrough).",
    )
    nudge_tool_calls: Optional[bool] = Field(
        None,
        description = "[x-unsloth] Opt-in tool-call recovery; mirrors the Chat Completions nudge_tool_calls field and defaults off.",
    )
    model_config = {"extra": "allow"}
    _message_ordinals: Optional[list[int]] = PrivateAttr(default = None)
    _omitted_thinking_is_off: bool = PrivateAttr(default = False)

    @model_validator(mode = "after")
    def _effort_from_output_config(self) -> "AnthropicMessagesRequest":
        if self.reasoning_effort is not None or not isinstance(self.output_config, dict):
            return self
        # Claude Code sends output_config.effort even with thinking off; do not re-enable it.
        if self.resolved_enable_thinking() is not True:
            return self
        effort = self.output_config.get("effort")
        if isinstance(effort, str) and effort in _ANTHROPIC_EFFORT_LEVELS:
            self.reasoning_effort = effort
        return self

    def resolved_enable_thinking(self) -> Optional[bool]:
        """Effective on/off, preferring the x-unsloth field over `thinking`."""
        if self.enable_thinking is not None:
            return self.enable_thinking
        if self.thinking is not None:
            return self.thinking.type != "disabled"
        # Omitted means the model default, as on Anthropic's API.
        return False if self._omitted_thinking_is_off else None

    @model_validator(mode = "before")
    @classmethod
    def normalize_system_messages(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data

        messages = data.get("messages")
        if not isinstance(messages, list):
            return data

        normalized_messages: list[Any] = []
        system_additions: list[str] = []
        retained_system = [_anthropic_content_to_system_text(data.get("system"))]
        pending: list[str] = []
        changed = False

        for message in messages:
            if isinstance(message, dict) and message.get("role") == "system":
                text = _anthropic_content_to_system_text(message.get("content", ""))
                changed = True
                if _is_repeated_claude_style_reminder(text, retained_system):
                    continue
                retained_system.append(text)
                previous = normalized_messages[-1] if normalized_messages else None
                if previous is None or not text.strip():
                    system_additions.append(text)
                elif isinstance(previous, dict) and previous.get("role") == "user":
                    # Hoisted, it renders above the tools: claude's per-session env message broke every new session's cache.
                    folded = _with_user_note(previous, _system_note(text), first = False)
                    if folded is None:
                        system_additions.append(text)
                    else:
                        normalized_messages[-1] = folded
                else:
                    pending.append(text)
                continue
            if pending and isinstance(message, dict) and message.get("role") == "user":
                note = "\n".join(_system_note(text) for text in pending)
                folded = _with_user_note(message, note, first = True)
                if folded is None:
                    system_additions.extend(pending)
                else:
                    message = folded
                pending = []
            normalized_messages.append(message)

        if not changed:
            return data

        # A trailing assistant turn is a prefill; a user turn after it would replace it.
        system_additions.extend(pending)

        normalized = dict(data)
        normalized["messages"] = normalized_messages
        normalized["system"] = _merge_anthropic_system(normalized.get("system"), system_additions)
        return normalized

    @model_validator(mode = "wrap")
    @classmethod
    def _record_message_ordinals(cls, data: Any, handler):
        # Error paths name the client's own message index, not the one left after system folding.
        model = handler(data)
        messages = data.get("messages") if isinstance(data, dict) else None
        if isinstance(messages, list):
            model._message_ordinals = [
                i
                for i, m in enumerate(messages)
                if not (isinstance(m, dict) and m.get("role") == "system")
            ]
        return model

    @field_validator("sandbox_level", mode = "before")
    @classmethod
    def _coerce_sandbox_level(cls, value: Any) -> Any:
        return _normalize_sandbox_level(value)

    @field_validator("permission_mode", mode = "before")
    @classmethod
    def _coerce_permission_mode(cls, value: Any) -> Any:
        # Unknown mode degrades to 'ask' instead of a 422.
        return _normalize_permission_mode(value)

    @model_validator(mode = "after")
    def _fold_full_permission_into_bypass(self) -> "AnthropicMessagesRequest":
        """permission_mode='full' equals bypass_permissions=true (mirrors the
        Chat Completions request)."""
        if self.permission_mode == "full":
            self.bypass_permissions = True
        elif self.bypass_permissions:
            # Legacy bypass callers map onto Full access (mirrors the tool loop).
            self.permission_mode = "full"
        elif self.permission_mode == "off":
            # "Off" never prompts, so route guards must see confirm disabled.
            self.confirm_tool_calls = False
        return self


class AnthropicUsage(BaseModel):
    input_tokens: int = 0
    cache_creation_input_tokens: int = 0
    cache_read_input_tokens: int = 0
    output_tokens: int = 0


class AnthropicResponseTextBlock(BaseModel):
    type: Literal["text"] = "text"
    text: str


class AnthropicResponseToolUseBlock(BaseModel):
    type: Literal["tool_use"] = "tool_use"
    id: str
    name: str
    input: dict


class AnthropicResponseServerToolUseBlock(BaseModel):
    type: Literal["server_tool_use"] = "server_tool_use"
    id: str
    name: str
    input: dict


class AnthropicResponseWebSearchToolResultBlock(BaseModel):
    type: Literal["web_search_tool_result"] = "web_search_tool_result"
    tool_use_id: str
    content: Union[list[dict], dict]


class AnthropicResponseThinkingBlock(BaseModel):
    type: Literal["thinking"] = "thinking"
    thinking: str
    # Nothing local can produce a valid Anthropic signature.
    signature: str = ""


AnthropicResponseBlock = Union[
    AnthropicResponseTextBlock,
    AnthropicResponseToolUseBlock,
    AnthropicResponseServerToolUseBlock,
    AnthropicResponseWebSearchToolResultBlock,
    AnthropicResponseThinkingBlock,
]


class AnthropicMessagesResponse(BaseModel):
    id: str = Field(default_factory = lambda: f"msg_{uuid.uuid4().hex[:24]}")
    type: Literal["message"] = "message"
    role: Literal["assistant"] = "assistant"
    content: list[AnthropicResponseBlock] = Field(default_factory = list)
    model: str = "default"
    stop_reason: Optional[str] = None
    stop_sequence: Optional[str] = None
    usage: AnthropicUsage = Field(default_factory = AnthropicUsage)


class MediaUnloadRequest(BaseModel):
    """Optional body of POST /images/unload and /video/unload."""

    expected_load_id: Optional[str] = Field(
        None,
        max_length = 128,
        description = "Unload only the load started with this load_token, and only while it is in "
        "flight or resident. A load that ended or was replaced is left alone (outcome superseded); "
        "one that has not started yet is refused when it arrives (outcome cancelled). Omit to "
        "unload whatever is loaded.",
    )


class MediaUnloadOutcome(BaseModel):
    """POST /images/unload or /video/unload with expected_load_id that touched nothing.

    Nothing of the slot is described: the load in it may be another account's.
    """

    unloaded: Literal[False] = Field(..., description = "Always false: nothing was unloaded")
    outcome: Literal["superseded", "cancelled"] = Field(
        ...,
        description = "superseded: that load ended or a newer one replaced it. cancelled: it has "
        "not started yet, and is refused when it arrives.",
    )


class DiffusionLoadRequest(BaseModel):
    """Request to load a local diffusion (text-to-image) checkpoint."""

    load_token: Optional[str] = Field(
        None,
        max_length = 128,
        description = "Opaque id the client picks for this load; POST /images/unload with "
        "expected_load_id set to it unloads this load only, and cancels it if it has not started yet.",
    )
    model_path: str = Field(..., description = "Diffusion repo id or local path")
    display_repo_id: Optional[str] = Field(None, description = "Logical Hub id of a local snapshot")
    _blank_display_id = field_validator("display_repo_id")(lambda v: (v or "").strip() or None)
    # The same inventory handle the picker was shown; see `resolve_inventory_handle`.
    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)
    gguf_filename: Optional[str] = Field(
        None,
        description = "The chosen single-file checkpoint (GGUF or safetensors) inside "
        "model_path. Required for the gguf / single_file kinds; omit for a full pipeline.",
    )
    model_kind: Optional[Literal["gguf", "single_file", "pipeline"]] = Field(
        None,
        description = "How to load the model (null = auto-detect from gguf_filename): gguf "
        "(single-file GGUF transformer, dequantised on-device), single_file (single-file "
        "safetensors transformer, e.g. fp8), or pipeline (a full diffusers repo via "
        "from_pretrained, embedded quant auto-applied). A single_file .safetensors loads from "
        "any repo; pipeline loads are restricted to unsloth/* repos, the official base repos, "
        "or a local path.",
    )
    base_repo: Optional[str] = Field(
        None, description = "Companion diffusers repo for VAE/text-encoders (default: family base)"
    )
    # Referenced out, so resolved back in, or a caller handed a `ref:` base cannot load it.
    _resolve_the_base_handle = field_validator("base_repo")(resolve_inventory_handle)
    text_encoder_file: Optional[Union[str, List[str]]] = Field(
        None,
        description = "Separate text-encoder file(s) to use instead of the base repo's, e.g. a ComfyUI "
        "models/text_encoders file. One path or a list (FLUX.1: clip_l + t5xxl); each is matched to the "
        "pipeline slot whose encoder class it fits. A local .safetensors path (relative paths resolve against "
        "model_path, so ../text_encoders/x.safetensors works from a ComfyUI diffusion_models folder) or "
        "owner/repo/path.safetensors under the same repo rule as model_path. Unquantized, scaled fp8 and "
        "int8 (ConvRot) files load; other ComfyUI formats are refused. Only with a gguf / single_file load; "
        "the base repo then supplies only configs and tokenizers for these encoders. Unset on a local DiT "
        "inside a ComfyUI models tree, the tree's text_encoders file that fits is used when exactly one is "
        "best (UNSLOTH_DIFFUSION_COMFY_TEXT_ENCODERS=0 turns that off).",
    )
    vae_file: Optional[str] = Field(
        None,
        description = "Separate VAE file to use instead of the base repo's, e.g. a ComfyUI models/vae file "
        "(ae.safetensors, qwen_image_vae.safetensors, wan_2.1_vae.safetensors). Same path rules as "
        "text_encoder_file. Only with a gguf / single_file load.",
    )
    family_override: Optional[str] = Field(
        None, description = "Force a family when it can't be inferred from the repo id"
    )
    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated repos")
    engine: Optional[Literal["auto", "diffusers", "sd_cpp"]] = Field(
        None,
        description = "Inference engine for this load: auto (default: diffusers on a GPU, native "
        "sd.cpp without one), diffusers, or sd_cpp (native; GGUF only, applies LoRA to GGUF "
        "models). UNSLOTH_DIFFUSION_ENGINE wins over it. A pick the engine cannot serve is "
        "refused, not swapped.",
    )
    cpu_offload: bool = Field(False, description = "Enable model CPU offload to fit low-VRAM cards")
    memory_mode: Optional[Literal["auto", "fast", "balanced", "low_vram"]] = Field(
        None,
        description = "Memory policy: auto (measured), fast (resident), balanced "
        "(stream the transformer, near-resident speed, moderate VRAM "
        "cut), low_vram (offload every component, lowest VRAM, slower). "
        "Overrides cpu_offload when set.",
    )
    allow_oversized_load: bool = Field(
        False,
        description = "Attempt the load even when the unified-memory check (Apple Silicon, integrated "
        "GPUs) estimates its weights will not fit. The check stays on by default; an oversized load "
        "can exhaust memory, swap heavily, stop the server or make the computer unresponsive. Same "
        "effect as the server's UNSLOTH_DIFFUSION_ALLOW_OVERSIZED_LOAD=1, for this load only.",
    )
    speed_mode: Optional[Literal["off", "eager", "default", "max"]] = Field(
        None,
        description = "Opt-in speed optims (default off -> bit-identical output): "
        "eager (channels_last + cudnn + attention + fused RMSNorm/AdaLayerNorm patches, "
        "NO torch.compile -> fast first image, no compile tax), "
        "default (also regional torch.compile where eligible), "
        "max (also TF32 + fused QKV).",
    )
    text_encoder_quant: Optional[
        Literal["auto", "none", "off", "fp8", "fp8_dynamic", "int8", "nvfp4"]
    ] = Field(
        None,
        description = "Quantise the companion text encoder(s). Unset or 'auto' lets the family "
        "choose (Qwen-Image-2.1 takes its hosted pre-cast fp8 encoder, 8.75 GiB against 16.33 "
        "dense); 'none'/'off' pins the released bf16 encoder. Explicit: fp8 (layerwise cast, "
        "~2x smaller, "
        "CUDA cc>=8.9), fp8_dynamic (torchao compute fp8 on the tensor cores, ~2x + faster, "
        "cc>=8.9), int8 (torchao compute int8 with per-family keep-bf16 layers; falls back to "
        "fp8 where no schedule exists; cc>=8.0), or nvfp4 (torchao weight-only, ~3.5x smaller, "
        "dequantised to bf16 per forward so the prompt encode is slower; cc>=8.0). A "
        "memory-vs-quality tradeoff (shifts fine detail), not free; pairs well with balanced mode. "
        "Fails CLOSED when NOTHING could be cast (409, or a load-progress error); an int8 request "
        "downgraded to fp8 loads and is reported through the status resolved record instead.",
    )
    transformer_quant: Optional[Literal["auto", "none", "off", "int8", "fp8", "nvfp4", "mxfp8"]] = (
        Field(
            None,
            description = "Transformer compute dtype. UNSET or auto (the default) picks the "
            "fastest precision the hardware supports: the DENSE bf16 transformer "
            "is loaded instead of the GGUF and torchao-quantised onto the "
            "low-precision tensor cores (int8 first on every tier, then fp8 on sm_89+), "
            "falling back to the GGUF when the device, VRAM or disk cannot take "
            "it. none/off pins running the GGUF as-is; an explicit scheme forces "
            "that scheme. Dense path needs CUDA + bf16. An EXPLICIT scheme fails "
            "CLOSED: where it cannot be honored the load is refused (409, or an "
            "error phase on load-progress for the footprint-dependent declines) "
            "rather than silently running the GGUF at another precision. Only "
            "auto falls back.",
        )
    )
    transformer_quant_fast_accum: Optional[bool] = Field(
        None,
        description = "fp8 only: FP8 matmul accumulate. null auto-detects by GPU class "
        "(fast FP16 accumulate on consumer/workstation cards, where FP32 "
        "accumulate is ~2x slower; precise FP32 accumulate on data-center "
        "HBM cards, which are not nerfed). true/false force it. Negligible "
        "quality effect (below the fp8 quant noise floor); no overflow risk.",
    )
    transformer_prequant_path: Optional[str] = Field(
        None,
        description = "Local path to a pre-quantized transformer checkpoint (built by "
        "scripts/build_prequant_checkpoint.py) for the requested transformer_quant "
        "scheme. Loads the already-quantized weights with the dense bf16 never on the "
        "GPU (~half the load VRAM and a smaller download). null uses the family's hosted "
        "checkpoint if configured, else quantises the dense transformer at load time. "
        "A local path installs arbitrary weights into the served model, so it is "
        "ignored unless the path resolves inside a directory the operator allowlisted "
        "via UNSLOTH_ALLOW_LOCAL_PREQUANT_PATH (one or more directories, separated by "
        "the OS path separator). A bare on/off value such as '1' is deliberately not "
        "accepted -- it must name an allowed directory.",
    )
    loras: Optional[list[LoraSpec]] = Field(
        None,
        max_length = 8,
        description = "LoRA adapters to BAKE into a torchao int8/fp8 build: they attach on "
        "the dense transformer before quantisation and compilation (the only ordering the "
        "quantized fast path supports), so they ride inside the compiled build. Weight "
        "changes and disabling apply live at generation time; CHANGING the adapter set "
        "needs a reload with the new selection. Ignored by every other load kind (bf16 / "
        "bnb-4bit loads take adapters at generation time; GGUF-as-is has no dense "
        "transformer). Also forces the dense build path: a baked-LoRA load skips the "
        "hosted pre-quantized checkpoint and pays the dense load peak.",
    )
    attention_backend: Optional[
        Literal[
            "auto",
            "native",
            "sdpa",
            "cudnn",
            "flash",
            "flash2",
            "flash3",
            "flash4",
            "sage",
            "xformers",
            "aiter",
        ]
    ] = Field(
        None,
        description = "Attention kernel via the diffusers dispatcher. auto picks the best "
        "exact backend for the device (cuDNN fused attention on NVIDIA, ~1.18x and "
        "near-lossless, when a speed profile is active; native SDPA elsewhere and when "
        "speed=off). native (alias sdpa) forces default SDPA; cudnn/flash/flash3/flash4 are exact "
        "(kernel/arch-gated); sage is INT8 attention (a small quality cost, consumer "
        "friendly); xformers/aiter are memory-efficient (NVIDIA) / AMD ROCm. An "
        "unavailable kernel falls back to the default.",
    )
    transformer_cache: Optional[Literal["off", "fbcache", "static"]] = Field(
        None,
        description = "Step caching. fbcache = First-Block-Cache: reuse the transformer tail "
        "across denoise steps when the first block's residual barely changes (~1.4x on Flux "
        "28-step at LPIPS ~0.08). Unset = auto: engages only on speed_mode=max with a 20+ step "
        "schedule, otherwise uncached. An explicit fbcache engages on every speed tier; off "
        "never caches. Composes with compile (drops fullgraph automatically); incompatible "
        "models run uncached. static = skip denoiser calls on a fixed schedule (first 20% and "
        "last 10% of the steps always run, every other middle step is extrapolated from the "
        "last two outputs; 12+ steps only), which keeps compile fullgraph and the CUDA graph. "
        "Never picked automatically.",
    )
    transformer_cache_threshold: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 1.0,
        description = "FBCache residual threshold (higher = skips more steps = faster, lower "
        "quality). null auto-picks 0.08 (0.12 when the transformer is quantised, which "
        "shifts the residual distribution). Ignored by static.",
    )
    gpu_ids: Optional[List[int]] = Field(
        None,
        description = "CUDA / ROCm physical indices this load may use, or null for automatic. "
        "Neither engine shards a diffusion checkpoint, so a selection of several cards resolves "
        "to the one with the most free VRAM. Refused with a 400 when an index does not exist "
        "here; ignored on XPU / MPS / CPU, which have no applicator for a physical index.",
    )

    @field_validator("attention_backend", mode = "before")
    @classmethod
    def _normalize_attention_backend(cls, value):
        # The dispatcher accepts case/whitespace variants, but the Literal above is validated before any normaliser runs, so fold it here.
        return value.strip().lower() if isinstance(value, str) else value

    @field_validator("text_encoder_file")
    @classmethod
    def _normalize_text_encoder_file(cls, value):
        if value is None:
            return None
        items = [value] if isinstance(value, str) else list(value)
        items = [item.strip() for item in items if isinstance(item, str) and item.strip()]
        if len(set(items)) != len(items):
            raise ValueError("text_encoder_file lists the same file twice")
        if len(items) > 4:
            raise ValueError("at most 4 text_encoder_file entries (one per encoder slot)")
        return items or None

    @field_validator("vae_file")
    @classmethod
    def _blank_vae_file(cls, value):
        return (value or "").strip() or None

    def supplied_text_encoder_files(self) -> Optional[list[str]]:
        value = self.text_encoder_file
        if value is None:
            return None
        return [value] if isinstance(value, str) else list(value)

    @field_validator("loras")
    @classmethod
    def _unique_lora_ids(cls, value: Optional[list["LoraSpec"]]) -> Optional[list["LoraSpec"]]:
        # Repeated ids would stack the same adapter past the weight bound.
        if value:
            seen: set[str] = set()
            for spec in value:
                if spec.id in seen:
                    raise ValueError(
                        f"duplicate LoRA id '{spec.id}'; list each adapter at most once"
                    )
                seen.add(spec.id)
        return value

    @model_validator(mode = "after")
    def _redirect_retired_full_copy(self) -> "DiffusionLoadRequest":
        # unsloth/flux-3-image-klein[-base] are retired full copies of the gated BFL repos; Studio's copy of those files
        # lives in the -FP8 repo now. Naming one, or a downloaded snapshot of one (its path, with the copy as the display
        # id), loads the base it copies, exactly as the picker's own row does, so the load fetches what the plan prices
        # (hosted encoder, mirror folders) instead of the whole bf16 repo. Its root bf16 ``model.safetensors`` is that
        # base's transformer, so a single-file pick of it is the pipeline load; supplied encoder / VAE files or another
        # companion base make it a different build, which stays on the copy. A copy complete on disk loads from disk.
        from core.inference.diffusion_families import (
            retired_copy_loads_from_disk,
            retired_full_copy_base,
        )

        base = retired_full_copy_base(self.model_path) or retired_full_copy_base(
            self.display_repo_id
        )
        if base is not None:
            single = (self.gguf_filename or "").strip().replace("\\", "/")
            root_pick = (
                single == "model.safetensors"
                and self.text_encoder_file is None
                and self.vae_file is None
                # An explicit companion base other than the one it copies is a different build too.
                and (
                    not (self.base_repo or "").strip()
                    or (retired_full_copy_base(self.base_repo) or self.base_repo) == base
                )
            )
            if (not single or root_pick) and retired_copy_loads_from_disk(self.model_path):
                # As a pipeline: a cached snapshot's root file links into blobs/, which single-file validation refuses.
                if root_pick:
                    self.gguf_filename, self.model_kind = None, "pipeline"
            elif not single or root_pick:
                self.model_path, self.display_repo_id = base, None
                self.gguf_filename, self.model_kind = None, "pipeline"
        # A companion base serving a single file only needs the transformer config; a pipeline opens its weights.
        if retired_full_copy_base(self.base_repo) is not None and not retired_copy_loads_from_disk(
            self.base_repo, companion = bool((self.gguf_filename or "").strip())
        ):
            self.base_repo = retired_full_copy_base(self.base_repo)
        return self


class HiresSpec(BaseModel):
    """Hires fix: render, upscale, then refine with img2img at ``denoise`` (txt2img only).

    ``steps`` is the exact refine count; None = the base pass's steps."""

    scale: float = Field(1.5, ge = 1.0, le = 4.0, description = "Upscale factor (A1111 'Hires upscale')")
    denoise: float = Field(
        0.5,
        ge = 0.0,
        le = 1.0,
        description = "Refine-pass denoising strength (A1111 'Denoising strength'); 0 = upscale only",
    )
    steps: Optional[int] = Field(
        None,
        ge = 1,
        le = 100,
        description = "Exact refine-pass steps (A1111 'Hires steps'); omitted = the base pass's steps",
    )
    upscaler: Optional[str] = Field(
        None,
        max_length = 160,
        description = "Upscaler id from status `hires.upscalers` (latent | lanczos | a model id); omitted = "
        "status `hires.default_upscaler`",
    )
    guidance: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 20.0,
        description = "Refine-pass guidance (Forge 'Hires CFG Scale'); omitted = guidance",
    )


class LoraSpec(BaseModel):
    """One LoRA adapter to apply for a generation, referenced by its discovery id.

    The id is resolved against the backend's own LoRA catalog + local scan (see
    core/inference/diffusion_lora.py); the client never supplies a raw filesystem
    path, so an arbitrary file can't be loaded. Weight 0 disables the adapter.
    """

    id: str = Field(
        ..., min_length = 1, max_length = 512, description = "LoRA discovery id (repo id or local stem)"
    )
    weight: float = Field(
        1.0, ge = 0.0, le = 2.0, description = "Adapter strength; 0 disables, 1.0 is full strength"
    )


class ControlNetSpec(BaseModel):
    """A ControlNet to condition this generation on: a discovery id plus a control image.

    The id resolves against the backend's ControlNet catalog + local scan (see
    core/inference/diffusion_controlnet.py); the client never supplies a raw filesystem path.
    ``image`` is either an already-made control map (``control_type='passthrough'``) or a source
    image the backend turns into a map (``control_type='canny'``). strength 0 disables it.
    """

    id: str = Field(
        ...,
        min_length = 1,
        max_length = 512,
        description = "ControlNet discovery id (repo id or local name)",
    )
    image: str = Field(
        ...,
        min_length = 1,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL control image (a source image or a preprocessed map)",
    )
    control_type: str = Field(
        "passthrough",
        description = "How to derive the control map: 'passthrough' (already a map) or 'canny'",
    )
    strength: float = Field(
        1.0, ge = 0.0, le = 2.0, description = "ControlNet conditioning scale; 0 disables"
    )
    guidance_start: float = Field(
        0.0, ge = 0.0, le = 1.0, description = "Fraction of steps at which ControlNet begins"
    )
    guidance_end: float = Field(
        1.0, ge = 0.0, le = 1.0, description = "Fraction of steps at which ControlNet ends"
    )

    @model_validator(mode = "after")
    def _check_guidance_range(self) -> "ControlNetSpec":
        # An inverted range means "act over no steps"; reject it as a clean 422 instead of a 500 deep in the denoise.
        if self.guidance_start > self.guidance_end:
            raise ValueError("guidance_start must be <= guidance_end")
        return self


class LocalizedEditSpec(BaseModel):
    """A localized edit for the unified-edit workflow (Qwen-Image-2.1). It guides a generative edit;
    unlike inpainting it does not keep the pixels outside the region."""

    mode: Literal["annotate", "paint", "mask"] = Field(
        ...,
        description = "annotate: `image` is an RGBA layer of marks composited over the source. "
        "paint: `image` is a mask whose white area is painted white onto the source. mask: `image` "
        "is a white-on-black mask sent as Image 2, right after the source.",
    )
    image: str = Field(
        ...,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL layer at the source image's geometry",
    )


# All images of one request, base64: ten maximal uploads would otherwise buffer ~320 MiB.
_MAX_CONDITION_PAYLOAD = 128 * 1024 * 1024

MAX_XY_CELLS = 64

XYAxisField = Literal[
    "seed",
    "steps",
    "guidance",
    "sampler",
    "schedule_type",
    "shift",
    "base_shift",
    "max_shift",
    "strength",
    "clip_skip",
    "cfg_rescale",
    "variation_seed",
    "variation_strength",
    "lora_weight",
    "prompt_sr",
]


class XYAxisSpec(BaseModel):
    """One axis of an X/Y grid: a request field and the values its cells take."""

    field: XYAxisField = Field(
        ...,
        description = "Request field the axis varies. lora_weight sets the weight of loras[index]; "
        "prompt_sr (AUTOMATIC1111 Prompt S/R) replaces the first value in the prompt and negative "
        "prompt with each value in turn, so the first cell keeps the prompt as typed.",
    )
    values: list[Union[StrictInt, StrictFloat, str]] = Field(
        ...,
        min_length = 1,
        max_length = MAX_XY_CELLS,
        description = "Values, one column (X) or row (Y) each",
    )
    index: Optional[int] = Field(
        None, ge = 0, le = 7, description = "lora_weight only: which `loras` entry the axis weights"
    )

    @model_validator(mode = "after")
    def _index_only_for_lora(self) -> "XYAxisSpec":
        if (self.field == "lora_weight") != (self.index is not None):
            raise ValueError("`index` is required for a lora_weight axis and only allowed there")
        if self.field == "prompt_sr" and not all(isinstance(v, str) for v in self.values):
            raise ValueError("prompt_sr values must be strings")
        if self.field == "prompt_sr" and not self.values[0]:
            raise ValueError(
                "prompt_sr: the first value is the text searched for and cannot be empty"
            )
        return self


class XYGridSpec(BaseModel):
    """X/Y grid: every combination of the axes' values renders as its own gallery image, plus one
    labelled grid image (X values across the top, Y values down the left)."""

    x: XYAxisSpec = Field(..., description = "Column axis")
    y: Optional[XYAxisSpec] = Field(None, description = "Row axis; omitted = a single row")

    @model_validator(mode = "after")
    def _bounded(self) -> "XYGridSpec":
        cells = len(self.x.values) * (len(self.y.values) if self.y else 1)
        if cells > MAX_XY_CELLS:
            raise ValueError(
                f"{cells} grid cells is over the limit of {MAX_XY_CELLS}; use fewer values"
            )
        y = self.y
        if y and y.field == self.x.field and y.field != "prompt_sr" and y.index == self.x.index:
            raise ValueError(f"x and y both vary {y.field}")
        return self


class DiffusionDetailerSpec(BaseModel):
    """Detailer (face fix) post-pass, after ADetailer and ComfyUI-Impact-Pack's FaceDetailer: SAM 3 finds the targets,
    each is inpainted in an enlarged crop and pasted back through a feathered mask. Defaults follow FaceDetailer
    (core/inference/diffusion_detailer.py). Needs a model whose status `workflows` has 'inpaint' and a downloaded SAM 3."""

    targets: str = Field(
        "face",
        min_length = 1,
        max_length = 500,
        description = "What to fix, as Mask from text takes it: comma-separated, `:N` caps a target "
        "(default 8 each, at most 20), e.g. 'face' or 'face, hand:2'",
    )
    prompt: Optional[str] = Field(
        None,
        max_length = 20000,
        description = "Prompt for the detail pass; omitted = the image's prompt. [PROMPT] inserts it, [SEP] gives "
        "later detections their own text (ADetailer).",
    )
    negative_prompt: Optional[str] = Field(
        None, max_length = 20000, description = "Negative prompt for the pass; omitted = the image's"
    )
    confidence: float = Field(
        0.5, ge = 0.0, le = 1.0, description = "SAM 3 score a detection must exceed"
    )
    denoise: float = Field(
        0.5,
        ge = 0.01,
        le = 1.0,
        description = "Inpaint strength of the pass (the UI request builder's floor)",
    )
    crop_factor: float = Field(
        3.0, ge = 1.0, le = 10.0, description = "Crop around each detection, times its box"
    )
    guide_size: int = Field(
        512, ge = 64, le = 2048, description = "The box's (or crop's) short side is enlarged to this"
    )
    guide_size_for: Literal["bbox", "crop_region"] = Field(
        "bbox", description = "What guide_size measures: the detection box or the whole crop"
    )
    max_size: int = Field(
        1024,
        ge = 64,
        le = 2048,
        description = "Caps the enlargement: an enlarged crop's sides stay within this. A crop "
        "already larger renders at its own size, never shrunk (FaceDetailer's force_inpaint)",
    )
    dilation: int = Field(
        10, ge = -128, le = 128, description = "Grow (or, negative, shrink) each mask by this many px"
    )
    feather: int = Field(5, ge = 0, le = 100, description = "Paste-back blur (px) at the mask's edge")
    drop_size: int = Field(
        10,
        ge = 1,
        le = 1024,
        description = "Detections with a box side at or below this (px) are skipped",
    )
    steps: Optional[int] = Field(
        None, ge = 1, le = 200, description = "Steps for the pass; omitted = the image's"
    )
    guidance: Optional[float] = Field(
        None, ge = 0.0, le = 100.0, description = "Guidance for the pass; omitted = the image's"
    )


class DiffusionGenerateRequest(BaseModel):
    """Request to generate one image from the loaded diffusion model."""

    prompt: str = Field(..., min_length = 1, description = "Text prompt")
    negative_prompt: Optional[str] = Field(
        None, description = "What to avoid (if the model supports it)"
    )
    width: int = Field(
        1024,
        ge = 256,
        le = MAX_REQUEST_SIDE,
        description = "Image width in pixels (multiple of 16; the loaded model may require more)",
    )
    height: int = Field(
        1024,
        ge = 256,
        le = MAX_REQUEST_SIDE,
        description = "Image height in pixels (multiple of 16; the loaded model may require more)",
    )
    steps: int = Field(
        9,
        ge = 1,
        le = 100,
        description = "Number of denoising steps. Omitted: the loaded model's default "
        "(status generation_defaults).",
    )
    guidance: float = Field(
        0.0,
        ge = 0.0,
        le = 20.0,
        description = "Classifier-free guidance scale. Omitted: the loaded model's default.",
    )
    # le = 2**53-1: seeds round-trip through JSON recipes, where JavaScript rounds larger integers and a restored recipe would differ.
    seed: Optional[int] = Field(
        None, ge = 0, le = 2**53 - 1, description = "Seed for reproducibility (random if omitted)"
    )
    batch_size: int = Field(
        1, ge = 1, le = 32, description = "Images generated in one forward pass (VRAM-heavy)"
    )
    # Batched multi-image generation: a prompt list renders one image per prompt (txt2img only), a seed list one per seed. Each image carries its OWN seed.
    prompts: Optional[list[str]] = Field(
        None,
        min_length = 1,
        max_length = 32,
        description = "Prompt list for batched generation: one image per prompt in a single "
        "forward pass (plain text-to-image only). Overrides `prompt` for the images; "
        "`prompt` is still required as the fallback/display value.",
    )
    enhance_prompt: Optional[bool] = Field(
        None,
        description = "Rewrite the prompt with the FLUX.3 prompt upsampler before encoding. Null = the "
        "family default (on for every FLUX.3 Klein family); ignored by every other family. An "
        "unavailable or failing upsampler leaves the prompt as typed.",
    )
    seeds: Optional[list[int]] = Field(
        None,
        min_length = 1,
        max_length = 32,
        description = "Per-image seeds for batched generation: one image per seed (with "
        "`prompts`, lengths must match; alone, every image uses `prompt`). Each image is "
        "individually reproducible from its own seed.",
    )

    @field_validator("prompts")
    @classmethod
    def _non_empty_prompts(cls, value: Optional[list[str]]) -> Optional[list[str]]:
        if value is not None and any(not p.strip() for p in value):
            raise ValueError("every prompt in prompts must be non-empty")
        return value

    @field_validator("seeds")
    @classmethod
    def _seeds_json_safe(cls, value: Optional[list[int]]) -> Optional[list[int]]:
        # Same JSON safe-integer bound as `seed`, so every per-image seed survives the gallery recipe.
        if value is not None and any(s < 0 or s > 2**53 - 1 for s in value):
            raise ValueError("every seed must be between 0 and 2**53 - 1")
        return value

    @model_validator(mode = "after")
    def _prompts_seeds_lengths_match(self) -> "DiffusionGenerateRequest":
        if (
            self.prompts is not None
            and self.seeds is not None
            and len(self.prompts) != len(self.seeds)
        ):
            raise ValueError(
                f"prompts and seeds must have the same length (got {len(self.prompts)} "
                f"prompts, {len(self.seeds)} seeds)"
            )
        return self

    # Cap each base64 string so one request cannot buffer a multi-GB payload; ~32 MiB fits a full 4096px image.
    init_image: Optional[str] = Field(
        None,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL source image for img2img or inpaint (omit for txt2img)",
    )
    mask_image: Optional[str] = Field(
        None,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL mask for inpaint (white = repaint, black = keep). "
        "Requires init_image.",
    )
    strength: Optional[float] = Field(
        None,
        # EXCLUSIVE lower bound: strength 0 leaves zero denoising steps, which raises in FLUX/Qwen/Z-Image and crashes SDXL img2img.
        gt = 0.0,
        le = 1.0,
        description = "img2img/inpaint denoise strength: low values stay close to the "
        "source, 1 fully redraws it. Must be greater than 0. Ignored for txt2img.",
    )
    upscale: Optional[float] = Field(
        None,
        ge = 1.0,
        le = 4.0,
        description = "Upscale (hires fix) factor for an init_image: enlarges the source "
        "by this multiple and re-denoises at low strength. Requires init_image; "
        "ignored for txt2img/inpaint/edit.",
    )
    live_preview: Optional[bool] = Field(
        None,
        description = "Stream a small live preview of the image while it denoises (generate-progress "
        "'preview'). Null = the server default (on unless UNSLOTH_DIFFUSION_PREVIEW=0).",
    )
    allow_oversized: bool = Field(
        False,
        description = "Run even when the generate-time memory check estimates this size will not "
        "fit the free GPU memory. Sizes that fit once the VAE decodes tile by tile already run "
        "without it; this is for the rest. An oversized run can fail with an out-of-memory error, "
        "or on Windows spill into system RAM and run very slowly. Same effect as the server's "
        "UNSLOTH_DIFFUSION_ALLOW_OVERSIZED_GENERATE=1, per request.",
    )
    reference_images: Optional[list[str]] = Field(
        None,
        max_length = 9,
        description = "Additional images (base64/data-URL) for the reference and edit workflows, "
        "after init_image and in this order. The loaded family bounds the total including "
        "init_image (FLUX.2: 4, Qwen-Image-2.1: 10); more is refused, never truncated.",
    )
    workflow: Optional[Literal["edit", "reference", "outpaint"]] = Field(
        None,
        description = "Explicit image-conditioned workflow; every one needs init_image. edit: "
        "follow the prompt as an instruction over init_image (and reference_images); reference: "
        "draw a new image from init_image plus reference_images; outpaint: runs as inpaint over "
        "the padded init_image under mask_image (required) and is recorded as outpaint. Omitted "
        "keeps the workflow implied by the other fields.",
    )
    reference_resolution: Optional[int] = Field(
        None,
        ge = 256,
        le = 2048,
        description = "Resolution each condition image is resized to (by area) before encoding, "
        "for families that expose it (Qwen-Image-2.1: 512, 1024 or 2048; default 1024). "
        "Separate from the output size.",
    )
    localized_edit: Optional[LocalizedEditSpec] = Field(
        None,
        description = "Localized edit layer for the edit workflow on a unified-edit model.",
    )
    loras: Optional[list[LoraSpec]] = Field(
        None,
        max_length = 8,
        description = "LoRA adapters to apply for this generation (by discovery id + weight). "
        "Omitted/empty applies none and behaves exactly as before. Rejected with a clear "
        "message when the loaded model or its quantisation can't apply LoRA.",
    )
    controlnet: Optional[ControlNetSpec] = Field(
        None,
        description = "ControlNet conditioning for this generation (id + control image + strength). "
        "Omitted applies none and behaves exactly as before. Rejected with a clear message when "
        "the loaded model or its quantisation can't apply ControlNet.",
    )
    sampler: Optional[Literal["default", "euler", "euler_a", "dpmpp_2m", "dpmpp_2m_sde"]] = Field(
        None,
        description = "Sampler for this generation, one of the loaded model's status `samplers` ids. "
        "Omitted or 'default' keeps the model's shipped scheduler.",
    )
    schedule_type: Optional[Literal["automatic", "uniform", "karras", "exponential"]] = Field(
        None,
        description = "Noise schedule for the sampler. Omitted or 'automatic' uses the sampler's "
        "usual schedule (Karras for DPM++ 2M, Exponential for DPM++ 2M SDE, else the model's).",
    )
    prompt_weighting: Optional[bool] = Field(
        None,
        description = "AUTOMATIC1111 prompt syntax on SDXL: (word:1.2), (word), [word], \\( escapes and "
        "BREAK. Omitted: on. A prompt without that syntax that fits in 75 CLIP tokens renders exactly "
        "as before; a longer one is encoded in 75-token chunks instead of truncated. false reads "
        "brackets literally (long prompts still chunk). "
        "true is refused for a model without the control.",
    )
    clip_skip: Optional[int] = Field(
        None,
        ge = 1,
        le = 12,
        description = "CLIP skip in AUTOMATIC1111 numbering: 1 = the model's own layer. On SDXL 1 and 2 "
        "both read the penultimate layer the model already uses (as in A1111 and Forge), 3 reads one "
        "layer earlier. Values above 1 are refused for models without the control.",
    )
    cfg_rescale: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 1.0,
        description = "CFG rescale (diffusers guidance_rescale, arXiv 2305.08891): 0 = off. Mostly for "
        "v-prediction / zero-terminal-SNR checkpoints, where 0.7 is the paper's value. Above 0 is "
        "refused for models without the control.",
    )
    variation_seed: Optional[int] = Field(
        None,
        ge = 0,
        le = 2**32 - 1,
        description = "Variation seed (AUTOMATIC1111 subseed): the seed's noise is slerped toward this "
        "seed's noise by variation_strength. Omitted with a strength: random. Text-to-image only.",
    )
    variation_strength: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 1.0,
        description = "How far toward the variation seed's noise: 0 = off, 1 = the variation seed alone. "
        "With a batch, every image keeps the seed and image i uses variation_seed + i.",
    )
    shift: Optional[float] = Field(
        None,
        gt = 0.0,
        le = 100.0,
        description = "Static flow shift for this generation, as ComfyUI's ModelSamplingSD3 / "
        "ModelSamplingAuraFlow `shift`, on models whose status `shift_control.node` is 'sd3'. "
        "Omitted keeps the model's schedule.",
    )
    base_shift: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 100.0,
        description = "ComfyUI ModelSamplingFlux `base_shift` (default 0.5) for models whose status "
        "`shift_control.node` is 'flux'. Omitted with `max_shift` keeps the model's schedule.",
    )
    max_shift: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 100.0,
        description = "ComfyUI ModelSamplingFlux `max_shift` (default 1.15), applied at the output "
        "size, for models whose status `shift_control.node` is 'flux'.",
    )
    mask_blur: Optional[int] = Field(
        None,
        ge = 0,
        le = 64,
        description = "Inpaint only: Gaussian blur radius (px) applied to the mask before inpainting "
        "(AUTOMATIC1111 'Mask blur'). Omitted or 0 uses the mask as painted.",
    )
    inpaint_only_masked: Optional[bool] = Field(
        None,
        description = "Inpaint only: render just the masked region (plus `inpaint_padding`) at full "
        "resolution and paste it back (AUTOMATIC1111 'Inpaint area: Only masked', diffusers "
        "padding_mask_crop). Requires status `supports_inpaint_only_masked`; omitted or false "
        "inpaints the whole picture.",
    )
    inpaint_padding: Optional[int] = Field(
        None,
        ge = 0,
        le = 256,
        description = "Padding (px) around the mask when `inpaint_only_masked` is set; omitted = 32.",
    )
    detailer: Optional[DiffusionDetailerSpec] = Field(
        None,
        description = "Detailer (face fix) post-pass on every image of the run. Omitted = off. Refused (400) "
        "when the loaded model has no inpaint pipeline or SAM 3 is not downloaded.",
    )
    hires: Optional[HiresSpec] = Field(
        None,
        description = "Hires fix for text to image: upscale the render and refine it in the same request. "
        "Requires status `hires` to be non-null; omitted = off.",
    )
    upscale_model: Optional[str] = Field(
        None,
        max_length = 160,
        description = "Upscale workflow only: a model upscaler id from status `upscale_models` used in place of "
        "the Lanczos resize. Omitted = Lanczos.",
    )
    provider_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Saved connection ID. When set, the prompt goes to that "
        "connection's /images/generations as `model` and the results are saved to the gallery. "
        "With `workflow` edit, init_image (then reference_images) and the prompt go to its "
        "/images/edits instead. No size is sent with an edit, so width and height are not used and "
        "the server picks the output size. No other image-input workflow runs on a connection.",
    )
    model: Optional[str] = Field(
        None, description = "Model name on the connection named by `provider_id`."
    )
    xy: Optional[XYGridSpec] = Field(
        None,
        description = "X/Y grid: render one image per combination of the axes' values, each saved to "
        "the gallery with its own recipe, plus one labelled grid image (returned as `grid`). Every "
        "cell runs at batch size 1 on the same seed unless seed is an axis. Local models only.",
    )

    @field_validator("loras")
    @classmethod
    def _unique_lora_ids(cls, value: Optional[list[LoraSpec]]) -> Optional[list[LoraSpec]]:
        # Both apply paths suffix colliding adapter names, so a repeated id would load the SAME adapter twice and stack its effect past the weight bound.
        if value:
            seen: set[str] = set()
            for spec in value:
                if spec.id in seen:
                    raise ValueError(
                        f"duplicate LoRA id '{spec.id}'; list each adapter at most once"
                    )
                seen.add(spec.id)
        return value

    @field_validator("reference_images")
    @classmethod
    def _bounded_reference_items(cls, value: Optional[list[str]]) -> Optional[list[str]]:
        # Each reference is a base64 image; bound its length like init_image so several cannot buffer a multi-GB payload.
        if value is not None:
            for item in value:
                if len(item) > 32 * 1024 * 1024:
                    raise ValueError("each reference image must be at most 32 MiB (base64)")
        return value

    @model_validator(mode = "after")
    def _bounded_condition_payload(self) -> "DiffusionGenerateRequest":
        total = len(self.init_image or "") + sum(len(r) for r in self.reference_images or [])
        if self.localized_edit is not None:
            total += len(self.localized_edit.image)
        if total > _MAX_CONDITION_PAYLOAD:
            raise ValueError(
                "the input images together must be at most 128 MiB (base64); use smaller images"
            )
        return self

    @field_validator("width", "height")
    @classmethod
    def _multiple_of_16(cls, value: int) -> int:
        # Z-Image requires dimensions divisible by 16 (8x VAE downsample + 2x patch); non-multiples crash deep in the pipeline.
        if value % 16 != 0:
            raise ValueError("must be a multiple of 16")
        return value

    @model_validator(mode = "after")
    def _xy_single_image_cells(self) -> "DiffusionGenerateRequest":
        if self.xy is None:
            return self
        if self.batch_size != 1 or self.prompts is not None or self.seeds is not None:
            raise ValueError(
                "xy runs every cell at batch size 1: drop batch_size, prompts and seeds"
            )
        if self.provider_id:
            raise ValueError("xy runs on the loaded local model, not a connection")
        for axis in (self.xy.x, self.xy.y):
            if axis and axis.field == "lora_weight" and axis.index >= len(self.loras or []):
                raise ValueError(f"lora_weight axis index {axis.index} has no entry in loras")
        return self

    @model_validator(mode = "after")
    def _batch_seeds_json_safe(self) -> "DiffusionGenerateRequest":
        # A batch derives seeds as seed..seed+batch_size-1, so a derived top-of-batch seed can exceed the 2**53-1 JSON-safe cap.
        if self.seed is not None and self.seed + self.batch_size - 1 > 2**53 - 1:
            raise ValueError(
                "seed + batch_size - 1 must not exceed 2**53 - 1 so every per-image seed "
                "stays JSON-safe (lower the seed or the batch_size)"
            )
        return self


class GalleryImage(BaseModel):
    """A persisted image's full generation recipe (embedded in the PNG too)."""

    id: str = Field(..., description = "Stable id (the on-disk filename stem)")
    url: str = Field(..., description = "Relative URL to fetch the PNG bytes")
    prompt: str = Field(..., description = "Prompt used")
    enhanced_prompt: Optional[str] = Field(
        None,
        description = "The caption the prompt upsampler wrote and the model encoded; null when "
        "not enhanced. Replaying it with enhance_prompt=false reproduces the image.",
    )
    prompt_enhancement: Optional[Literal["applied", "off", "unavailable", "failed"]] = Field(
        None,
        description = "Prompt upsampling outcome for families that have one: applied | off | "
        "unavailable (not downloaded or no llama-server) | failed; null otherwise.",
    )
    negative_prompt: Optional[str] = Field(None, description = "Negative prompt, if any")
    width: int = Field(..., description = "Image width")
    height: int = Field(..., description = "Image height")
    steps: int = Field(..., description = "Denoising steps")
    guidance: float = Field(..., description = "Guidance scale")
    seed: int = Field(..., description = "Seed used for THIS image")
    batch_seed: Optional[int] = Field(
        None,
        description = (
            "Seed restore must replay this image from. For a batch_size batch that is the base "
            "seed the batch launched with (the native engine derives per-image seeds as "
            "base + index, so the derived seed alone would not reproduce it); for a "
            "prompts/seeds list, where each image carries its own seed, it equals seed. "
            "Older records without it fall back to seed."
        ),
    )
    batch_index: int = Field(0, description = "Position within its batch (0-based)")
    batch_size: int = Field(
        1, description = "Batch size used; with batch_index it lets restore replay this image"
    )
    generation_seconds: Optional[float] = Field(
        None,
        description = "Elapsed generation seconds until images are ready to save, shared by the request",
    )
    generation_count: Optional[int] = Field(
        None, description = "Number of images in the timed request; absent on older records"
    )
    model: Optional[str] = Field(None, description = "Model repo id that produced it")
    # The load-time BUILD. The repo id alone does not identify a pipeline (quant choice, torchao scheme, baked adapters), so without these a recipe cannot be rebuilt.
    engine: Optional[str] = Field(
        None,
        description = "Engine that ran it (diffusers, sd_cpp or mlx); the same seed draws different noise on each",
    )
    model_kind: Optional[str] = Field(
        None, description = "How the model was loaded: gguf, single_file or pipeline"
    )
    gguf_filename: Optional[str] = Field(
        None,
        description = "The single-file checkpoint the load committed, for a gguf/single_file load",
    )
    transformer_quant: Optional[str] = Field(
        None,
        description = "Transformer quantisation scheme actually engaged on the dense fast path "
        "(int8/fp8/nvfp4/mxfp8), or null when the GGUF ran as-is",
    )
    text_encoder_quant: Optional[str] = Field(
        None,
        description = "Text-encoder quantisation actually engaged (fp8/fp8_dynamic/int8/nvfp4), "
        "or null when the dense bf16 encoder ran. Absent on records written before this existed.",
    )
    memory_mode: Optional[str] = Field(
        None, description = "Memory mode the load ran under: auto | fast | balanced | low_vram"
    )
    offload_policy: Optional[str] = Field(
        None,
        description = "Offload policy actually engaged: none | group | model | sequential. Part of "
        "the build: an offloaded pipeline declines the torchao text-encoder modes.",
    )
    denoiser_offload: Optional[str] = Field(
        None,
        description = "Under group offload, where this generation's denoiser ran: resident | partial | "
        "streamed (streamed blocks move from CPU on every step). Null for other policies and older records.",
    )
    speed_mode: Optional[str] = Field(
        None,
        description = "Speed profile engaged for this generation (eager | default | max | off), after "
        "any deferred compile. Absent on records written before this existed.",
    )
    attention_backend: Optional[str] = Field(
        None,
        description = "Attention backend engaged for this generation, or null for default SDPA. "
        "Absent on records written before this existed.",
    )
    transformer_cache: Optional[str] = Field(
        None,
        description = "Step cache engaged for this generation (fbcache | static), or null when off. "
        "Absent on records written before this existed.",
    )
    cpu_offload: Optional[bool] = Field(
        None,
        description = "Whether CPU offload was active for this generation. Absent on records written "
        "before this existed.",
    )
    schema_version: Optional[int] = Field(
        None,
        description = "Recipe format version embedded in the PNG unsloth chunk. Absent on older images.",
    )
    baked_loras: list[str] = Field(
        default_factory = list,
        description = "Adapter ids baked into the transformer AT LOAD TIME (before quantize + "
        "compile). Part of the build, not of this generation: reloading without them gives a "
        "different pipeline even though disabling them here contributes nothing to the image.",
    )
    loras: list[str] = Field(
        default_factory = list, description = "LoRA adapters applied, formatted as 'id:weight'"
    )
    controlnet: Optional[str] = Field(
        None, description = "ControlNet applied, formatted as 'id:control_type:strength'"
    )
    # Conditioned-workflow settings. The images themselves are NOT persisted (user uploads with their own lifetime), so these say what ran and let the client ask for them back.
    workflow: Optional[str] = Field(
        None,
        description = "Workflow that produced it: txt2img, img2img, inpaint, upscale, edit, "
        "reference or controlnet. Absent on records written before this was recorded.",
    )
    strength: Optional[float] = Field(
        None, description = "img2img/inpaint denoise strength, when the workflow used one"
    )
    upscale: Optional[float] = Field(None, description = "Upscale factor, for the upscale workflow")
    upscale_model: Optional[str] = Field(
        None, description = "Model upscaler id the upscale workflow used; null = Lanczos"
    )
    hires_scale: Optional[float] = Field(
        None, description = "Hires fix upscale factor; null = no Hires fix"
    )
    hires_denoise: Optional[float] = Field(None, description = "Hires fix refine denoising strength")
    hires_steps: Optional[int] = Field(
        None, description = "Hires fix refine steps as requested; null = the base pass's steps"
    )
    hires_upscaler: Optional[str] = Field(None, description = "Hires fix upscaler id")
    hires_guidance: Optional[float] = Field(
        None, description = "Hires fix refine guidance; null = the base guidance"
    )
    hires_base_width: Optional[int] = Field(None, description = "Hires fix base-pass width")
    hires_base_height: Optional[int] = Field(None, description = "Hires fix base-pass height")
    controlnet_guidance: Optional[str] = Field(
        None, description = "ControlNet guidance interval, formatted as 'start:end'"
    )
    reference_image_count: Optional[int] = Field(
        None,
        description = "How many ADDITIONAL images (reference_images, beyond the source) the "
        "reference or edit workflow used",
    )
    reference_resolution: Optional[int] = Field(
        None, description = "Condition-image preprocessing resolution, when the model has one"
    )
    localized_edit: Optional[str] = Field(
        None, description = "Localized edit convention used: annotate, paint or mask"
    )
    sampler: Optional[str] = Field(
        None, description = "Sampler id the image ran with; null = the model's shipped scheduler"
    )
    schedule_type: Optional[str] = Field(
        None, description = "Schedule type the sampler ran with (resolved); null = the config's"
    )
    prompt_weighting: Optional[bool] = Field(
        None,
        description = "True when AUTOMATIC1111 weight syntax was applied; false when the request turned "
        "it off (literal prompt); null = nothing to weight",
    )
    clip_skip: Optional[int] = Field(
        None, description = "CLIP skip (AUTOMATIC1111 numbering) above 1; null = the model's layer"
    )
    cfg_rescale: Optional[float] = Field(None, description = "CFG rescale; null = off")
    variation_seed: Optional[int] = Field(
        None, description = "Variation seed THIS image used; null = no variation"
    )
    variation_strength: Optional[float] = Field(
        None, description = "Variation strength; null = no variation"
    )
    shift: Optional[float] = Field(
        None, description = "Requested static flow shift; null = the model's"
    )
    base_shift: Optional[float] = Field(
        None, description = "Requested ModelSamplingFlux base shift; null = the model's"
    )
    max_shift: Optional[float] = Field(
        None, description = "Requested ModelSamplingFlux max shift; null = the model's"
    )
    embeddings: Optional[list[str]] = Field(
        None, description = "Textual-inversion embeddings the prompts used (filename stems)"
    )
    mask_blur: Optional[int] = Field(
        None, description = "Inpaint mask blur radius (px) applied; null = none"
    )
    inpaint_only_masked: Optional[bool] = Field(
        None,
        description = "True when the inpaint rendered only the masked area; null = whole picture",
    )
    inpaint_padding: Optional[int] = Field(
        None, description = "Padding (px) around the mask for an only-masked inpaint"
    )
    xy_grid: Optional[dict[str, Any]] = Field(
        None,
        description = "Set on an X/Y grid image: its axes ({field, index, values, labels}) and the "
        "cell image ids row by row. Its other recipe fields are the first cell's, as in AUTOMATIC1111.",
    )
    detailer: Optional[Dict[str, Any]] = Field(
        None,
        description = "The Detailer pass this image ran: its settings, each detection (target, score, box, crop, "
        "size, seed) and timing, or `error` when it did not run; null = no pass",
    )
    created_at: float = Field(..., description = "Creation time (epoch seconds)")
    # Library state, not recipe: stored beside the PNG, so older files simply read as unset.
    pinned: bool = Field(False, description = "Pinned to the front of the gallery")
    archived: bool = Field(False, description = "Moved to the archived shelf, hidden from the strip")
    order_at: Optional[float] = Field(
        None,
        description = "Unpinned sort key (epoch-second scale): the manual key once dragged, else the file mtime",
    )


class GalleryFlagsPatch(BaseModel):
    """Partial update of one gallery item's pin/archive flags; omitted fields are left alone."""

    pinned: Optional[bool] = Field(None, description = "Pin (True) or unpin (False) the item")
    archived: Optional[bool] = Field(None, description = "Archive (True) or restore (False) the item")


class GalleryMoveRequest(BaseModel):
    """Drag one gallery item to a new place on the active shelf."""

    after_id: Optional[str] = Field(
        None, description = "Id the item now follows, as displayed; null moves it to the front"
    )


class GalleryProjectRequest(BaseModel):
    """Copy one gallery item into a chat project's folder."""

    project_id: str = Field(..., description = "Chat project to add the item to")


class GalleryProjectResponse(BaseModel):
    path: str = Field(..., description = "Where the copy now lives, inside the project's folder")
    already: bool = Field(
        False, description = "The project already held this item; nothing was copied"
    )


class DiffusionGenerateResponse(BaseModel):
    """The persisted gallery records for one generation call (a batch)."""

    images: list[GalleryImage] = Field(..., description = "Saved records, one per image in the batch")
    grid: Optional[GalleryImage] = Field(
        None,
        description = "xy only: the labelled grid image, also saved to the gallery; `images` holds "
        "the cells row by row",
    )


class GalleryListResponse(BaseModel):
    """A newest-first page of persisted images, for infinite scroll."""

    images: list[GalleryImage] = Field(default_factory = list)
    has_more: bool = Field(False, description = "Whether older images remain past this page")


class ImageQueueJob(BaseModel):
    """One job in the image generation queue: the settings that tell it apart, its state and, once done, its images."""

    id: str
    status: Literal["queued", "running", "done", "failed", "cancelled"]
    position: Optional[int] = Field(
        None, description = "0-based place among your queued jobs; null once started"
    )
    prompt: str
    width: int
    height: int
    steps: Optional[int] = Field(
        None, description = "Requested steps; null follows the loaded model's default"
    )
    seed: Optional[int] = Field(
        None, description = "Requested seed; null draws one when the job runs"
    )
    batch_size: int
    workflow: Optional[str] = None
    loras: list[str] = Field(default_factory = list, description = "Applied adapters as id:weight")
    created_at: float
    started_at: Optional[float] = None
    finished_at: Optional[float] = None
    error: Optional[str] = None
    image_ids: list[str] = Field(
        default_factory = list, description = "Gallery ids of the finished images"
    )
    seed_used: Optional[int] = Field(
        None, description = "The run's base seed once done, for Reuse last seed"
    )


class ImageQueueResponse(BaseModel):
    """Your image jobs in run order: running first, then queued, then the most recent finished ones."""

    jobs: list[ImageQueueJob] = Field(default_factory = list)


class ImageQueueMoveRequest(BaseModel):
    """Body of POST /images/queue/{job_id}/move."""

    index: int = Field(..., ge = 0, description = "New 0-based place among your queued jobs (clamped)")


class PromptUpsamplerDownloadRequest(BaseModel):
    """Body of POST /images/prompt-upsampler/download (optional)."""

    hf_token: Optional[str] = Field(None, description = "Hugging Face token for the download")


class MaskSegmenterDownloadRequest(BaseModel):
    """Body of POST /images/segment/download (optional)."""

    hf_token: Optional[str] = Field(
        None,
        description = "Hugging Face token, needed only for a gated segmenter variant (facebook/sam3)",
    )


class MaskSegmentRequest(BaseModel):
    """Make an inpaint / localized-edit mask from text with SAM 3."""

    image: str = Field(
        ...,
        min_length = 1,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL source image (as init_image on /images/generate)",
    )
    prompt: str = Field(
        ...,
        min_length = 1,
        max_length = 2000,
        description = "Comma-separated concepts; a trailing :N keeps up to N of that concept (default 1), "
        "e.g. 'sofa, red lamp, pillow:2'",
    )
    threshold: float = Field(
        0.5,
        ge = 0.0,
        le = 1.0,
        description = "Detection score threshold (ComfyUI SAM3 Detect's default 0.5)",
    )


class PromptUpsamplerPreviewRequest(BaseModel):
    """Enhance one prompt with the FLUX.3 prompt upsampler without generating."""

    prompt: str = Field(..., min_length = 1, description = "The prompt as typed")
    reference_images: Optional[list[str]] = Field(
        None,
        max_length = 10,
        description = "Reference images (base64/data-URL, as /images/generate) for an edit, in order",
    )
    variant: Optional[Literal["distilled", "base"]] = Field(
        None,
        description = "Sampling variant; null = the loaded FLUX.3 family's (distilled when none is loaded)",
    )

    @field_validator("reference_images")
    @classmethod
    def _bounded_reference_items(cls, value: Optional[list[str]]) -> Optional[list[str]]:
        if value is not None:
            for item in value:
                if len(item) > 32 * 1024 * 1024:
                    raise ValueError("each reference image must be at most 32 MiB (base64)")
            if sum(len(item) for item in value) > _MAX_CONDITION_PAYLOAD:
                raise ValueError(
                    "the input images together must be at most 128 MiB (base64); use smaller images"
                )
        return value


class PromptUpsamplerPreviewResponse(BaseModel):
    enhanced_prompt: str = Field(..., description = "The caption the upsampler wrote")


class DiffusionGenerateProgressResponse(BaseModel):
    """Live per-step progress for an in-flight generation."""

    active: bool = Field(False, description = "Whether a generation is running")
    step: int = Field(0, description = "Denoising steps completed so far")
    total_steps: int = Field(0, description = "Total denoising steps for this run")
    fraction: float = Field(0.0, description = "step / total_steps, clamped to [0,1]")
    eta_seconds: Optional[float] = Field(None, description = "Estimated seconds remaining")
    phase: Optional[str] = Field(
        None,
        description = "enhance (FLUX.3 prompt upsampling, before the run) | encode | denoise | decode; null "
        "from engines that report no phase (sd.cpp)",
    )
    preview: Optional[str] = Field(
        None, description = "Live latent preview of the image being denoised, as a JPEG data URL"
    )
    preview_seq: int = Field(0, description = "Moves each time a new preview is published")
    message: Optional[str] = Field(
        None,
        description = "Status text for a phase with no steps (phase 'enhance': 'Enhancing prompt...')",
    )
    target: Optional[Literal["connection"]] = Field(
        None,
        description = "'connection' when the run is on a saved image connection, so a page that "
        "resumed it sends Stop to POST /images/generate/cancel?target=connection",
    )


class DiffusionLoadProgressResponse(BaseModel):
    """Download/finalize progress for an in-flight diffusion load."""

    phase: Optional[
        Literal["downloading", "finalizing", "saving_chat_context", "ready", "error"]
    ] = Field(None, description = "Load phase; null when idle")
    bytes_downloaded: int = Field(0, description = "Bytes present in the HF cache so far")
    bytes_total: int = Field(0, description = "Estimated total bytes to download (0 = unknown)")
    fraction: float = Field(0.0, description = "bytes_downloaded / bytes_total, clamped to [0,1]")
    error: Optional[str] = Field(None, description = "Failure message when phase is 'error'")
    error_code: Optional[str] = Field(
        None,
        description = "Stable code for error: 'unified-memory-load' when the unified-memory check refused "
        "the load (retry with allow_oversized_load to attempt it anyway); null otherwise.",
    )


class DiffusionResolvedControl(BaseModel):
    """One Advanced control's engaged value + provenance, for the "Auto: X" badges.

    ``value`` is what actually applied (a scheme string, a mode string, ``null`` when the
    control is off, or ``true``/``false`` for cpu_offload), so it is typed ``Any``.
    ``source`` is "auto" when this backend decided it or "explicit" when the caller did;
    ``reason`` is the short human-readable why the frontend shows as a tooltip.

    ``requested`` and ``status`` carry the OTHER half: what was asked for and whether it was
    honored. Without them a declined request was indistinguishable from an honored one -- the
    engaged value was reported truthfully, but the ask it replaced was gone, so the UI kept
    advertising a precision that never engaged.
    """

    value: Any = Field(
        None, description = "The engaged value: a string, a boolean (cpu_offload), or null."
    )
    requested: Any = Field(
        None,
        description = "What the caller asked for, verbatim (a string, a boolean for cpu_offload), "
        "or null when they left this control to the backend. Compare with ``value`` to see "
        "whether the request survived.",
    )
    source: str = Field(..., description = '"auto" (backend decided) or "explicit" (caller set it)')
    status: str = Field(
        "applied",
        description = 'Whether the request was honored: "applied" (it was, or there was no '
        'request), "fell_back" (an explicit request was declined and something else engaged) or '
        '"unsupported" (an explicit request cannot run on this host / model at all). Defaulted '
        "so a client reading an older backend's payload still parses.",
    )
    reason: str = Field("", description = "Short human-readable reason for the resolved value.")
    artifact: Optional[str] = Field(
        None,
        description = "The hosted or local file the engaged value came from, as "
        '"prequant:<repo>/<file>", when a pre-quantized checkpoint was seeded rather than the '
        "weights being quantised in memory. Declared here or pydantic drops it and no API client "
        "ever sees the provenance. Null on every other control and on a runtime quantise.",
    )
    replaced: Optional[str] = Field(
        None,
        description = 'The picked checkpoint that did NOT run, as "gguf:<file>", when a GGUF pick whose memory plan '
        "offloads loaded the hosted pre-quantized checkpoint (``artifact``) instead. Null otherwise.",
    )
    steps: Optional[List[Dict[str, Any]]] = Field(
        None,
        description = "speed_mode only: the auto-optimizer's per-step audit for this load, in order, each "
        '{"step", "status": "engaged" | "declined" | "failed", "reason"} (why a step did not engage, or the '
        "error it failed with). Null on every other control.",
    )


class DiffusionDownloadPlanEntry(BaseModel):
    """One repo the pick needs, with the exact files to fetch from it."""

    repo_id: str = Field(..., description = "Repo to download from")
    files: List[str] = Field(
        default_factory = list,
        description = "Exact files the loader reads. Scoped on purpose: a full snapshot would "
        "also pull the packaged root single, transformer/ shards and fp16 twins the loader "
        "never opens (tens of GB on a FLUX repo).",
    )
    bytes: int = Field(
        0, description = "Declared size of the files still missing from cache, 0 when unknown"
    )
    gguf_filename: Optional[str] = Field(
        None, description = "Set when this entry is the single-file GGUF checkpoint"
    )
    checkpoint: bool = Field(
        False,
        description = "This entry holds the SELECTED model rather than a companion repo. The "
        "planner has to say so: a gated base is staged from its ungated mirror, so the entry's "
        "repo id is not the id the caller picked and the role cannot be recovered downstream.",
    )
    hosted_denoiser: bool = Field(
        False,
        description = "This checkpoint entry holds a hosted denoiser replacing the pipeline's "
        "dense weights, which a pinned snapshot of that pipeline does not contain.",
    )


class DiffusionDownloadPlanResponse(BaseModel):
    """Files to stage before loading; plan_failed marks an incomplete listing."""

    entries: List[DiffusionDownloadPlanEntry] = Field(default_factory = list)
    plan_failed: bool = Field(False, description = "Metadata discovery left the file list incomplete")
    total_bytes: int = Field(
        0, description = "Sum of the remaining download entries, 0 when ready or unknown"
    )
    required_bytes: int = Field(
        0,
        description = "Full declared footprint of every file the load requires, including cached files",
    )
    checkpoint_bytes: int = Field(
        0, description = "Declared size of the selected checkpoint within required_bytes"
    )
    incompatible_reason: Optional[str] = Field(
        None,
        description = "Why this pick cannot load as selected (today: a FLUX.2 GGUF paired with a "
        "different-size base), so the picker can refuse at selection time instead of after a "
        "multi-GB download. Reported rather than raised: the images page falls back to "
        "/images/load on any plan failure, which would start that very download. Null means "
        "nothing is known to be wrong -- the check reads metadata only and stays silent on an "
        "unreadable header, an unmapped base or an offline host.",
    )
    incompatible_code: Optional[str] = Field(
        None,
        description = "Stable code for incompatible_reason: 'unified-memory-load' when the unified-memory "
        "check refused the pick (send allow_oversized_load to attempt it anyway); null otherwise.",
    )


class DiffusionStatusResponse(BaseModel):
    """Current diffusion backend state."""

    load_id: Optional[str] = Field(
        None,
        description = "The load_token of the load in flight or resident (one Studio made up for a "
        "load sent without one); POST unload with expected_load_id set to it unloads that load only.",
    )
    resident_load_id: Optional[str] = Field(
        None,
        description = "The load_token of the model resident in the slot, also while another load is "
        "in flight over it (equal to load_id when none is); a failed replacement leaves this model loaded.",
    )
    resident_mib: Optional[int] = Field(
        None,
        description = "Best-effort memory the resident model holds, in MiB; null when unknown.",
    )
    multi_gpu: Optional[Dict[str, Any]] = Field(
        None,
        description = "Multi-GPU placement (component -> card, primary, secondary) and CFG-parallel state (armed, "
        "call counts, or why it declined); null when the load had one card to use. A multi-card load that kept "
        "everything on its primary card reports why it declined.",
    )
    graph_engagement: Optional[Dict[str, Any]] = Field(
        None,
        description = "Compile / CUDA-graph engagement counters: this load's graph captures, replays and ungraphed "
        "denoiser calls (whole-step, per block, per-card segments, and the per-block graphs a whole-step graph falls "
        "back to), and the process's dynamo frame and graph-break totals; null when nothing is loaded.",
    )
    loaded: bool = Field(False, description = "Whether a diffusion model is loaded")
    evicted: List[str] = Field(
        default_factory = list,
        description = "Models this load unloaded to make room. Filled only on the load answer.",
    )
    evicted_slots: List[EvictedSlot] = Field(
        default_factory = list,
        description = "The same models as evicted, each with its kind and public model id.",
    )
    repo_id: Optional[str] = Field(None, description = "Loaded repo id or local path")
    display_repo_id: Optional[str] = Field(None, description = "Logical Hub id of a local snapshot")
    family: Optional[str] = Field(None, description = "Detected diffusion family")
    supported_families: List[str] = Field(default_factory = list, description = "Loadable families")
    modular_families: List[str] = Field(
        default_factory = list, description = "Loadable families shipped as Modular Diffusers pipelines"
    )
    supports_prompt_upsampler: bool = Field(
        False,
        description = "Whether the loaded family can enhance prompts with the FLUX.3 prompt upsampler",
    )
    prompt_upsampler_default: bool = Field(
        False, description = "Whether enhance_prompt defaults to on for the loaded family"
    )
    base_repo: Optional[str] = Field(None, description = "Companion diffusers base repo")
    device: Optional[str] = Field(None, description = "Device the pipeline is on")
    dtype: Optional[str] = Field(None, description = "Compute dtype")
    model_kind: Optional[str] = Field(
        None, description = "Resolved load kind: gguf | single_file | pipeline (gates GGUF-only UI)"
    )
    gguf_filename: Optional[str] = Field(
        None, description = "Loaded single-file checkpoint filename, or null for a pipeline"
    )
    gguf_variant: Optional[str] = Field(
        None, description = "Selected GGUF quantisation variant (for example Q8_0)"
    )
    component_files: Optional[Dict[str, str]] = Field(
        None,
        description = "Supplied text-encoder / VAE files by pipeline component (e.g. text_encoder_2: "
        "t5xxl_fp8_e4m3fn_scaled.safetensors); null when every companion came from the base repo",
    )
    cpu_offload: bool = Field(False, description = "Whether CPU offload is engaged")
    offload_policy: Optional[str] = Field(
        None, description = "Resolved offload policy: none | group | model | streaming | sequential"
    )
    denoiser_offload: Optional[str] = Field(
        None,
        description = "Under group offload, where the denoiser lives now: resident (only the text encoders "
        "stream) | partial | streamed (blocks move from CPU on every step). Null for other policies.",
    )
    vae_tiling: bool = Field(False, description = "Whether VAE tiling/slicing is enabled")
    memory_mode: Optional[str] = Field(None, description = "Requested memory mode")
    speed_mode: Optional[str] = Field(None, description = "Requested speed mode")
    speed_optims: list[str] = Field(
        default_factory = list, description = "Speed optimisations actually engaged"
    )
    text_encoder_quant: Optional[str] = Field(
        None, description = "Text-encoder quantisation engaged: fp8 | nvfp4 | null"
    )
    transformer_quant: Optional[str] = Field(
        None,
        description = "Transformer quant engaged on the dense fast path: int8 | fp8 | "
        "nvfp4 | mxfp8 | null (null = the GGUF transformer was loaded)",
    )
    transformer_quant_backend: Optional[str] = Field(
        None,
        description = "Which NVFP4 kernel path the loaded DiT actually runs: flashinfer | "
        "torchao | null (null for every scheme but nvfp4). The scheme alone does not say: "
        "flashinfer is selected per device and falls back to torchao on a preflight failure, so "
        "this is the only place a render's speed can be attributed to the backend that served it.",
    )
    transformer_quant_backend_reason: Optional[str] = Field(
        None,
        description = "Why flashinfer is not serving an NVFP4 load that runs torchao: the on-demand "
        "install was refused (offline, opt-out, ineligible host) or failed and was rolled back. "
        "null when the backend is flashinfer, the scheme is not nvfp4, or no reason was recorded.",
    )
    attention_backend: Optional[str] = Field(
        None,
        description = "Attention backend engaged via the diffusers dispatcher (e.g. "
        "_native_cudnn), or null for the default SDPA",
    )
    transformer_cache: Optional[str] = Field(
        None, description = "Step cache engaged: fbcache | static | null"
    )
    baked_loras: list[str] = Field(
        default_factory = list,
        description = "Adapter ids baked into the transformer at load time, as GalleryImage.baked_loras "
        "records them; empty when the load baked none",
    )
    transformer_cache_stats: Optional[dict] = Field(
        None,
        description = "Static step skip only: mode, schedule and the last generation's "
        "calls / computed / skipped transformer calls; null for any other cache",
    )
    workflows: list[str] = Field(
        default_factory = list,
        description = "Image workflows the loaded family supports (drives UI tab gating): "
        "txt2img, img2img, inpaint. Empty when nothing is loaded or on the native engine.",
    )
    conditioning: Optional[Dict[str, Any]] = Field(
        None,
        description = "Image-conditioning limits of the loaded model on the active engine: "
        "max_condition_images (total, including the source), alpha, dimension_multiple, "
        "max_output_side, max_output_pixels, reference_resolutions and localized_edit_modes. "
        "Null when nothing is loaded.",
    )
    engine: Optional[str] = Field(
        None,
        description = "Active diffusion engine: diffusers | sd_cpp | mlx (opt-in, Apple Silicon)",
    )
    native_mode: Optional[str] = Field(
        None,
        description = "Native sd.cpp execution mode: server (resident sd-server) | oneshot "
        "(per-image sd-cli) | null (diffusers engine)",
    )
    fallback_reason: Optional[str] = Field(
        None,
        description = "Why diffusers was chosen over the native sd.cpp engine (null when none)",
    )
    mlx_fallback_reason: Optional[str] = Field(
        None,
        description = "Why an Apple Silicon load did not get the MLX engine (null when MLX is off, the host is "
        "not an Apple Silicon Mac, or MLX is in use)",
    )
    engine_routing: Optional[dict[str, Any]] = Field(
        None,
        description = "Per-request routing of the default Apple Silicon MLX engine: mode, default_engine, resident "
        "engines, txt2img_engine (where plain text-to-image runs next), engines_fit_together, last_served_by and "
        "last_reason. Null for every other engine.",
    )
    engine_forced: Optional[str] = Field(
        None,
        description = "Engine UNSLOTH_DIFFUSION_ENGINE pins (diffusers | sd_cpp); a load's own engine pick "
        "is ignored while set. Null when unset.",
    )
    native_engine_eligible: bool = Field(
        False,
        description = "Whether the loaded pick is a GGUF of a family the native sd.cpp engine can run "
        "(the binary itself is checked when a load asks for it).",
    )
    lora_via_native: bool = Field(
        False,
        description = "LoRA is unavailable on the current engine for this GGUF, but reloading it on the "
        "native sd.cpp engine would apply LoRAs.",
    )
    lora_after_reload: bool = Field(
        False,
        description = "LoRA is off only because Speed=Auto compiled the model on its 3rd image; "
        "reloading it (still Speed=Auto) brings LoRAs back until then.",
    )
    supports_lora: bool = Field(
        False,
        description = "Whether the loaded model + quantisation can apply LoRA adapters (drives the "
        "LoRA picker's enabled state). torchao int8/fp8 builds support LoRA via the load-time "
        "bake: select the adapters when loading; weight changes apply live, a different adapter "
        "set needs a reload. False on unsupported families/quant (e.g. nvfp4/mxfp8, "
        "a whole-pipeline SDXL GGUF, or Qwen-Image on the native engine).",
    )
    lora_unavailable_reason: Optional[str] = Field(
        None,
        description = "Why the loaded model cannot apply LoRA adapters on its current engine, shown on the "
        "Images page in place of the LoRA picker. Null when supports_lora is true or nothing is loaded.",
    )
    supports_controlnet: bool = Field(
        False,
        description = "Whether the loaded model can apply a ControlNet (drives the ControlNet "
        "picker's enabled state). Diffusers only, for families with a ControlNet pipeline; False "
        "for the native engine, GGUF-via-diffusers, and torchao fp8/int8 dense.",
    )
    supports_inpaint_only_masked: bool = Field(
        False,
        description = "Whether the loaded model's inpaint pipeline can render only the masked area "
        "(`inpaint_only_masked`, diffusers padding_mask_crop). Diffusers only; False for the "
        "native and MLX engines and when nothing is loaded.",
    )
    supports_negative_prompt: bool = Field(
        True,
        description = "Whether the loaded model applies a negative prompt on this engine "
        "(drives the Negative prompt field). False for FLUX and Ideogram 4 on diffusers, and "
        "for FLUX.1 / Kontext / FLUX.2-dev on the native engine.",
    )
    negative_prompt_min_guidance: Optional[float] = Field(
        None,
        description = "The guidance Unsloth passes a negative prompt above (1 for classifier-free guidance, 0 "
        "for Z-Image and Krea 2 on diffusers); null when guidance does not gate it. Drives the Negative prompt hint.",
    )
    supports_guidance: bool = Field(
        True,
        description = "Whether the loaded model reads the guidance value on this engine (drives the Guidance "
        "control). False on diffusers for FLUX.3 Klein (distilled), whose pipeline has no guidance, and for "
        "distilled FLUX.2 klein checkpoints, which Flux2KleinPipeline runs without it.",
    )
    supports_live_preview: bool = Field(
        True,
        description = "Whether generations on this load can stream live denoise previews (drives the Live preview "
        "switch). False on the native and MLX engines and for families without a fitted preview map.",
    )
    prompt_hint: Optional[str] = Field(
        None,
        description = "How the loaded model reads prompts, in one or two sentences; null when "
        "it has no tip.",
    )
    samplers: list[Dict[str, Any]] = Field(
        default_factory = list,
        description = "Samplers the loaded model can run, each {id, label, schedule_types}; the "
        "first is 'default' (the shipped scheduler). Empty when there is no choice: flow-matching "
        "models, the native and MLX engines, or nothing loaded.",
    )
    sd_controls: Optional[Dict[str, Any]] = Field(
        None,
        description = "SDXL prompt weighting, CLIP skip, CFG rescale and variation seed: "
        "{prompt_weighting, clip_skip {min, max, default, same_as_default_through}, cfg_rescale "
        "{min, max, default, recommended}, variation_seed, vary_strength, prediction_type}. Null when "
        "the loaded model has none of them (every non-SDXL family, the native and MLX engines).",
    )
    shift_control: Optional[Dict[str, Any]] = Field(
        None,
        description = "The Shift control the loaded flow-matching model takes, or null to hide it: "
        "{node: 'sd3', shift} (one static shift, ComfyUI ModelSamplingSD3 / AuraFlow; shift = the "
        "loaded value or null when resolution-dependent) or {node: 'flux', base_shift, max_shift} "
        "(ComfyUI ModelSamplingFlux defaults). Diffusers engine only.",
    )
    hires: Optional[Dict[str, Any]] = Field(
        None,
        description = "The Hires fix control the loaded model takes, or null to hide it: {upscalers: [{id, label, "
        "kind}], default_upscaler, defaults: {scale, denoise}, max_side}.",
    )
    hires_unavailable_reason: Optional[str] = Field(
        None,
        description = "Why Hires fix is hidden for the loaded model, when there is a reason worth showing",
    )
    upscale_models: list[Dict[str, Any]] = Field(
        default_factory = list,
        description = "Model upscalers ({id, label, scale}) the Upscale workflow can use; empty = Lanczos only.",
    )
    textual_inversion: Optional[str] = Field(
        None,
        description = "Textual-inversion embedding format the loaded model takes ('sdxl'), or null when "
        "it takes none. Embeddings are listed by GET /api/models/diffusion-embeddings.",
    )
    # declare provenance explicitly because Pydantic extra="ignore" would otherwise discard it.
    resolved: Optional[Dict[str, DiffusionResolvedControl]] = Field(
        None,
        description = "Per-control resolved value + provenance (source auto|explicit + reason), "
        "keyed by Advanced control name; null when unloaded or unavailable.",
    )
    generation_defaults: Optional[Dict[str, float]] = Field(
        None,
        description = "Default steps and guidance for the loaded model (file header before base repo); "
        "null when unloaded or on an engine that does not report it.",
    )


class DiffusionLoadUnloadedResponse(DiffusionStatusResponse):
    """POST /images/unload with expected_load_id that unloaded that load: the state it left behind."""

    unloaded: Literal[True] = Field(..., description = "Always true: that load was unloaded")
    outcome: Literal["unloaded"] = Field(..., description = "Always unloaded")


# What POST /images/unload answers: the state it left behind without expected_load_id, and with it
# either that, marked unloaded, or the outcome alone.
DiffusionUnloadResponse = Union[
    DiffusionLoadUnloadedResponse, MediaUnloadOutcome, DiffusionStatusResponse
]


class DiffusionInferenceInfo(BaseModel):
    """bf16 component sizes and 0.1 GB resident estimates by transformer quantization scheme."""

    family: str = Field(..., description = "Diffusion family name (auto-policy table key).")
    transformer_bf16_gb: float = Field(..., description = "bf16-resident transformer size in GB.")
    text_encoders_bf16_gb: float = Field(
        ..., description = "bf16-resident text encoder(s) size in GB."
    )
    vae_bf16_gb: float = Field(..., description = "bf16-resident VAE size in GB.")
    estimated_resident_gb: Dict[str, float] = Field(
        ...,
        description = "Estimated resident GB keyed by scheme: bf16, int8, fp8, mxfp8, nvfp4.",
    )


class DiffusionInferenceInfoResponse(BaseModel):
    """Static per-family footprint summary for the Advanced Dtype tradeoff (GET
    /api/inference/images/info). Hardware-independent: no GPU probing, so it is served
    from the pure auto-policy tables and is safe to fetch before anything is loaded."""

    families: List[DiffusionInferenceInfo] = Field(default_factory = list)


# ── OpenAI-compatible images API (POST /v1/images/generations) ──
# OpenAI-compatible images API; GPT-image-only knobs are accepted and ignored. The route parses size and rejects stream.


class ImageGenerationRequest(BaseModel):
    """OpenAI ``CreateImageRequest`` for ``POST /v1/images/generations``.

    ``prompt`` is the only required field, per the spec. Unlisted OpenAI fields
    are ignored (Pydantic's default), matching dall-e-2's treatment of the
    GPT-image-only parameters."""

    prompt: str = Field(..., min_length = 1, description = "Text description of the image(s).")
    model: Optional[str] = Field(
        None, description = "Model id (informational; the loaded image model is used)."
    )
    n: int = Field(1, ge = 1, le = 10, description = "Number of images to generate (1-10).")
    size: str = Field(
        "auto", description = "'auto' or '<width>x<height>' (256-2048, each a multiple of 16)."
    )
    response_format: Literal["url", "b64_json"] = Field(
        "url", description = "Return each image as a URL or a base64-encoded PNG."
    )
    user: Optional[str] = Field(None, description = "End-user identifier (accepted, unused).")
    # gpt-image-only; declared so we can reject it clearly instead of returning JSON to a client that asked for an SSE stream.
    stream: Optional[bool] = Field(
        None, description = "Streaming image generation is not supported; omit or set false."
    )
    width: Optional[int] = Field(
        None,
        ge = 256,
        le = 2048,
        description = "[x-unsloth] Image width in pixels (multiple of 16); send with height "
        "instead of size.",
    )
    height: Optional[int] = Field(
        None,
        ge = 256,
        le = 2048,
        description = "[x-unsloth] Image height in pixels (multiple of 16); send with width "
        "instead of size.",
    )
    steps: Optional[int] = Field(
        None, ge = 1, le = 100, description = "[x-unsloth] Denoising steps (default per model)."
    )
    guidance: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 20.0,
        description = "[x-unsloth] Classifier-free guidance scale (default per model).",
    )
    seed: Optional[int] = Field(
        None,
        ge = 0,
        le = 2**53 - 1,
        description = "[x-unsloth] Seed for a repeatable image (random if omitted). With n > 1 "
        "each image derives its own seed from it.",
    )
    negative_prompt: Optional[str] = Field(
        None, description = "[x-unsloth] What to avoid, on models that take a negative prompt."
    )

    @field_validator("n", "size", "response_format", mode = "before")
    @classmethod
    def _null_means_default(cls, value, info):
        # OpenAI marks these nullable WITH a default, so an explicit null means "use the default": coalesce rather than 400.
        if value is None:
            return cls.model_fields[info.field_name].default
        return value

    @field_validator("seed", mode = "before")
    @classmethod
    def _minus_one_seed_means_random(cls, value):
        # -1 = random (A1111, sd.cpp); seed was ignored here before, so -1 must not start 400ing.
        return None if value == -1 else value


class ImageGenerationData(BaseModel):
    """One image in an ``ImagesResponse`` (OpenAI ``Image``). Exactly one of
    ``url`` / ``b64_json`` is set, per the request's ``response_format``; the
    route serializes with ``exclude_none`` so the unused key is omitted."""

    b64_json: Optional[str] = Field(
        None, description = "Base64-encoded PNG (response_format=b64_json)."
    )
    url: Optional[str] = Field(None, description = "URL to the PNG bytes (response_format=url).")


class ImageGenerationResponse(BaseModel):
    """OpenAI ``ImagesResponse``. dall-e-shaped: the GPT-image-only top-level
    fields (background/output_format/size/quality/usage) are omitted, since our
    sizes wouldn't satisfy their fixed enums and we report no token usage."""

    created: int = Field(..., description = "Unix timestamp (seconds) the images were created.")
    data: list[ImageGenerationData] = Field(..., description = "The generated images.")


class AudioSpeechRequest(BaseModel):
    """OpenAI ``CreateSpeechRequest`` for ``POST /v1/audio/speech``.

    ``voice`` picks a saved voice or a built-in speaker; OpenAI's own voice names are accepted
    and ignored. ``reference`` clones from uploaded audio, a history clip or a saved voice."""

    input: str = Field(..., min_length = 1, description = "The text to synthesize.")
    model: Optional[str] = Field(
        None,
        description = (
            "Model id. A downloaded text-to-speech model named here is loaded first when "
            "model auto-switch is on; otherwise the loaded audio model is used."
        ),
    )
    voice: Optional[Union[str, "AudioSpeechVoice"]] = Field(
        None,
        description = (
            'A saved voice\'s id (or {"id": ...}), else a built-in speaker of the model. Other '
            "names, such as OpenAI's, are ignored."
        ),
    )
    reference: Optional["AudioSourceRef"] = Field(
        None,
        description = "[x-unsloth] Audio to clone: an uploaded input, a history clip or a saved voice.",
    )
    reference_text: Optional[str] = Field(
        None,
        max_length = 4000,
        description = "[x-unsloth] What is said in the reference, for models that use it.",
    )
    response_format: Optional[str] = Field(
        "wav", description = "Output format: wav, mp3, flac, opus, aac or pcm."
    )
    stream_format: Optional[Literal["audio", "sse"]] = Field(
        None, description = "Only 'audio' (the whole file in one response) is supported."
    )
    speed: Optional[float] = Field(
        None, ge = 0.25, le = 4.0, description = "Speech rate, applied where the model supports it."
    )
    instructions: Optional[str] = Field(
        None,
        description = "Scene or music-description instructions for compatible audio models.",
    )
    language: Optional[str] = Field(
        None,
        description = "Target-language hint for compatible audio models.",
    )
    seed: Optional[int] = Field(
        None,
        ge = -(2**63),
        le = 2**64 - 1,
        description = "Best-effort deterministic generation seed.",
    )
    max_new_tokens: Optional[int] = Field(
        None,
        ge = 1,
        description = (
            "Maximum generated audio tokens/frames; MiniMax Music 3 uses 25 frames per second."
        ),
    )
    audio_options: Optional[Dict[str, Any]] = Field(
        None,
        description = (
            "[x-unsloth] Per-model request options ({name: value}) for audio GGUF models, as listed "
            "in the loaded model's audio_options. Unknown names are dropped."
        ),
    )
    provider_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Saved connection ID. When set, synthesis is proxied to that "
        "provider's /audio/speech and model/voice/speed are forwarded as sent.",
    )
    provider_base_url: Optional[str] = Field(
        None,
        description = "[x-unsloth] Browser-snapshotted connection base URL. Required with a "
        "legacy encrypted_api_key so an edit cannot route that key to another endpoint.",
    )
    encrypted_api_key: Optional[str] = Field(
        None,
        description = "[x-unsloth] Per-request key for a browser still holding a legacy "
        "provider key, used when the connection has none saved server side.",
    )

    @field_validator("response_format", mode = "before")
    @classmethod
    def _null_format_means_default(cls, value):
        # openai marks response_format nullable with a default, so an explicit null means wav
        return "wav" if value is None else value


class AudioGalleryItem(BaseModel):
    """One persisted TTS clip. ``url`` serves the WAV bytes (auth required)."""

    id: str
    url: str
    prompt: str
    model: str
    audio_type: str
    sample_rate: int
    duration_s: float
    created_at: str
    pinned: bool = Field(False, description = "Pinned to the top of history")
    archived: bool = Field(False, description = "Moved to the archived shelf, hidden from history")
    workflow: Optional[str] = Field(
        None,
        description = "Audio page workflow that made the clip: speak, clone, edit, convert, music or separate",
    )
    order_at: Optional[float] = Field(
        None,
        description = "Unpinned sort key (epoch-second scale): the manual key once dragged, else the file mtime",
    )
    group_id: Optional[str] = Field(None, description = "Clips made by one run share this id")
    role: Optional[str] = Field(None, description = "The clip's part in its run, e.g. output")
    source_clip_id: Optional[str] = Field(
        None, description = "History clip the run took its reference from"
    )
    voice_id: Optional[str] = Field(None, description = "Saved voice the run spoke in")
    settings: Optional[Dict[str, Any]] = Field(
        None, description = "Language, options, speed and whether a transcript was used"
    )
    reference_name: Optional[str] = Field(None, description = "Name of the reference clip or voice")
    source_input_id: Optional[str] = Field(
        None, description = "Uploaded input a conversion took its recording from"
    )
    source_name: Optional[str] = Field(None, description = "Name of the recording a run converted")
    target_builtin: Optional[str] = Field(
        None, description = "Built-in voice a conversion converted to"
    )
    target_clip_id: Optional[str] = Field(
        None, description = "History clip a conversion took its target voice from"
    )
    target_input_id: Optional[str] = Field(
        None, description = "Uploaded input a conversion took its target voice from"
    )
    source_saved: bool = Field(False, description = "Served at /audio/gallery/{id}/source/file")


_AUDIO_ID_PATTERN = r"^[A-Za-z0-9_-]{1,128}$"
# A run names audio by id only. Option names with these words carry a location...
_AUDIO_FILE_OPTION_WORDS = frozenset({"path", "paths", "file", "files", "dir", "url", "uri"})
# Options ending in audio, ref, video etc. name clip files; min_new_audio_steps is a setting.
_AUDIO_CLIP_OPTION_ENDINGS = frozenset({"audio", "wav", "ref", "video", "image", "img", "midi"})


def _names_a_file(name: str, value: Any) -> bool:
    words = re.split(r"[^a-z0-9]+", name.lower())
    # Vevo2's target_voice is a file, but neither of its words gives that away.
    if name.lower() == "target_voice" or any(word in _AUDIO_FILE_OPTION_WORDS for word in words):
        return True
    return isinstance(value, str) and words[-1] in _AUDIO_CLIP_OPTION_ENDINGS


class AudioSourceRef(BaseModel):
    """Audio named by id: an uploaded input, a history clip or a saved voice. Exactly one."""

    model_config = ConfigDict(extra = "forbid")

    input_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)
    clip_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)
    voice_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)

    @model_validator(mode = "after")
    def _exactly_one(self):
        named = [v for v in (self.input_id, self.clip_id, self.voice_id) if v]
        if len(named) != 1:
            raise ValueError("Name exactly one of input_id, clip_id or voice_id.")
        return self


class AudioSpeechVoice(BaseModel):
    """OpenAI's custom-voice object: here a saved voice's id."""

    id: str = Field(..., pattern = _AUDIO_ID_PATTERN)


class AudioGenerateRequest(ChatCompletionRequest):
    """``POST /audio/generate``: speak the last user message, as chat's read aloud does."""

    voice_id: Optional[str] = Field(
        None,
        pattern = _AUDIO_ID_PATTERN,
        description = (
            "[x-unsloth] A saved voice to speak in, as the Audio page's Speak does; the loaded "
            "model must clone. Language, instructions, options, seed and the token cap apply."
        ),
    )
    persist: bool = Field(
        True, description = "[x-unsloth] Keep the clip in Audio history. Read aloud sends false."
    )


class AudioRunInputs(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    reference: Optional[AudioSourceRef] = None
    source: Optional[AudioSourceRef] = None
    reference_text: Optional[str] = Field(None, max_length = 4000)
    emotion: Optional[AudioSourceRef] = None
    target: Optional[AudioSourceRef] = None
    # A 5 minute source (CONVERT_SOURCE_MAX_SECONDS) runs well past 4000 characters of speech.
    source_text: Optional[str] = Field(None, max_length = 16000)


class AudioConvertParams(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    mode: Literal["speech", "singing"] = "speech"
    pitch: Optional[int] = Field(None, ge = -24, le = 24)
    pitch_auto: bool = False
    style: Literal["source", "target"] = "source"
    voice: Optional[Literal["default", "manthos", "chocola", "fraise"]] = None


class AudioRunEdit(BaseModel):
    """Words: client-rendered DotTTS markup or FireRedAudio instructions, checked against both
    transcripts. Delivery (FireRedAudio): numbers only."""

    model_config = ConfigDict(extra = "forbid")

    mode: Literal["words", "delivery"] = "words"
    markup: Optional[str] = Field(None, max_length = 8000)
    instructions: Optional[List[Annotated[str, Field(min_length = 1, max_length = 300)]]] = Field(
        None, max_length = 8
    )
    speed: Optional[float] = Field(None, ge = 0.5, le = 2.0)
    pitch_steps: Optional[int] = Field(None, ge = 1, le = 12)


class AudioMusicRange(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    start_s: float = Field(..., ge = 0, le = 24 * 3600)
    end_s: float = Field(..., gt = 0, le = 24 * 3600)

    @model_validator(mode = "after")
    def _ordered(self):
        if self.end_s <= self.start_s:
            raise ValueError("A range must end after it starts.")
        return self


class AudioMusicEdit(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    action: Literal["repaint", "extend", "cover", "continue", "inpaint", "restyle"]
    ranges: List[AudioMusicRange] = Field(default_factory = list, max_length = 8)
    strength: Optional[float] = Field(None, ge = 0, le = 1)
    extend_s: Optional[float] = Field(None, gt = 0, le = 600)


class AudioRunRequest(BaseModel):
    """``POST /audio/run``: one Audio page run. Audio is named by id; the server picks the files."""

    model_config = ConfigDict(extra = "forbid")

    workflow: Literal["clone", "speak", "edit", "convert", "music", "separate"]
    model: Optional[str] = Field(
        None,
        max_length = 512,
        description = "A downloaded audio model to load first when model auto-switch is on; "
        "otherwise the loaded model runs it",
    )
    # Required except for a conversion or a separation (the routes answer those given text with a 400).
    text: Optional[str] = None
    language: Optional[str] = Field(None, max_length = 64)
    instructions: Optional[str] = Field(None, max_length = 4000)
    inputs: AudioRunInputs = Field(default_factory = AudioRunInputs)
    mode: Optional[Literal["song", "sfx", "edit"]] = None
    lyrics: Optional[str] = Field(None, max_length = 20000)
    instrumental: bool = False
    duration_s: Optional[float] = Field(None, ge = 0.5, le = 600)
    variations: int = Field(1, ge = 1, le = 4)
    # Music edits carry an action; speech edits (workflow edit) never do.
    edit: Optional[Union[AudioMusicEdit, AudioRunEdit]] = None
    options: Optional[Dict[str, Any]] = Field(
        None, description = "Per-model options, as listed in audio_options or by a tool panel"
    )
    speed: Optional[float] = Field(None, ge = 0.25, le = 4.0)
    seed: Optional[int] = Field(None, ge = -(2**63), le = 2**64 - 1)
    max_tokens: Optional[int] = Field(None, ge = 1)
    convert: Optional[AudioConvertParams] = None
    # One take of a music run the page sends take by take; its clips share group_id.
    take: Optional[int] = Field(None, ge = 1, le = 4)
    group_id: Optional[str] = Field(None, pattern = r"^[0-9a-f]{32}$")
    cancel_id: Optional[str] = Field(
        None,
        min_length = 8,
        max_length = 64,
        pattern = r"^[A-Za-z0-9_-]+$",
        description = "Your id for this run; POST it to /audio/cancel to stop the run",
    )
    provider_id: Optional[str] = Field(
        None,
        description = "[x-unsloth] Saved connection ID. When set, Speak sends the text to that "
        "connection's /audio/speech as `model` and the clip is saved to history.",
    )
    voice: Optional[str] = Field(
        None, max_length = 256, description = "Voice on the connection named by `provider_id`."
    )

    @model_validator(mode = "after")
    def _take_fields(self):
        if (self.take, self.group_id) != (None, None) and (
            self.workflow != "music" or self.variations != 1 or None in (self.take, self.group_id)
        ):
            raise ValueError("take and group_id go together, for music with variations 1.")
        return self

    @model_validator(mode = "after")
    def _fields_of_the_workflow(self):
        inputs = self.inputs
        if self.workflow == "convert":
            if self.text is not None:
                raise ValueError("A conversion takes no text.")
            if inputs.reference is not None or inputs.emotion is not None:
                raise ValueError("A conversion takes inputs.source and inputs.target.")
            if self.convert is None:
                self.convert = AudioConvertParams()
            return self
        if self.text is None and self.workflow != "separate":
            raise ValueError("text is required.")
        # inputs.source also carries a Music edit's clip; the route refuses it elsewhere.
        if self.convert is not None or any(
            v is not None for v in (inputs.target, inputs.source_text)
        ):
            raise ValueError("convert and the target inputs are for workflow convert.")
        return self

    @model_validator(mode = "after")
    def _edit_fields(self):
        if self.workflow == "edit" and not isinstance(self.edit, AudioRunEdit):
            raise ValueError("Send edit with workflow edit.")
        if isinstance(self.edit, AudioRunEdit) and self.workflow != "edit":
            raise ValueError("A speech edit is for workflow edit.")
        if self.workflow == "edit" and (
            self.inputs.reference is not None or self.inputs.emotion is not None
        ):
            raise ValueError("An edit takes inputs.source, not a reference or emotion clip.")
        return self

    @field_validator("options")
    @classmethod
    def _no_file_options(cls, value):
        if value is None:
            return value
        for name, option in value.items():
            if _names_a_file(str(name), option):
                raise ValueError(f"Option '{name}' is not accepted; name audio by id in inputs.")
            if isinstance(option, (dict, list)):
                raise ValueError(f"Option '{name}' must be a single value.")
        return value

    @model_validator(mode = "after")
    def _workflow_fields(self):
        if self.workflow == "music":
            if self.mode is None:
                raise ValueError("Pick a music mode: song, sfx or edit.")
            if self.text is None:
                raise ValueError("text is required for music.")
        elif self.workflow not in ("convert", "separate") and not self.text:
            raise ValueError("text must not be empty.")
        return self


class AudioRunClip(BaseModel):
    id: str
    role: str = "output"
    url: str
    sample_rate: int
    duration_s: float
    workflow: str
    seed: Optional[int] = None
    voice_id: Optional[str] = None
    source_clip_id: Optional[str] = None


class AudioRunAudio(BaseModel):
    data: str
    format: str = "wav"
    sample_rate: int
    seed: Optional[int] = None


class AudioRunResponse(BaseModel):
    clips: List[AudioRunClip] = Field(default_factory = list)
    # One separation's stems share it; None for a single clip.
    group_id: Optional[str] = None
    model: str
    audio: Optional[AudioRunAudio] = Field(
        None, description = "The audio inline, only when saving it to history failed"
    )
    ignored_options: List[str] = Field(
        default_factory = list, description = "Sent options the model does not take; not sent"
    )
    applied: Dict[str, Any] = Field(
        default_factory = dict,
        description = "Values Unsloth Studio used for settings it can change, e.g. duration_s",
    )
    warnings: List[str] = Field(default_factory = list)

    @model_validator(mode = "after")
    def _ignored_option_warnings(self):
        # FastAPI validates the response model again, so add each line once.
        for name in self.ignored_options:
            line = f"Ignored option {name}: the model does not take it."
            if line not in self.warnings:
                self.warnings.append(line)
        return self


class AudioInputRecord(BaseModel):
    id: str
    name: str
    duration_s: float
    sample_rate: int
    channels: int
    url: str
    expires_at: str


class AudioInputTranscribeRequest(SttContextSettings):
    model_config = ConfigDict(extra = "forbid")

    model: str = Field(..., min_length = 1, max_length = 512)
    engine: Optional[str] = Field(None, max_length = 64)
    device: Optional[Literal["auto", "cpu", "gpu"]] = None
    language: Optional[str] = Field(None, max_length = 64)
    purpose: Literal["reference", "convert"] = "reference"


class AudioInputTranscript(BaseModel):
    text: str
    language: Optional[str] = None
    model: str


class TranscribeSourceRef(BaseModel):
    """The audio to transcribe, by id: an upload, a history clip or a saved voice. Exactly one."""

    model_config = ConfigDict(extra = "forbid")

    input_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)
    clip_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)
    voice_id: Optional[str] = Field(None, pattern = _AUDIO_ID_PATTERN)

    @model_validator(mode = "after")
    def _exactly_one(self):
        named = [v for v in (self.input_id, self.clip_id, self.voice_id) if v]
        if len(named) != 1:
            raise ValueError("Name exactly one of input_id, clip_id or voice_id.")
        return self


class TranscribeSourceRequest(SttContextSettings):
    """``POST /audio/transcribe/source``: Audio page audio named by id, transcribed and saved."""

    model_config = ConfigDict(extra = "forbid")

    source: TranscribeSourceRef
    model: str = Field(..., min_length = 1, max_length = 512)
    engine: Optional[str] = Field(None, max_length = 64)
    device: Optional[Literal["auto", "cpu", "gpu"]] = None
    language: Optional[str] = Field(None, max_length = 64)
    timestamps: bool = Field(False, description = "Ask for segment and word timestamps")
    speakers: bool = Field(False, description = "Keep who spoke each segment, when the model tells")
    title: Optional[str] = Field(None, max_length = 255, description = "Defaults to the source's name")
    provider_id: Optional[str] = Field(
        None,
        max_length = 128,
        description = "Saved connection ID. When set, the audio goes to that connection's "
        "/audio/transcriptions as `model`; engine and device are ignored.",
    )


class AudioAnalyzeRequest(TranscribeSourceRef):
    """``POST /audio/analyze``: measure one clip, upload or voice; nothing is saved."""

    expected_text: Optional[str] = Field(
        None, max_length = 20000, description = "Text the audio should say; adds match_score"
    )


class AudioAnalyzeResponse(BaseModel):
    duration_s: float
    sample_rate: int
    channels: int
    integrated_lufs: Optional[float] = Field(None, description = "BS.1770 loudness; None for silence")
    true_peak_dbtp: Optional[float] = None
    clipped_samples: int
    clipping_ratio: float
    speech_start_s: Optional[float] = None
    speech_end_s: Optional[float] = None
    transcript: Optional[str] = None
    match_score: Optional[float] = Field(
        None,
        description = "1 - word error rate against expected_text; null when the texts are too "
        "long to align",
    )
    stt_model: Optional[str] = None


class AudioCancelRequest(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    cancel_id: str = Field(..., min_length = 8, max_length = 64, pattern = r"^[A-Za-z0-9_-]+$")


class TranscriptPatch(BaseModel):
    """``PATCH /audio/transcripts/{id}``: archive or restore, and name speakers (None clears)."""

    model_config = ConfigDict(extra = "forbid")

    archived: Optional[bool] = None
    # transcript_gallery.set_speaker_names validates ids and lengths against the record.
    speaker_names: Optional[Dict[str, Optional[str]]] = None


class AudioVoice(BaseModel):
    id: str
    name: str
    transcript: Optional[str] = None
    language: Optional[str] = None
    duration_s: float
    sample_rate: int
    created_at: str
    url: str


class AudioVoiceCreate(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    source: AudioSourceRef
    name: str = Field(..., min_length = 1, max_length = 80)
    transcript: Optional[str] = Field(None, max_length = 4000)
    language: Optional[str] = Field(None, max_length = 64)

    @model_validator(mode = "after")
    def _from_input_or_clip(self):
        if self.source.voice_id:
            raise ValueError("A voice is saved from an input or a history clip.")
        return self


class AudioVoicePatch(BaseModel):
    model_config = ConfigDict(extra = "forbid")

    name: Optional[str] = Field(None, min_length = 1, max_length = 80)
    transcript: Optional[str] = Field(None, max_length = 4000)
    language: Optional[str] = Field(None, max_length = 64)


class AudioVoiceListResponse(BaseModel):
    voices: List[AudioVoice] = Field(default_factory = list)


class AudioCatalogModel(BaseModel):
    """One audio.cpp model Unsloth Studio can offer: an umbrella folder or a Community repo."""

    id: str
    repo_id: str
    folder: str = ""
    source: Literal["umbrella", "community"]
    display_name: str
    family: Optional[str] = None
    task: Literal["tts", "music", "asr", "sep", ""] = ""
    workflows: List[
        Literal["speak", "clone", "edit", "convert", "music", "separate", "transcribe"]
    ] = Field(default_factory = list)
    description: Optional[str] = None
    languages: Optional[List[str]] = None
    status: Optional[Literal["supported", "community", "experimental", "testing", "wip"]] = None
    size_bytes: Optional[int] = None
    # GiB of GPU memory the load check requires for size_bytes; set per request (it reads the GPUs).
    estimated_resident_gb: Optional[float] = None
    # The smallest variant a GPU runs: a row fits a card when that variant does.
    smallest_size_bytes: Optional[int] = None
    smallest_estimated_resident_gb: Optional[float] = None
    downloaded: bool = False
    unsupported_reason: Optional[str] = None


class AudioCatalogResponse(BaseModel):
    """The audio.cpp model catalog, with where its umbrella listing came from."""

    source: Literal["hub", "saved", "cache"]
    fetched_at: float
    runtime_specs: bool = False
    models: List[AudioCatalogModel] = Field(default_factory = list)


class AudioGalleryFlagsPatch(BaseModel):
    pinned: Optional[bool] = Field(None, description = "Pin (True) or unpin (False) the clip")
    archived: Optional[bool] = Field(None, description = "Archive (True) or restore (False) the clip")


class AudioGalleryListResponse(BaseModel):
    """A window of the audio gallery for infinite scroll: pinned first, then newest first."""

    audio: List[AudioGalleryItem] = Field(default_factory = list)
    has_more: bool = False
    # Cursor: the last clip's order key (mtime unless dragged), id, and pin rank (None if unpinned).
    next_before_mtime: Optional[float] = None
    next_before_id: Optional[str] = None
    next_before_pin: Optional[float] = None


class VideoJobCreateRequest(BaseModel):
    prompt: str = Field(..., min_length = 1)
    model: Optional[str] = None
    seconds: Optional[str] = Field(
        None, description = "Clip duration in seconds, snapped to the loaded family's frame lattice."
    )
    size: Optional[str] = Field(
        None, description = "'<width>x<height>', a resolution preset of the loaded family."
    )
    # Unsloth Studio extensions; a plain OpenAI request leaves them all out.
    seed: Optional[int] = Field(
        None,
        ge = 0,
        le = 2**53 - 1,
        description = "Seed for a repeatable take. Omitted: Unsloth Studio draws one and returns "
        "it on the job.",
    )
    negative_prompt: Optional[str] = Field(
        None, description = "What the video should avoid, on models that take a negative prompt."
    )
    steps: Optional[int] = Field(
        None, ge = 1, le = 100, description = "Number of denoising steps (default per model)."
    )
    guidance: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 20.0,
        description = "Classifier-free guidance scale (default per model).",
    )
    num_frames: Optional[int] = Field(
        None,
        ge = 1,
        le = MAX_VIDEO_NUM_FRAMES,
        description = "Frame count on the model's frame lattice; send seconds or num_frames, "
        "not both.",
    )
    fps: Optional[int] = Field(
        None, ge = 1, le = 120, description = "Playback frame rate (default per model)."
    )
    last_frame: Optional[str] = Field(
        None,
        # A 32 MB image, the input_reference limit, as a base64 data URL.
        max_length = VIDEO_INPUT_REFERENCE_JSON_MAX_BYTES,
        description = "Image the clip ends on (MiniMax-H3 only, status supports_last_frame): a "
        'file upload, a base64 data URL or {"image_url": ...}.',
    )
    reference_images: Optional[list[str]] = Field(
        None,
        max_length = 9,
        description = "Subject, style or scene references, at most 9, in the shapes "
        "input_reference takes. The prompt calls them <Picture 1>, <Picture 2>, ... in order. "
        "One request body carries about 32 MB of images and audio in all.",
    )
    reference_audios: Optional[list[Union[str, AudioSourceRef]]] = Field(
        None,
        max_length = 3,
        description = "Voice or score references, at most 3 of up to 24 MB each: a file upload, a "
        'base64 data URL or an Unsloth Studio audio id {"input_id" | "clip_id" | "voice_id": ...}. '
        "The prompt calls them <Audio 1>, <Audio 2>, ... in order. They need a reference image "
        "to go with. Inline audio counts toward the request body's 32 MB, so send larger or "
        "several clips as ids (POST /v1/audio/inputs stores one).",
    )

    @field_validator("model", "seconds", "size", mode = "before")
    @classmethod
    def _blank_means_default(cls, value, info):
        if value is None:
            return None
        text = str(value).strip()
        # "auto" is OpenAI's omitted duration, so it must not count against num_frames.
        if info.field_name == "seconds" and text.lower() == "auto":
            return None
        return text or None

    @field_validator(
        "seed",
        "negative_prompt",
        "steps",
        "guidance",
        "num_frames",
        "fps",
        "last_frame",
        mode = "before",
    )
    @classmethod
    def _blank_means_omitted(cls, value):
        # A multipart form sends an empty field as "".
        if isinstance(value, str) and not value.strip():
            return None
        return value

    @field_validator("reference_images", "reference_audios")
    @classmethod
    def _bounded_references(cls, value, info):
        # Bound each item like last_frame, so a list cannot buffer what one field may not:
        # a 32 MB image or a 24 MB audio clip, base64-encoded.
        image = info.field_name == "reference_images"
        cap = VIDEO_INPUT_REFERENCE_JSON_MAX_BYTES if image else _VIDEO_REFERENCE_AUDIO_MAX_CHARS
        for item in value or []:
            if isinstance(item, str) and len(item) > cap:
                raise ValueError(
                    "each reference image must be at most 32 MB"
                    if image
                    else "each reference audio must be at most 24 MB"
                )
        return value

    @model_validator(mode = "after")
    def _one_length_and_one_conditioning(self) -> "VideoJobCreateRequest":
        if self.seconds is not None and self.num_frames is not None:
            raise ValueError("Send seconds or num_frames, not both.")
        if self.last_frame and (self.reference_images or self.reference_audios):
            raise ValueError(
                "keyframes and references cannot be combined: MiniMax-H3 runs them against "
                "different denoiser partitions"
            )
        return self


class VideoJobError(BaseModel):
    code: str
    message: str


class VideoJob(BaseModel):
    id: str
    object: Literal["video"] = "video"
    model: str
    status: Literal["queued", "in_progress", "completed", "failed"]
    progress: int = Field(0, ge = 0, le = 100)
    created_at: int
    completed_at: Optional[int] = None
    expires_at: Optional[int] = None
    prompt: Optional[str] = None
    size: str
    seconds: str
    # Unsloth Studio extension: the seed this take used; null on jobs from before seeds were kept.
    seed: Optional[int] = None
    error: Optional[VideoJobError] = None
    remixed_from_video_id: Optional[str] = None


class VideoJobListResponse(BaseModel):
    object: Literal["list"] = "list"
    data: List[VideoJob] = Field(default_factory = list)
    first_id: Optional[str] = None
    last_id: Optional[str] = None
    has_more: bool = False


class VideoJobDeleteResponse(BaseModel):
    id: str
    object: Literal["video.deleted"] = "video.deleted"
    deleted: bool = True


class VideoLoadRequest(BaseModel):
    """Request to load a local text-to-video checkpoint."""

    load_token: Optional[str] = Field(
        None,
        max_length = 128,
        description = "Opaque id the client picks for this load; POST /video/unload with "
        "expected_load_id set to it unloads this load only, and cancels it if it has not started yet.",
    )
    model_path: str = Field(..., description = "Video repo id or local path")
    display_repo_id: Optional[str] = Field(None, description = "Logical Hub id of a local snapshot")
    _blank_display_id = field_validator("display_repo_id")(lambda v: (v or "").strip() or None)
    # The same inventory handle the picker was shown; see `resolve_inventory_handle`.
    _resolve_the_handle = field_validator("model_path")(resolve_inventory_handle)
    gguf_filename: Optional[str] = Field(
        None,
        description = "The chosen single-file checkpoint (GGUF or safetensors) inside "
        "model_path. Required for the gguf / single_file kinds; omit for a full pipeline.",
    )
    model_kind: Optional[Literal["gguf", "single_file", "pipeline"]] = Field(
        None,
        description = "How to load the model (null = auto-detect from gguf_filename): gguf "
        "(single-file GGUF transformer, dequantised on-device), single_file (single-file "
        "safetensors transformer, e.g. fp8), or pipeline (a full diffusers repo via "
        "from_pretrained). A single_file .safetensors loads from any repo; pipeline loads are "
        "restricted to unsloth/* repos, the official family base repos, or a local path.",
    )
    base_repo: Optional[str] = Field(
        None,
        description = "Companion diffusers repo for VAE/text-encoders (default: family base)",
    )
    # As on the diffusion request above: referenced out, so resolved back in.
    _resolve_the_base_handle = field_validator("base_repo")(resolve_inventory_handle)
    family_override: Optional[str] = Field(
        None, description = "Force a family when it can't be inferred from the repo id"
    )
    hf_token: Optional[str] = Field(None, description = "HuggingFace token for gated repos")
    memory_mode: Optional[Literal["auto", "fast", "balanced", "low_vram"]] = Field(
        None,
        description = "Memory policy: auto (measured), fast (resident), balanced "
        "(stream the transformer, near-resident speed, moderate VRAM cut), low_vram "
        "(offload every component, lowest VRAM, slower).",
    )
    allow_oversized_load: bool = Field(
        False,
        description = "Attempt the load even when the unified-memory check (Apple Silicon, integrated "
        "GPUs) estimates its weights will not fit. The check stays on by default; an oversized load "
        "can exhaust memory, swap heavily, stop the server or make the computer unresponsive. Same "
        "effect as the server's UNSLOTH_DIFFUSION_ALLOW_OVERSIZED_LOAD=1, for this load only.",
    )
    speed_mode: Optional[Literal["off", "eager", "default", "max"]] = Field(
        None,
        description = "Opt-in speed optims (default off -> bit-identical output): "
        "eager (channels_last + cudnn + attention + fused norm patches, NO torch.compile), "
        "default (also regional torch.compile where eligible), "
        "max (also TF32 + fused QKV). GGUF video loads default to the near-lossless "
        "compile profile.",
    )
    attention_backend: Optional[
        Literal[
            "auto",
            "native",
            "sdpa",
            "cudnn",
            "flash",
            "flash2",
            "flash3",
            "flash4",
            "sage",
            "xformers",
            "aiter",
        ]
    ] = Field(
        None,
        description = "Attention kernel via the diffusers dispatcher. auto picks the best "
        "exact backend for the device (cuDNN fused attention on NVIDIA when a speed profile "
        "is active; native SDPA elsewhere and when speed=off). native (alias sdpa) forces "
        "default SDPA; cudnn/flash/flash3/flash4 are exact (kernel/arch-gated); sage is INT8 "
        "attention; xformers/aiter are memory-efficient (NVIDIA) / AMD ROCm. An unavailable "
        "kernel falls back to the default.",
    )
    transformer_cache: Optional[Literal["off", "fbcache", "static"]] = Field(
        None,
        description = "Step caching. fbcache = First-Block-Cache: reuse the transformer tail "
        "across denoise steps when the first block's residual barely changes. Unset = auto: "
        "engages only on speed_mode=max with a 20+ step schedule, otherwise uncached. An "
        "explicit fbcache engages on every speed tier; incompatible models run uncached. "
        "static = skip denoiser calls on a fixed schedule (first 20% and last 10% of the steps "
        "always run, every other middle step is extrapolated from the last two computed "
        "outputs; 12+ steps only), which keeps compile fullgraph and the CUDA graph. "
        "Single-denoiser video-only families: a two-expert MoE (Wan2.2 A14B), a joint "
        "audio + video denoiser (LTX-2) and the MiniMax-H3 modular workflow run uncached. "
        "Never picked automatically.",
    )
    transformer_cache_threshold: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 1.0,
        description = "FBCache residual threshold (higher = skips more steps = faster, lower "
        "quality). null auto-picks the family default. Ignored by static.",
    )
    transformer_quant: Optional[Literal["auto", "none", "off", "int8", "fp8", "nvfp4", "mxfp8"]] = (
        Field(
            None,
            description = "Quantise the dense DiT(s) on a full-pipeline load. On a diffusers "
            "pipeline load the dense bf16 transformer(s) are torchao-quantised in place onto "
            "the low-precision tensor cores (int8 first on every tier, then fp8 on sm_89+), which is "
            "faster than running dense bf16. For a dual-expert MoE family (Wan2.2-A14B) BOTH "
            "experts are quantised with the same scheme. null/none/off keeps the DiT(s) at "
            "their loaded precision; an explicit scheme forces it. Needs CUDA + bf16; ignored "
            "on gguf/single_file loads (they carry their own precision). Mirrors the image "
            "backend's transformer_quant field.",
        )
    )
    text_encoder_quant: Optional[
        Literal["auto", "none", "off", "fp8", "fp8_dynamic", "int8", "nvfp4"]
    ] = Field(
        None,
        description = "Quantise the dense companion text encoder (Gemma3 / UMT5 / Qwen2.5-VL), "
        "which loads bf16 from the base repo regardless of how the DiT was sourced and is often "
        "the largest resident component. fp8 = diffusers layerwise casting (memory only, cc >= "
        "8.9); fp8_dynamic = torchao per-row fp8 COMPUTE on the tensor cores (cc >= 8.9); int8 = "
        "torchao int8 COMPUTE with per-family keep-bf16 selection (cc >= 8.0; falls back to fp8 "
        "for a family without a measured schedule); nvfp4 = torchao 4-bit weight-only, "
        "dequantised to bf16 per forward (cc >= 8.0). null/auto leaves the choice to the backend, "
        "which takes the hosted pre-quantized encoder matching ComfyUI's template for the family: "
        "fp8 for Wan, LTX-2 / LTX-2.3 and HunyuanVideo-1.5, int8 ConvRot for LTX-2.5, and the "
        "hosted quantized conditioner on MiniMax-H3; a host that cannot run it keeps the dense "
        "encoder. none/off always keeps the released bf16 encoder. Mirrors the image backend's "
        "field.",
    )

    h3_task: Optional[Literal["fl2va", "ref2va"]] = Field(
        None,
        description = "Which MiniMax-H3 denoiser partition to bring up: fl2va (text-to-video "
        "and first/last-frame video, the default) or ref2va (omni-reference video). They are "
        "separate ~62 GB partitions, so a load serves one of them. Ignored for a GGUF pick, "
        "whose filename already names the partition; rejected if it contradicts that filename.",
    )
    gpu_ids: Optional[List[int]] = Field(
        None,
        description = "CUDA / ROCm physical indices this load may use, or null for automatic. "
        "Neither engine shards a video checkpoint, so a selection of several cards resolves to "
        "the one with the most free VRAM. Refused with a 400 when an index does not exist here; "
        "ignored on XPU / MPS / CPU, which have no applicator for a physical index. Mirrors the "
        "image backend's field.",
    )

    @field_validator("attention_backend", mode = "before")
    @classmethod
    def _normalize_attention_backend(cls, value):
        # The dispatcher accepts case/whitespace variants, but the Literal above is validated before any normaliser runs, so fold it here.
        return value.strip().lower() if isinstance(value, str) else value


class VideoReferenceVideo(BaseModel):
    """One reference video, with the soundtrack MiniMax-H3 conditions on alongside it."""

    video: str = Field(
        ...,
        max_length = 96 * 1024 * 1024,
        description = "Base64/data-URL video file, 2 to 15 seconds. Resampled onto the model's "
        "24 fps and onto the canvas its own aspect ratio resolves to.",
    )
    audio: Optional[str] = Field(
        None,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL soundtrack for THIS video. Omitted takes the track "
        "embedded in the file, if it has one; sent explicitly it replaces it.",
    )
    trim_start_seconds: Optional[float] = Field(
        None, ge = 0.0, description = "Inclusive start of an explicit video trim, in seconds."
    )
    trim_end_seconds: Optional[float] = Field(
        None, gt = 0.0, description = "Exclusive end of an explicit video trim, in seconds."
    )

    @model_validator(mode = "after")
    def _trim_is_a_complete_h3_interval(self) -> "VideoReferenceVideo":
        from core.inference.video_minimax_h3 import validate_h3_reference_trim
        validate_h3_reference_trim(self.trim_start_seconds, self.trim_end_seconds)
        return self


class VideoGenerateRequest(BaseModel):
    """Request to generate one clip from the loaded video model."""

    prompt: str = Field(..., min_length = 1, description = "Text prompt")
    negative_prompt: Optional[str] = Field(
        None, description = "What to avoid (if the model supports it)"
    )
    model: Optional[str] = Field(
        None,
        description = "Video model to generate on. Only read when media auto-switch is on, "
        "where a downloaded model that is not the resident one is loaded first; omit to use "
        "whatever is loaded. The Video page never sends it.",
    )
    live_preview: Optional[bool] = Field(
        None,
        description = "Stream a small live preview of the first frame while the clip denoises "
        "(generate-progress 'preview'). Null = the server default (on unless UNSLOTH_DIFFUSION_PREVIEW=0).",
    )
    # Width/height/num_frames/fps default per loaded family, so they are optional here. These bounds
    # stay a COARSE family-agnostic outer guard: the enforced rule is the LOADED family's own
    # (sizes near its presets and the k * frame_step + frame_offset lattice), which the route checks with
    # validate_video_request_shape. With no model loaded there is no family to judge against.
    width: Optional[int] = Field(
        None,
        ge = 32,
        le = 2048,
        description = "Frame width in pixels (a multiple of the loaded family's resolution_multiple near its presets)",
    )
    height: Optional[int] = Field(
        None,
        ge = 32,
        le = 2048,
        description = "Frame height in pixels (see width)",
    )
    num_frames: Optional[int] = Field(
        None,
        ge = 1,
        le = MAX_VIDEO_NUM_FRAMES,
        description = "Number of frames; must lie on the family's temporal lattice (k * frame_step + frame_offset)",
    )
    fps: Optional[int] = Field(
        None, ge = 1, le = 120, description = "Playback frame rate (default per family)"
    )
    steps: Optional[int] = Field(
        None, ge = 1, le = 100, description = "Number of denoising steps (default per model)"
    )
    guidance: Optional[float] = Field(
        None, ge = 0.0, le = 20.0, description = "Classifier-free guidance scale (default per model)"
    )
    guidance_2: Optional[float] = Field(
        None,
        ge = 0.0,
        le = 20.0,
        description = "Low-noise-stage guidance scale for a dual-expert MoE family (Wan2.2-A14B): "
        "the guidance the second transformer uses on the low-noise denoise steps. null lets the "
        "pipeline default it to the main guidance. Ignored by single-DiT families (their pipeline "
        "signature has no second guidance kwarg).",
    )
    # le = 2**53-1: seeds round-trip through JSON recipes, where JavaScript rounds larger integers and a restored recipe would differ.
    seed: Optional[int] = Field(
        None, ge = 0, le = 2**53 - 1, description = "Seed for reproducibility (random if omitted)"
    )
    # Bounded so one request cannot buffer a multi-GB payload; ~32 MiB fits a 4096px source.
    first_frame: Optional[str] = Field(
        None,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL image the clip starts from (image-to-video). With width "
        "and height omitted it picks the canvas: MiniMax-H3 matches its aspect and stretches it "
        "on; Wan2.2-TI2V-5B and LTX-2 take the resolution preset nearest its aspect and "
        "centre-crop it on. Omit for text-to-video. Rejected by a family that takes no first "
        "frame (status supports_first_frame).",
    )
    last_frame: Optional[str] = Field(
        None,
        max_length = 32 * 1024 * 1024,
        description = "Base64/data-URL image the clip ends on (MiniMax-H3 only, status "
        "supports_last_frame). Valid on its own (generate up TO a frame) or with first_frame "
        "(first-and-last-frame video), in which case it follows the first and is centre "
        "cover-cropped onto the canvas.",
    )

    continuation_video: Optional[str] = Field(
        None,
        max_length = 96 * 1024 * 1024,
        description = "Base64/data-URL video to continue (Cosmos3-Nano only, status "
        "supports_video_continuation): the clip keeps 5 frames from one end of it and generates "
        "what follows. At most 15 seconds; frames are resampled onto fps and centre-cropped to "
        "the canvas aspect. With width and height omitted the canvas is the preset nearest the "
        "clip's aspect. Cannot be combined with keyframes or references.",
    )
    continuation_keep: Optional[Literal["last", "first"]] = Field(
        None,
        description = "Which end of continuation_video to keep: last (default) continues the "
        "clip from its final frames; first keeps its opening frames and generates on from there.",
    )

    # Separate lists preserve the model's image, video, then audio packing order.
    reference_images: Optional[list[str]] = Field(
        None,
        max_length = 9,
        description = "Subject / style / scene reference images (base64/data-URL), at most 9. "
        "The prompt refers to them as <Picture 1>, <Picture 2>, ... in this order.",
    )
    reference_videos: Optional[list[VideoReferenceVideo]] = Field(
        None,
        max_length = 3,
        description = "Motion / camera reference videos, at most 3. The prompt refers to them "
        "as <Video 1>, <Video 2>, ... in this order.",
    )
    reference_audios: Optional[list[str]] = Field(
        None,
        max_length = 3,
        description = "Standalone reference audio (base64/data-URL), at most 3, for voice or "
        "score. The prompt refers to them as <Audio 1>, <Audio 2>, ... in this order. Audio "
        "cannot be the only kind of reference a request carries.",
    )
    flow_shift: Optional[float] = Field(
        None,
        gt = 0.0,
        le = 100.0,
        description = "Sigma shift of the video schedule (MiniMax-H3 ships 12.0). Higher spends "
        "more of the schedule at high noise, which reads as more motion and less detail. null "
        "keeps the released value.",
    )
    audio_flow_shift: Optional[float] = Field(
        None,
        gt = 0.0,
        le = 100.0,
        description = "Sigma shift of the audio schedule (MiniMax-H3 ships 3.0). Needs the "
        "Diffusers engine: stable-diffusion.cpp derives the audio schedule against a hardcoded "
        "3.0, so it has no flag to map this onto. null keeps the released value.",
    )
    reference_image_size: Optional[Literal["match", "max"]] = Field(
        None,
        description = "How reference images are sized: match (default) scales each down to the "
        "generation's pixel area; max uses the reference pipeline's 2048px short edge for "
        "stronger identity fidelity, several times slower. max needs the Diffusers engine -- "
        "stable-diffusion.cpp rescales every reference to the generation area regardless.",
    )

    @field_validator("reference_images", "reference_audios")
    @classmethod
    def _bounded_reference_media(cls, value: Optional[list[str]]) -> Optional[list[str]]:
        # Bound each item like first_frame, so a list cannot buffer what one field may not.
        if value is not None:
            for item in value:
                if len(item) > 32 * 1024 * 1024:
                    raise ValueError("each reference must be at most 32 MiB (base64)")
        return value

    @model_validator(mode = "after")
    def _references_fit_the_models_budget(self) -> "VideoGenerateRequest":
        images = self.reference_images or []
        videos = self.reference_videos or []
        audios = self.reference_audios or []
        total = len(images) + len(videos) + len(audios)
        if total > 12:
            raise ValueError(f"MiniMax-H3 takes at most 12 references in total, got {total}")
        # Standalone audio must accompany an image or video reference.
        if audios and not images and not videos:
            raise ValueError(
                "reference audio needs at least one reference image or video to go with"
            )
        if self.continuation_video and (
            images or videos or audios or self.first_frame or self.last_frame
        ):
            raise ValueError(
                "A clip to continue cannot be combined with a start frame, end frame or references."
            )
        if self.continuation_keep is not None and not self.continuation_video:
            raise ValueError("continuation_keep needs a continuation_video.")
        if (images or videos or audios) and (self.first_frame or self.last_frame):
            raise ValueError(
                "keyframes and references cannot be combined: MiniMax-H3 runs them against "
                "different denoiser partitions"
            )
        return self

    @model_validator(mode = "after")
    def _keyframe_canvas_needs_both_axes(self) -> "VideoGenerateRequest":
        # Keyframe only: a half-specified canvas is silently replaced by the source aspect; other families resolve the missing axis from a preset.
        if not (self.first_frame or self.last_frame):
            return self
        if (self.width is None) != (self.height is None):
            raise ValueError("width and height must be sent together, or both omitted")
        return self


class GalleryVideo(BaseModel):
    """A persisted clip's full generation recipe (the JSON sidecar of the MP4)."""

    id: str = Field(..., description = "Stable id (the on-disk filename stem)")
    url: str = Field(..., description = "Relative URL to fetch the MP4 bytes")
    prompt: str = Field(..., description = "Prompt used")
    negative_prompt: Optional[str] = Field(None, description = "Negative prompt, if any")
    width: int = Field(..., description = "Frame width")
    height: int = Field(..., description = "Frame height")
    num_frames: int = Field(..., description = "Number of frames")
    fps: int = Field(..., description = "Playback frame rate")
    duration_s: float = Field(..., description = "Clip duration in seconds")
    steps: int = Field(..., description = "Denoising steps")
    guidance: float = Field(..., description = "Guidance scale")
    guidance_2: Optional[float] = Field(
        None, description = "Second-expert guidance scale (dual-expert families), if sent"
    )
    flow_shift: Optional[float] = Field(
        None, description = "Video-schedule sigma shift used, for families that expose it"
    )
    audio_flow_shift: Optional[float] = Field(
        None, description = "Audio-schedule sigma shift used, for families that expose it"
    )
    seed: int = Field(..., description = "Seed used")
    has_audio: bool = Field(False, description = "Whether the MP4 carries an audio track")
    conditioning: Optional[str] = Field(
        None,
        description = "How the clip was conditioned, in MiniMax-H3's own task names: t2va "
        "(prompt only), i2va (first frame), l2va (last frame) or fl2va (both). Absent on "
        "clips saved before keyframes existed.",
    )
    model: Optional[str] = Field(None, description = "Model repo id that produced it")
    # All optional so old sidecars still list; the repo id alone omits the checkpoint and precision.
    model_kind: Optional[str] = Field(
        None, description = "How the model was loaded: gguf, single_file or pipeline"
    )
    gguf_filename: Optional[str] = Field(
        None,
        description = "The single-file checkpoint the load committed, for a gguf/single_file load",
    )
    transformer_quant: Optional[str] = Field(
        None,
        description = "Dense DiT quantisation actually engaged (int8/fp8/nvfp4/mxfp8), or null "
        "when the DiT(s) ran at their loaded bf16 precision",
    )
    text_encoder_quant: Optional[str] = Field(
        None,
        description = "Text-encoder quantisation actually engaged (fp8/fp8_dynamic/int8/nvfp4), "
        "or null when the dense bf16 encoder ran",
    )
    memory_mode: Optional[str] = Field(
        None, description = "Memory mode the load ran under: auto | fast | balanced | low_vram"
    )
    offload_policy: Optional[str] = Field(
        None, description = "Offload policy actually engaged: none | group | model | sequential"
    )
    created_at: str = Field(..., description = "Creation time (ISO 8601 timestamp)")
    # Library state, not recipe: stored beside the clip, so older sidecars simply read as unset.
    pinned: bool = Field(False, description = "Pinned to the front of the gallery")
    archived: bool = Field(False, description = "Moved to the archived shelf, hidden from the strip")
    order_at: Optional[float] = Field(
        None,
        description = "Unpinned sort key (epoch-second scale): the manual key once dragged, else the file mtime",
    )


class VideoGenerateResponse(BaseModel):
    """Acknowledgement that a generation was accepted and started.

    Generation runs as a background job (a clip takes minutes, and secure mode's
    tunnel caps the origin response window near 100 seconds, so the POST cannot
    span it). The saved gallery record arrives via GET /video/generate-progress
    when its phase reaches "completed"."""

    status: Literal["started"] = Field(
        "started", description = "Discriminator: the generation job was started"
    )
    video: Optional[GalleryVideo] = Field(
        None,
        description = "Always null (kept for response-shape compatibility); the saved "
        "record is delivered by generate-progress on completion",
    )


class VideoGalleryListResponse(BaseModel):
    """A newest-first page of persisted videos, for infinite scroll."""

    videos: list[GalleryVideo] = Field(default_factory = list)
    has_more: bool = Field(False, description = "Whether older videos remain past this page")


class VideoGenerateProgressResponse(BaseModel):
    """Live progress for an in-flight video generation, plus the terminal outcome
    of the background job POST /video/generate started."""

    active: bool = Field(False, description = "Whether a generation is running")
    phase: Optional[str] = Field(
        None,
        description = "Current phase: queued | encode | denoise | decode | export | completed | failed | null",
    )
    step: int = Field(0, description = "Denoising steps completed so far")
    total: int = Field(0, description = "Total denoising steps for this run")
    # Image-endpoint-compatible aliases so one poller works against both APIs.
    total_steps: int = Field(0, description = "Total denoising steps (alias of total)")
    fraction: float = Field(0.0, description = "step / total, clamped to [0,1]")
    eta_seconds: Optional[float] = Field(None, description = "Estimated seconds remaining")
    preview: Optional[str] = Field(
        None,
        description = "Live latent preview of the first frame being denoised, as a JPEG data URL",
    )
    preview_seq: int = Field(0, description = "Moves each time a new preview is published")
    video: Optional[GalleryVideo] = Field(
        None, description = "Saved gallery record when phase is 'completed'"
    )
    error: Optional[str] = Field(
        None, description = "Client-safe failure detail when phase is 'failed'"
    )


class VideoLoadProgressResponse(BaseModel):
    """Download/finalize progress for an in-flight video load."""

    phase: Optional[
        Literal["downloading", "finalizing", "saving_chat_context", "ready", "error"]
    ] = Field(None, description = "Load phase; null when idle")
    downloaded_bytes: int = Field(0, description = "Bytes present in the HF cache so far")
    expected_bytes: Optional[int] = Field(
        None, description = "Estimated total bytes to download (null = unknown)"
    )
    error: Optional[str] = Field(None, description = "Failure message when phase is 'error'")
    error_code: Optional[str] = Field(
        None,
        description = "Stable code for error: 'unified-memory-load' when the unified-memory check refused "
        "the load (retry with allow_oversized_load to attempt it anyway); null otherwise.",
    )


class VideoGenerationDefaults(BaseModel):
    """Per-family generation defaults + shape constraints for the loaded video model."""

    steps: int = Field(..., description = "Default denoising steps")
    guidance: float = Field(..., description = "Default guidance scale")
    num_frames: int = Field(..., description = "Default frame count")
    fps: int = Field(..., description = "Default playback frame rate")
    fps_range: Optional[list[int]] = Field(
        None,
        description = "Inclusive [min, max] frame rate a request may pick, or null (see fps_choices)",
    )
    fps_choices: list[int] = Field(
        default_factory = list,
        description = "Frame rates a request may pick; with neither this nor fps_range the rate is fixed",
    )
    min_num_frames: Optional[int] = Field(None, description = "Smallest frame count the family takes")
    max_num_frames: Optional[int] = Field(
        None, description = "Largest frame count the family takes, or null for no family cap"
    )
    frame_step: int = Field(..., description = "Temporal lattice stride")
    frame_offset: int = Field(
        1, description = "Temporal lattice offset: valid counts are k * frame_step + frame_offset"
    )
    duration_presets: list[float] = Field(
        default_factory = list, description = "Clip durations in seconds the UI offers"
    )
    resolution_multiple: int = Field(..., description = "Width/height must be divisible by this")
    resolution_presets: list[list[int]] = Field(
        default_factory = list, description = "(width, height) presets the UI offers, default first"
    )
    custom_size_min_pixels: Optional[int] = Field(
        None,
        description = "Smallest width * height accepted off the presets, or null when only the snap applies",
    )
    custom_size_max_pixels: Optional[int] = Field(
        None,
        description = "Largest width * height accepted off the presets (see custom_size_min_pixels)",
    )
    custom_size_max_aspect: Optional[float] = Field(
        None,
        description = "Widest long:short ratio accepted off the presets (see custom_size_min_pixels)",
    )
    canvas_short_edge: Optional[int] = Field(
        None,
        description = "Short edge a source-derived canvas aims for, or null when the family "
        "has no keyframe canvas rule. With canvas_max_pixels and resolution_multiple this is "
        "the whole rule: short edge, then cap the area, then round both axes.",
    )
    canvas_max_pixels: Optional[int] = Field(
        None, description = "Area budget of a source-derived canvas, or null (see canvas_short_edge)"
    )
    canvas_from_presets: bool = Field(
        False,
        description = "True when a first frame without width/height takes the resolution preset "
        "nearest its aspect ratio (a declared image-to-video pipeline), instead of the "
        "canvas_short_edge rule",
    )
    flow_shift: Optional[float] = Field(
        None,
        description = "Released video-schedule sigma shift, or null when the family does not "
        "expose the control",
    )
    audio_flow_shift: Optional[float] = Field(
        None, description = "Released audio-schedule sigma shift, or null (see flow_shift)"
    )
    supports_audio_flow_shift: bool = Field(
        False,
        description = "Whether the ACTIVE engine can honour audio_flow_shift; false on "
        "stable-diffusion.cpp, which pins the audio schedule at its released value",
    )


class VideoStatusResponse(BaseModel):
    """Current video backend state."""

    load_id: Optional[str] = Field(
        None,
        description = "The load_token of the load in flight or resident (one Studio made up for a "
        "load sent without one); POST unload with expected_load_id set to it unloads that load only.",
    )
    resident_load_id: Optional[str] = Field(
        None,
        description = "The load_token of the model resident in the slot, also while another load is "
        "in flight over it (equal to load_id when none is); a failed replacement leaves this model loaded.",
    )
    resident_mib: Optional[int] = Field(
        None,
        description = "Best-effort memory the resident model holds, in MiB; null when unknown.",
    )
    multi_gpu: Optional[Dict[str, Any]] = Field(
        None,
        description = "Multi-GPU placement (component -> card, primary, secondary) and CFG-parallel state (armed, "
        "call counts, or why it declined); null when the load had one card to use. A multi-card load that kept "
        "everything on its primary card reports why it declined.",
    )
    graph_engagement: Optional[Dict[str, Any]] = Field(
        None,
        description = "Compile / CUDA-graph engagement counters: this load's graph captures, replays and ungraphed "
        "denoiser calls (whole-step, per block, per-card segments, and the per-block graphs a whole-step graph falls "
        "back to), and the process's dynamo frame and graph-break totals; null when nothing is loaded.",
    )
    loaded: bool = Field(False, description = "Whether a video model is loaded")
    evicted: List[str] = Field(
        default_factory = list,
        description = "Models this load unloaded to make room. Filled only on the load answer.",
    )
    evicted_slots: List[EvictedSlot] = Field(
        default_factory = list,
        description = "The same models as evicted, each with its kind and public model id.",
    )
    repo_id: Optional[str] = Field(None, description = "Loaded repo id or local path")
    display_repo_id: Optional[str] = Field(None, description = "Logical Hub id of a local snapshot")
    family: Optional[str] = Field(None, description = "Detected video family")
    supported_families: List[str] = Field(default_factory = list, description = "Loadable families")
    modular_families: List[str] = Field(default_factory = list, description = "Modular families")
    base_repo: Optional[str] = Field(None, description = "Companion diffusers base repo")
    device: Optional[str] = Field(None, description = "Device the pipeline is on")
    dtype: Optional[str] = Field(None, description = "Compute dtype")
    model_kind: Optional[str] = Field(
        None, description = "Resolved load kind: gguf | single_file | pipeline (gates GGUF-only UI)"
    )
    engine: Optional[str] = Field(None, description = "Active video engine: diffusers | sd_cpp")
    gguf_variant: Optional[str] = Field(
        None, description = "Selected GGUF quantisation variant (for example Q8_0)"
    )
    offload_policy: Optional[str] = Field(
        None, description = "Resolved offload policy: none | group | model | sequential"
    )
    vae_tiling: bool = Field(False, description = "Whether VAE tiling is enabled")
    memory_mode: Optional[str] = Field(None, description = "Requested memory mode")
    speed_mode: Optional[str] = Field(None, description = "Requested speed mode")
    speed_optims: list[str] = Field(
        default_factory = list, description = "Speed optimisations actually engaged"
    )
    attention_backend: Optional[str] = Field(
        None,
        description = "Attention backend engaged via the diffusers dispatcher (e.g. "
        "_native_cudnn), or null for the default SDPA",
    )
    sd_cpp_cudnn_attention: Optional[str] = Field(
        None,
        description = "MiniMax-H3 on stable-diffusion.cpp only: cuDNN fused attention state. ready (a "
        "CUDA 12 cuDNN is named to sd.cpp, no render yet) | engaged | fallback (sd.cpp kept its own "
        "kernels) | unavailable (no CUDA 12 cuDNN could be provided) | off (switched off) | null "
        "(not applicable: the build has no cuDNN attention, or the card, platform or engine is not "
        "eligible).",
    )
    sd_cpp_cudnn_reason: Optional[str] = Field(
        None, description = "Why sd_cpp_cudnn_attention is not engaged or ready, when known"
    )
    transformer_cache: Optional[str] = Field(
        None, description = "Step cache engaged: fbcache | static | null"
    )
    transformer_cache_stats: Optional[dict] = Field(
        None,
        description = "Static step skip only: the schedule (mode, head, tail, every, "
        "planned_skips) and the denoiser call counts (calls, computed, skipped) of the clip in "
        "flight, else of the last one. null for any other step cache.",
    )
    transformer_quant: Optional[str] = Field(
        None,
        description = "Dense transformer quant engaged on a pipeline load: int8 | fp8 | nvfp4 | "
        "mxfp8 | null (null = the DiT(s) run at their loaded bf16 precision). For a dual-expert "
        "MoE family both experts share the reported scheme.",
    )
    transformer_quant_backend: Optional[str] = Field(
        None,
        description = "Which NVFP4 kernel path the loaded DiT(s) run: flashinfer | torchao | null "
        "(null for every scheme but nvfp4).",
    )
    transformer_quant_backend_reason: Optional[str] = Field(
        None,
        description = "Why flashinfer is not serving an NVFP4 load that runs torchao: the on-demand "
        "install was refused (offline, opt-out, ineligible host) or failed and was rolled back. "
        "null when the backend is flashinfer, the scheme is not nvfp4, or no reason was recorded.",
    )
    text_encoder_quant: Optional[str] = Field(
        None,
        description = "Text-encoder quant engaged: fp8 | fp8_dynamic | int8 | nvfp4 | null "
        "(null = the dense bf16 encoder is loaded). An int8 request without a per-family "
        "keep-bf16 schedule is reported as the fp8 it fell back to.",
    )
    has_audio: bool = Field(
        False, description = "Whether the loaded family produces a synchronized audio track"
    )
    supports_keyframes: bool = Field(
        False,
        description = "Whether the LOADED checkpoint takes first/last-frame conditioning images "
        "(gates the image-to-video controls)",
    )
    supports_first_frame: bool = Field(
        False,
        description = "Whether the LOADED checkpoint takes a first_frame (image-to-video): "
        "MiniMax-H3 keyframes, or a family's declared image-to-video pipeline (Wan2.2-TI2V-5B, "
        "LTX-2 / LTX-2.3) built over the loaded components",
    )
    supports_last_frame: bool = Field(
        False,
        description = "Whether the LOADED checkpoint takes a last_frame. Only MiniMax-H3's "
        "keyframe partition does; the image-to-video pipelines condition on a first frame alone",
    )
    supports_references: bool = Field(
        False,
        description = "Whether the LOADED checkpoint takes reference images / videos / audio "
        "(gates the reference-to-video controls). Never true at the same time as "
        "supports_keyframes: MiniMax-H3 serves the two from different denoiser partitions.",
    )
    supports_video_continuation: bool = Field(
        False,
        description = "Whether the LOADED checkpoint takes continuation_video (Cosmos3-Nano "
        "only): it keeps frames from one end of a clip and generates what happens next",
    )
    h3_task: Optional[str] = Field(
        None,
        description = "The MiniMax-H3 denoiser partition that is up: fl2va | ref2va, or null "
        "for any other family",
    )
    supports_cfg: bool = Field(
        True, description = "Whether guidance and negative prompts apply to this family"
    )
    defaults: Optional[VideoGenerationDefaults] = Field(
        None, description = "Per-family generation defaults + shape constraints; null when unloaded"
    )
    prompt_hint: Optional[str] = Field(
        None,
        description = "How the loaded model reads prompts, in one or two sentences; null when "
        "it has no tip.",
    )
    # Additive per-control provenance, same shape as the diffusion status; null when nothing is loaded.
    resolved: Optional[Dict[str, DiffusionResolvedControl]] = Field(
        None,
        description = "Per-control resolved value + provenance (source auto|explicit + reason), "
        "keyed by Advanced control name; null when unloaded or unavailable.",
    )


class VideoLoadUnloadedResponse(VideoStatusResponse):
    """POST /video/unload with expected_load_id that unloaded that load: the state it left behind."""

    unloaded: Literal[True] = Field(..., description = "Always true: that load was unloaded")
    outcome: Literal["unloaded"] = Field(..., description = "Always unloaded")


# What POST /video/unload answers: the state it left behind without expected_load_id, and with it
# either that, marked unloaded, or the outcome alone.
VideoUnloadResponse = Union[VideoLoadUnloadedResponse, MediaUnloadOutcome, VideoStatusResponse]