handler/Dockerfile

# Base: torch~=2.7 is a real, hard dependency of ltx-core (its own
# pyproject.toml, not a guess). CUDA 13.0 chosen deliberately over the
# 12.6-based safer option -- Blackwell (96GB tier) support requires it, and
# torch==2.7.1 is confirmed (Qwen-Image-Edit-runpod's own real 2026-07-31
# deploy) as the first stable torch release with real sm_120 kernels. This
# reopens the "some RunPod hosts refuse CUDA>=12.8 containers" risk
# documented in ../BiRefNet-runpod/README.md and ../Qwen-Image-Edit-runpod/
# Dockerfile -- a deliberate, discussed tradeoff for this repo, not an
# oversight.
#
# ACTUAL RESOLVED VERSION, confirmed by a real local build + import test
# (2026-07-31, no GPU needed for this check): `uv sync --frozen` installs
# LTX-2's own uv.lock-pinned torch, which overrides whatever ships with this
# base image -- the real result is torch==2.9.1+cu128, NOT 2.7.1+cu1300 as
# this image's tag implies. Still satisfies ltx-core's `torch~=2.7`
# constraint (2.9.1 is within the 2.x series, >=2.7). If anything this is a
# BETTER outcome than planned: cu128 is exactly the build Qwen-Image-Edit-
# runpod already confirmed has working Blackwell/sm_120 kernels in a real
# deploy, not the untested cu130 this base image's own tag suggested.
FROM runpod/pytorch:1.0.3-cu1300-torch271-ubuntu2404
WORKDIR /app

# uv is LTX-2's own install method (uv sync --frozen from the repo root),
# not a pip package -- see LTX-2/README.md's quickstart. Installed via the
# official standalone installer rather than pip, matching upstream docs.
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"

# LTX v1.4.2: keep handler calls and all pipeline return formats at this pin.
ARG LTX2_COMMIT=9ec55f9f22798a3198d9c923856824821bc3317e
ENV LTX_UPSTREAM_COMMIT=${LTX2_COMMIT}
# Full clone (not --depth 1): the pin is a specific commit, not the branch
# tip, and a shallow clone would need its own --depth-1-of-that-commit
# fetch anyway (a second network round trip, not a saving) since the commit
# isn't known to git until it's fetched.
#
# The repo's own .gitattributes DOES configure git-lfs for several
# extensions (*.safetensors, *.png, *.mp4, test-asset *.wav, etc.) -- but
# the actual multi-GB model weights are NOT committed here; they live on
# Hugging Face (Lightricks/LTX-2.3, google/gemma-3-...) and are only
# referenced by path/URL from this repo's scripts. Confirmed by cloning it:
# the checkout is 5.0MB total. git-lfs is NOT installed in this image on
# purpose -- without it, any LFS-tracked file this repo does contain (small
# doc/test assets under packages/ltx-pipelines/tests/assets/, not anything
# this handler's code path touches) checks out as its plain-text LFS
# pointer instead of real content. Harmless here since nothing in
# ltx-core/ltx-pipelines' actual import path depends on those files, but
# flagged rather than silently assumed away.
RUN git clone https://github.com/Lightricks/LTX-2.git /opt/ltx2 \
 && cd /opt/ltx2 \
 && git checkout ${LTX2_COMMIT}

# `uv sync` WITHOUT --frozen, and that is a real regression to be aware of.
# The 2.3 build used `uv sync --frozen` against upstream's committed uv.lock.
# Upstream DELETED uv.lock in commit 2362161 ("Automated PR - 2026-08-11", the
# LTX-2.5 release), so --frozen now fails outright: there is no lockfile to
# freeze against. Verified by `git cat-file -e <pin>:uv.lock` at both pins.
#
# CONSEQUENCE: dependency resolution now happens at BUILD time, so two builds
# of the same LTX2_COMMIT can install different versions. To restore
# reproducibility, copy the uv.lock this build produces out of the image
# (/opt/ltx2/uv.lock), commit it to THIS repo, COPY it in before this step and
# put --frozen back. Deliberately not done pre-first-build: the resolution has
# to succeed once before it is worth pinning.
#
# `--extra natten` IS used, and skipping it was a real bug. The previous comment
# here claimed natten "only matters for the compiled attention path this handler
# does not enable" -- wrong on both counts, proven by a real job on 2026-08-25:
#
#   DiffVAE: natten is NOT installed. Falling back to a slower neighborhood-
#   attention backend (Triton if available, else pure-PyTorch tiled SDPA).
#   This path is for compatibility only -- install natten for production
#   DiffVAE decode
#   DiffVAE NA fallback: using Triton na3d.
#   -> RuntimeError: Triton Error [CUDA]: invalid argument
#
# natten is the DiffVAE VIDEO DECODER's neighborhood-attention backend, which
# EVERY job goes through. Without it the selection order is natten -> Triton ->
# eager SDPA, and the Triton na3d kernel fails at large frame counts: a 481-frame
# (20s) job generated fine through both denoising stages, peaked at 58.88 GiB,
# and then died in decode. 121 frames survives the fallback; 481 does not.
#
# And the build-risk half was wrong too: ltx-core's `natten` extra pins
# `natten==0.21.7+torch2130cu132` from https://whl.natten.org -- a PREBUILT wheel
# matching the torch 2.13.0+cu132 this image already resolves to. No CUDA compile,
# so the 30-minute build cap is not in play. Upstream's own README install line is
# exactly `uv sync --extra natten`.
#
# HEADS UP on torch: at this pin ltx-core pins torch==2.13.0 (cu132), a large
# jump from the 2.9.1+cu128 the 2.3 build actually resolved to. Upstream's own
# pyproject carries an override-dependencies entry forcing
# nvidia-cudnn-cu13==9.21.1.3, because the version torch pulls omits
# libcudnn_engines_tensor_ir and the soname then resolves against the system
# cuDNN, raising CUDNN_STATUS_SUBLIBRARY_VERSION_MISMATCH. That override comes
# along automatically with the workspace sync -- but it is written against
# THEIR CI image's system cuDNN, not this base image's. If the first build or
# first job dies with a cuDNN version mismatch, this comment is the reason.
# ltx-kernels (CUDA-compiled extensions) deliberately excluded from the
# default workspace by LTX-2's own pyproject.toml (see its
# `[tool.uv.workspace] exclude` comment) specifically so a plain `uv sync`
# never forces a CUDA toolchain at build time -- not opting into the
# `kernels` group here for that same reason, one fewer unverified variable.
#
# CONSEQUENCE, and it is the only thing gating the nvfp4 cost experiment:
# LTX_QUANTIZATION=nvfp4-cast / nvfp4-prequant need `ltx_kernels.nvfp4`, which
# lives in that excluded group. Enabling it means `uv sync --frozen --group
# kernels` here AND accepting a CUDA toolchain at build time (longer builds,
# and RunPod's GitHub integration caps a build at 30 minutes). Do that as a
# deliberate experiment -- with the nvfp4 transformer file already in the
# bundle -- not as a default.
WORKDIR /opt/ltx2
RUN uv sync --extra natten

# This project's own glue code (runpod SDK, GCS upload, image download) --
# kept separate from ltx-pipelines' own dependency set rather than editing
# their pyproject.toml/uv.lock, so `uv sync --frozen` above stays a clean,
# unmodified reproduction of upstream's own resolution.
COPY requirements.txt /app/requirements.txt
RUN uv pip install --python /opt/ltx2/.venv/bin/python -r /app/requirements.txt

# NOTE: do NOT bake the ~71GB of model weights into this image -- same
# reasoning as every other repo in this family (BiRefNet-runpod,
# Qwen-Image-Edit-runpod, Wan2.2-runpod): RunPod's own 80GB image-size cap
# (confirmed via RunPod's docs while building Qwen-Image-Edit-runpod) would be
# blown by this alone, before even counting the base image.
#
# SINGLE BUNDLE REPO STRATEGY. RunPod's cached-model feature ("Model" field)
# allows exactly ONE repo per endpoint ("Each endpoint is currently limited to
# one cached model at a time", docs.runpod.io/serverless/endpoints/model-caching)
# but provisions it UNBILLED ("You aren't billed for worker time while your
# model is being downloaded"). It also CANNOT filter which files it pulls (the
# same docs page: "the system currently downloads all quantization versions"),
# so naming Lightricks/LTX-2.5 in that field would pre-pull the whole 298.7GB
# repo -- including the *-comfy-int8-convrot.safetensors variants ltx-pipelines
# cannot even read.
#
# Fix: ONE user-owned HF "bundle" repo mirroring only what is needed, at
# IDENTICAL paths to upstream so handler.py's defaults work against either.
# Built 2026-08-24 with huggingface_hub.copy_files() -- server-side repo-to-repo
# copies, no bytes downloaded or uploaded, 140.75GB in ~11 seconds. Contents
# (see ../shoupapp/LTX_25_MIGRATION_PLAN.md section 3):
#   diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors  42.02 GB  <- this handler
#   text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors          26.26 GB  <- this handler
#   vae/ltx-2.5-video-vae-bf16.safetensors                                1.47 GB  <- this handler
#   vae/ltx-2.5-audio-vae-bf16.safetensors                                0.36 GB  <- this handler
#   latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0...  1.00 GB  <- this handler
#   diffusion_models/ltx-2.5-22b-distilled-transformer-nvfp4.safetensors 18.72 GB  <- nvfp4 experiment
#   diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors        42.02 GB  <- 360deg/keyframe, later
#   loras/ltx-2.5-22b-distilled-lora-450-bf16.safetensors                 8.90 GB  <- 360deg/keyframe, later
# The last three are NOT loaded by this handler; they are staged so the
# keyframe-interpolation and premium-quality work needs no re-provisioning.
#
# !! REQUIRED CONSOLE SETTINGS !!
#   - "Model" field = the bundle repo id (tugrulv89/LTX_2.5-handler)
#   - Endpoint env var: LTX_MODEL_REPO=<same bundle repo id>
# handler.py resolves everything through the standard HF cache (HF_HUB_CACHE ->
# /runpod-volume/huggingface-cache/hub), which is exactly where the Model field
# pre-provisions files -- no local_dir= anywhere, so nothing is downloaded
# twice, and no Network Volume is required. Without the Model field the handler
# still works standalone -- it downloads ~71GB into that same cache, on BILLED
# time, on every cold start. Configure the field.
#
# The 2.3 trio (LTX_CHECKPOINT_REPO / LTX_GEMMA_REPO / LTX_GEMMA_SUBFOLDER) is
# GONE: 2.5's text encoder is a single file, not a Gemma snapshot directory, so
# there is no subfolder to point at. Per-file overrides are LTX_TRANSFORMER_FILE
# / LTX_TEXT_ENCODER_FILE / LTX_VIDEO_VAE_FILE / LTX_AUDIO_VAE_FILE /
# LTX_UPSCALER_FILE.
#
# !! HF_TOKEN !! required as a RunPod Secret while the bundle repo is private or
# the upstream repo is gated (Lightricks/LTX-2.5 is gated:auto -- the license
# must be accepted once on the model page).

COPY handler.py /app/handler.py

# DEV OVERRIDE (added 2026-07-31, after the 4th from-scratch GitHub build):
# if /runpod-volume/dev/handler.py exists, run IT instead of the baked-in
# /app/handler.py. Rationale: this endpoint deploys via RunPod's GitHub
# integration, which builds and redeploys on EVERY push to the watched
# branch (docs.runpod.io/serverless/workers/github-integration -- also the
# source of the 30-minute docker-build cap and 80GB image cap); its builder
# cache is not under our control, so in practice each handler-only tweak
# cost a full from-scratch image build. With this override, iterating on
# handler.py needs ZERO builds: copy the new file to the network volume
# (from any pod attached to it, e.g. `curl -o /runpod-volume/dev/handler.py
# <raw github url>`), then let the endpoint's workers restart. DELETE the
# file to return to the image's own pinned handler -- that is the
# production configuration; the override is a development mechanism.
# The echo makes an active override loudly visible in every worker log so
# it can't linger unnoticed.
CMD ["/bin/sh", "-c", "if [ -f /runpod-volume/dev/handler.py ]; then echo '!! DEV handler override active: /runpod-volume/dev/handler.py (delete it to use the baked-in handler)' && exec /opt/ltx2/.venv/bin/python -u /runpod-volume/dev/handler.py; else exec /opt/ltx2/.venv/bin/python -u /app/handler.py; fi"]