space_config.py

"""User-editable Hugging Face Space configuration for the LTX-2.5 app.

This file is the supported customization surface for forks. Runtime invariants,
ZeroGPU quota logic, quantization safety checks, UUID isolation, and fallback
implementation intentionally remain outside this customization surface in
``app.py`` and the ``ltx/`` runtime modules.

Model/component overrides are best-effort. If an override cannot be loaded or
integrated, the app logs the failure and falls back to the corresponding base
component. If the configured base model itself is unusable, the app falls back
to the pinned canonical LTX-2.5 Diffusers repository. The effective runtime
sources are always exposed in the UI and diagnostics; fallback is never silent.
"""

# -----------------------------------------------------------------------------
# Base model
# -----------------------------------------------------------------------------

# Must provide an LTX-2/LTX-2.5 Diffusers-compatible repository layout expected
# by this Space. Arbitrary checkpoints are not converted automatically.
MODEL_REPO_ID = "Lightricks/LTX-2.5-Diffusers"
MODEL_REVISION = "549f18015d588ce728aad02aebff9212d94f598e"

# "nf4_auto":
#   - unquantized transformer/text encoder -> quantize to NF4 on load
#   - prequantized BitsAndBytes NF4 -> load as-is (no double quantization)
#   - other prequantized formats -> reject that base/override and fall back
#
# "repo_native":
#   - trust the repository's own quantization metadata / precision. This may use
#     substantially more memory and is intentionally not the canonical default.
MODEL_QUANTIZATION_POLICY = "nf4_auto"


# -----------------------------------------------------------------------------
# Runtime profile (restart-required, exclusive)
# -----------------------------------------------------------------------------

# "distilled_nf4": canonical fast profile using transformer/.
# "full_sft_nf4": full/SFT Stage 1 using transformer_full/ plus the required
#                  Stage-2 distilled LoRA. Switching profiles requires a Space
#                  restart; both transformers are never intentionally resident
#                  in the same runtime.
MODEL_RUNTIME_PROFILE = "distilled_nf4"

# ZeroGPU GPU size for forks/maintainers. "large" is the canonical 48GB path.
# "xlarge" requests the full 96GB worker and consumes 2x ZeroGPU quota; it is
# intentionally an opt-in escape hatch rather than a user-facing in-session toggle.
ZEROGPU_GPU_SIZE = "large"

# Full/SFT transformer source. Leave repo/revision as None to inherit the base
# MODEL_REPO_ID / MODEL_REVISION. This is independent from the Stage-2
# distilled adapter source so third-party Full fine-tunes can replace either
# component without adding UI controls. All changes are restart-required.
FULL_SFT_TRANSFORMER_REPO_ID = None
FULL_SFT_TRANSFORMER_REVISION = None
FULL_SFT_TRANSFORMER_PATH = "transformer_full"

# Internal Stage-2 distilled adapter. This is NOT a user LoRA slot. Leave
# repo/revision as None to inherit MODEL_REPO_ID / MODEL_REVISION.
FULL_SFT_STAGE2_LORA_REPO_ID = None
FULL_SFT_STAGE2_LORA_REVISION = None
FULL_SFT_STAGE2_LORA_WEIGHT_NAME = "ltx-2.5-22b-distilled-lora-450-bf16.safetensors"
FULL_SFT_STAGE2_LORA_STRENGTH = 1.0


# -----------------------------------------------------------------------------
# Audio-to-Video product tab (restart-required profile)
# -----------------------------------------------------------------------------

# Current live-validated A2V product profile. Keep these values fixed in this
# productization wave so the P21R3 frozen-audio behavior remains the reference.
# Input audio is CPU-prepared before ZeroGPU quota.
A2V_ENABLED = True
A2V_WIDTH = 512
A2V_HEIGHT = 512
A2V_FRAMES = 121
A2V_ZEROGPU_DURATION_SECONDS = 110

# Startup-fetched product example. Reuse only donor media/prompt; the runtime
# remains this Space's LTX-2.5 Full/SFT pipeline. Exact revision is pinned so a
# future donor UI update cannot silently change the live-gate input.
A2V_EXAMPLE_SPECS = [
    {
        "label": "Puppet superhero wakes up · image + audio",
        "repo_id": "alexnasa/ltx-2-TURBO",
        "repo_type": "space",
        "revision": "72ca15061ee5db3fad4b773c016c6910d184a597",
        "image": "supergirl-2.png",
        "audio": "supergirl.m4a",
        "prompt": (
            "A fuzzy puppet superhero character resembling a female puppet with blonde hair and a blue superhero suit "
            "sleeping in bed and just waking up, she gradually gets up, rubbing her eyes and looking at her dog that "
            "just popped on the bed. the scene feels chaotic, comedic, and emotional with expressive puppet reactions, "
            "cinematic lighting, smooth camera motion, shallow depth of field, and high-quality puppet-style animation"
        ),
        "attribution": "alexnasa/ltx-2-TURBO S2V example",
    },
]


# -----------------------------------------------------------------------------
# Optional transformer override
# -----------------------------------------------------------------------------

# Leave as None to use MODEL_REPO_ID/transformer.
TRANSFORMER_OVERRIDE_REPO_ID = None

# If this ends in ".gguf", it is treated as a single GGUF file inside the Hub
# repository and loaded with Diffusers' model-level from_single_file path.
# Otherwise it is treated as a subfolder for from_pretrained. None means repo root.
TRANSFORMER_OVERRIDE_PATH = None
TRANSFORMER_OVERRIDE_REVISION = None


# -----------------------------------------------------------------------------
# Optional text encoder override (experimental / best effort)
# -----------------------------------------------------------------------------

# Leave as None to use MODEL_REPO_ID/text_encoder.
# Third-party encoders are NOT guaranteed to match the tokenizer, hidden-state
# dimensions, connector contract, quantization scheme, memory budget, or output
# quality expected by LTX-2.5. Failure falls back to the base text encoder and is
# reported in logs/UI rather than silently ignored.
TEXT_ENCODER_OVERRIDE_REPO_ID = None

# Subfolder inside the override repository. None means repo root.
TEXT_ENCODER_OVERRIDE_PATH = None
TEXT_ENCODER_OVERRIDE_REVISION = None


# -----------------------------------------------------------------------------
# Prompt enhancer (LTX-2.5 dedicated Gemma 4)
# -----------------------------------------------------------------------------

# LTX-2.5's fine-tuned text encoder is not the prompt enhancer. This separate
# Gemma 4 model is loaded into CPU RAM at startup in BitsAndBytes NF4 and moved
# to GPU only while one dedicated Prompt Tools callback is running. The
# Unsloth repository is used as a plain Transformers checkpoint; the Space does
# not depend on the Unsloth runtime/package. Pin revisions for reproducibility.
PROMPT_ENHANCER_ENABLED = True
PROMPT_ENHANCER_REPO_ID = "unsloth/gemma-4-E2B-it"
PROMPT_ENHANCER_REVISION = "9e469bd761461de321e0ba2ec3a00bced655f881"

# "nf4_auto" quantizes an unquantized checkpoint to BitsAndBytes NF4 on load,
# while accepting a repo that is already BitsAndBytes NF4 without double
# quantization. Other prequantized formats are rejected explicitly.
PROMPT_ENHANCER_QUANTIZATION_POLICY = "nf4_auto"

# Prompt Tools reuse the same dedicated Gemma callback.  Keep the reservation
# explicit because fork/runtime performance can differ from the reference
# ZeroGPU environment.
PROMPT_TOOL_ZEROGPU_DURATION_SECONDS = 30

# Built-in contracts for the two additional Prompt Tools.  Enhance Prompt does
# not use either value: it keeps Diffusers/LTX-2.5's official system prompts.
# The UI exposes optional full-manual overrides for Translate / Write only.
PROMPT_TRANSLATE_LTX_ENGLISH_SYSTEM_PROMPT = """
You are a translation assistant for LTX-2.5 video-generation prompts. Translate the user's input into natural, precise English while preserving its meaning, chronology, names, numbers, visual details, camera instructions, audio instructions, and exact quoted dialogue. Do not add new creative content, remove requested content, or change the intended scene. If the input is already English, only normalize wording when needed for clarity. Keep visual and audio descriptions literal and concrete. Return exactly one continuous English paragraph suitable for LTX-2.5, with no title, preface, bullet list, Markdown, code fence, or commentary.
""".strip()

PROMPT_WRITE_FROM_SEED_SYSTEM_PROMPT = """
You are an LTX-2.5 video-prompt writer. Turn the user's seed idea, keywords, fragment, or rough concept into one complete English video-generation prompt. Preserve every explicit seed constraint, then invent useful missing visual, motion, setting, lighting, texture, and sound details so the result is concrete and chronologically coherent. Use active present-progressive language. Do not invent dialogue unless the seed mentions speech, talking, singing, or conversation; preserve any supplied dialogue exactly except obvious typos. Do not invent camera movement unless the seed requests it. Describe only visual and audible information. Prefer a single flowing paragraph under about 200 words. Return only the finished prompt, with no title, preface, Markdown, code fence, or commentary.
""".strip()


# -----------------------------------------------------------------------------
# Auto Duration (LTX-2.5 duration head)
# -----------------------------------------------------------------------------

# Keep manual duration as the product default. When Auto Duration is selected,
# LTX-2.5 predicts a natural shot length from the text-connector outputs and the
# prediction is clamped to this small standard-range cap before snapping to the
# model's 8k+1 temporal grid. ZeroGPU must reserve against the cap because the
# prediction itself is only known after GPU allocation.
AUTO_DURATION_ENABLED = True
DEFAULT_USE_AUTO_DURATION = False
AUTO_DURATION_MIN_SECONDS = 1.0
AUTO_DURATION_MAX_SECONDS = 8.0


# -----------------------------------------------------------------------------
# Optional diffusion decoder
# -----------------------------------------------------------------------------

# Load the LTX-2.5 diffusion video decoder into CPU RAM at startup, but do not
# include it in module-scope CUDA/ZeroGPU packing. The 512x512 25f and 361f/15s
# paths are live-passed on ZeroGPU large 48GB; the UI remains opt-in by default.
DIFFUSION_DECODER_ENABLED = True
DEFAULT_USE_DIFFUSION_DECODER = False


# -----------------------------------------------------------------------------
# Built-in LoRA catalog
# -----------------------------------------------------------------------------

# Canonical distribution intentionally ships with no default LoRA enabled.
# Forks can add entries such as:
# {
#     "label": "My Style",
#     "repo_id": "owner/repo",
#     "weight_name": "pytorch_lora_weights.safetensors",
#     "revision": "",  # optional commit / tag / branch
# }
# The pinned Motion Stabilizer witness is retained as an opt-in regression/interoperability
# preset after live closure. It remains unselected by default and is not a claim that every
# LTX-2.3 LoRA is semantically equivalent on LTX-2.5. Forks may add more ordinary LoRAs.
BUILTIN_LORAS = [
    {
        "label": "[Probe] Motion Stabilizer · LTX-2.3",
        "repo_id": "vpakarinen/motion-stabilizer-ltx-lora",
        "weight_name": "motion_stabilizer_ltx_lora_v2.safetensors",
        "revision": "14f0bf50218894ea134e6d22904653a363290677",
    },
]
DEFAULT_SELECTED_LORAS = []
DEFAULT_LORA_STRENGTH = 1.0

# -----------------------------------------------------------------------------
# Dedicated IC-Colorizer (separate tab; not part of the ordinary LoRA picker)
# -----------------------------------------------------------------------------

# Live-closed dedicated Colorizer. The adapter is downloaded/prepared on CPU before
# the ZeroGPU callback, then loaded request-scoped and deleted before callback return.
# The revision below is the current verified repository head observed 2026-08-21.
IC_COLORIZER_ENABLED = True
IC_COLORIZER_LORA_REPO_ID = "Lightricks/LTX-2.3-22b-IC-LoRA-Colorization"
IC_COLORIZER_LORA_REVISION = "0151def1e9b5cf612023c482c24a5df23445ca3f"
IC_COLORIZER_LORA_WEIGHT_NAME = "ltx-2.3-22b-ic-lora-colorization-0.9.safetensors"
IC_COLORIZER_LORA_STRENGTH = 1.0
IC_COLORIZER_REFERENCE_DOWNSCALE_FACTOR = 1
IC_COLORIZER_REFERENCE_STRENGTH = 1.0
IC_COLORIZER_CONDITIONING_ATTENTION_STRENGTH = 1.0

# Live-calibrated product profiles. The donor-fast profile is the default after
# visual/runtime closure; the 512-class profile remains the lower-quota option.
# Reservations retain ~10s guard bands over returned callbacks (~19.37s / ~10.11s).
IC_COLORIZER_DEFAULT_PROFILE = "Donor fast · 768×448 · 49f"
IC_COLORIZER_PROFILES = {
    "Probe · 512×512 · 25f": {
        "width": 512,
        "height": 512,
        "num_frames": 25,
        "zerogpu_duration_seconds": 20,
        "calibration_status": "live callbacks ~9.8-10.1s; calibrated product reservation 20s",
    },
    "Donor fast · 768×448 · 49f": {
        "width": 768,
        "height": 448,
        "num_frames": 49,
        "zerogpu_duration_seconds": 30,
        "calibration_status": "live callback 19.374s with maintainer visual PASS; calibrated product reservation 30s",
    },
}

# -----------------------------------------------------------------------------
# LTX-2.5 Pixel Spatial Upscaler (Distilled IC-LoRA; separate tab)
# -----------------------------------------------------------------------------

# Official LTX-2.5 x2 IC-LoRA. The weight is gated and therefore fetched during
# CPU preflight with the Space HF token; no LFS/Xet/binary asset is committed.
# Standalone product path: Diffusers LTX2InContextPipeline renders the x2 target
# in one distilled pass while preprocessing the reference at target/2.
IC_PIXEL_UPSCALER_ENABLED = True
IC_PIXEL_UPSCALER_LORA_REPO_ID = "Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler"
IC_PIXEL_UPSCALER_LORA_REVISION = "c8140e3c0b838f883ed527e97014700ba51bfea8"
IC_PIXEL_UPSCALER_LORA_WEIGHT_NAME = "ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors"
IC_PIXEL_UPSCALER_LORA_STRENGTH = 1.0
IC_PIXEL_UPSCALER_REFERENCE_DOWNSCALE_FACTOR = 2
IC_PIXEL_UPSCALER_REFERENCE_STRENGTH = 1.0
IC_PIXEL_UPSCALER_CONDITIONING_ATTENTION_STRENGTH = 1.0
IC_PIXEL_UPSCALER_MAX_DURATION_SECONDS = 3.0
IC_PIXEL_UPSCALER_MAX_OUTPUT_SIDE = 768
IC_PIXEL_UPSCALER_ZEROGPU_DURATION_SECONDS = 55

# Donor media only. These official LTX-2.3 upscaler examples are fetched at
# startup and reused to exercise the LTX-2.5 x2 model; runtime/model authority
# remains the LTX-2.5 product pin above.
IC_PIXEL_UPSCALER_EXAMPLE_SPECS = [
    {
        "label": "Jellyfish · official upscaler donor",
        "repo_id": "Lightricks/ltx-2-3-spatial-upscaler",
        "repo_type": "space",
        "revision": "125b50558f2fa7185deeabf9b3504ec9ced24ab1",
        "video": "jellyfish_glide.mp4",
        "prompt": "a jellyfish gliding gracefully through deep blue water, translucent bioluminescent detail",
        "attribution": "Official Lightricks LTX-2.3 Pixel Spatial Upscaler demo media",
    },
    {
        "label": "Waterfall · official upscaler donor",
        "repo_id": "Lightricks/ltx-2-3-spatial-upscaler",
        "repo_type": "space",
        "revision": "125b50558f2fa7185deeabf9b3504ec9ced24ab1",
        "video": "waterfall_forest.mp4",
        "prompt": "a waterfall cascading through a lush green forest, misty spray and wet mossy rocks",
        "attribution": "Official Lightricks LTX-2.3 Pixel Spatial Upscaler demo media",
    },
    {
        "label": "Squirrel · official upscaler donor",
        "repo_id": "Lightricks/ltx-2-3-spatial-upscaler",
        "repo_type": "space",
        "revision": "125b50558f2fa7185deeabf9b3504ec9ced24ab1",
        "video": "squirrel_eating.mp4",
        "prompt": "a squirrel eating a nut, detailed fur, soft natural daylight",
        "attribution": "Official Lightricks LTX-2.3 Pixel Spatial Upscaler demo media",
    },
]


# -----------------------------------------------------------------------------
# LTX-2.5 Inpainting / Outpainting (officially reuses LTX-2.3 IC-LoRA)
# -----------------------------------------------------------------------------

# The LTX-2.5 official workflow explicitly reuses this LTX-2.3 adapter. Binary
# weights are gated and fetched during CPU preflight; never committed to the repo.
# P72 live evidence proved the LTX-2.3 adapter works on the LTX-2.5 Distilled
# runtime. Product generation now uses the two-stage visual refinement path.
IC_INOUTPAINT_ENABLED = True
IC_INOUTPAINT_LORA_REPO_ID = "Lightricks/LTX-2.3-22b-IC-LoRA-In-Outpainting"
IC_INOUTPAINT_LORA_REVISION = None
IC_INOUTPAINT_LORA_WEIGHT_NAME = "ltx-2.3-22b-ic-lora-in-outpainting-0.9.safetensors"
IC_INOUTPAINT_LORA_STRENGTH = 1.0
IC_INOUTPAINT_REFERENCE_DOWNSCALE_FACTOR = 1
IC_INOUTPAINT_REFERENCE_STRENGTH = 1.0
IC_INOUTPAINT_CONDITIONING_ATTENTION_STRENGTH = 1.0
IC_INOUTPAINT_MAX_DURATION_SECONDS = 2.0
IC_INOUTPAINT_MAX_OUTPUT_SIDE = 768
IC_INOUTPAINT_ZEROGPU_DURATION_SECONDS = 40

# Official Lightricks Space media is used only as startup-fetched source footage
# for In/Outpainting examples. No task media is committed to this deploy artifact.
IC_INOUTPAINT_EXAMPLE_SPECS = [
    {
        "label": "Jellyfish · official Lightricks source",
        "repo_id": "Lightricks/ltx-2-3-spatial-upscaler",
        "repo_type": "space",
        "revision": "125b50558f2fa7185deeabf9b3504ec9ced24ab1",
        "video": "jellyfish_glide.mp4",
        "prompt": "",
        "mode": "Outpainting",
        "layout": "Wide · 768×448",
        "attribution": "Official Lightricks demo media reused only as an Outpainting source witness",
    }
]


# Dedicated IC-Colorizer example authority. Keep separate from EXAMPLE_SPECS:
# this media fills only the IC tab and does not imply an ordinary I2V example.
# The public donor Space is intentionally resolved at startup so no LFS/Xet media
# must be committed into this deploy artifact. Download failure is non-fatal.
IC_COLORIZER_EXAMPLE_SPECS = [
    {
        "label": "Rabbit on rocks · old Colorizer donor",
        "repo_id": "ltx-community/ltx-2.3-colorize",
        "repo_type": "space",
        "revision": "main",
        "video": "examples/rabbit_rocks_gray.mp4",
        "profile": "Donor fast · 768×448 · 49f",
        "prompt": (
            "a young brown cottontail rabbit with warm tan and grey-brown fur, a pale cream "
            "underside and soft pink inner ears, perched on weathered grey granite boulders "
            "flecked with green and ochre lichen, with bleached driftwood and clumps of golden "
            "dry grass in warm late-afternoon sun; gentle wind, distant birdsong and soft "
            "rustling grass"
        ),
        "attribution": "LTX-2.3 Colorize donor example",
    }
]


# Historical IC-LoRA / task-adapter catalog salvaged from prior LTX Spaces in
# the project megapack. These entries are intentionally NOT wired into the
# ordinary T2V/I2V LoRA picker: each requires a reference-video / IC-edit
# workflow or other task-specific conditioning. They are retained here so
# future dedicated tabs (Colorizer, HDR, Motion Track, Union Control, Outpaint,
# JoyFox restoration/editing) can reuse verified repo/weight metadata without
# rediscovery. Empty revision means "not pinned by the historical source"; pin
# before promoting a catalog entry into a live product path.
IC_LORA_PRESET_CATALOG = [
    {
        "label": "Colorization · official LTX-2.3 IC-LoRA",
        "repo_id": "Lightricks/LTX-2.3-22b-IC-LoRA-Colorization",
        "weight_name": "ltx-2.3-22b-ic-lora-colorization-0.9.safetensors",
        "revision": "",
        "workflow_family": "ic_reference_video_colorization",
        "ui_exposed": False,
        "access": "gated",
        "source": "megapack:ltx23_ic_colorizer",
    },
    {
        "label": "HDR · official LTX-2.3 IC-LoRA",
        "repo_id": "Lightricks/LTX-2.3-22b-IC-LoRA-HDR",
        "weight_name": "ltx-2.3-22b-ic-lora-hdr-0.9.safetensors",
        "revision": "",
        "workflow_family": "ic_reference_video_hdr",
        "ui_exposed": False,
        "access": "gated",
        "source": "megapack:ltx_lora_playground",
    },
    {
        "label": "Motion Track Control · official LTX-2.3 IC-LoRA",
        "repo_id": "Lightricks/LTX-2.3-22b-IC-LoRA-Motion-Track-Control",
        "weight_name": "ltx-2.3-22b-ic-lora-motion-track-control-ref0.5.safetensors",
        "revision": "572bb9c",
        "workflow_family": "ic_reference_video_motion_track",
        "reference_downscale_factor": 2,
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground + web-verified-current",
    },
    {
        "label": "Union Control · official LTX-2.3 IC-LoRA",
        "repo_id": "Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control",
        "weight_name": "ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors",
        "revision": "b4d1c4d",
        "workflow_family": "ic_reference_video_union_control",
        "reference_downscale_factor": 2,
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground + web-verified-current",
    },
    {
        "label": "Outpaint · LTX-2.3 IC-LoRA",
        "repo_id": "oumoumad/LTX-2.3-22b-IC-LoRA-Outpaint",
        "weight_name": "ltx-2.3-22b-ic-lora-outpaint.safetensors",
        "revision": "b747e10",
        "workflow_family": "ic_reference_video_outpaint",
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground + web-verified-current",
    },
    {
        "label": "Video Restoration · JoyFox LTX-2.3 ICEdit",
        "repo_id": "joyfox/LTX2.3-ICEdit-Insight",
        "weight_name": "ltx2.3-video-restoration-general.safetensors",
        "revision": "",
        "workflow_family": "joyfox_insight_video_edit",
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground",
    },
    {
        "label": "HD Enhancement · JoyFox LTX-2.3 ICEdit",
        "repo_id": "joyfox/LTX2.3-ICEdit-Insight",
        "weight_name": "ltx2.3-ic-video-upscale-general.safetensors",
        "revision": "",
        "workflow_family": "joyfox_insight_video_edit",
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground",
    },
    {
        "label": "Watermark Removal · JoyFox LTX-2.3 ICEdit",
        "repo_id": "joyfox/LTX2.3-ICEdit-Insight",
        "weight_name": "ltx2.3-ic-watermark-remove-general.safetensors",
        "revision": "",
        "workflow_family": "joyfox_insight_video_edit",
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground",
    },
    {
        "label": "Subtitle Removal · JoyFox LTX-2.3 ICEdit",
        "repo_id": "joyfox/LTX2.3-ICEdit-Insight",
        "weight_name": "ltx2.3-ic-subtitles-remove-general.safetensors",
        "revision": "",
        "workflow_family": "joyfox_insight_video_edit",
        "ui_exposed": False,
        "access": "public",
        "source": "megapack:ltx_lora_playground",
    },
]


# -----------------------------------------------------------------------------
# External startup examples
# -----------------------------------------------------------------------------

# Examples are fetched from the Hub at Space startup so forks do not need to
# commit LFS/Xet media into the Space repository. Download failure is non-fatal:
# the affected example is omitted and the failure is logged. repo_type accepts
# "model", "dataset", or "space". Pin revision to a commit when provenance is
# important; "main" is allowed for low-risk demonstration assets.
EXAMPLE_SPECS = [
    {
        "label": "Cats · I2V",
        "repo_id": "huggingface/documentation-images",
        "repo_type": "dataset",
        "revision": "main",
        "start_image": "diffusers/coco-cats.png",
        "end_image": None,
        "prompt": (
            "A pair of tabby cats resting on a bright pink sofa; one cat slowly lifts its head and stretches "
            "while the other shifts gently, natural indoor room tone, steady camera."
        ),
        "license": "CC BY-NC-SA 4.0",
        "attribution": "Hugging Face documentation-images",
    },
    {
        "label": "Blue bird · I2V",
        "repo_id": "huggingface/documentation-images",
        "repo_type": "dataset",
        "revision": "main",
        "start_image": "diffusers/flf2v_input_first_frame.png",
        "end_image": None,
        "prompt": (
            "CG animation style, a small blue bird takes off from the ground, flapping its wings. "
            "The camera follows the bird upward through a bright blue sky with soft clouds; delicate "
            "wing motion, stable composition, and light natural ambience."
        ),
        "license": "CC BY-NC-SA 4.0",
        "attribution": "Hugging Face documentation-images",
    },
    {
        "label": "Blue bird · first + last frame",
        "repo_id": "huggingface/documentation-images",
        "repo_type": "dataset",
        "revision": "main",
        "start_image": "diffusers/flf2v_input_first_frame.png",
        "end_image": "diffusers/flf2v_input_last_frame.png",
        "prompt": (
            "CG animation style, a small blue bird takes off from the ground, flapping its wings. "
            "The camera follows the bird upward, smoothly connecting the supplied first and last frames "
            "with coherent motion and synchronized light natural ambience."
        ),
        "license": "CC BY-NC-SA 4.0",
        "attribution": "Hugging Face documentation-images",
    },
    {
        "label": "Kingfisher · official LTX-2.5",
        "repo_id": "Lightricks/LTX-2.5",
        "repo_type": "space",
        "revision": "e1c94ba",
        "start_image": "examples/bird_kingfisher.jpg",
        "end_image": None,
        "prompt": (
            "The kingfisher launches from the branch and skims low over the water, wings beating fast, "
            "droplets trailing behind"
        ),
        "attribution": "Official Lightricks LTX-2.5 Space example",
    },
    {
        "label": "Aurora · official LTX-2.5",
        "repo_id": "Lightricks/LTX-2.5",
        "repo_type": "space",
        "revision": "e1c94ba",
        "start_image": "examples/aurora.jpg",
        "end_image": None,
        "prompt": (
            "The green aurora ripples across the starry night sky above the snow-capped mountains, wind gusting"
        ),
        "attribution": "Official Lightricks LTX-2.5 Space example",
    },
    {
        "label": "Cherry blossom pond · official LTX-2.5",
        "repo_id": "Lightricks/LTX-2.5",
        "repo_type": "space",
        "revision": "e1c94ba",
        "start_image": "examples/cherry_blossom_pond.jpg",
        "end_image": None,
        "prompt": "Pink cherry-blossom petals drift down and gently ripple the calm pond",
        "attribution": "Official Lightricks LTX-2.5 Space example",
    },
]

# Number of completed generations retained in the browser-session history.
HISTORY_LIMIT = 5


# -----------------------------------------------------------------------------
# Product UI defaults
# -----------------------------------------------------------------------------

# Fork-visible product surface. These values define the standard UI limits and
# preset choices; runtime validation/derived frame counts live under ``ltx/``.
# Keep the canonical 24 fps / 15s standard / 30s experimental contract unless a
# fork intentionally owns the resulting runtime/performance differences.
FRAME_RATE = 24.0
STANDARD_MAX_SECONDS = 15.0
EXPERIMENTAL_MAX_SECONDS = 30.0
RESOLUTIONS = {
    "512 × 512 · validated": (512, 512),
    "768 × 512 · experimental": (768, 512),
    "512 × 768 · experimental": (512, 768),
}

DEFAULT_PROMPT = (
    "A small red fox walks slowly through fresh snow at dawn while the camera "
    "tracks beside it; soft wind moves the trees and quiet footsteps are audible."
)
DEFAULT_RESOLUTION = "512 × 512 · validated"
DEFAULT_DURATION_SECONDS = 1.0
DEFAULT_SEED = 42
DEFAULT_RANDOMIZE_SEED = True

# Canonical baseline is SDPA. Other backends are explicit opt-in and remain
# experimental; the LTX25_ATTENTION_BACKEND environment variable can override it.
DEFAULT_ATTENTION_BACKEND = "sdpa"