AnimoFlow hosted-demo wrapper — initial public release (v0.1.0-beta)

.dockerignore

@@ -0,0 +1,25 @@
+# Don't ship local junk into the image
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.venv
+venv
+.git
+.gitignore
+.dockerignore
+*.egg-info
+build
+dist
+.env
+.env.local
+output
+.weights
+.checkpoints
+.DS_Store
+.vscode
+.idea
+README.md
+LICENSE
+docs
+tests

.env.example

@@ -0,0 +1,47 @@
+# animoflow-app environment — copy to .env for local dev (never commit .env)
+
+# Where the orchestrator writes generated FBX/GLB
+OUTPUT_DIR=/tmp/animoflow-output
+
+# Where Y_bot.fbx etc. live (cloned from comfyui-animoflow at Docker build)
+CHARACTERS_DIR=/opt/comfyui-animoflow/characters
+
+# WEB_DIR controls whether the AnimoFlow web app's static SPA mounts. Set to a
+# non-existent path on HF so Gradio takes the "/" route instead.
+WEB_DIR=/nonexistent
+
+# Upstream model paths — set by Dockerfile, used by inference modules.
+# For local dev outside Docker, point at your local clones.
+MDM_PATH=/opt/mdm-codes
+MOMASK_PATH=/opt/momask-codes
+PRIORMDM_PATH=/opt/priormdm-codes
+HML_DATASET_DIR=/opt/priormdm-codes/dataset/HumanML3D
+
+# Where MDM-family checkpoints live. download_weights.sh populates this on first boot.
+CHECKPOINTS_DIR=/opt/checkpoints
+
+# Blender binary (required for retarget + GLB export). Leave unset to let
+# pipeline_hf._find_blender() auto-detect:
+#   1. blender on PATH
+#   2. /Applications/Blender.app/Contents/MacOS/Blender (macOS)
+#   3. /opt/blender/blender (Docker image)
+# Override here if your install lives elsewhere.
+# BLENDER_BIN=/Applications/Blender.app/Contents/MacOS/Blender
+
+# These point at non-existent endpoints on HF (no model servers run as separate
+# processes). animoflow-api's _health_poller will log "unreachable" but won't crash.
+MDM_ENDPOINT=http://127.0.0.1:65500
+PRIORMDM_ENDPOINT=http://127.0.0.1:65501
+MOMASK_ENDPOINT=http://127.0.0.1:65502
+MOMASK_PLUS_ENDPOINT=http://127.0.0.1:65503
+KIMODO_ENDPOINT=http://127.0.0.1:65504
+COMFYUI_URL=http://127.0.0.1:65505
+
+# Health poll cadence — bumped high so we don't spam logs with "unreachable"
+HEALTH_POLL_INTERVAL=600
+
+# Gradio / FastAPI port (HF Spaces convention is 7860)
+PORT=7860
+
+# Disable PyTorch CUDA emulation warnings outside @spaces.GPU
+TRANSFORMERS_NO_ADVISORY_WARNINGS=1

.github/workflows/cla.yml

@@ -0,0 +1,28 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+permissions:
+  actions: write
+  contents: read
+  pull-requests: write
+  statuses: write
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_SIGNATURES_PAT }}
+        with:
+          path-to-signatures: "signatures/version1/cla.json"
+          path-to-document: "https://github.com/AnimoFlow/legal/blob/main/CLA/individual.md"
+          remote-organization-name: "AnimoFlow"
+          remote-repository-name: "cla-signatures"
+          branch: "main"
+          allowlist: "AnimoFlow,dependabot[bot]"

.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.venv*/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Local secrets / runtime
+.env
+.env.local
+output/
+.weights/
+.checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to animoflow-app
+
+This repository is the **deployment wrapper** for the hosted AnimoFlow demo
+(the Hugging Face Space). Most contributions belong in the components it
+wraps:
+
+- API surface, job contract, error copy → [animoflow-api](https://github.com/AnimoFlow/animoflow-api)
+- Models, pipeline nodes, retargeting → [comfyui-animoflow](https://github.com/AnimoFlow/comfyui-animoflow)
+- Blender addon → [animoflow-blender](https://github.com/AnimoFlow/animoflow-blender)
+
+If your change really is about the Space deployment itself (bootstrap,
+ZeroGPU handling, the Gradio wrapper): external contributions require a
+one-time Contributor License Agreement — a bot will ask on your first PR.
+CLA text and the per-repo license map: [AnimoFlow/legal](https://github.com/AnimoFlow/legal).
+
+## Development
+
+```bash
+pip install pytest
+python -m pytest -q     # unit tests; no GPU or Space needed
+```
+
+Note that a real end-to-end run requires the Space environment (ZeroGPU,
+private checkpoint repos) — deployment changes are verified on the Space
+itself by the maintainer.
+
+Questions first? Open an issue or write to guy@animoflow.ai.

Dockerfile

@@ -0,0 +1,286 @@
+# syntax=docker/dockerfile:1.6
+#
+# animoflow-app — HF Space + OSS local Docker image.
+#
+# Single-venv orchestrator with warm MDM-family models loaded at module level.
+# Per-(comfy+model) escape-hatch venvs isolate outlier models
+# (Kimodo NVIDIA stack, future additions).
+#
+# ─────────────────────────────────────────────────────────────────────
+# AUTH: this Dockerfile uses two BuildKit secrets, both never landing
+# in any image layer:
+#
+#   gh_token  — read access to AnimoFlow/{comfyui-animoflow,animoflow-api}
+#               (currently private; the secret-mount keeps working
+#               after either repo flips public).
+#   hf_token  — read access to AnimoFlow/animoflow-checkpoints (the
+#               private HF Hub model repo where MDM weights live; baked
+#               into the image at build time).
+#
+# HF Spaces autopopulate Space-level secrets with these names. For local
+# builds you pass them via `--secret id=<name>,src=<path-to-token-file>`.
+#
+# Mac local build:
+#     gh auth token > /tmp/gh_token
+#     DOCKER_BUILDKIT=1 docker build \
+#         --secret id=gh_token,src=/tmp/gh_token \
+#         -t animoflow/app .
+#     rm /tmp/gh_token
+#
+# HF Space build: configure a Space secret named `gh_token` in
+# Settings → Variables and secrets. HF passes it to the build automatically.
+#
+# Run (OSS local, after build):
+#     docker run --rm -p 7860:7860 animoflow/app
+#
+# Build args let you pin upstream SHAs reproducibly. CI bumps these
+# deliberately, never via `git pull` behind our back (wrap upstream
+# repos, don't fork them).
+
+ARG PYTHON_VERSION=3.11
+ARG BLENDER_VERSION=4.2.5
+ARG COMFYUI_ANIMOFLOW_REPO=https://github.com/AnimoFlow/comfyui-animoflow.git
+ARG ANIMOFLOW_API_REPO=https://github.com/AnimoFlow/animoflow-api.git
+ARG MDM_REPO=https://github.com/GuyTevet/motion-diffusion-model.git
+ARG MOMASK_REPO=https://github.com/EricGuo5513/momask-codes.git
+# SHA pins — update deliberately, not via `git pull`
+ARG COMFYUI_ANIMOFLOW_SHA=main
+ARG ANIMOFLOW_API_SHA=main
+ARG MDM_SHA=main
+ARG MOMASK_SHA=main
+
+# Baked checkpoints — pulled from a private HF Hub model repo at build
+# time using the `hf_token` BuildKit secret. SHA-pinned for reproducibility;
+# bump deliberately. The repo holds full training artifacts (final + earlier
+# checkpoints + optimizer state + eval logs) but the Dockerfile filters via
+# `allow_patterns` to bake only the inference-essential files.
+ARG ANIMOFLOW_CHECKPOINTS_REPO=AnimoFlow/animoflow-checkpoints
+ARG ANIMOFLOW_CHECKPOINTS_REVISION=9c8b352f849c5e81869a50f71667d43c064571eb
+
+FROM python:${PYTHON_VERSION}-slim AS base
+
+# ─────────────────────────────────────────────────────────────────────
+# System deps
+# ─────────────────────────────────────────────────────────────────────
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl wget ca-certificates xz-utils \
+        xvfb xauth \
+        libxi6 libxrender1 libxxf86vm1 libxfixes3 libxkbcommon0 \
+        libsm6 libxext6 libgl1 libglu1-mesa libegl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# ─────────────────────────────────────────────────────────────────────
+# Blender 4.2 LTS (pinned tarball — apt's blender lags 3.x).
+# Arch-aware: Docker BuildKit auto-populates TARGETARCH (amd64 / arm64).
+# Default `docker build` (no buildx) leaves it empty and falls through to
+# amd64, matching HF Spaces (x86_64 H200 hosts).
+# ─────────────────────────────────────────────────────────────────────
+ARG BLENDER_VERSION
+ARG TARGETARCH
+RUN BLENDER_MAJ=$(echo "${BLENDER_VERSION}" | cut -d. -f1,2) \
+ && case "${TARGETARCH:-amd64}" in \
+        amd64|x86_64|"") BLENDER_ARCH=linux-x64 ;; \
+        arm64|aarch64)   BLENDER_ARCH=linux-arm64 ;; \
+        *) echo "Unsupported TARGETARCH=${TARGETARCH}" >&2 ; exit 1 ;; \
+    esac \
+ && echo "Building for ${TARGETARCH:-amd64} → blender-${BLENDER_VERSION}-${BLENDER_ARCH}.tar.xz" \
+ && curl -fsSL "https://download.blender.org/release/Blender${BLENDER_MAJ}/blender-${BLENDER_VERSION}-${BLENDER_ARCH}.tar.xz" -o /tmp/blender.tar.xz \
+ && mkdir -p /opt/blender \
+ && tar -xf /tmp/blender.tar.xz -C /opt/blender --strip-components=1 \
+ && rm /tmp/blender.tar.xz \
+ && /opt/blender/blender --version
+ENV BLENDER_BIN=/opt/blender/blender
+
+# ────────────────��────────────────────────────────────────────────────
+# Clone wrapper repos — wrap-don't-modify, pinned by SHA build args.
+#
+# Both `comfyui-animoflow` and `animoflow-api` are currently private. We
+# clone both via a BuildKit secret named `gh_token` (the token is
+# interpolated into the URL temporarily and never lands in any image
+# layer — we strip the remote URL after the clone). The same pattern
+# works once either repo is flipped to public, so this keeps working
+# across the public flip.
+# ─────────────────────────────────────────────────────────────────────
+ARG COMFYUI_ANIMOFLOW_REPO
+ARG COMFYUI_ANIMOFLOW_SHA
+ARG ANIMOFLOW_API_REPO
+ARG ANIMOFLOW_API_SHA
+
+RUN --mount=type=secret,id=gh_token,required=true \
+    GH_TOKEN="$(cat /run/secrets/gh_token)" \
+ && _AUTH_CAF=$(echo "${COMFYUI_ANIMOFLOW_REPO}" | sed -e "s|https://|https://x-access-token:${GH_TOKEN}@|") \
+ && _AUTH_AFW=$(echo "${ANIMOFLOW_API_REPO}"     | sed -e "s|https://|https://x-access-token:${GH_TOKEN}@|") \
+ && git clone "${_AUTH_CAF}" /opt/comfyui-animoflow \
+ && git -C /opt/comfyui-animoflow checkout "${COMFYUI_ANIMOFLOW_SHA}" \
+ && git -C /opt/comfyui-animoflow remote set-url origin "${COMFYUI_ANIMOFLOW_REPO}" \
+ && git clone "${_AUTH_AFW}" /opt/animoflow-api \
+ && git -C /opt/animoflow-api checkout "${ANIMOFLOW_API_SHA}" \
+ && git -C /opt/animoflow-api remote set-url origin "${ANIMOFLOW_API_REPO}" \
+ && unset GH_TOKEN _AUTH_CAF _AUTH_AFW
+
+# ─────────────────────────────────────────────────────────────────────
+# Clone upstream models.
+# priorMDM and Kimodo come in later iterations.
+# ─────────────────────────────────────────────────────────────────────
+ARG MDM_REPO
+ARG MDM_SHA
+ARG MOMASK_REPO
+ARG MOMASK_SHA
+RUN git clone "${MDM_REPO}" /opt/mdm-codes \
+ && git -C /opt/mdm-codes checkout "${MDM_SHA}"
+RUN git clone "${MOMASK_REPO}" /opt/momask-codes \
+ && git -C /opt/momask-codes checkout "${MOMASK_SHA}"
+
+ENV MDM_PATH=/opt/mdm-codes
+ENV MOMASK_PATH=/opt/momask-codes
+
+# ─────────────────────────────────────────────────────────────────────
+# Single Python venv (orchestrator + MDM family).
+# `uv venv` creates a bare virtualenv (no pip bundled by default — uv
+# expects `uv pip install --python <venv>` instead of bare pip). Use the
+# `uv pip` form throughout.
+# ─────────────────────────────────────────────────────────────────────
+RUN pip install --no-cache-dir uv==0.5.11
+
+# Create venv + install orchestrator/MDM-family deps.
+#
+# `--seed` populates the venv with pip + setuptools + wheel, and
+# `--no-build-isolation` makes uv build sdists against the target venv
+# (which has those tools) instead of uv's pip-less isolated build env.
+# That combo handles legacy packages whose setup.py imports pip internals,
+# without disabling build isolation everywhere.
+COPY requirements.txt /opt/animoflow-app/requirements.txt
+RUN uv venv /opt/venvs/api --python ${PYTHON_VERSION} --seed \
+ && uv pip install --python /opt/venvs/api --no-cache --no-build-isolation \
+        -r /opt/animoflow-app/requirements.txt
+
+# NOTE: we deliberately do NOT install
+# `comfyui-animoflow/containers/mdm/requirements.txt` here. That file pins
+# torch==2.3.0 which downgrades our 2.4.1 pin and removes
+# `torch.library.register_fake` — an API the upstream MDM source uses, so
+# the wrapper falls back to placeholder mode.
+#
+# Instead we lift the MDM-container deps that aren't already in our pin
+# (einops) directly into requirements.txt above. The local Docker
+# stack uses a different topology (each model in its own container with
+# its own venv) so the version skew there doesn't bite.
+
+# ─────────────────────────────────────────────────────────────────────
+# Bake model checkpoints from the AnimoFlow/animoflow-checkpoints HF Hub
+# model repo. Token only mounted for the duration of this RUN — never
+# lands in any image layer. Failure here aborts the build (we don't want
+# to ship an HF Space without weights).
+#
+# To override the source repo or pin a specific revision, pass build args:
+#   --build-arg ANIMOFLOW_CHECKPOINTS_REPO=AnimoFlow/different-repo
+#   --build-arg ANIMOFLOW_CHECKPOINTS_REVISION=<commit-sha>
+# ─────────────────────────────────────────────────────────────────────
+ARG ANIMOFLOW_CHECKPOINTS_REPO
+ARG ANIMOFLOW_CHECKPOINTS_REVISION
+RUN --mount=type=secret,id=hf_token,required=true \
+    export HF_TOKEN="$(cat /run/secrets/hf_token)" \
+ && echo "Downloading checkpoints from ${ANIMOFLOW_CHECKPOINTS_REPO}@${ANIMOFLOW_CHECKPOINTS_REVISION}…" \
+ && /opt/venvs/api/bin/python -c "\
+import os; \
+from huggingface_hub import snapshot_download; \
+path = snapshot_download( \
+    repo_id='${ANIMOFLOW_CHECKPOINTS_REPO}', \
+    revision='${ANIMOFLOW_CHECKPOINTS_REVISION}', \
+    repo_type='model', \
+    local_dir='/opt/checkpoints', \
+    allow_patterns=[ \
+        'humanml_enc_512_50steps/model000750000.pt', \
+        'humanml_enc_512_50steps/args.json', \
+    ], \
+    token=os.environ['HF_TOKEN']); \
+print('checkpoints baked at', path)" \
+ && unset HF_TOKEN \
+ && cp /opt/comfyui-animoflow/containers/mdm/t2m_mean.npy /opt/checkpoints/t2m_mean.npy \
+ && cp /opt/comfyui-animoflow/containers/mdm/t2m_std.npy  /opt/checkpoints/t2m_std.npy \
+ && ls -laR /opt/checkpoints/ \
+ && du -sh /opt/checkpoints/
+
+# WEIGHTS_DIR is what comfyui-animoflow/containers/mdm/inference.py reads for
+# both the model checkpoint AND the t2m_mean/std normalization arrays.
+# Setting it as ENV makes the MDM wrapper find them without per-run config.
+ENV WEIGHTS_DIR=/opt/checkpoints
+
+# ─────────────────────────────────────────────────────────────────────
+# Multilingual prompt rewriter — Qwen2.5-1.5B-Instruct + RAFSL few-shot
+# from the local HumanML3D caption corpus. Phase-0 verified at 90% pass
+# rate / 0.32s server-only on ZeroGPU. See:
+#   - animoflow-api/api/rewriter.py (the consumer)
+#
+# All three assets SHA-pinned. Bump deliberately, not via "latest".
+# ─────────────────────────────────────────────────────────────────────
+ARG REWRITER_MODEL_REPO=Qwen/Qwen2.5-1.5B-Instruct
+ARG REWRITER_MODEL_REVISION=989aa7980e4c
+ARG REWRITER_RETRIEVER_REPO=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+ARG REWRITER_RETRIEVER_REVISION=e8f8c211226b
+ARG REWRITER_CORPUS_REPO=AnimoFlow/rewriter-corpus
+ARG REWRITER_CORPUS_REVISION=5b98da4d2db075d40afd59badf51f2eefe1db5e2
+
+RUN /opt/venvs/api/bin/python -c "\
+from huggingface_hub import snapshot_download; \
+snapshot_download( \
+    repo_id='${REWRITER_MODEL_REPO}', \
+    revision='${REWRITER_MODEL_REVISION}', \
+    local_dir='/opt/rewriter/qwen', \
+    allow_patterns=['*.safetensors','*.json','tokenizer*','*.model','*.txt','vocab*','merges*'], \
+); \
+snapshot_download( \
+    repo_id='${REWRITER_RETRIEVER_REPO}', \
+    revision='${REWRITER_RETRIEVER_REVISION}', \
+    local_dir='/opt/rewriter/minilm', \
+    allow_patterns=['*.safetensors','*.json','tokenizer*','*.txt','vocab*','*.bin'], \
+); \
+snapshot_download( \
+    repo_id='${REWRITER_CORPUS_REPO}', \
+    revision='${REWRITER_CORPUS_REVISION}', \
+    repo_type='dataset', \
+    local_dir='/opt/rewriter/corpus', \
+    allow_patterns=['captions.json','embeddings.npy'], \
+); \
+print('rewriter baked at /opt/rewriter')" \
+ && ls -laR /opt/rewriter/ \
+ && du -sh /opt/rewriter/*
+
+ENV REWRITER_DATA_DIR=/opt/rewriter
+
+ENV PATH=/opt/venvs/api/bin:${PATH}
+ENV PYTHONUNBUFFERED=1
+
+# ─────────────────────────────────────────────────────────────────────
+# Copy the orchestrator code last (cache-friendly)
+# ─────────────────────────────────────────────────────────────────────
+COPY . /opt/animoflow-app
+
+# ─────────────────────────────────────────────────────────────────────
+# Runtime config
+# ─────────────────────────────────────────────────────────────────────
+ENV OUTPUT_DIR=/tmp/animoflow-output
+ENV CHECKPOINTS_DIR=/opt/checkpoints
+ENV CHARACTERS_DIR=/opt/comfyui-animoflow/characters
+ENV WEB_DIR=/nonexistent
+# Bogus model-server URLs — animoflow-api's health poller will log "unreachable"
+# but no separate model-server processes run on HF. Harmless.
+ENV MDM_ENDPOINT=http://127.0.0.1:65500
+ENV PRIORMDM_ENDPOINT=http://127.0.0.1:65501
+ENV MOMASK_ENDPOINT=http://127.0.0.1:65502
+ENV KIMODO_ENDPOINT=http://127.0.0.1:65504
+ENV COMFYUI_URL=http://127.0.0.1:65505
+ENV HEALTH_POLL_INTERVAL=600
+ENV PORT=7860
+
+RUN mkdir -p ${OUTPUT_DIR} ${CHECKPOINTS_DIR} \
+ && chmod +x /opt/animoflow-app/entrypoint.sh /opt/animoflow-app/scripts/*.sh
+
+EXPOSE 7860
+WORKDIR /opt/animoflow-app
+
+# Healthcheck via the FastAPI health endpoint (exposed even before Gradio mounts)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+    CMD curl -fsS http://localhost:7860/v1/health || exit 1
+
+CMD ["/opt/animoflow-app/entrypoint.sh"]

LICENSE

@@ -0,0 +1,83 @@
+Required Notice: Copyright (c) 2026 Guy Tevet ("AnimoFlow") (https://animoflow.ai)
+
+# AnimoFlow Community License 1.0.0
+
+<https://animoflow.ai/licenses/community/1.0.0>
+
+> **In plain terms** — this summary is for orientation and is not part of the license: this software is free to use, forever, for (1) individuals, (2) charities and other non-profits, (3) schools, universities, and public research organizations, and (4) any organization with fewer than 100 people and less than 5,000,000 USD (2026 dollars) per year in total finances. Anyone may read the source. Larger commercial organizations may evaluate the software free for 30 days, and then need a commercial license from AnimoFlow — contact guy@animoflow.ai. This is a source-available license, not an open-source license.
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright (c) 2026 Guy Tevet ("AnimoFlow") (https://animoflow.ai)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, or public research organization is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding. However, use is not use for a permitted purpose under this section if it is primarily for the benefit of another organization that has control over, is under the control of, or is under common control with the organization using the software, unless that other organization's own use would be use for a permitted purpose under these terms.
+
+## Small Organizations
+
+Use of the software for the benefit of your company is use for a permitted purpose if your company has fewer than 100 total individuals working as employees and independent contractors, and less than 5,000,000 USD (2026) total finances in the prior tax year. Adjust this financial threshold for inflation according to the United States Bureau of Labor Statistics' consumer price index for all urban consumers, U.S. city average, for all items, not seasonally adjusted, with 1982–1984=100 reference base.
+
+## Evaluation
+
+Use of the software for no more than 30 consecutive calendar days to decide whether to obtain a commercial license from the licensor is use for a permitted purpose. This evaluation use must not include use in production or use for the benefit of anyone outside your company.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Total finances** means the largest of your company's aggregate gross revenue, entire budget, and total funding received, in each case calculated across your company as a whole for the prior tax year.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

README.md

@@ -0,0 +1,235 @@
+---
+title: AnimoFlow Demo
+emoji: 🎭
+colorFrom: blue
+colorTo: pink
+sdk: gradio
+sdk_version: 5.31.0
+hardware: zero-a10g
+python_version: "3.11"
+pinned: false
+license: other
+license_name: animoflow-community-license-1.0.0
+license_link: LICENSE
+short_description: Text → Motion → FBX/GLB. MDM diffusion + Blender retarget.
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
+preload_from_hub:
+  - "Qwen/Qwen2.5-1.5B-Instruct"
+  - "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+---
+
+# animoflow-app
+
+Deployment wrapper for [AnimoFlow](https://github.com/AnimoFlow). Same image runs as a
+[Hugging Face Space ZeroGPU](https://huggingface.co/docs/hub/en/spaces-zerogpu)
+demo and as a one-command OSS local server.
+
+The app is a thin layer on top of three sibling repos. None of them are forked
+or modified — each is `git clone`d at Docker build time, pinned by SHA:
+
+- [`comfyui-animoflow`](https://github.com/AnimoFlow/comfyui-animoflow) — model wrappers, IK + retarget code, Blender scripts
+- [`animoflow-api`](https://github.com/AnimoFlow/animoflow-api) — `/v1/jobs` async FastAPI, validation models, task catalog
+- upstream model repos — [MDM](https://github.com/GuyTevet/motion-diffusion-model), [momask-codes](https://github.com/EricGuo5513/momask-codes), more added per iteration
+
+More documentation: the [AnimoFlow user guide](https://animoflow-alpha.pages.dev/guide/) covers all the ways to use the platform; all repositories are under [github.com/AnimoFlow](https://github.com/AnimoFlow).
+
+Net new code in this repo: the `Dockerfile`, `entrypoint.sh`, `app.py` (mounts
+Gradio on the imported animoflow-api FastAPI), `ui.py` (Gradio Blocks), and
+`pipeline_hf.py` (replaces ComfyUI orchestration with in-process pipeline so
+ZeroGPU's `@spaces.GPU` works).
+
+## Architecture
+
+Short version:
+
+- **Single venv on HF.** Orchestrator + warm MDM-family models loaded at module
+  level. ZeroGPU forks the orchestrator process at each `@spaces.GPU` call; the
+  fork inherits warm models via copy-on-write, runs inference on real H200
+  for ~10–15 s, dies, releases GPU.
+- **GPU only on inference.** Resample, IK (momask `Joint2BVHConvertor`), foot/
+  outlier fix, Blender retarget → FBX, Blender FBX → GLB all run CPU-side in the
+  persistent orchestrator process — no GPU billing.
+- **Escape hatch for outlier models.** Models whose deps don't merge with the
+  orchestrator venv (Kimodo's NVIDIA stack, future Tier-2 models) live in
+  `/opt/venvs/comfy-X/` and are subprocess-called from inside `@spaces.GPU`
+  only when their model is selected. Cold-start tax (~15 s) accepted in
+  exchange for full dep isolation.
+
+## API
+
+Same `/v1/*` surface as the rest of AnimoFlow:
+
+```
+POST /v1/jobs            { input: {type, prompt}, model, character, duration, seed }
+GET  /v1/jobs/{id}       { status, progress, stage, download_url, error, ... }
+GET  /v1/files/{name}    binary FBX or GLB
+GET  /v1/tasks           { tasks: [...] }
+GET  /v1/models          { stages: [...] }
+GET  /v1/characters      { characters: [...] }
+GET  /v1/health          { status: "ok" }
+```
+
+Anything Gradio can do, you can also do via `curl`, `gradio_client`,
+`@gradio/client` JS, or the Blender add-on.
+
+## Run locally (no HF account, no Docker)
+
+Requires Python 3.11, Blender 4.2 LTS on PATH (or `BLENDER_BIN` set), and
+the sibling repos cloned alongside.
+
+```bash
+git clone https://github.com/AnimoFlow/comfyui-animoflow ../comfyui-animoflow
+git clone https://github.com/AnimoFlow/animoflow-api      ../animoflow-api
+git clone https://github.com/GuyTevet/motion-diffusion-model ../mdm-codes
+git clone https://github.com/EricGuo5513/momask-codes        ../momask-codes
+
+cd animoflow-app
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Point at your local clones
+cp .env.example .env
+$EDITOR .env  # set CHECKPOINTS_DIR, CHARACTERS_DIR, and ANIMOFLOW_API_API_DIR (path to ../animoflow-api/api)
+
+# Download MDM checkpoints
+./scripts/download_weights.sh
+
+.venv/bin/python app.py
+# → http://localhost:7860
+```
+
+## Run locally (Docker)
+
+The Dockerfile uses two [BuildKit secrets](https://docs.docker.com/build/building/secrets/), neither
+of which lands in any image layer:
+
+- `gh_token` — read access to `AnimoFlow/{comfyui-animoflow,animoflow-api}` (only needed while the repos are private)
+- `hf_token` — read access to BOTH `AnimoFlow/animoflow-checkpoints` (private HF Hub model repo where MDM weights live) AND `AnimoFlow/character-assets` (private repo with the Mixamo character FBXs, split out of the checkpoints repo 2026-07-06)
+
+```bash
+# 1. Drop tokens into files (gh + hf CLIs extract them if you're logged in)
+gh auth token                          > /tmp/gh_token
+huggingface-cli auth token             > /tmp/hf_token   # or: cat ~/.cache/huggingface/token > /tmp/hf_token
+
+# 2. Build with both secrets mounted
+DOCKER_BUILDKIT=1 docker build \
+    --secret id=gh_token,src=/tmp/gh_token \
+    --secret id=hf_token,src=/tmp/hf_token \
+    -t animoflow/app .
+
+# 3. Clean up
+rm /tmp/gh_token /tmp/hf_token
+
+# 4. Run — checkpoints are already baked in, no extra mounts needed
+docker run --rm -p 7860:7860 animoflow/app
+# → http://localhost:7860
+```
+
+The Dockerfile is arch-aware (Blender 4.2 LTS for both `linux/amd64` and
+`linux/arm64`). On Apple Silicon Macs, native arm64 builds work — but if
+you want byte-parity with HF's amd64 ZeroGPU hosts, force the platform:
+
+```bash
+DOCKER_BUILDKIT=1 docker build --platform linux/amd64 \
+    --secret id=gh_token,src=/tmp/gh_token \
+    --secret id=hf_token,src=/tmp/hf_token \
+    -t animoflow/app .
+```
+
+This is the same image deployed to HF Spaces. `@spaces.GPU` no-ops when
+`spaces` isn't on the PYTHONPATH (or when `SPACE_ID` isn't set), so locally
+you get whatever GPU the host has — or CPU fallback.
+
+## Run on HF Spaces
+
+This repo's `README.md` has the Space card YAML at the top. To deploy:
+
+1. Create a Space at <https://huggingface.co/new-space> — pick the `Gradio`
+   SDK, `ZeroGPU` hardware, and the visibility you want.
+2. **Configure two Space secrets** under Settings → Variables and secrets:
+   - `gh_token` — fine-grained GitHub PAT with read access to `AnimoFlow/animoflow-api` and `AnimoFlow/comfyui-animoflow`
+   - `hf_token` — HF token with read access to BOTH `AnimoFlow/animoflow-checkpoints` AND `AnimoFlow/character-assets` (fine-grained tokens must list both repos explicitly — a token missing the character-assets scope crashes bootstrap with RepositoryNotFoundError)
+
+   HF makes Space secrets available to BuildKit's `--mount=type=secret`
+   automatically, so the Dockerfile picks them up without further config.
+3. Push:
+   ```bash
+   git remote add space https://huggingface.co/spaces/AnimoFlow/animoflow-demo
+   git push space main
+   ```
+
+HF builds the Dockerfile (cloning the private repos via `gh_token`,
+baking the MDM checkpoints via `hf_token`), allocates ZeroGPU on each
+request, and serves the Gradio UI at the Space URL.
+
+**Note on file downloads:** On HF Spaces, generated FBX/GLB files are
+served through Gradio's UI (the `gr.Model3D` widget renders them directly).
+External clients should use `gradio_client` to fetch results. The `/v1/files`
+REST endpoint works locally and in OSS Docker mode but is mangled by
+Gradio's reverse proxy on HF Spaces — use the Gradio client API instead.
+
+## Repo layout
+
+```
+animoflow-app/
+├── Dockerfile                    # multi-arg build, Blender pinned tarball
+├── entrypoint.sh                 # downloads weights → starts uvicorn
+├── requirements.txt              # orchestrator + MDM family
+├── app.py                        # mounts Gradio on imported animoflow-api FastAPI
+├── ui.py                         # Gradio Blocks
+├── pipeline_hf.py                # GPU-decorated inference + CPU pipeline
+├── bootstrap.py                  # build/startup: repos, weights, characters, Blender
+├── spaces_compat.py              # @spaces.GPU graceful fallback
+├── animoflow_models/
+│   ├── __init__.py
+│   └── registry.py               # warm-loaded MDM family at module level
+├── escape_hatch/
+│   ├── __init__.py
+│   └── invoke.py                 # subprocess into /opt/venvs/comfy-X
+├── scripts/
+│   ├── download_weights.sh       # idempotent weight download
+│   └── run_inference_kimodo.py   # escape-hatch subprocess runner (kimodo)
+├── tests/
+│   ├── conftest.py
+│   ├── test_app_imports.py       # FastAPI mounts, no model deps required
+│   ├── test_pipeline_hf.py       # mocked GPU + real CPU pipeline
+│   └── test_spaces_compat.py     # decorator behavior
+├── .env.example
+├── .gitignore
+├── .dockerignore
+└── LICENSE                       # AnimoFlow Community License 1.0.0
+```
+
+## License
+
+**AnimoFlow Community License 1.0.0** (see [`LICENSE`](LICENSE)) — the same
+source-available, perpetual threshold license as `animoflow-api`: free
+forever for individuals, non-profits, academia, and organizations under
+$5M USD (2026) total finances & 100 people; commercial license above
+(guy@animoflow.ai). At runtime this wrapper fetches components that carry
+their own licenses — `comfyui-animoflow` is AGPL-3.0, `animoflow-api` is
+AFCL; see [AnimoFlow/legal](https://github.com/AnimoFlow/legal) for the
+full per-repo map.
+
+### Third-party model licenses
+
+The Space loads inference code and weights from upstream projects with their
+own terms. Bundling them does not change this wrapper's AnimoFlow
+Community License declaration, but downstream users should observe each
+model's license:
+
+- **MDM** (Motion Diffusion Model) — code: [MIT](https://github.com/GuyTevet/motion-diffusion-model);
+  HumanML3D-trained checkpoint published by the authors.
+- **MoMask** — code: [MIT](https://github.com/EricGuo5513/momask-codes);
+  HumanML3D-trained checkpoint with the dataset's research-use terms.
+- **Kimodo (NVIDIA)** — code: Apache-2.0
+  ([nv-tlabs/kimodo](https://github.com/nv-tlabs/kimodo)). Weights:
+  `Kimodo-SOMA-RP-v1` ships under the NVIDIA Open Model License
+  (commercial use permitted). The Space deliberately uses ONLY the
+  commercial-OK variants; the research-only `Kimodo-SMPLX-RP-v1` is not loaded.
+- **LLaMA-3-8B-Instruct** (text encoder used by Kimodo) — pulled from the
+  ungated `NousResearch/Meta-Llama-3-8B-Instruct` mirror. Use is governed by
+  Meta's [LLaMA-3 Community License](https://llama.meta.com/llama3/license/).
+- **SOMA-X** ([NVlabs/SOMA-X](https://github.com/NVlabs/SOMA-X)) — used by
+  Kimodo for SOMA→SMPL mesh skinning. See the upstream repo for terms.

SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately to **guy@animoflow.ai** — do not
+open a public issue. You'll get an acknowledgment within a few days.
+
+## Scope notes
+
+- This code runs the hosted demo at animoflow.ai / the AnimoFlow Space.
+  Issues in the API contract itself are best reported against
+  animoflow-api, but reports here reach the same maintainer.
+- The Space executes no code from prompts or uploads; generated animation
+  leaves as data files (FBX/GLB) only.
+- Prompts are logged for service health; no accounts or PII are stored.
+
+There is no bug bounty program at this time.

animoflow_models/__init__.py

@@ -0,0 +1,18 @@
+"""
+Model registry for animoflow-app.
+
+Imports the upstream model `inference.py` modules into the orchestrator
+process at module level (per ZeroGPU best practice). Each model becomes
+warm and is inherited by the @spaces.GPU fork via copy-on-write — no
+per-request load cost.
+
+Outlier models (Kimodo etc. — separate dep tree, won't merge here) live
+in escape_hatch/ and are subprocess-called only when their model is
+selected.
+
+Carries MDM, priorMDM, and MoMask.
+"""
+
+from .registry import generate, list_models, model_status
+
+__all__ = ["generate", "list_models", "model_status"]

animoflow_models/registry.py

@@ -0,0 +1,334 @@
+"""
+Warm-model registry: imports upstream model inference modules into the
+orchestrator process at module level so the @spaces.GPU fork inherits
+them via copy-on-write.
+
+Each model wrapper lives in `comfyui-animoflow/containers/<model>/` and
+exposes a class (e.g. `MDMInference`) with a `.generate(prompt, …) ->
+(npz_bytes, metadata)` method. We don't modify any of that — we just
+import it and hold a singleton.
+
+If a model fails to import (missing weights, dep conflict surfacing
+later, etc.), it's logged and removed from the active set — the API
+will report it as unavailable instead of crashing the whole orchestrator.
+
+Per [[Wrap, don't fork upstream model repos]] and [[animoflow-app — HF +
+OSS deployment wrapper]].
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import sys
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Model definitions — declarative.
+# Each entry says where the wrapper module lives, which class to instantiate,
+# and what the .generate() signature looks like (so we can adapt args).
+# ---------------------------------------------------------------------------
+
+_COMFYUI_ANIMOFLOW = Path(
+    os.environ.get("COMFYUI_ANIMOFLOW_DIR", "/opt/comfyui-animoflow")
+)
+
+_DEFINITIONS: dict[str, dict[str, Any]] = {
+    "mdm": {
+        "container_dir": _COMFYUI_ANIMOFLOW / "containers" / "mdm",
+        "module_name": "inference",
+        "class_name": "MDMInference",
+        # MDMInference.generate(prompt, num_frames, seed, guidance_param) -> (bytes, dict)
+        "generate_kwargs": {
+            "guidance_param_default": 7.5,
+            "guidance_param_name": "guidance_param",
+        },
+    },
+    "momask": {
+        "container_dir": _COMFYUI_ANIMOFLOW / "containers" / "momask",
+        "module_name": "inference_momask",
+        "class_name": "MoMaskInference",
+        # MoMaskInference.generate uses cond_scale (not guidance_param) and
+        # reads CHECKPOINTS_DIR at module import time, so we override the env
+        # to point at the momask/ subdir (populated by bootstrap snapshot
+        # download from AnimoFlow/animoflow-checkpoints `momask/t2m/**`).
+        "generate_kwargs": {
+            "guidance_param_default": 5.0,
+            "guidance_param_name": "cond_scale",
+        },
+        "env_overrides_factory": lambda: {
+            "CHECKPOINTS_DIR": os.path.join(
+                os.environ.get("CHECKPOINTS_DIR", "/app/checkpoints"), "momask"
+            ),
+        },
+    },
+    "priormdm": {
+        "container_dir": _COMFYUI_ANIMOFLOW / "containers" / "priormdm",
+        "module_name": "inference",
+        "class_name": "PriorMDMInference",
+        # PriorMDMInference.generate(prompt, num_frames, seed, guidance_param,
+        # trajectory=, curve_2d=, accel_frac=, decel_frac=) — the extra
+        # kwargs are forwarded by pipeline_hf.run() when model=="priormdm".
+        # Upstream default cfg=2.5 (≠ MDM's 7.5). (The container also accepts
+        # `sample_id` for legacy HumanML3D-dataset references; retired from
+        # the public API on 2026-06-24 and no longer forwarded by the wrapper.)
+        "generate_kwargs": {
+            "guidance_param_default": 2.5,
+            "guidance_param_name": "guidance_param",
+        },
+        # inference.py reads PRIORMDM_PATH, WEIGHTS_DIR, CHECKPOINT_DIR,
+        # HML_DATASET_DIR at module-import time. We plant the first three;
+        # HML_DATASET_DIR stays unset — sample_id path raises a clean 503
+        # at request time, not at load time. PRIORMDM_PATH defaults to the
+        # bootstrap clone target under EXTERNAL_DIR.
+        "env_overrides_factory": lambda: {
+            "PRIORMDM_PATH": os.environ.get(
+                "PRIORMDM_PATH",
+                str(_COMFYUI_ANIMOFLOW.parent / "priormdm-codes"),
+            ),
+            "WEIGHTS_DIR": os.path.join(
+                os.environ.get("CHECKPOINTS_DIR", "/app/checkpoints"),
+                "priormdm",
+            ),
+            "CHECKPOINT_DIR": os.path.join(
+                os.environ.get("CHECKPOINTS_DIR", "/app/checkpoints"),
+                "priormdm",
+            ),
+        },
+    },
+    # Kimodo lives in escape_hatch/ because of its NVIDIA stack.
+}
+
+# Singletons keyed by model name; populated lazily on first .generate().
+# Once loaded, the model stays warm in process memory.
+_INSTANCES: dict[str, Any] = {}
+_LOAD_LOCK = threading.Lock()
+_LOAD_FAILED: dict[str, str] = {}  # model → error message
+
+
+@contextmanager
+def _isolated_sys_path(extra: Path):
+    """Temporarily prepend `extra` to sys.path. Restores on exit so we don't
+    leak a sibling-module on the path that could shadow other models'
+    imports."""
+    extra_str = str(extra)
+    sys.path.insert(0, extra_str)
+    try:
+        yield
+    finally:
+        try:
+            sys.path.remove(extra_str)
+        except ValueError:
+            pass
+
+
+# Top-level package names that BOTH MDM and MoMask vendor at the root of their
+# respective repos (e.g. `utils/`, `model/`). If MoMask is imported first, its
+# `utils` package gets cached in sys.modules — and a subsequent MDM import
+# then sees MoMask's `utils` (no `config` submodule) and silently fails.
+# Pre-load cleanup is the simplest fix that doesn't require subprocess
+# isolation (and keeps failures loud — no silent fallback).
+_SHADOWING_NAMESPACES = (
+    "utils",
+    "model",
+    "diffusion",
+    "data_loaders",
+    "data_loader",
+    "options",
+    "common",
+    "networks",
+)
+
+
+def _evict_shadowing_modules() -> None:
+    """Pop modules whose names collide across our wrapped upstream repos.
+
+    Called BEFORE each model load so the next model's top-level imports
+    resolve against its own MDM_PATH / MOMASK_PATH directory, not against
+    whatever the previous model left in sys.modules.
+    """
+    evicted: list[str] = []
+    for ns in _SHADOWING_NAMESPACES:
+        # Pop the namespace itself and any cached submodules under it.
+        for key in [k for k in list(sys.modules) if k == ns or k.startswith(ns + ".")]:
+            sys.modules.pop(key, None)
+            evicted.append(key)
+    if evicted:
+        log.info("evicted %d shadowing modules from sys.modules: %s",
+                 len(evicted), ", ".join(sorted(evicted)[:8]) + ("…" if len(evicted) > 8 else ""))
+
+
+def _load(name: str) -> Any:
+    """Load an upstream wrapper module and instantiate its inference class.
+
+    Lazy + thread-safe + memoized. Returns the singleton or raises
+    RuntimeError with a hopefully-actionable message.
+    """
+    with _LOAD_LOCK:
+        if name in _INSTANCES:
+            return _INSTANCES[name]
+        if name in _LOAD_FAILED:
+            raise RuntimeError(
+                f"Model '{name}' previously failed to load: {_LOAD_FAILED[name]}"
+            )
+        if name not in _DEFINITIONS:
+            raise RuntimeError(
+                f"Unknown model '{name}'. Known: {sorted(_DEFINITIONS.keys())}. "
+                "Outlier models (Kimodo, etc.) are handled by escape_hatch/, not this registry."
+            )
+
+        spec = _DEFINITIONS[name]
+        container_dir: Path = spec["container_dir"]
+        if not container_dir.is_dir():
+            msg = (
+                f"Container dir missing for '{name}': {container_dir}. "
+                "Was the comfyui-animoflow clone created at Docker build time?"
+            )
+            _LOAD_FAILED[name] = msg
+            raise RuntimeError(msg)
+
+        # Determine device. Module-level loading goes on CPU (or ZeroGPU
+        # emulation); the @spaces.GPU fork will materialize tensors to real
+        # GPU at call time.
+        device = "cpu"
+        try:
+            import torch
+
+            if torch.cuda.is_available():
+                device = "cuda"
+        except ImportError:
+            pass  # torch not installed in test env — fine, model load will fail later
+
+        log.info("Loading model %r from %s (device=%s)", name, container_dir, device)
+        # Install numpy compat shim BEFORE any model load. MDM (af061ca) uses
+        # `np.float` which was removed in numpy 1.24; momask-codes uses
+        # `np.core.umath_tests.inner1d` removed in numpy 2.0. The shim lives
+        # in pipeline_hf because it's also needed by the retargeter, but it
+        # must fire BEFORE inference too — not just at retarget time, when
+        # MDM's `_load_model` has already crashed. Idempotent.
+        from pipeline_hf import _install_numpy_compat_shim
+        _install_numpy_compat_shim()
+        # Evict any shadowing top-level packages cached from a previously-loaded
+        # model's import (e.g. MoMask's `utils` shadowing MDM's `utils`). This
+        # is what fixes the "[MDM] model load failed (No module named
+        # 'utils.config')" placeholder regression diagnosed 2026-06-08.
+        _evict_shadowing_modules()
+        # Apply per-model env overrides (e.g. MoMask needs CHECKPOINTS_DIR
+        # to point at its own subdir). Reads happen at module import time,
+        # so set BEFORE importlib.import_module. Save originals so other
+        # models (loaded later) see their own values.
+        env_factory = spec.get("env_overrides_factory")
+        env_saved: dict[str, str | None] = {}
+        if env_factory:
+            for k, v in env_factory().items():
+                env_saved[k] = os.environ.get(k)
+                os.environ[k] = v
+                log.info("  env override: %s=%s", k, v)
+        try:
+            try:
+                # Keep container_dir on sys.path PERMANENTLY (in addition to
+                # the temporary insertion below). Some wrappers reference
+                # container-local helper modules from inside their methods
+                # — e.g. priormdm/inference.py:generate() does
+                # `from trajectory_utils import bake_trajectory` lazily.
+                # If container_dir gets popped post-load, that import 500s
+                # at generate-time. This mirrors how MDM/MoMask wrappers
+                # do `sys.path.insert(0, MDM_PATH)` at module-import time
+                # and never remove it.
+                container_dir_str = str(container_dir)
+                if container_dir_str not in sys.path:
+                    sys.path.append(container_dir_str)
+                with _isolated_sys_path(container_dir):
+                    # Re-import the wrapper's module fresh in case another
+                    # model already imported a same-named module.
+                    module_name = spec["module_name"]
+                    saved_module = sys.modules.pop(module_name, None)
+                    try:
+                        mod = importlib.import_module(module_name)
+                        klass = getattr(mod, spec["class_name"])
+                        inst = klass(device=device)
+                    finally:
+                        sys.modules.pop(module_name, None)
+                        if saved_module is not None:
+                            sys.modules[module_name] = saved_module
+            finally:
+                # Restore env even if loading raised.
+                for k, original in env_saved.items():
+                    if original is None:
+                        os.environ.pop(k, None)
+                    else:
+                        os.environ[k] = original
+            _INSTANCES[name] = inst
+            log.info("Loaded %r: %s", name, type(inst).__name__)
+            return inst
+        except Exception as exc:  # noqa: BLE001  (we want to log the full error)
+            msg = f"{type(exc).__name__}: {exc}"
+            _LOAD_FAILED[name] = msg
+            log.exception("Failed to load model %r", name)
+            raise RuntimeError(f"Model '{name}' failed to load: {msg}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def list_models() -> list[str]:
+    """Names of registered models (whether loaded or not)."""
+    return sorted(_DEFINITIONS.keys())
+
+
+def model_status() -> dict[str, str]:
+    """Per-model status: 'loaded' | 'failed' | 'pending'."""
+    out: dict[str, str] = {}
+    for name in _DEFINITIONS:
+        if name in _INSTANCES:
+            out[name] = "loaded"
+        elif name in _LOAD_FAILED:
+            out[name] = "failed"
+        else:
+            out[name] = "pending"
+    return out
+
+
+def generate(
+    name: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    *,
+    guidance_param: float | None = None,
+    **extra: Any,
+) -> tuple[bytes, dict]:
+    """Run the model's .generate() and return (npz_bytes, metadata).
+
+    Loads the model on first call (lazy). Subsequent calls reuse the
+    in-memory instance.
+
+    Inside @spaces.GPU on HF, this runs on real GPU. Outside HF, runs on
+    whatever device torch chose at load time.
+    """
+    inst = _load(name)
+    spec = _DEFINITIONS[name]
+    gen_cfg = spec.get("generate_kwargs", {})
+    kwargs: dict[str, Any] = {
+        "prompt": prompt,
+        "num_frames": num_frames,
+        "seed": seed,
+    }
+    if guidance_param is None:
+        guidance_param = gen_cfg.get("guidance_param_default", 7.5)
+    # Each model uses its own kwarg name (MDM: guidance_param,
+    # MoMask: cond_scale). MoMask raises on unknown kwargs.
+    param_name = gen_cfg.get("guidance_param_name", "guidance_param")
+    kwargs[param_name] = guidance_param
+    kwargs.update(extra)
+
+    npz_bytes, metadata = inst.generate(**kwargs)
+    return npz_bytes, metadata

app.py

@@ -0,0 +1,270 @@
+"""
+animoflow-app — orchestrator entry point.
+
+Mounts a Gradio UI on top of the imported animoflow-api FastAPI app, then
+monkeypatches animoflow-api's `pipeline.run` / `pipeline.run_timeline` with
+our HF-flavored pipeline that calls the GPU-decorated inference function
+in-process and runs all post-processing CPU-side in the orchestrator.
+
+NOTHING in animoflow-api/api/main.py or animoflow-api/api/pipeline.py is
+modified on disk. The wrap-don't-modify rule extends transitively to our
+own repos here.
+
+Order of operations matters:
+  1. sys.path inject /opt/animoflow-api/api so its sibling-module imports
+     (`import config`, `import job_store`, `from auth import …`) resolve.
+  2. Import the `pipeline` module FROM that path.
+  3. Replace pipeline.run / pipeline.run_timeline with our pipeline_hf
+     versions. Functions are looked up at call time inside
+     animoflow-api/api/main.py:_run_pipeline, so monkeypatching after import
+     is enough.
+  4. Import animoflow-api's `main` (which pulls in pipeline by name).
+  5. Build Gradio Blocks and mount them on the FastAPI app at "/".
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO"),
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+log = logging.getLogger("animoflow-app")
+
+# ---------------------------------------------------------------------------
+# Step -2: ensure OUTPUT_DIR is consistent across all modules.
+#
+# pipeline_hf defaults to /tmp/animoflow-output; animoflow-api/api/config.py
+# defaults to a home-directory path. On HF Spaces (Gradio SDK, no Dockerfile ENV),
+# the env var may not be set, so the two defaults diverge and /v1/files/
+# returns 404 (config.OUTPUT_DIR points at a dir the pipeline never wrote to).
+# Fix: plant the env var before any animoflow-api import.
+# ---------------------------------------------------------------------------
+
+os.environ.setdefault("OUTPUT_DIR", "/tmp/animoflow-output")
+
+# HF Space's xet protocol fails with "Permission denied (os error 13)" trying
+# to write its cache logs to /home/user/.cache/huggingface/xet/. Bootstrapping
+# huggingface_hub via the legacy LFS-style download avoids the issue. Surfaced
+# when sentence-transformers landed in requirements.txt and pip resolved
+# transformers up to 5.12 which uses xet by default.
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+
+# ---------------------------------------------------------------------------
+# Step -1: bootstrap external repos + checkpoints when running on HF Gradio
+# Spaces (which have no Docker build phase). No-op in Docker mode.
+# ---------------------------------------------------------------------------
+
+# Make sure our own dir is on sys.path so `import bootstrap` works regardless
+# of how the process was launched.
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+
+import bootstrap as _bootstrap  # noqa: E402
+
+_bootstrap.bootstrap_external_repos()
+
+# ---------------------------------------------------------------------------
+# Step 0: auto-detect Blender for the rig + GLB stages.
+# `MotionRetargeter.bvh_to_fbx` reads $BLENDER_BIN at module load. If it's
+# not set (e.g. a fresh OSS-local Mac dev), we plant the right value here
+# before any retargeter import. The pipeline_hf._find_blender() helper
+# uses the same priority order.
+# ---------------------------------------------------------------------------
+
+import shutil as _shutil
+from pathlib import Path as _Path
+
+if not os.environ.get("BLENDER_BIN", "").strip():
+    for _candidate in (
+        _shutil.which("blender"),
+        "/Applications/Blender.app/Contents/MacOS/Blender",
+        "/opt/blender/blender",
+    ):
+        if _candidate and _Path(_candidate).is_file():
+            os.environ["BLENDER_BIN"] = _candidate
+            log.info("Auto-detected Blender at %s", _candidate)
+            break
+    else:
+        log.warning(
+            "Blender not found on PATH or at common install locations. "
+            "Rig + GLB stages will fail. Set BLENDER_BIN to override."
+        )
+
+# ---------------------------------------------------------------------------
+# Step 1: locate animoflow-api and put its api/ on sys.path
+# ---------------------------------------------------------------------------
+
+_ANIMOFLOW_API_API = os.environ.get(
+    "ANIMOFLOW_API_API_DIR", "/opt/animoflow-api/api"
+)
+if not Path(_ANIMOFLOW_API_API).is_dir():
+    raise RuntimeError(
+        f"animoflow-api/api not found at {_ANIMOFLOW_API_API!r}. "
+        "Set ANIMOFLOW_API_API_DIR or rebuild the Docker image. "
+        "The wrapper repo must be cloned at Docker build time."
+    )
+if _ANIMOFLOW_API_API not in sys.path:
+    sys.path.insert(0, _ANIMOFLOW_API_API)
+
+# ---------------------------------------------------------------------------
+# Step 2: locate animoflow-app's own code on sys.path so pipeline_hf etc.
+# import cleanly when uvicorn is invoked from another cwd.
+# ---------------------------------------------------------------------------
+
+_ANIMOFLOW_APP = Path(__file__).resolve().parent
+if str(_ANIMOFLOW_APP) not in sys.path:
+    sys.path.insert(0, str(_ANIMOFLOW_APP))
+
+# ---------------------------------------------------------------------------
+# Step 3: import animoflow-api's `pipeline` and replace its public functions
+# ---------------------------------------------------------------------------
+
+import pipeline as _animoflow_api_pipeline  # noqa: E402  (animoflow-api's module)
+import pipeline_hf  # noqa: E402  (ours, replaces the ComfyUI-orchestrated path)
+
+_animoflow_api_pipeline.run = pipeline_hf.run
+_animoflow_api_pipeline.run_timeline = pipeline_hf.run_timeline
+log.info("Monkeypatched animoflow-api pipeline.run / run_timeline → pipeline_hf")
+
+# ---------------------------------------------------------------------------
+# Step 4: import the FastAPI app from animoflow-api/api/main.py
+# ---------------------------------------------------------------------------
+
+from main import app as fastapi_app  # noqa: E402
+
+log.info("Imported animoflow-api FastAPI app (title=%r)", fastapi_app.title)
+
+# ---------------------------------------------------------------------------
+# Step 4b: warm up the multilingual prompt rewriter in the parent process so
+# the @spaces.GPU fork inherits the loaded Qwen + MiniLM + corpus via COW on
+# every subsequent call. Without this, the very first GPU rewrite has to
+# pay the model-load + CUDA-move cost INSIDE the @GPU budget, and gets killed
+# by ZeroGPU with 'GPU task aborted' once it exceeds the duration.
+# Same eager-load pattern as the MDM registry (animoflow_models/registry.py).
+# ---------------------------------------------------------------------------
+try:
+    import rewriter as _rewriter  # noqa: E402  (animoflow-api's module)
+    _rewriter.warmup()
+    log.info("Rewriter warmed up in orchestrator process")
+except ImportError:
+    log.warning("Rewriter module not on sys.path — skipping warmup")
+except Exception as e:
+    log.warning("Rewriter warmup raised — first /v1/jobs request will retry: %s", e)
+
+# ---------------------------------------------------------------------------
+# Step 5: build the Gradio Blocks UI and mount on "/"
+# ---------------------------------------------------------------------------
+
+import gradio as gr  # noqa: E402
+from ui import build_blocks  # noqa: E402
+
+_blocks = build_blocks()
+
+# Kimodo health surface. animoflow-api's _MODEL_HEALTH_URLS polls
+# ${KIMODO_ENDPOINT}/health every HEALTH_POLL_INTERVAL seconds. Default
+# KIMODO_ENDPOINT in animoflow-api/api/config.py points at localhost:8005
+# (the local-stack Docker container), which is unreachable inside the HF
+# Space. bootstrap._set_env_for_kimodo plants KIMODO_ENDPOINT pointing at
+# this in-process route — Kimodo surfaces as available in /v1/models (and
+# the webUI dropdown) once the venv build finishes.
+@fastapi_app.get("/__internal/kimodo/health")
+def _kimodo_internal_health():  # noqa: D401
+    from fastapi.responses import JSONResponse
+    # escape_hatch/__init__.py does `from .invoke import invoke` which
+    # overwrites the submodule reference with the function. Even
+    # `import escape_hatch.invoke as X` then binds X to the function. Pull
+    # the module straight from sys.modules to bypass the shadowing.
+    import escape_hatch  # noqa: F401 — ensure escape_hatch.invoke is in sys.modules
+    import sys as _sys
+    _ehi = _sys.modules["escape_hatch.invoke"]
+
+    if os.environ.get("ENABLE_KIMODO", "true").strip().lower() == "false":
+        return JSONResponse(status_code=503, content={"status": "disabled"})
+    failed = _ehi._kimodo_failed_message()
+    if failed:
+        return JSONResponse(
+            status_code=503,
+            content={"status": "failed", "error": failed[:400]},
+        )
+    event = _ehi._KIMODO_READY
+    ready_sentinel = _ehi._external_dir() / ".kimodo_ready"
+    ready = ready_sentinel.is_file() or (event is not None and event.is_set())
+    if ready:
+        return {"status": "ok"}
+    return JSONResponse(status_code=503, content={"status": "warming"})
+
+
+# `gr.mount_gradio_app` registers Gradio's routes on the FastAPI app.
+# WEB_DIR=/nonexistent in our Dockerfile makes animoflow-api skip its
+# StaticFiles("/") catch-all, so "/" is free for Gradio to claim.
+_output_dir = os.environ.get("OUTPUT_DIR", "/tmp/animoflow-output")
+fastapi_app = gr.mount_gradio_app(
+    fastapi_app, _blocks, path="/",
+    allowed_paths=[_output_dir],
+)
+log.info("Mounted Gradio UI at / (allowed_paths=%s)", [_output_dir])
+
+# HF Gradio SDK auto-detection: expose `demo` at module level
+demo = _blocks
+
+
+def main() -> None:
+    """Local-dev convenience entry: `python app.py` boots uvicorn."""
+    import uvicorn
+
+    uvicorn.run(
+        "app:fastapi_app",
+        host="0.0.0.0",
+        port=int(os.environ.get("PORT", "7860")),
+        log_level=os.environ.get("LOG_LEVEL", "info").lower(),
+    )
+
+
+if __name__ == "__main__":
+    if os.environ.get("SPACE_ID"):
+        # On HF Gradio SDK — ZeroGPU requires demo.launch() for GPU
+        # registration. We monkey-patch Gradio's app factory to inject
+        # our /v1/* FastAPI routes into the Gradio-managed app.
+        import gradio.routes as _gr_routes
+
+        _orig_create = _gr_routes.App.create_app
+
+        def _patched_create(blocks, **kw):
+            gapp = _orig_create(blocks, **kw)
+            # Inject animoflow-api's API routes. PREPEND, don't append —
+            # Starlette matches routes in registration order and Gradio
+            # ships its own `/openapi.json`, `/docs`, `/redoc` that would
+            # otherwise win and serve Gradio's internal spec instead of
+            # animoflow-api's branded one (title: "AnimoFlow API",
+            # 10 documented /v1/* routes). Inserting at index 0 in
+            # reverse iteration order preserves animoflow-api's own
+            # ordering. The /v1/* + /oauth/* routes were already unique
+            # to animoflow-api so prepending doesn't change their
+            # behavior — only the spec-surface routes flip to ours.
+            for route in reversed(list(fastapi_app.routes)):
+                gapp.routes.insert(0, route)
+            # Copy middleware
+            for mw in fastapi_app.user_middleware:
+                gapp.add_middleware(mw.cls, **mw.kwargs)
+            # Copy exception handlers
+            for exc_cls, handler in fastapi_app.exception_handlers.items():
+                gapp.add_exception_handler(exc_cls, handler)
+            # slowapi's RateLimitExceeded handler reads
+            # request.app.state.limiter — and request.app here is THIS
+            # Gradio app, not animoflow-api's. Without this line every
+            # rate-limit hit 500s with AttributeError instead of a 429
+            # (found 2026-07-06 by the quota probe's parallel round).
+            gapp.state.limiter = fastapi_app.state.limiter
+            log.info("Injected animoflow-api routes into Gradio app (prepended for /openapi.json + /redoc + /docs precedence)")
+            return gapp
+
+        _gr_routes.App.create_app = _patched_create
+        demo.launch(allowed_paths=[_output_dir])
+    else:
+        main()

bootstrap.py

@@ -0,0 +1,1416 @@
+"""
+Bootstrap external repos + checkpoints when running on HF Gradio SDK
+Spaces (no Docker build phase to do it for us).
+
+In Docker mode the Dockerfile already cloned the wrapper + upstream repos
+and downloaded the baked checkpoints, so this module is a no-op there.
+On HF Gradio Spaces (or any clean OSS-local checkout where the user
+hasn't already provisioned external repos), we git-clone everything to
+a known base dir and call `huggingface_hub.snapshot_download` for the
+checkpoints.
+
+Auth:
+  * Private GitHub repos via the `gh_token` env var (Space secret on HF;
+    plain env var locally).
+  * Private HF Hub repo via `hf_token` env var.
+
+Both never persisted to disk: the gh_token is used in a clone URL only
+during the clone, then stripped from the remote URL post-clone.
+
+Idempotent — safe to call multiple times. Skips any repo / file that
+already exists at the target path.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Config — overridable via env vars so OSS users can point this anywhere.
+# ---------------------------------------------------------------------------
+
+# Base dir for cloned external repos. On HF Gradio Spaces the working
+# directory is /home/user/app/, so external/ sits next to the app code.
+# In Docker mode the Dockerfile uses /opt/* and this whole module is a no-op
+# (the Docker-mode marker is COMFYUI_ANIMOFLOW_DIR pointing at /opt/...).
+_DEFAULT_EXTERNAL = (
+    "/home/user/app/external"
+    if os.path.isdir("/home/user/app")
+    else str(Path(__file__).resolve().parent / "external")
+)
+
+EXTERNAL_DIR = Path(os.environ.get("ANIMOFLOW_EXTERNAL_DIR", _DEFAULT_EXTERNAL))
+
+# Pinned upstream SHAs / revisions. Bump deliberately, not via git pull.
+# MDM repo HEAD diverged (BERT encoder, refactored encode_text → shape
+# changes, new imports) and breaks text-conditioned generation.  Pin to the
+# last known-good commit that matches the checkpoint's architecture.
+MDM_PINNED_COMMIT = os.environ.get("MDM_PINNED_COMMIT", "af061ca")
+
+# Optional pins for AnimoFlow's own repos (empty = track main, today's
+# behavior). Set these as Space variables at release time so a rebuild can
+# never silently pick up newer main — e.g. the v0.1.0-beta tag's SHAs.
+COMFYUI_PINNED_COMMIT = os.environ.get("COMFYUI_PINNED_COMMIT", "")
+API_PINNED_COMMIT = os.environ.get("API_PINNED_COMMIT", "")
+
+ANIMOFLOW_CHECKPOINTS_REPO = os.environ.get(
+    "ANIMOFLOW_CHECKPOINTS_REPO", "AnimoFlow/animoflow-checkpoints"
+)
+ANIMOFLOW_CHECKPOINTS_REVISION = os.environ.get(
+    "ANIMOFLOW_CHECKPOINTS_REVISION",
+    # 841707a = Pete removed; f0af610 = The Boss removed (2026-07-03,
+    # Guy's call). Predecessor
+    # cfbfe3c = first commit with characters/** (2026-07-03 webui character
+    # bake — Mixamo FBXs live in this private repo, NOT in public
+    # comfyui-animoflow; current roster: Vanguard/Knight/Suzie/Doozy). Predecessor
+    # ff21939 was the first commit with priormdm/** (2026-06-21); its
+    # predecessor 6df4521 had momask/t2m/** but no priorMDM, so
+    # snapshot_download with allow_patterns=["priormdm/**"] globbed nothing
+    # and the registry's _load("priormdm") failed cleanly at first call —
+    # same bug class would hit characters/** on any pre-cfbfe3c revision.
+    # 2026-07-06: characters/** moved OUT to ANIMOFLOW_CHARACTER_ASSETS_REPO
+    # (Adobe-content isolation); this repo/revision now feeds weights only.
+    "841707a1584c2ffc6085fff44f5b00c555fab634",
+)
+
+ANIMOFLOW_CHARACTER_ASSETS_REPO = os.environ.get(
+    "ANIMOFLOW_CHARACTER_ASSETS_REPO", "AnimoFlow/character-assets"
+)
+ANIMOFLOW_CHARACTER_ASSETS_REVISION = os.environ.get(
+    "ANIMOFLOW_CHARACTER_ASSETS_REVISION",
+    # 07d4ab0 = adds Y_bot + Kaya (2026-07-07), byte-identical to the FBXs
+    # comfyui-animoflow@7a91fa3 untracked for public launch — full 6-rig
+    # roster now lives here. Predecessor
+    # eec5ed0 = initial commit (2026-07-06): byte-identical characters/**
+    # split out of animoflow-checkpoints@841707a — Adobe Mixamo FBXs get
+    # their own private repo so the checkpoints repo can be shared without
+    # dragging Adobe-licensed content along, and so tokens can be scoped
+    # per-repo. eec5ed0 only mirrored the 4 checkpoints-repo rigs
+    # (Doozy/Knight/Suzie/Vanguard) — Y_bot/Kaya lived in comfyui HEAD, so
+    # the roster silently dropped to 4 on the first deploy of the split.
+    # Same silent-glob bug class as documented on
+    # ANIMOFLOW_CHECKPOINTS_REVISION applies: allow_patterns=
+    # ["characters/**"] globs NOTHING (no error) on a revision lacking the
+    # folder — this repo has it from commit one, but keep the pin anyway.
+    # NEVER super_squash_history either private repo: pins die with it.
+    "07d4ab0955b80af50db35847bf9b01d33087e710",
+)
+
+# Marker that says "Docker mode already provisioned everything" — if any of
+# these exist we skip the bootstrap entirely.
+_DOCKER_MODE_PATHS = (
+    "/opt/comfyui-animoflow",
+    "/opt/animoflow-api",
+)
+
+# What we need to clone. (repo_name, target_subdir, is_private).
+_GIT_REPOS: tuple[tuple[str, str, str, bool], ...] = (
+    # (full_url_template_or_url, target_subdir, friendly_name, private)
+    (
+        "https://github.com/AnimoFlow/comfyui-animoflow.git",
+        "comfyui-animoflow",
+        "comfyui-animoflow",
+        True,
+    ),
+    (
+        "https://github.com/AnimoFlow/animoflow-api.git",
+        "animoflow-api",
+        "animoflow-api",
+        True,
+    ),
+    (
+        "https://github.com/GuyTevet/motion-diffusion-model.git",
+        "mdm-codes",
+        "mdm-codes",
+        False,
+    ),
+    (
+        "https://github.com/EricGuo5513/momask-codes.git",
+        "momask-codes",
+        "momask-codes",
+        False,
+    ),
+    (
+        "https://github.com/priorMDM/priorMDM.git",
+        "priormdm-codes",
+        "priormdm-codes",
+        False,
+    ),
+)
+
+
+# Kimodo source repos cloned separately (not in _GIT_REPOS) so that the
+# ENABLE_KIMODO kill-switch can skip them entirely without affecting MDM/MoMask.
+# kimodo-viser is cloned NESTED inside kimodo-src/ to match the editable-install
+# layout the upstream Dockerfile expects (containers/kimodo/Dockerfile:22).
+_KIMODO_REPOS: tuple[tuple[str, str, str], ...] = (
+    ("https://github.com/nv-tlabs/kimodo.git", "kimodo-src", "kimodo-src"),
+    ("https://github.com/nv-tlabs/kimodo-viser.git", "kimodo-src/kimodo-viser", "kimodo-viser"),
+)
+
+
+def _docker_mode() -> bool:
+    """Return True if the Dockerfile already provisioned the external repos."""
+    return any(Path(p).is_dir() for p in _DOCKER_MODE_PATHS)
+
+
+# Blender 5.0.1 portable Linux tarball. Replaces Debian Trixie's apt Blender
+# (4.3.2) — its retarget runtime was ~75x slower per stage timings.
+_BLENDER_VERSION = "5.0.1"
+_BLENDER_TARBALL_URL = (
+    f"https://download.blender.org/release/Blender5.0/"
+    f"blender-{_BLENDER_VERSION}-linux-x64.tar.xz"
+)
+_BLENDER_INSTALL_DIR = Path("/home/user/app") / f"blender-{_BLENDER_VERSION}-linux-x64"
+_BLENDER_BIN_PATH = _BLENDER_INSTALL_DIR / "blender"
+
+
+# gltfpack (meshoptimizer) — Draco + Meshopt GLB compression for Plan A.
+# Used by pipeline_hf._compress_glb. Pinning to a release tag (not SHA) because
+# upstream releases are stable artifacts — see [[preview-perf-2026-06-08
+# -handoff]] gotcha 10.
+_GLTFPACK_VERSION = "1.1"
+_GLTFPACK_ZIP_URL = (
+    f"https://github.com/zeux/meshoptimizer/releases/download/"
+    f"v{_GLTFPACK_VERSION}/gltfpack-ubuntu.zip"
+)
+_GLTFPACK_INSTALL_DIR = Path("/home/user/app/bin")
+_GLTFPACK_BIN_PATH = _GLTFPACK_INSTALL_DIR / "gltfpack"
+
+
+def _install_gltfpack() -> None:
+    """Install gltfpack (from meshoptimizer) for GLB compression.
+
+    Used by pipeline_hf._compress_glb to apply Draco (geometry) + Meshopt
+    (animation tracks + remaining buffers) compression to the GLB output.
+    Validated 9.74x compression on a production Y_bot GLB (2.65 MB → 272 KB)
+    pre-deployment.
+
+    Per the no-silent-fallback rule:
+    if the download or extract fails, raise. The Space must boot loudly
+    on this kind of failure, not boot cleanly and only blow up on the
+    first /generate call with a confusing "gltfpack not found" error.
+
+    Idempotent — if the binary is already present and executable, just
+    plant GLTFPACK_BIN and return. No-op in Docker mode (the container
+    image is responsible for its own tooling).
+    """
+    import time
+    import urllib.request
+    import zipfile
+
+    if _docker_mode():
+        log.info("_install_gltfpack: docker mode, skip (container handles it)")
+        return
+
+    if _GLTFPACK_BIN_PATH.is_file() and os.access(_GLTFPACK_BIN_PATH, os.X_OK):
+        os.environ["GLTFPACK_BIN"] = str(_GLTFPACK_BIN_PATH)
+        log.info("_install_gltfpack: already installed at %s", _GLTFPACK_BIN_PATH)
+        return
+
+    log.info("_install_gltfpack: downloading gltfpack %s from %s",
+             _GLTFPACK_VERSION, _GLTFPACK_ZIP_URL)
+    t0 = time.perf_counter()
+    zip_path = Path("/tmp") / f"gltfpack-{_GLTFPACK_VERSION}.zip"
+
+    # GitHub release downloads work with default Python urllib UA, but
+    # mirror the Blender installer's defensive Mozilla UA — cheap insurance
+    # if Cloudflare ever changes its mind about default Python clients.
+    req = urllib.request.Request(
+        _GLTFPACK_ZIP_URL,
+        headers={"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"},
+    )
+    with urllib.request.urlopen(req, timeout=120) as src, open(zip_path, "wb") as dst:
+        shutil.copyfileobj(src, dst)
+    log.info("_install_gltfpack: downloaded in %.1fs (%d KB)",
+             time.perf_counter() - t0, zip_path.stat().st_size // 1024)
+
+    _GLTFPACK_INSTALL_DIR.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        zf.extractall(_GLTFPACK_INSTALL_DIR)
+    try:
+        zip_path.unlink()
+    except OSError:
+        pass
+
+    if not _GLTFPACK_BIN_PATH.is_file():
+        raise RuntimeError(
+            f"_install_gltfpack: expected binary at {_GLTFPACK_BIN_PATH} after "
+            f"extracting {_GLTFPACK_ZIP_URL} — upstream asset layout may have "
+            f"changed; check `gh release view v{_GLTFPACK_VERSION} -R "
+            f"zeux/meshoptimizer --json assets`"
+        )
+    os.chmod(_GLTFPACK_BIN_PATH, 0o755)
+    os.environ["GLTFPACK_BIN"] = str(_GLTFPACK_BIN_PATH)
+    log.info("_install_gltfpack: installed at %s (%d KB)",
+             _GLTFPACK_BIN_PATH, _GLTFPACK_BIN_PATH.stat().st_size // 1024)
+
+
+def _install_blender_portable() -> None:
+    """Install Blender 5.0.1 portable Linux tarball and point BLENDER_BIN at it.
+
+    Replaces Debian Trixie's apt Blender 4.3.2 which is ~75x slower at the
+    BVH→FBX retarget step per the Space's [STAGE_TIMINGS] (~90s/job vs ~1.2s
+    on Mac native Blender 5.0.1).
+
+    Idempotent: if the binary already exists at the install path, just sets
+    BLENDER_BIN and returns. No-op in Docker mode (the container's
+    Dockerfile.cpu already pins its own Blender).
+    """
+    import subprocess as _subproc
+    import tarfile
+    import time
+    import urllib.request
+
+    if _docker_mode():
+        log.info("_install_blender_portable: docker mode, skip (container handles Blender)")
+        return
+
+    # Idempotency check — survives Space restarts when /home/user/app persists
+    if _BLENDER_BIN_PATH.is_file():
+        os.environ["BLENDER_BIN"] = str(_BLENDER_BIN_PATH)
+        log.info("_install_blender_portable: already installed at %s", _BLENDER_BIN_PATH)
+        return
+
+    log.info("_install_blender_portable: downloading Blender %s (~360 MB) from %s",
+             _BLENDER_VERSION, _BLENDER_TARBALL_URL)
+    t0 = time.perf_counter()
+    tarball_path = Path("/tmp") / f"blender-{_BLENDER_VERSION}-linux-x64.tar.xz"
+    # download.blender.org is Cloudflare-fronted and 403s on default Python UA.
+    req = urllib.request.Request(
+        _BLENDER_TARBALL_URL,
+        headers={"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=300) as src, open(tarball_path, "wb") as dst:
+            while True:
+                chunk = src.read(1024 * 1024)
+                if not chunk:
+                    break
+                dst.write(chunk)
+    except Exception as e:
+        log.warning("_install_blender_portable: download FAILED (%s) — falling back to apt Blender", e)
+        return
+    log.info("_install_blender_portable: downloaded in %.1fs (%d MB)",
+             time.perf_counter() - t0, tarball_path.stat().st_size // (1024 * 1024))
+
+    t1 = time.perf_counter()
+    install_parent = _BLENDER_INSTALL_DIR.parent
+    install_parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with tarfile.open(tarball_path, "r:xz") as tar:
+            tar.extractall(install_parent)
+    except Exception as e:
+        log.warning("_install_blender_portable: extract FAILED (%s) — falling back to apt Blender", e)
+        return
+    try:
+        tarball_path.unlink()
+    except Exception:
+        pass
+    log.info("_install_blender_portable: extracted in %.1fs to %s",
+             time.perf_counter() - t1, _BLENDER_INSTALL_DIR)
+
+    if not _BLENDER_BIN_PATH.is_file():
+        log.warning("_install_blender_portable: binary missing at %s after extract — falling back to apt Blender",
+                    _BLENDER_BIN_PATH)
+        return
+
+    os.environ["BLENDER_BIN"] = str(_BLENDER_BIN_PATH)
+
+    # Smoke test
+    try:
+        ver = _subproc.run(
+            [str(_BLENDER_BIN_PATH), "--version"],
+            capture_output=True, text=True, timeout=30,
+        )
+        first_line = (ver.stdout or "").splitlines()[0] if ver.stdout else ""
+        log.info("_install_blender_portable: BLENDER_BIN=%s | %s",
+                 _BLENDER_BIN_PATH, first_line or "<no output>")
+    except Exception as e:
+        log.warning("_install_blender_portable: version smoke failed (%s) but BLENDER_BIN set anyway", e)
+
+
+# ---------------------------------------------------------------------------
+# Kimodo escape-hatch venv builder
+# ---------------------------------------------------------------------------
+# Kimodo's NVIDIA stack pins transformers==5.1.0 + py-soma-x + warp-lang etc.
+# which fight the MDM/MoMask pins in the orchestrator venv. We isolate it in
+# /home/user/app/venvs/kimodo/ and invoke via subprocess from escape_hatch.
+# Build runs in a background thread so the Gradio UI comes up promptly and
+# MDM/MoMask stay usable while Kimodo warms (~5-10 min cold install: pip deps
+# + 16 GB LLaMA-3-8B encoder download).
+#
+# Sentinels in EXTERNAL_DIR:
+#   .kimodo_ready  — venv built, weights cached. Set on success.
+#   .kimodo_failed — captured error text. Set on any failure during install.
+#
+# Per the no-silent-fallback rule: any failure raises loudly and writes
+# .kimodo_failed; the runner script + escape_hatch.invoke surface it to the UI.
+
+_KIMODO_VENV_DIR = Path("/home/user/app/venvs/kimodo")
+_KIMODO_BUILD_THREAD: "threading.Thread | None" = None
+_KIMODO_BUILD_EVENT: "threading.Event | None" = None  # set when ready
+
+
+def _kimodo_ready_sentinel() -> Path:
+    return EXTERNAL_DIR / ".kimodo_ready"
+
+
+def _kimodo_failed_sentinel() -> Path:
+    return EXTERNAL_DIR / ".kimodo_failed"
+
+
+def _kimodo_text_encoders_dir() -> Path:
+    return EXTERNAL_DIR / "text-encoders"
+
+
+def _kimodo_assets_dir() -> Path:
+    return EXTERNAL_DIR / "kimodo-assets"
+
+
+def _kimodo_src_dir() -> Path:
+    return EXTERNAL_DIR / "kimodo-src"
+
+
+def _clone_kimodo_repos() -> None:
+    """Clone Kimodo + kimodo-viser. Idempotent. Skipped via ENABLE_KIMODO=false."""
+    EXTERNAL_DIR.mkdir(parents=True, exist_ok=True)
+    for url, subdir, name in _KIMODO_REPOS:
+        target = EXTERNAL_DIR / subdir
+        if target.is_dir():
+            log.info("kimodo-clone: %s already at %s — skip", name, target)
+            continue
+        log.info("kimodo-clone (public): %s → %s", name, target)
+        _git_clone(url, target)
+
+
+def _patch_kimodo_requirements() -> None:
+    """Strip MotionCorrection from Kimodo's lockfile (C++ post-processor that
+    needs cmake + CUDA; we don't use post-processing). Mirrors the Docker
+    Dockerfile RUN sed -i '/MotionCorrection/d' line. Idempotent."""
+    req_path = _kimodo_src_dir() / "docker_requirements.txt"
+    if not req_path.is_file():
+        log.warning("_patch_kimodo_requirements: %s not found, skipping", req_path)
+        return
+    text = req_path.read_text()
+    if "MotionCorrection" not in text:
+        log.info("_patch_kimodo_requirements: already stripped — skip")
+        return
+    new_lines = [ln for ln in text.splitlines(keepends=True) if "MotionCorrection" not in ln]
+    req_path.write_text("".join(new_lines))
+    log.info("_patch_kimodo_requirements: stripped MotionCorrection from %s", req_path)
+
+
+def _kimodo_venv_python() -> Path:
+    return _KIMODO_VENV_DIR / "bin" / "python"
+
+
+def _ensure_kimodo_venv() -> None:
+    """Create the venv with stdlib `venv`. Idempotent."""
+    if _kimodo_venv_python().is_file():
+        log.info("_ensure_kimodo_venv: venv already at %s — skip", _KIMODO_VENV_DIR)
+        return
+    log.info("_ensure_kimodo_venv: creating venv at %s", _KIMODO_VENV_DIR)
+    _KIMODO_VENV_DIR.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        [sys.executable, "-m", "venv", str(_KIMODO_VENV_DIR)],
+        check=True, capture_output=True, text=True,
+    )
+
+
+def _kimodo_pip(*args: str, env_extra: dict | None = None, cwd: str | None = None) -> None:
+    """Run pip inside the Kimodo venv. Raises on non-zero.
+
+    ``cwd`` is required when the lockfile contains relative editable paths
+    like ``-e ./kimodo-viser`` (Kimodo's ``docker_requirements.txt`` does
+    this). The upstream Dockerfile changes directory before running pip;
+    mirror that.
+    """
+    cmd = [str(_kimodo_venv_python()), "-m", "pip", *args]
+    log.info(
+        "kimodo-pip%s: %s",
+        f" (cwd={cwd})" if cwd else "",
+        " ".join(args[:3]) + (" …" if len(args) > 3 else ""),
+    )
+    env = {**os.environ, **(env_extra or {})}
+    proc = subprocess.run(cmd, capture_output=True, text=True, env=env, cwd=cwd)
+    if proc.returncode != 0:
+        # Surface tail of stderr AND stdout (pip writes most of its useful
+        # diagnostics to stdout, not stderr) so the .kimodo_failed sentinel
+        # captures the actionable detail. 4000 chars each is generous but
+        # the sentinel is one-shot per build attempt.
+        raise RuntimeError(
+            f"kimodo-pip failed (rc={proc.returncode}): {' '.join(args[:8])}\n"
+            f"stdout (last 4000 chars): {proc.stdout[-4000:]}\n"
+            f"stderr (last 4000 chars): {proc.stderr[-4000:]}"
+        )
+
+
+def _install_kimodo_deps() -> None:
+    """Install Kimodo's pinned lockfile into the Kimodo venv."""
+    req = _kimodo_src_dir() / "docker_requirements.txt"
+    if not req.is_file():
+        raise RuntimeError(f"Kimodo docker_requirements.txt missing at {req}")
+    # Upgrade pip + install wheel/setuptools first. The Kimodo Docker image
+    # is based on nvcr.io/nvidia/pytorch which ships these; our stdlib venv
+    # does not, and some pinned deps build sdists that need `wheel` present.
+    _kimodo_pip("install", "--upgrade", "pip", "setuptools", "wheel")
+    # docker_requirements.txt contains `-e ./kimodo-viser` (relative editable
+    # install). pip resolves it against the current working directory, so we
+    # must `cd` into kimodo-src — matching containers/kimodo/Dockerfile L30
+    # (`RUN cd /workspace/kimodo-src && pip install -r docker_requirements.txt`).
+    # The lockfile also triggers py-soma-x's setup.py which conditionally
+    # imports MotionCorrection if SKIP_MOTION_CORRECTION_IN_SETUP is unset.
+    _kimodo_pip(
+        "install", "-r", "docker_requirements.txt",
+        env_extra={"SKIP_MOTION_CORRECTION_IN_SETUP": "1"},
+        cwd=str(_kimodo_src_dir()),
+    )
+
+
+def _prefetch_llama_encoder(hf_token: str | None) -> None:
+    """Pre-fetch LLaMA-3-8B (NousResearch ungated mirror) into the
+    text-encoders dir so first inference doesn't pay the ~16 GB download."""
+    # Use the ORCHESTRATOR's huggingface_hub (cheaper than spawning the Kimodo
+    # venv just to download). Both venvs see the same EXTERNAL_DIR mount.
+    from huggingface_hub import snapshot_download
+
+    target = _kimodo_text_encoders_dir() / "NousResearch" / "Meta-Llama-3-8B-Instruct"
+    if (target / "config.json").is_file():
+        log.info("_prefetch_llama_encoder: already at %s — skip", target)
+        return
+    target.parent.mkdir(parents=True, exist_ok=True)
+    log.info("_prefetch_llama_encoder: downloading ~16 GB to %s", target)
+    snapshot_download(
+        repo_id="NousResearch/Meta-Llama-3-8B-Instruct",
+        local_dir=str(target),
+        token=hf_token,  # works with or without token (this repo is ungated)
+    )
+
+
+
+def _patch_llm2vec_configs() -> None:
+    """Rewrite LLM2Vec adapter configs to point at the ungated LLaMA mirror.
+
+    Reuses comfyui-animoflow/containers/kimodo/app.py:_patch_llm2vec_for_ungated_llama
+    by importing it as a plain function (no FastAPI app served)."""
+    container_kimodo = (
+        Path(os.environ.get("COMFYUI_ANIMOFLOW_DIR", str(EXTERNAL_DIR / "comfyui-animoflow")))
+        / "containers" / "kimodo"
+    )
+    app_py = container_kimodo / "app.py"
+    if not app_py.is_file():
+        raise RuntimeError(
+            f"_patch_llm2vec_configs: helper not found at {app_py}. "
+            "comfyui-animoflow must be cloned before this step."
+        )
+    # Plant TEXT_ENCODERS_DIR + HF_HOME so the helper writes to our paths.
+    os.environ["TEXT_ENCODERS_DIR"] = str(_kimodo_text_encoders_dir())
+    # Import-via-spec so the module's top-level FastAPI construction doesn't
+    # require Kimodo deps in the orchestrator venv (the helper itself only
+    # needs huggingface_hub which we have).
+    import importlib.util as _ilu
+    spec = _ilu.spec_from_file_location("_kimodo_helpers", app_py)
+    mod = _ilu.module_from_spec(spec)  # type: ignore[arg-type]
+    # The helper imports torch + fastapi at module top. To dodge those when
+    # we only want the config rewrite, monkey-load the source and exec only
+    # the function we need.
+    source = app_py.read_text()
+    # Extract just the _patch_llm2vec_for_ungated_llama function by string
+    # slicing — small, stable surface. Falls back to full module exec if the
+    # markers move (with a clearer error than NameError later).
+    start = source.find("def _patch_llm2vec_for_ungated_llama")
+    if start < 0:
+        raise RuntimeError(
+            "_patch_llm2vec_configs: marker 'def _patch_llm2vec_for_ungated_llama' "
+            f"not found in {app_py}. Source layout changed; update bootstrap."
+        )
+    # Find the end of the function — next top-level def or end of file.
+    end_markers = ("\ndef ", "\nclass ", "\n# -")
+    end = len(source)
+    for m in end_markers:
+        idx = source.find(m, start + 1)
+        if idx > 0:
+            end = min(end, idx)
+    fn_source = source[start:end]
+    # The function also references module-level constants we need to plant.
+    preamble = (
+        "import json, os\n"
+        "from pathlib import Path\n"
+        "from huggingface_hub import snapshot_download\n"
+        f"_ENCODERS_DIR = {str(_kimodo_text_encoders_dir())!r}\n"
+        "_UNGATED_LLAMA = 'NousResearch/Meta-Llama-3-8B-Instruct'\n"
+        "_LLM2VEC_ADAPTERS = [\n"
+        "    'McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp',\n"
+        "    'McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised',\n"
+        "]\n"
+    )
+    ns: dict = {}
+    exec(preamble + fn_source, ns)  # noqa: S102 — controlled source from our own repo
+    ns["_patch_llm2vec_for_ungated_llama"]()
+    log.info("_patch_llm2vec_configs: LLM2Vec adapter configs rewired to ungated LLaMA")
+
+
+def _audit_disk() -> None:
+    """Loud warning if /home/user/app is approaching the HF Space quota."""
+    try:
+        proc = subprocess.run(
+            ["du", "-sh", "/home/user/app"],
+            capture_output=True, text=True, timeout=30,
+        )
+        log.info("kimodo-bootstrap: disk usage %s", proc.stdout.strip())
+    except Exception as e:  # noqa: BLE001
+        log.warning("kimodo-bootstrap: disk audit failed: %s", e)
+
+
+def _install_kimodo_sync(hf_token: str | None) -> None:
+    """Synchronous Kimodo venv build. Called from a background thread by
+    _install_kimodo_async. Sets .kimodo_ready on success or .kimodo_failed on
+    any error, both consumed by run_inference_kimodo.py + escape_hatch.invoke.
+    """
+    import time
+    t0 = time.perf_counter()
+    failed_sentinel = _kimodo_failed_sentinel()
+    ready_sentinel = _kimodo_ready_sentinel()
+    # Clear stale sentinels from previous attempts.
+    for s in (failed_sentinel, ready_sentinel):
+        try:
+            s.unlink()
+        except FileNotFoundError:
+            pass
+    try:
+        log.info("[kimodo-bootstrap] starting")
+        _clone_kimodo_repos()
+        _patch_kimodo_requirements()
+        _ensure_kimodo_venv()
+        _install_kimodo_deps()
+        _prefetch_llama_encoder(hf_token)
+        _patch_llm2vec_configs()
+        _audit_disk()
+        ready_sentinel.write_text("ok\n")
+        if _KIMODO_BUILD_EVENT is not None:
+            _KIMODO_BUILD_EVENT.set()
+        log.info(
+            "[kimodo-bootstrap] ready in %.0fs (venv=%s, ready=%s)",
+            time.perf_counter() - t0, _KIMODO_VENV_DIR, ready_sentinel,
+        )
+    except Exception as exc:  # noqa: BLE001 — capture everything so UI can show it
+        import traceback
+        msg = f"{type(exc).__name__}: {exc}\n\n{traceback.format_exc()}"
+        try:
+            failed_sentinel.write_text(msg)
+        except Exception:
+            pass
+        log.exception("[kimodo-bootstrap] FAILED after %.0fs", time.perf_counter() - t0)
+        # Don't re-raise: background thread exits, but the sentinel + UI surface
+        # the error. escape_hatch.invoke reads .kimodo_failed and refuses to
+        # call into a broken venv.
+
+
+def _install_kimodo_async(hf_token: str | None) -> None:
+    """Kick off Kimodo build in a daemon thread. Returns immediately. Calling
+    again is a no-op if the build is already running, ready, or failed."""
+    import threading as _threading
+    global _KIMODO_BUILD_THREAD, _KIMODO_BUILD_EVENT
+
+    if _KIMODO_BUILD_EVENT is None:
+        _KIMODO_BUILD_EVENT = _threading.Event()
+    # Expose the event on escape_hatch.invoke for the readiness gate.
+    # NOTE: escape_hatch/__init__.py does `from .invoke import invoke` which
+    # overwrites the submodule reference with the function — even
+    # `import escape_hatch.invoke as X` then binds X to the function. Pull
+    # the module from sys.modules to bypass the shadowing.
+    try:
+        import escape_hatch  # noqa: F401 — ensures escape_hatch.invoke is loaded
+        import sys as _sys
+        _ehi = _sys.modules["escape_hatch.invoke"]
+        _ehi._KIMODO_READY = _KIMODO_BUILD_EVENT  # type: ignore[attr-defined]
+    except Exception:  # noqa: BLE001
+        # escape_hatch import may fail during early bootstrap; the runner
+        # also reads the sentinel file as a backup.
+        pass
+
+    # Fast paths: nothing to do.
+    if _kimodo_ready_sentinel().is_file():
+        if not _KIMODO_BUILD_EVENT.is_set():
+            _KIMODO_BUILD_EVENT.set()
+        log.info("_install_kimodo_async: .kimodo_ready already present — skip")
+        return
+    if _KIMODO_BUILD_THREAD is not None and _KIMODO_BUILD_THREAD.is_alive():
+        log.info("_install_kimodo_async: build already in progress — skip")
+        return
+    if _kimodo_failed_sentinel().is_file():
+        log.warning(
+            "_install_kimodo_async: previous build FAILED (see %s). "
+            "Delete the sentinel + restart to retry.",
+            _kimodo_failed_sentinel(),
+        )
+        return
+
+    log.info("_install_kimodo_async: spawning build thread")
+    _KIMODO_BUILD_THREAD = _threading.Thread(
+        target=_install_kimodo_sync,
+        args=(hf_token,),
+        daemon=True,
+        name="kimodo-bootstrap",
+    )
+    _KIMODO_BUILD_THREAD.start()
+
+
+def _set_env_for_kimodo() -> None:
+    """Plant env vars the runner script + escape_hatch + animoflow-api read
+    to find the Kimodo venv, runner, assets, and health endpoint."""
+    os.environ.setdefault("KIMODO_VENV_PYTHON", str(_kimodo_venv_python()))
+    os.environ.setdefault(
+        "KIMODO_RUNNER_SCRIPT",
+        str(Path(__file__).resolve().parent / "scripts" / "run_inference_kimodo.py"),
+    )
+    os.environ.setdefault("KIMODO_SRC_DIR", str(_kimodo_src_dir()))
+    os.environ.setdefault("KIMODO_ASSETS_DIR", str(_kimodo_assets_dir()))
+    os.environ.setdefault("TEXT_ENCODERS_DIR", str(_kimodo_text_encoders_dir()))
+    # Health endpoint: animoflow-api's _MODEL_HEALTH_URLS polls
+    # ${KIMODO_ENDPOINT}/health. We expose /__internal/kimodo_health on the
+    # same FastAPI app — see app.py.
+    port = os.environ.get("PORT", "7860")
+    os.environ.setdefault(
+        "KIMODO_ENDPOINT", f"http://127.0.0.1:{port}/__internal/kimodo",
+    )
+
+
+def _git_clone(url: str, target: Path, *, depth: int = 1) -> None:
+    """Shell out to `git clone --depth N`. Raises CalledProcessError on failure."""
+    subprocess.run(
+        ["git", "clone", f"--depth={depth}", url, str(target)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _strip_remote_auth(target: Path, clean_url: str) -> None:
+    """Replace the origin URL with the unauthenticated URL post-clone, so the
+    token isn't persisted on disk in `.git/config`."""
+    subprocess.run(
+        ["git", "-C", str(target), "remote", "set-url", "origin", clean_url],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _clone_all(gh_token: str | None) -> None:
+    EXTERNAL_DIR.mkdir(parents=True, exist_ok=True)
+
+    for url, subdir, name, private in _GIT_REPOS:
+        target = EXTERNAL_DIR / subdir
+        if target.is_dir():
+            log.info("clone: %s already at %s — skip", name, target)
+            continue
+        if private:
+            if not gh_token:
+                raise RuntimeError(
+                    f"gh_token env var missing — cannot clone private repo {name}. "
+                    "On HF Spaces, configure a Space secret named `gh_token` with "
+                    "Read access to AnimoFlow private repos."
+                )
+            auth_url = url.replace("https://", f"https://x-access-token:{gh_token}@")
+            log.info("clone (private): %s → %s", name, target)
+            _git_clone(auth_url, target)
+            _strip_remote_auth(target, url)
+        else:
+            log.info("clone (public): %s → %s", name, target)
+            _git_clone(url, target)
+
+        # Pin MDM to a known-good commit (HEAD diverged, see MDM_PINNED_COMMIT).
+        if subdir == "mdm-codes" and MDM_PINNED_COMMIT:
+            _pin_to_commit(target, MDM_PINNED_COMMIT, name)
+        # Release pins for AnimoFlow's own repos (no-op while unset).
+        if subdir == "comfyui-animoflow" and COMFYUI_PINNED_COMMIT:
+            _pin_to_commit(target, COMFYUI_PINNED_COMMIT, name)
+        if subdir == "animoflow-api" and API_PINNED_COMMIT:
+            _pin_to_commit(target, API_PINNED_COMMIT, name)
+
+
+def _pin_to_commit(target: Path, commit: str, name: str) -> None:
+    """Fetch a specific commit and checkout, so the clone stays at a
+    known-good revision regardless of what HEAD points to.
+
+    GitHub doesn't allow fetching arbitrary SHAs by default on shallow
+    clones.  Strategy: try shallow fetch first (works on some hosts);
+    if that fails, unshallow the repo and then checkout.
+    """
+    try:
+        # Fast path: try fetching the SHA directly (works on GH if
+        # uploadpack.allowReachableSHA1InWant is enabled).
+        subprocess.run(
+            ["git", "-C", str(target), "fetch", "--depth=1", "origin", commit],
+            check=True, capture_output=True, text=True,
+        )
+    except subprocess.CalledProcessError:
+        # Slow path: unshallow so the commit is reachable, then checkout.
+        log.info("pin: shallow fetch of %s failed for %s — unshallowing", commit, name)
+        try:
+            subprocess.run(
+                ["git", "-C", str(target), "fetch", "--unshallow"],
+                check=True, capture_output=True, text=True,
+            )
+        except subprocess.CalledProcessError:
+            # Already unshallow or fetch failed — try a plain fetch
+            subprocess.run(
+                ["git", "-C", str(target), "fetch", "origin"],
+                check=True, capture_output=True, text=True,
+            )
+    try:
+        subprocess.run(
+            ["git", "-C", str(target), "checkout", commit],
+            check=True, capture_output=True, text=True,
+        )
+        log.info("pin: %s checked out at %s", name, commit)
+    except subprocess.CalledProcessError as exc:
+        log.warning("pin: failed to checkout %s at %s: %s", name, commit, exc.stderr)
+
+
+def _download_checkpoints(hf_token: str | None) -> Path | None:
+    """Download MDM checkpoints from HF Hub and return the local dir, or
+    None if no token (caller decides whether that's fatal)."""
+    ckpt_dir = EXTERNAL_DIR / "checkpoints"
+    ckpt_dir.mkdir(parents=True, exist_ok=True)
+
+    target_pt = ckpt_dir / "humanml_enc_512_50steps" / "model000750000.pt"
+    if target_pt.exists():
+        log.info("checkpoints: already present at %s", ckpt_dir)
+        return ckpt_dir
+
+    if not hf_token:
+        log.warning(
+            "hf_token env var missing — MDM checkpoints not downloaded. "
+            "MDM will fall back to placeholder mode. Configure `hf_token` "
+            "Space secret with Read access to %s.",
+            ANIMOFLOW_CHECKPOINTS_REPO,
+        )
+        return None
+
+    from huggingface_hub import snapshot_download
+
+    log.info(
+        "checkpoints: snapshot_download %s @ %s → %s",
+        ANIMOFLOW_CHECKPOINTS_REPO,
+        ANIMOFLOW_CHECKPOINTS_REVISION[:8],
+        ckpt_dir,
+    )
+    snapshot_download(
+        repo_id=ANIMOFLOW_CHECKPOINTS_REPO,
+        revision=ANIMOFLOW_CHECKPOINTS_REVISION,
+        repo_type="model",
+        local_dir=str(ckpt_dir),
+        allow_patterns=[
+            "humanml_enc_512_50steps/model000750000.pt",
+            "humanml_enc_512_50steps/args.json",
+            # MoMask T2M checkpoints — required by inference_momask.py which
+            # reads `${CHECKPOINTS_DIR}/t2m/{rvq,t2m,tres,length_estimator}/...`.
+            # We override CHECKPOINTS_DIR to `${ckpt_dir}/momask` per-model in
+            # registry._load() so this path becomes `${ckpt_dir}/momask/t2m/...`.
+            "momask/t2m/**",
+            # priorMDM trajectory + timeline heads. The registry's
+            # env_overrides_factory plants CHECKPOINT_DIR=${ckpt_dir}/priormdm
+            # so inference.py's _discover_checkpoint() looks inside
+            # priormdm/{root_horizontal_control_50steps,humanml-encoder-512-50steps}/.
+            "priormdm/**",
+        ],
+        token=hf_token,
+    )
+
+    # Copy t2m_mean / t2m_std from the comfyui-animoflow clone — the
+    # MDM wrapper expects them in WEIGHTS_DIR alongside the .pt.
+    src_dir = EXTERNAL_DIR / "comfyui-animoflow" / "containers" / "mdm"
+    for npy in ("t2m_mean.npy", "t2m_std.npy"):
+        src = src_dir / npy
+        dst = ckpt_dir / npy
+        if src.exists() and not dst.exists():
+            shutil.copyfile(src, dst)
+            log.info("copied %s → %s", src, dst)
+
+    # Mirror for priorMDM: its inference.py reads mean/std from WEIGHTS_DIR
+    # which the registry sets to ${ckpt_dir}/priormdm. Same files shipped in
+    # the priormdm container — copy them so the path resolves.
+    pmdm_src_dir = EXTERNAL_DIR / "comfyui-animoflow" / "containers" / "priormdm"
+    pmdm_dst_dir = ckpt_dir / "priormdm"
+    if pmdm_src_dir.exists():
+        pmdm_dst_dir.mkdir(parents=True, exist_ok=True)
+        for npy in ("t2m_mean.npy", "t2m_std.npy"):
+            src = pmdm_src_dir / npy
+            dst = pmdm_dst_dir / npy
+            if src.exists() and not dst.exists():
+                shutil.copyfile(src, dst)
+                log.info("copied %s → %s", src, dst)
+
+    return ckpt_dir
+
+
+def _download_private_characters(hf_token: str | None) -> None:
+    """Fetch the Mixamo character FBXs from the private character-assets
+    repo into the cloned comfyui-animoflow characters dir.
+
+    The public comfyui-animoflow repo only carries download instructions
+    (Mixamo terms forbid redistribution) plus the small bone_map.json
+    sidecars; the hosted demo gets the actual FBXs from
+    AnimoFlow/character-assets `characters/**` (split out of the
+    checkpoints repo 2026-07-06 to isolate Adobe-licensed content).
+    Idempotent: skips files already present. No token → loud warning,
+    characters absent → /v1/characters only lists whatever the public
+    clone carries (nothing, since comfyui-animoflow@7a91fa3 untracked its
+    dev-convenience FBXs). NOTE: a token that lacks read scope on
+    the character-assets repo raises RepositoryNotFoundError here (HF
+    404s private repos it can't see) and crashes startup — loud on
+    purpose; extend the Space `hf_token` scope, don't wrap this in
+    try/except.
+    """
+    chars_dir = EXTERNAL_DIR / "comfyui-animoflow" / "characters"
+    if not chars_dir.is_dir():
+        log.warning("characters: %s missing — clone step failed?", chars_dir)
+        return
+    if not hf_token:
+        log.warning(
+            "hf_token env var missing — private characters not downloaded; "
+            "the character dropdown will only show the public-clone rigs."
+        )
+        return
+
+    from huggingface_hub import snapshot_download
+
+    log.info(
+        "characters: snapshot_download %s @ %s characters/** → %s",
+        ANIMOFLOW_CHARACTER_ASSETS_REPO,
+        ANIMOFLOW_CHARACTER_ASSETS_REVISION[:8],
+        chars_dir,
+    )
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        snapshot_download(
+            repo_id=ANIMOFLOW_CHARACTER_ASSETS_REPO,
+            revision=ANIMOFLOW_CHARACTER_ASSETS_REVISION,
+            repo_type="model",
+            token=hf_token,
+            local_dir=tmp,
+            allow_patterns=["characters/**"],
+        )
+        src_dir = Path(tmp) / "characters"
+        if not src_dir.is_dir():
+            # The silent-glob failure mode: download "succeeded" but the
+            # pattern matched nothing at this revision. Loud, per the
+            # no-silent-fallback rule.
+            log.warning(
+                "characters: %s @ %s has NO characters/ folder — pattern "
+                "globbed nothing; the character dropdown will be missing "
+                "the private rigs. Check the repo/revision pin.",
+                ANIMOFLOW_CHARACTER_ASSETS_REPO,
+                ANIMOFLOW_CHARACTER_ASSETS_REVISION[:8],
+            )
+            return
+        n = 0
+        for f in sorted(src_dir.iterdir()):
+            if not f.is_file():
+                continue
+            dst = chars_dir / f.name
+            if dst.exists() and dst.stat().st_size == f.stat().st_size:
+                continue
+            shutil.copy2(f, dst)
+            n += 1
+        log.info("characters: installed %d file(s) into %s", n, chars_dir)
+
+
+def _set_env_for_external() -> None:
+    """Plant env vars that the rest of the orchestrator code reads, so
+    pipeline_hf, models.registry, etc. find the cloned paths without
+    knowing whether we're in Docker or Gradio mode."""
+    os.environ.setdefault(
+        "COMFYUI_ANIMOFLOW_DIR", str(EXTERNAL_DIR / "comfyui-animoflow")
+    )
+    os.environ.setdefault(
+        "COMFYUI_ANIMOFLOW_NODES_DIR",
+        str(EXTERNAL_DIR / "comfyui-animoflow" / "nodes"),
+    )
+    os.environ.setdefault(
+        "ANIMOFLOW_API_API_DIR", str(EXTERNAL_DIR / "animoflow-api" / "api")
+    )
+    os.environ.setdefault("MDM_PATH", str(EXTERNAL_DIR / "mdm-codes"))
+    os.environ.setdefault("MOMASK_PATH", str(EXTERNAL_DIR / "momask-codes"))
+    os.environ.setdefault("PRIORMDM_PATH", str(EXTERNAL_DIR / "priormdm-codes"))
+    os.environ.setdefault(
+        "CHARACTERS_DIR",
+        str(EXTERNAL_DIR / "comfyui-animoflow" / "characters"),
+    )
+    os.environ.setdefault("WEB_DIR", "/nonexistent")
+    os.environ.setdefault("WEIGHTS_DIR", str(EXTERNAL_DIR / "checkpoints"))
+    os.environ.setdefault("CHECKPOINTS_DIR", str(EXTERNAL_DIR / "checkpoints"))
+
+
+def _patch_mdm_model_util():
+    """Ensure MDM's utils/model_util.py has a ``load_saved_model`` function.
+
+    The MDM inference wrapper (comfyui-animoflow/containers/mdm/inference.py)
+    imports ``load_saved_model`` from ``utils.model_util``, but the upstream
+    MDM repo only exposes ``load_model_wo_clip``.  Without this shim the
+    import fails silently (caught by a broad except), and the model falls
+    back to a hardcoded walk-cycle placeholder — ignoring the text prompt
+    entirely.
+
+    This patch adds a thin ``load_saved_model(model, path, **kw)`` wrapper
+    that loads the state dict from *path* and delegates to
+    ``load_model_wo_clip``.  Idempotent — skips if the function already
+    exists in the file.
+    """
+    mdm_path = EXTERNAL_DIR / "mdm-codes"
+    model_util = mdm_path / "utils" / "model_util.py"
+    if not model_util.is_file():
+        log.info("_patch_mdm_model_util: %s not found, skipping", model_util)
+        return
+
+    text = model_util.read_text()
+    if "def load_saved_model" in text:
+        log.info("_patch_mdm_model_util: load_saved_model already present — skip")
+        return
+
+    shim = '''
+
+def load_saved_model(model, model_path, use_avg=False, **kwargs):
+    """Compatibility shim: load checkpoint and delegate to load_model_wo_clip.
+
+    The checkpoint stores only the non-CLIP weights (CLIP weights are
+    stripped at training-time save). ``load_model_wo_clip`` loads them
+    with ``strict=False`` so the freshly-downloaded CLIP weights in the
+    model are preserved.
+    """
+    import torch as _torch
+    state_dict = _torch.load(model_path, map_location="cpu")
+    load_model_wo_clip(model, state_dict)
+'''
+    model_util.write_text(text + shim)
+    log.info("_patch_mdm_model_util: injected load_saved_model shim into %s", model_util)
+
+
+def _patch_priormdm_source() -> None:
+    """Mirror comfyui-animoflow/containers/priormdm/Dockerfile lines 46-53.
+
+    priorMDM's upstream source still uses numpy 1.x aliases (np.float, np.int,
+    np.bool) removed in numpy 1.24+, and asserts dataset size > 1 which our
+    single-sample inference path violates. The container's Dockerfile sed-fixes
+    these at image build time; we mirror them here because we run priorMDM
+    inside the orchestrator venv (numpy 2.x), not the container's 1.23 pin.
+
+    Idempotent via a sentinel file. Safe to re-run after each bootstrap.
+    """
+    import re
+
+    src = EXTERNAL_DIR / "priormdm-codes"
+    if not src.is_dir():
+        log.info("_patch_priormdm_source: %s not found, skipping", src)
+        return
+    sentinel = src / ".animoflow_patched"
+    if sentinel.is_file():
+        log.info("_patch_priormdm_source: already patched (%s) — skip", sentinel)
+        return
+
+    np_alias_subs = [
+        (re.compile(r"\bnp\.float\b"), "float"),
+        (re.compile(r"\bnp\.int\b"),   "int"),
+        (re.compile(r"\bnp\.bool\b"),  "bool"),
+    ]
+    touched = 0
+    for py in src.rglob("*.py"):
+        text = py.read_text()
+        new = text
+        for pat, repl in np_alias_subs:
+            new = pat.sub(repl, new)
+        if new != text:
+            py.write_text(new)
+            touched += 1
+
+    dset = src / "data_loaders" / "humanml" / "data" / "dataset.py"
+    if dset.is_file():
+        t = dset.read_text()
+        t2 = t.replace(
+            "assert len(self.t2m_dataset) > 1",
+            "assert len(self.t2m_dataset) >= 1",
+        )
+        if t2 != t:
+            dset.write_text(t2)
+
+    sentinel.write_text("ok\n")
+    log.info(
+        "_patch_priormdm_source: patched %d .py files + dataset assert in %s",
+        touched, src,
+    )
+
+
+def _patch_blender_bvh_addon():
+    """Fix Blender's io_anim_bvh addon: 'rU' mode removed in Python 3.12.
+
+    Strategy: create a full copy of Blender's scripts directory at
+    /home/user/app/blender_scripts_patched, fix the BVH addon, and set
+    BLENDER_SYSTEM_SCRIPTS to redirect Blender there.
+    """
+    import shutil
+
+    sys_scripts = Path("/usr/share/blender/scripts")
+    if not sys_scripts.is_dir():
+        log.info("_patch_blender_bvh_addon: /usr/share/blender/scripts not found, skipping")
+        return
+
+    target_file = sys_scripts / "addons/io_anim_bvh/import_bvh.py"
+    if not target_file.is_file():
+        log.info("_patch_blender_bvh_addon: %s not found, skipping", target_file)
+        return
+
+    # Check if system file has the bug
+    sys_text = target_file.read_text()
+    if "'rU'" not in sys_text and '"rU"' not in sys_text:
+        log.info("_patch_blender_bvh_addon: no 'rU' found in system file, already clean")
+        return
+
+    # Try direct fix first (might work if container allows it)
+    try:
+        fixed = sys_text.replace("'rU'", "'r'").replace('"rU"', '"r"')
+        target_file.write_text(fixed)
+        # Verify
+        if "'rU'" not in target_file.read_text():
+            log.info("_patch_blender_bvh_addon: patched system file directly at %s", target_file)
+            return
+    except PermissionError:
+        log.info("_patch_blender_bvh_addon: no write access to system file, using BLENDER_SYSTEM_SCRIPTS override")
+
+    # Fallback: copy entire scripts dir and set BLENDER_SYSTEM_SCRIPTS
+    patched_dir = Path("/home/user/app/blender_scripts_patched")
+    if patched_dir.is_dir():
+        log.info("_patch_blender_bvh_addon: patched dir already exists at %s", patched_dir)
+        os.environ["BLENDER_SYSTEM_SCRIPTS"] = str(patched_dir)
+        return
+
+    shutil.copytree(sys_scripts, patched_dir)
+    patch_target = patched_dir / "addons/io_anim_bvh/import_bvh.py"
+    text = patch_target.read_text()
+    text = text.replace("'rU'", "'r'").replace('"rU"', '"r"')
+    patch_target.write_text(text)
+    os.environ["BLENDER_SYSTEM_SCRIPTS"] = str(patched_dir)
+    log.info("_patch_blender_bvh_addon: created patched scripts at %s, set BLENDER_SYSTEM_SCRIPTS", patched_dir)
+
+
+def _ensure_blender_numpy() -> None:
+    """Install numpy so Blender's glTF2 addon can export GLB.
+
+    On HF Gradio Spaces (Debian Trixie), apt Blender links against
+    python3.11 but the Space's default ``pip3`` targets python3.12+.
+    Running ``pip3 install numpy`` installs for the wrong interpreter.
+
+    Strategy:
+      1. Probe Blender for ``sys.version_info`` to know the Python version.
+      2. Try ``python<ver> -m pip install numpy`` (works on tarball Blender).
+      3. If that fails (apt Blender has no pip for 3.11), install numpy
+         to a ``--target`` directory via the system pip, then set
+         ``PYTHONPATH`` so Blender's Python can find it.
+      4. Verify by actually importing numpy inside Blender.
+
+    Idempotent: probes numpy inside Blender first (using sys.exit to
+    get a reliable return code — Blender returns 0 on --python-expr
+    exceptions otherwise).
+    """
+    import shutil as _shutil
+    import subprocess as _subproc
+    from pathlib import Path as _Path
+
+    blender = os.environ.get("BLENDER_BIN", "").strip() or _shutil.which("blender")
+    if not blender or not _Path(blender).exists():
+        log.warning("Blender not found — skipping numpy install for GLB export")
+        return
+
+    # --- Step 1: probe Blender for numpy + Python version ---
+    # Use sys.exit(code) to get a reliable return code from Blender.
+    probe_script = (
+        "import sys\n"
+        "try:\n"
+        "    import numpy; print('NUMPY_OK', numpy.__version__); sys.exit(0)\n"
+        "except ImportError:\n"
+        "    print('NUMPY_MISSING')\n"
+        "    print('PYVER', f'{sys.version_info.major}.{sys.version_info.minor}')\n"
+        "    sys.exit(42)\n"
+    )
+    probe = _subproc.run(
+        [blender, "--background", "--python-expr", probe_script],
+        capture_output=True, text=True, timeout=30,
+    )
+    # Parse stdout for our markers
+    probe_data: dict[str, str] = {}
+    for line in probe.stdout.splitlines():
+        parts = line.split(maxsplit=1)
+        if len(parts) >= 1 and parts[0] in ("NUMPY_OK", "NUMPY_MISSING", "PYVER"):
+            probe_data[parts[0]] = parts[1].strip() if len(parts) == 2 else ""
+
+    if "NUMPY_OK" in probe_data:
+        log.info("Blender numpy: already present (numpy %s, skip)",
+                 probe_data["NUMPY_OK"])
+        return
+
+    py_ver = probe_data.get("PYVER", "")
+    log.info("Blender Python version: %s, numpy missing — installing", py_ver)
+
+    # --- Step 2: get pip working for Blender's Python, then install numpy ---
+    blender_python = _shutil.which(f"python{py_ver}") if py_ver else None
+    if not blender_python and py_ver:
+        candidate = f"/usr/bin/python{py_ver}"
+        if _Path(candidate).is_file():
+            blender_python = candidate
+    if not blender_python:
+        log.warning("Cannot find python%s — skipping numpy install", py_ver)
+        return
+
+    log.info("Blender's Python: %s", blender_python)
+    installed = False
+
+    # Strategy A: try ensurepip + pip install (works on tarball Blender)
+    _subproc.run(
+        [blender_python, "-m", "ensurepip", "--upgrade"],
+        capture_output=True, text=True, timeout=120,
+    )
+    direct = _subproc.run(
+        [blender_python, "-m", "pip", "install", "--no-cache-dir",
+         "--break-system-packages", "numpy"],
+        capture_output=True, text=True, timeout=300,
+    )
+    if direct.returncode == 0:
+        log.info("Installed numpy via %s -m pip", blender_python)
+        installed = True
+
+    # Strategy B: bootstrap pip for this Python via get-pip.py, then install
+    if not installed:
+        log.info("%s has no pip — bootstrapping via get-pip.py", blender_python)
+        import urllib.request
+        get_pip = "/tmp/get-pip.py"
+        try:
+            urllib.request.urlretrieve(
+                "https://bootstrap.pypa.io/get-pip.py", get_pip,
+            )
+        except Exception as e:
+            log.warning("Failed to download get-pip.py: %s", e)
+            # Continue to Strategy C
+        else:
+            bootstrap_pip = _subproc.run(
+                [blender_python, get_pip, "--break-system-packages"],
+                capture_output=True, text=True, timeout=120,
+            )
+            if bootstrap_pip.returncode == 0:
+                install_np = _subproc.run(
+                    [blender_python, "-m", "pip", "install", "--no-cache-dir",
+                     "--break-system-packages", "numpy"],
+                    capture_output=True, text=True, timeout=300,
+                )
+                if install_np.returncode == 0:
+                    log.info("Installed numpy via get-pip.py + %s -m pip", blender_python)
+                    installed = True
+                else:
+                    log.info("pip install after get-pip failed (rc=%s): %s",
+                             install_np.returncode, (install_np.stderr or "")[-300:])
+            else:
+                log.info("get-pip.py failed (rc=%s): %s",
+                         bootstrap_pip.returncode, (bootstrap_pip.stderr or "")[-300:])
+
+    # Strategy C: pip download wheels for the correct python version, install with --target
+    if not installed:
+        log.info("Trying pip download with --python-version %s ...", py_ver)
+        pip3 = _shutil.which("pip3") or _shutil.which("pip")
+        if pip3:
+            dl_dir = _Path("/tmp/numpy_wheels")
+            dl_dir.mkdir(parents=True, exist_ok=True)
+            target_dir = _Path("/home/user/app/blender_numpy_packages")
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            dl = _subproc.run(
+                [pip3, "download", "--no-cache-dir",
+                 "--python-version", py_ver,
+                 "--abi", f"cp{py_ver.replace('.', '')}",
+                 "--platform", "manylinux2014_x86_64",
+                 "--only-binary=:all:",
+                 "-d", str(dl_dir), "numpy"],
+                capture_output=True, text=True, timeout=120,
+            )
+            if dl.returncode == 0:
+                wheels = list(dl_dir.glob("*.whl"))
+                if wheels:
+                    inst = _subproc.run(
+                        [pip3, "install", "--no-deps", "--no-cache-dir",
+                         "--break-system-packages",
+                         "--target", str(target_dir)] + [str(w) for w in wheels],
+                        capture_output=True, text=True, timeout=120,
+                    )
+                    if inst.returncode == 0:
+                        existing = os.environ.get("PYTHONPATH", "")
+                        os.environ["PYTHONPATH"] = (
+                            f"{target_dir}:{existing}" if existing else str(target_dir)
+                        )
+                        log.info("Installed numpy wheels to %s, PYTHONPATH=%s",
+                                 target_dir, os.environ["PYTHONPATH"])
+                        installed = True
+
+    if not installed:
+        log.warning("All numpy install strategies failed for python%s", py_ver)
+        return
+
+    # --- Step 4: verify inside Blender ---
+    verify_script = (
+        "import sys\n"
+        "try:\n"
+        "    import numpy; print('VERIFY_OK', numpy.__version__); sys.exit(0)\n"
+        "except ImportError as e:\n"
+        "    print('VERIFY_FAIL', e); sys.exit(1)\n"
+    )
+    confirm = _subproc.run(
+        [blender, "--background", "--python-expr", verify_script],
+        capture_output=True, text=True, timeout=30,
+    )
+    for line in confirm.stdout.splitlines():
+        if line.startswith("VERIFY_OK"):
+            log.info("Blender numpy install verified: %s", line)
+            return
+        if line.startswith("VERIFY_FAIL"):
+            log.warning("Blender numpy verification failed: %s", line)
+            return
+    log.warning("Blender numpy verification inconclusive (rc=%s, stderr=%s)",
+                confirm.returncode, (confirm.stderr or "")[-300:])
+
+
+_CONTAINER_SPECS_LOGGED = False
+
+
+def _log_container_specs() -> None:
+    """Log CPU/RAM/Blender specs once per process for ZeroGPU diagnostics."""
+    global _CONTAINER_SPECS_LOGGED
+    if _CONTAINER_SPECS_LOGGED:
+        return
+    _CONTAINER_SPECS_LOGGED = True
+
+    import multiprocessing
+    import time
+
+    specs: dict[str, str] = {}
+
+    # CPU counts
+    specs["mp_cpu_count"] = str(multiprocessing.cpu_count())
+    specs["os_cpu_count"] = str(os.cpu_count())
+
+    # RAM
+    try:
+        page = os.sysconf("SC_PAGE_SIZE")
+        pages = os.sysconf("SC_PHYS_PAGES")
+        specs["total_ram_gb"] = f"{page * pages / 1024**3:.2f}"
+    except (ValueError, OSError):
+        specs["total_ram_gb"] = "unknown"
+
+    try:
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemAvailable:"):
+                    kb = int(line.split()[1])
+                    specs["avail_ram_gb"] = f"{kb / 1024**2:.2f}"
+                    break
+            else:
+                specs["avail_ram_gb"] = "unknown"
+    except OSError:
+        specs["avail_ram_gb"] = "unknown"
+
+    # CPU model
+    try:
+        with open("/proc/cpuinfo") as f:
+            for line in f:
+                if line.startswith("model name"):
+                    specs["cpu_model"] = line.split(":", 1)[1].strip()
+                    break
+            else:
+                specs["cpu_model"] = "unknown"
+    except OSError:
+        specs["cpu_model"] = "unknown"
+
+    # Blender cold-start time
+    import shutil as _shutil
+    blender = os.environ.get("BLENDER_BIN", "").strip() or _shutil.which("blender")
+    if blender and Path(blender).exists():
+        try:
+            t0 = time.monotonic()
+            subprocess.run(
+                [blender, "--version"],
+                capture_output=True, text=True, timeout=60,
+            )
+            specs["blender_startup_s"] = f"{time.monotonic() - t0:.3f}"
+        except Exception as e:
+            specs["blender_startup_s"] = f"error:{e}"
+    else:
+        specs["blender_startup_s"] = "not_found"
+
+    # cgroup limits (ZeroGPU containers use cgroup v2)
+    try:
+        with open("/sys/fs/cgroup/cpu.max") as f:
+            specs["cgroup_cpu_max"] = f.read().strip()
+    except Exception:
+        specs["cgroup_cpu_max"] = "unavailable"
+    try:
+        with open("/sys/fs/cgroup/memory.max") as f:
+            raw = f.read().strip()
+            if raw == "max":
+                specs["cgroup_mem_max"] = "max (unlimited)"
+            else:
+                specs["cgroup_mem_max"] = f"{int(raw) / 1024**3:.2f}GB"
+    except Exception:
+        specs["cgroup_mem_max"] = "unavailable"
+
+    parts = " | ".join(f"{k}={v}" for k, v in specs.items())
+    log.info("[CONTAINER_SPECS] %s", parts)
+
+
+def bootstrap_external_repos() -> None:
+    """Idempotent. Clone external repos + download checkpoints if not
+    already present. No-op in Docker mode."""
+    if _docker_mode():
+        log.info("Docker mode detected (/opt/* paths present) — skip bootstrap")
+        return
+
+    log.info("Bootstrap mode (HF Gradio or fresh OSS-local) — base=%s", EXTERNAL_DIR)
+
+    gh_token = os.environ.get("gh_token") or os.environ.get("GH_TOKEN")
+    hf_token = os.environ.get("hf_token") or os.environ.get("HF_TOKEN")
+
+    _install_blender_portable()
+    _install_gltfpack()
+    _clone_all(gh_token)
+    _download_checkpoints(hf_token)
+    _download_private_characters(hf_token)
+    _set_env_for_external()
+    _patch_mdm_model_util()
+    _patch_priormdm_source()
+    _patch_blender_bvh_addon()
+    _ensure_blender_numpy()
+    # Kimodo escape-hatch venv build runs in a background thread so the Gradio
+    # UI comes up promptly with MDM/MoMask. ENABLE_KIMODO=false disables (kill
+    # switch). Per the no-silent-fallback rule: any failure writes the
+    # .kimodo_failed sentinel and is surfaced to the UI; we never silently
+    # degrade.
+    if os.environ.get("ENABLE_KIMODO", "true").strip().lower() != "false":
+        _set_env_for_kimodo()
+        _install_kimodo_async(hf_token)
+    else:
+        log.info("ENABLE_KIMODO=false — Kimodo bootstrap skipped")
+    _log_container_specs()
+    log.info("Bootstrap complete: external repos at %s", EXTERNAL_DIR)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level="INFO",
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    bootstrap_external_repos()

entrypoint.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# animoflow-app entrypoint — boots the orchestrator inside the HF Space (or
+# any host running this image). Idempotent.
+#
+# DELIBERATE: not `set -e`. Weight download and Blender health-check are
+# best-effort; the orchestrator must start even if either fails. /v1/health
+# and /v1/tasks work without weights or Blender; inference / rig / GLB
+# routes will surface clear errors at request time if their deps are
+# missing. Better than dying silently in a Space we can't easily debug.
+set -uo pipefail
+
+cd /opt/animoflow-app
+
+# 1. Download MDM checkpoints if missing. download_weights.sh is idempotent
+#    AND best-effort: a non-zero exit logs a warning but does not abort
+#    boot. Set SKIP_CHECKPOINTS=1 to skip the download step entirely.
+if [ "${SKIP_CHECKPOINTS:-0}" != "1" ] && [ -x /opt/animoflow-app/scripts/download_weights.sh ]; then
+    /opt/animoflow-app/scripts/download_weights.sh \
+        || echo "[entrypoint] WARN: weight download script returned non-zero. Orchestrator will boot anyway; inference will fail with a clear 'checkpoint missing' error until weights are present."
+fi
+
+# 2. Health-check Blender (warn only — do not abort).
+if ! "${BLENDER_BIN:-/opt/blender/blender}" --version >/dev/null 2>&1; then
+    echo "[entrypoint] WARN: Blender not found at ${BLENDER_BIN:-/opt/blender/blender}"
+    echo "[entrypoint] Rig + GLB stages will fail. Inference-only requests still work."
+fi
+
+# 3. Launch FastAPI + Gradio. uvicorn loads fastapi_app from app.py.
+exec /opt/venvs/api/bin/uvicorn \
+    --app-dir /opt/animoflow-app \
+    --host 0.0.0.0 \
+    --port "${PORT:-7860}" \
+    app:fastapi_app

escape_hatch/__init__.py

@@ -0,0 +1,18 @@
+"""
+Escape hatch for outlier-model venvs.
+
+Models whose deps don't merge cleanly with the orchestrator venv (e.g.
+Kimodo's NVIDIA stack, future Tier-2 models) live in their own
+`/opt/venvs/comfy-X/` venv inside the same Docker image. The
+@spaces.GPU-decorated `run_inference` function in pipeline_hf.py
+delegates to these via subprocess — the subprocess inherits CUDA
+visibility from the GPU fork and pays cold-start (~15s) for full dep
+isolation.
+
+The registry currently carries Kimodo; adding further outlier models
+is purely additive — no orchestrator changes.
+"""
+
+from .invoke import is_outlier, invoke
+
+__all__ = ["is_outlier", "invoke"]

escape_hatch/invoke.py

@@ -0,0 +1,194 @@
+"""
+Subprocess-based invocation for outlier-model venvs.
+
+For each outlier model, we maintain:
+  /opt/venvs/comfy-<model>/  — its isolated Python venv (built at Docker time)
+  scripts/run_inference_<model>.py — a tiny CLI we own that calls the
+                                     model's wrapper code with JSON args
+
+The decorated @spaces.GPU function in pipeline_hf.py calls invoke(model, …)
+which spawns the subprocess. CUDA visibility is inherited via the fork
+parent → subprocess env chain.
+
+Adding an outlier model: add an entry to _OUTLIERS and ship the
+matching CLI script.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+import threading
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+# Map model name → {venv_python, runner_script}.
+# Paths are env-overridable so bootstrap.py (HF Gradio mode) and the Dockerfile
+# (OSS local Docker mode) can plant them at the locations they actually build.
+_OUTLIERS: dict[str, dict[str, str]] = {
+    "kimodo": {
+        "venv_python": os.environ.get(
+            "KIMODO_VENV_PYTHON", "/home/user/app/venvs/kimodo/bin/python",
+        ),
+        "runner_script": os.environ.get(
+            "KIMODO_RUNNER_SCRIPT",
+            "/home/user/app/scripts/run_inference_kimodo.py",
+        ),
+    },
+}
+
+# Per-model subprocess timeout (seconds). Kimodo's first call after a Space
+# restart pays the full model load (~120 s including LLaMA encode warmup);
+# warm calls are ~10-15 s. The matching @spaces.GPU(duration=…) lives in
+# pipeline_hf._run_inference_gpu_kimodo.
+_TIMEOUTS: dict[str, int] = {
+    "kimodo": 300,
+}
+
+# Set by bootstrap._install_kimodo_async once the venv build finishes. The
+# runner script also reads the .kimodo_ready sentinel as a backup, so this is
+# defence-in-depth (the event lets us fail fast without spawning a subprocess
+# that would immediately exit with "venv not ready").
+_KIMODO_READY: threading.Event | None = None
+
+
+def _external_dir() -> Path:
+    """Mirror bootstrap.EXTERNAL_DIR without importing bootstrap (which would
+    re-run import-time work)."""
+    return Path(
+        os.environ.get(
+            "ANIMOFLOW_EXTERNAL_DIR",
+            "/home/user/app/external"
+            if os.path.isdir("/home/user/app")
+            else str(Path(__file__).resolve().parent.parent / "external"),
+        )
+    )
+
+
+def _kimodo_failed_message() -> str | None:
+    """Return the captured Kimodo bootstrap error, or None if no .kimodo_failed."""
+    sentinel = _external_dir() / ".kimodo_failed"
+    if not sentinel.is_file():
+        return None
+    try:
+        return sentinel.read_text()[:1200]
+    except OSError:
+        return "(unreadable .kimodo_failed sentinel)"
+
+
+def is_outlier(model: str) -> bool:
+    """True if the model is registered as an outlier and should be invoked
+    via subprocess instead of the in-orchestrator registry."""
+    return model in _OUTLIERS
+
+
+def invoke(
+    model: str,
+    *,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    guidance_param: float | None = None,
+    timeout: int | None = None,
+    **extra: Any,
+) -> bytes:
+    """Invoke an outlier model via subprocess. Returns NPZ bytes.
+
+    The subprocess inherits CUDA_VISIBLE_DEVICES from the parent process —
+    on HF this is the GPU fork created by @spaces.GPU. The subprocess
+    re-initializes CUDA cleanly because it's a fresh Python process (spawn-
+    style isolation), avoiding the "Cannot re-initialize CUDA in forked
+    subprocess" error that bites multiprocessing.fork.
+
+    ``timeout`` defaults to the per-model value in ``_TIMEOUTS`` (Kimodo: 300 s),
+    falling back to 60 s.
+    """
+    if model not in _OUTLIERS:
+        raise RuntimeError(
+            f"Model {model!r} not registered as an outlier. Known outliers: "
+            f"{sorted(_OUTLIERS.keys())}. Add to escape_hatch.invoke._OUTLIERS first."
+        )
+
+    spec = _OUTLIERS[model]
+    venv_python = spec["venv_python"]
+    runner_script = spec["runner_script"]
+
+    # Kimodo-specific readiness gate. Bootstrap builds the venv in a background
+    # thread; refuse to spawn the subprocess until .kimodo_ready exists (or the
+    # ready Event is set). Per the no-silent-fallback policy: if the build
+    # FAILED, surface the captured error verbatim.
+    if model == "kimodo":
+        failed_msg = _kimodo_failed_message()
+        if failed_msg is not None:
+            raise RuntimeError(
+                f"Kimodo venv build FAILED at bootstrap. "
+                f"Captured error:\n{failed_msg}"
+            )
+        ready_sentinel = _external_dir() / ".kimodo_ready"
+        if not ready_sentinel.is_file():
+            # Block briefly on the in-process Event so a request that lands
+            # right at the tail of the build doesn't 503 needlessly.
+            event = _KIMODO_READY
+            wait_s = int(os.environ.get("KIMODO_READY_WAIT_S", "30"))
+            if event is not None and not event.is_set():
+                event.wait(timeout=wait_s)
+            if not ready_sentinel.is_file() and (event is None or not event.is_set()):
+                raise RuntimeError(
+                    "Kimodo venv still warming up — bootstrap installs deps "
+                    "and downloads the 16 GB LLaMA-3-8B encoder on first boot. "
+                    "Typical cold-start is 5-10 minutes; please retry."
+                )
+
+    if not Path(venv_python).exists():
+        raise RuntimeError(
+            f"Outlier venv not found: {venv_python}. "
+            f"Was the bootstrap venv builder run? (set ENABLE_KIMODO=true)"
+        )
+    if not Path(runner_script).exists():
+        raise RuntimeError(f"Runner script missing: {runner_script}")
+
+    payload = {
+        "prompt": prompt,
+        "num_frames": num_frames,
+        "seed": seed,
+        "guidance_param": guidance_param,
+        **extra,
+    }
+
+    effective_timeout = timeout if timeout is not None else _TIMEOUTS.get(model, 60)
+
+    log.info(
+        "Invoking outlier %r via %s (timeout=%ds, cwd-isolated subprocess)",
+        model,
+        venv_python,
+        effective_timeout,
+    )
+
+    # Pass payload via stdin to avoid shell-quoting nightmares
+    result = subprocess.run(
+        [venv_python, runner_script],
+        input=json.dumps(payload).encode(),
+        capture_output=True,
+        timeout=effective_timeout,
+        env={**os.environ},  # inherit CUDA_VISIBLE_DEVICES from GPU fork
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"Outlier {model!r} subprocess exited {result.returncode}. "
+            f"stderr (last 400 chars): {result.stderr.decode(errors='replace')[-400:]}"
+        )
+
+    # Stdout is the NPZ bytes; stderr carries logs only
+    npz_bytes = result.stdout
+    if not npz_bytes:
+        raise RuntimeError(
+            f"Outlier {model!r} produced empty NPZ output. "
+            f"stderr: {result.stderr.decode(errors='replace')[-400:]}"
+        )
+    return npz_bytes

packages.txt

@@ -0,0 +1,3 @@
+blender
+xauth
+xvfb

pipeline_hf.py

@@ -0,0 +1,920 @@
+"""
+HF pipeline — replaces animoflow-api's ComfyUI-orchestrated `pipeline.run`.
+
+Same call signature as animoflow-api/api/pipeline.py:run, so the FastAPI
+in animoflow-api/api/main.py can call this without modification.
+
+Compute layout:
+
+  Receive request          (CPU, orchestrator)
+  ──► run_inference(...)   (GPU, @spaces.GPU(duration=30))
+       └── npz bytes
+  ──► resample             (CPU, shared stage library)
+  ──► IK npz → bvh         (CPU — momask Joint2BVHConvertor)
+  ──► Blender bvh → fbx    (CPU subprocess)
+  ──► Blender fbx → glb    (CPU subprocess, shared stage library script)
+  ──► return filename
+
+Only run_inference is GPU-billed. Everything else stays in the persistent
+orchestrator process. ZeroGPU daily quota burns at ~10-15s per request,
+not 60-120s.
+
+PIPELINE SHAPE AND STAGE SEMANTICS ARE SHARED, NOT DUPLICATED: this
+executor walks the plan from comfyui-animoflow/animoflow_stages/plan.py
+— the exact plan the API server compiles into the local ComfyUI node
+DAG. Per-model parameter mapping (genparams), the resample stage, and
+the FBX→GLB Blender script (snap-to-ground, trajectory restore, Y_bot
+brand tint, matte-character flatten, keyframe RDP) all come from the stage
+library, so the hosted pipeline and the local graph cannot drift.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import logging
+import os
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Callable
+
+# Make sure the orchestrator's own modules are importable when this module
+# is loaded by uvicorn from a different cwd.
+import sys
+
+_THIS_DIR = Path(__file__).resolve().parent
+if str(_THIS_DIR) not in sys.path:
+    sys.path.insert(0, str(_THIS_DIR))
+
+from spaces_compat import GPU  # noqa: E402
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Output dir — match animoflow-api's OUTPUT_DIR convention
+# ---------------------------------------------------------------------------
+
+_OUTPUT_DIR = Path(os.environ.get("OUTPUT_DIR", "/tmp/animoflow-output"))
+_OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+# comfyui-animoflow checkout (cloned at Docker build time on the Space).
+_COMFY_ROOT = Path(
+    os.environ.get("COMFYUI_ANIMOFLOW_DIR", "/opt/comfyui-animoflow")
+)
+
+# ---------------------------------------------------------------------------
+# Lazy imports — defer heavy modules so app.py boots cheaply for tests
+# ---------------------------------------------------------------------------
+
+_retargeter = None
+_post_funcs = None
+_stage_lib = None
+
+
+def _stages():
+    """Load the shared stage library from the comfyui-animoflow checkout
+    (cached). Path-based import — the repo isn't pip-installed."""
+    global _stage_lib
+    if _stage_lib is None:
+        pkg_init = _COMFY_ROOT / "animoflow_stages" / "__init__.py"
+        if not pkg_init.is_file():
+            raise RuntimeError(
+                f"animoflow_stages not found at {pkg_init}. Was "
+                "comfyui-animoflow cloned at Docker build time (and is the "
+                "clone new enough to contain the stage library)?"
+            )
+        # Purge any stale entries first — `from animoflow_stages import x`
+        # binds cached submodules WITHOUT attaching them to a freshly
+        # inserted package object, leaving `stages.plan` unset.
+        for k in [k for k in sys.modules
+                  if k == "animoflow_stages" or k.startswith("animoflow_stages.")]:
+            del sys.modules[k]
+        spec = importlib.util.spec_from_file_location(
+            "animoflow_stages", str(pkg_init),
+            submodule_search_locations=[str(pkg_init.parent)])
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules["animoflow_stages"] = mod
+        spec.loader.exec_module(mod)  # type: ignore[union-attr]
+        from animoflow_stages import (  # noqa: F401 — register submodules
+            fps, genparams, glb_export, glb_post, plan, resample,
+        )
+        _stage_lib = sys.modules["animoflow_stages"]
+    return _stage_lib
+
+
+def _install_numpy_compat_shim() -> None:
+    """Make momask-codes' legacy numpy 1.x calls work under numpy 2.x.
+
+    momask-codes was written against numpy < 1.24 and uses two APIs that
+    have since been removed:
+
+      * `np.float` / `np.int` / `np.bool` / `np.object` — removed in numpy 1.24.
+        Used in `momask-codes/common/quaternion.py` and similar.
+      * `numpy.core.umath_tests` — internal module removed in numpy 2.0.
+        Used by `momask-codes/visualization/Animation.py` for its `inner1d`
+        helper. We replace it with a tiny shim that uses `np.einsum`.
+
+    Per the wrap-don't-modify rule we do not patch momask-codes itself.
+    Instead we install these shims in our orchestrator process BEFORE the
+    first momask import. Idempotent + no-op on numpy < 2.0.
+    """
+    import warnings as _warnings  # noqa: I001
+
+    import numpy as _np
+
+    # 1. np.float / np.int / np.bool / np.object aliases.
+    # `hasattr` triggers a numpy FutureWarning on some legacy attrs even
+    # though the attribute itself doesn't exist as a real symbol — silence
+    # those during the probe so they don't pollute orchestrator startup.
+    with _warnings.catch_warnings():
+        _warnings.simplefilter("ignore", FutureWarning)
+        _warnings.simplefilter("ignore", DeprecationWarning)
+        for _legacy, _replacement in (
+            ("float", _np.float64),
+            ("int", _np.int64),
+            ("bool", _np.bool_),
+            ("object", _np.object_),
+            ("complex", _np.complex128),
+            ("str", _np.str_),
+            ("long", _np.int64),
+        ):
+            if not hasattr(_np, _legacy):
+                setattr(_np, _legacy, _replacement)
+
+    # 2. numpy.core.umath_tests stub. The original module exposed several
+    # ufunc helpers that momask uses; we provide drop-ins for all known
+    # callers and surface a clear error for anything else so we discover
+    # gaps via a useful exception, not a cryptic AttributeError.
+    if "numpy.core.umath_tests" not in sys.modules:
+        import types as _types
+
+        _stub = _types.ModuleType("numpy.core.umath_tests")
+
+        def _inner1d(a, b):
+            """np.core.umath_tests.inner1d → einsum element-wise dot."""
+            return _np.einsum("...i,...i->...", a, b)
+
+        def _matrix_multiply(a, b):
+            """np.core.umath_tests.matrix_multiply → np.matmul (handles
+            stacked matrices the same way the old C ufunc did)."""
+            return _np.matmul(a, b)
+
+        def _innerwt(a, b, w):
+            """np.core.umath_tests.innerwt → weighted inner product."""
+            return _np.einsum("...i,...i,...i->...", a, b, w)
+
+        _stub.inner1d = _inner1d
+        _stub.matrix_multiply = _matrix_multiply
+        _stub.innerwt = _innerwt
+        sys.modules["numpy.core.umath_tests"] = _stub
+        # Also attach to numpy.core so `from numpy.core import umath_tests`
+        # style imports resolve.
+        try:
+            import numpy.core as _np_core
+
+            if not hasattr(_np_core, "umath_tests"):
+                _np_core.umath_tests = _stub
+        except ImportError:
+            pass
+
+
+def _get_retargeter():
+    """Lazy-load the comfyui-animoflow MotionRetargeter singleton.
+
+    Loads the upstream momask Joint2BVHConvertor under the hood. Pure-Python
+    (numpy / matplotlib / scipy / torch) — no GPU required for IK or BVH.
+    """
+    global _retargeter
+    if _retargeter is None:
+        # Install numpy-compat shim BEFORE importing anything from momask.
+        _install_numpy_compat_shim()
+
+        nodes_dir = Path(
+            os.environ.get(
+                "COMFYUI_ANIMOFLOW_NODES_DIR",
+                str(_COMFY_ROOT / "nodes"),
+            )
+        )
+        if not nodes_dir.is_dir():
+            raise RuntimeError(
+                f"comfyui-animoflow/nodes/ not found at {nodes_dir}. "
+                "Was comfyui-animoflow cloned at Docker build time?"
+            )
+        # The package name has a hyphen so a plain `import` won't work —
+        # same dynamic loading pattern as the AnimoFlow IK/Rig nodes.
+        pkg_init = nodes_dir / "retargeter" / "__init__.py"
+        spec = importlib.util.spec_from_file_location(
+            "animoflow_retargeter", str(pkg_init)
+        )
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules["animoflow_retargeter"] = mod
+        spec.loader.exec_module(mod)  # type: ignore[union-attr]
+        _retargeter = mod.MotionRetargeter()
+        log.info("Loaded MotionRetargeter from %s", pkg_init)
+    return _retargeter
+
+
+def _get_post_funcs():
+    """Lazy-load CPU post-processing helpers from comfyui-animoflow nodes.
+
+    No post-process steps ship today — outlier_fix + foot_skating_fix were
+    retired 2026-06-24 (see tests/outlier-post-proc/). The registry is kept
+    as the integration point for any future BVH→BVH transformer added to
+    comfyui-animoflow/motion_utils/; new entries get wired here and called
+    from the ik stage of _run_tail.
+    """
+    global _post_funcs
+    if _post_funcs is None:
+        _post_funcs = {}
+    return _post_funcs
+
+
+# ---------------------------------------------------------------------------
+# GPU-decorated inference — the only call that allocates ZeroGPU
+# ---------------------------------------------------------------------------
+
+# ZeroGPU forks a worker for each @spaces.GPU call and serializes the return
+# value back across a pipe. Empirically, exception args are stripped to the
+# class name (sometimes via repr — producing a literal `'RuntimeError'`
+# symptom on the Space). To avoid relying on
+# that serialization, every GPU function catches its own exceptions, JSON-
+# encodes them with a sentinel prefix, and returns bytes. The CPU-side caller
+# detects the sentinel and re-raises a real RuntimeError with the original
+# message + traceback preserved.
+_ERR_SENTINEL = b"\x00\x00ANIMOFLOW_ERR\x00\x00"
+
+
+def _do_inference(
+    model: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    *,
+    guidance_param: float | None = None,
+    **extra: Any,
+) -> bytes:
+    """Body of inference. Identical CPU/GPU behaviour for both @GPU wrappers.
+
+    For models in the orchestrator venv (MDM family), the fork inherits the
+    warm singleton via copy-on-write. For outliers (Kimodo, future), the
+    function delegates to escape_hatch.invoke() which subprocess-calls into
+    the model's own venv — that subprocess inherits the GPU from the fork.
+    """
+    from escape_hatch import is_outlier, invoke as escape_invoke
+
+    if is_outlier(model):
+        # Subprocess timeout tracks the active admission window minus a
+        # margin, so OUR loud, classified timeout fires before ZeroGPU
+        # kills the slot from outside (which would strip the error).
+        _window = _kimodo_window_s() if model == "kimodo" else None
+        return escape_invoke(
+            model,
+            prompt=prompt,
+            num_frames=num_frames,
+            seed=seed,
+            guidance_param=guidance_param,
+            **({"timeout": max(30, _window - 5)} if _window else {}),
+            **extra,
+        )
+
+    from animoflow_models import generate as model_generate
+
+    npz_bytes, _meta = model_generate(
+        model,
+        prompt=prompt,
+        num_frames=num_frames,
+        seed=seed,
+        guidance_param=guidance_param,
+        **extra,
+    )
+    return npz_bytes
+
+
+def _safe_do_inference(
+    model: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    *,
+    guidance_param: float | None = None,
+    **extra: Any,
+) -> bytes:
+    """_do_inference wrapped to survive ZeroGPU's cross-worker exception strip.
+
+    Returns either the raw NPZ bytes, OR `_ERR_SENTINEL + json(...)` carrying
+    the error class + message + truncated traceback. Callers MUST check the
+    sentinel and re-raise.
+    """
+    try:
+        return _do_inference(
+            model, prompt, num_frames, seed,
+            guidance_param=guidance_param, **extra,
+        )
+    except BaseException as e:
+        payload = json.dumps({
+            "error_class": type(e).__name__,
+            "error_module": type(e).__module__,
+            "message": str(e) or repr(e),
+            "traceback": traceback.format_exc()[-4000:],
+        }).encode()
+        return _ERR_SENTINEL + payload
+
+
+def _unwrap_gpu_result(npz_bytes: bytes) -> bytes:
+    """Inverse of _safe_do_inference: raise if the sentinel is present,
+    otherwise pass the NPZ bytes through.
+
+    Reraises as a RuntimeError carrying the original message — preserved
+    across the ZeroGPU process boundary via JSON instead of pickle.
+    """
+    if not npz_bytes.startswith(_ERR_SENTINEL):
+        return npz_bytes
+    try:
+        err = json.loads(npz_bytes[len(_ERR_SENTINEL):].decode())
+    except Exception:  # noqa: BLE001
+        raise RuntimeError("GPU worker failed (error payload unparseable)")
+    msg = err.get("message") or f"{err.get('error_class', 'Unknown')}: <no message>"
+    tb = err.get("traceback") or ""
+    if tb:
+        log.error("GPU worker raised %s:\n%s", err.get("error_class"), tb)
+    raise RuntimeError(msg)
+
+
+# GPU-decorated wrappers around the same body. MDM/MoMask take the cheap
+# 30-second slot. Kimodo's admission window is DYNAMIC (spaces supports
+# duration=callable, resolved per call in this process): 300 s cold —
+# the first call after boot pays LLaMA-encoder-sidecar startup (~150 s
+# measured 2026-07-07) — then ~70 s warm (holds 25-42 s measured; wire =
+# decorator × duration_factor 1.5 → 105 s, fitting even a fresh anonymous
+# ZeroGPU bucket of 120 s). Behind KIMODO_WINDOW=dynamic; the default
+# (static) keeps the flat 300 s. Dispatch happens at the orchestrator
+# (CPU) layer in run() — MDM/MoMask quota burn is unaffected.
+
+_KIMODO_COLD_WINDOW_S = 300
+_kimodo_warmed = False  # set after the first successful inference; reset on
+                        # a warm-window timeout so the next call self-heals
+                        # with the cold window (loud, never silent)
+
+
+def _kimodo_window_s() -> int:
+    if os.environ.get("KIMODO_WINDOW", "static").strip().lower() != "dynamic":
+        return _KIMODO_COLD_WINDOW_S
+    if not _kimodo_warmed:
+        return _KIMODO_COLD_WINDOW_S
+    try:
+        return int(os.environ.get("KIMODO_WARM_WINDOW_S", "70") or 70)
+    except ValueError:
+        return _KIMODO_COLD_WINDOW_S
+
+
+def _kimodo_prewarm_loop() -> None:
+    """Boot pre-warm (KIMODO_PREWARM=1): one token-less Kimodo inference as
+    soon as the venv sentinel appears, so the first USER call gets the warm
+    window instead of paying the ~150 s sidecar startup. Runs outside any
+    gradio request → schedules token-less on the Space's shared pool by
+    construction. Failure is LOUD and leaves the cold window active — the
+    system stays correct, just slower (no silent fallback)."""
+    import threading  # noqa: F401 — imported here to keep module deps flat
+
+    try:
+        from bootstrap import _kimodo_ready_sentinel
+    except Exception:
+        log.exception("[kimodo-prewarm] cannot resolve bootstrap sentinel — "
+                      "pre-warm disabled, cold window stays active")
+        return
+    deadline = time.time() + 30 * 60
+    while time.time() < deadline:
+        if _kimodo_ready_sentinel().is_file():
+            break
+        time.sleep(10)
+    else:
+        log.error("[kimodo-prewarm] venv sentinel never appeared in 30 min — "
+                  "pre-warm skipped, cold window stays active")
+        return
+    log.info("[kimodo-prewarm] venv ready — running the cold call now "
+             "(shared pool, ~150 s)")
+    try:
+        raw = _run_inference_gpu_kimodo(
+            "kimodo", "a person walks forward", 100, 0)
+        _unwrap_gpu_result(raw)
+        global _kimodo_warmed
+        _kimodo_warmed = True
+        log.info("[kimodo-prewarm] done — warm window (%ss) active",
+                 _kimodo_window_s())
+    except Exception:
+        log.exception("[kimodo-prewarm] FAILED — cold window stays active")
+
+
+def start_kimodo_prewarm_if_enabled() -> None:
+    """Called at module import (Space boot). No-op unless KIMODO_PREWARM=1."""
+    if os.environ.get("KIMODO_PREWARM", "").strip() != "1":
+        return
+    import threading
+    threading.Thread(target=_kimodo_prewarm_loop, daemon=True,
+                     name="kimodo-prewarm").start()
+    log.info("[kimodo-prewarm] armed (waiting for venv sentinel)")
+
+
+@GPU(duration=30)
+def _run_inference_gpu_fast(
+    model: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    *,
+    guidance_param: float | None = None,
+    **extra: Any,
+) -> bytes:
+    return _safe_do_inference(
+        model, prompt, num_frames, seed,
+        guidance_param=guidance_param, **extra,
+    )
+
+
+@GPU(duration=lambda *a, **k: _kimodo_window_s())
+def _run_inference_gpu_kimodo(
+    model: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    *,
+    guidance_param: float | None = None,
+    **extra: Any,
+) -> bytes:
+    return _safe_do_inference(
+        model, prompt, num_frames, seed,
+        guidance_param=guidance_param, **extra,
+    )
+
+
+# Timeline GPU wrapper — priorMDM double-take. Pass 1 (N segments × ~50 steps)
+# + Pass 2 (handshake re-diffuse, ~5 steps) is ~30-50 s warm on H200 for a
+# 4-segment ~6 s clip. 60 s budget is comfortable; runs on a separate
+# decorator from the 30 s _run_inference_gpu_fast slot because ZeroGPU
+# duration is a static decorator arg.
+@GPU(duration=60)
+def _run_timeline_gpu(
+    segments: list[dict],
+    seed: int,
+    *,
+    guidance_param: float = 2.5,
+    handshake_size: int = 10,
+    blend_len: int = 10,
+) -> bytes:
+    """ZeroGPU-wrapped priorMDM.generate_timeline.
+
+    Same sentinel-prefix pattern as `_safe_do_inference` — ZeroGPU strips
+    exception args across the worker boundary, so we round-trip errors as
+    JSON and let `_unwrap_gpu_result` re-raise them on the orchestrator side.
+    """
+    try:
+        from animoflow_models.registry import _load
+
+        inst = _load("priormdm")
+        npz_bytes, _meta = inst.generate_timeline(
+            segments=segments,
+            seed=seed,
+            guidance_param=guidance_param,
+            handshake_size=handshake_size,
+            blend_len=blend_len,
+        )
+        return npz_bytes
+    except BaseException as e:  # noqa: BLE001 — round-trip across the worker
+        payload = json.dumps({
+            "error_class": type(e).__name__,
+            "error_module": type(e).__module__,
+            "message": str(e) or repr(e),
+            "traceback": traceback.format_exc()[-4000:],
+        }).encode()
+        return _ERR_SENTINEL + payload
+
+
+# ---------------------------------------------------------------------------
+# Plan executor — walks the SAME plan the API server compiles for ComfyUI
+# ---------------------------------------------------------------------------
+
+
+def _make_stage_cb(on_progress, on_stage):
+    def _stage(label: str, progress: float) -> None:
+        if on_stage:
+            try:
+                on_stage(label)
+            except Exception:  # noqa: BLE001
+                log.exception("on_stage callback raised")
+        if on_progress:
+            try:
+                on_progress(progress)
+            except Exception:  # noqa: BLE001
+                log.exception("on_progress callback raised")
+    return _stage
+
+
+def _run_tail(
+    *,
+    job_id: str,
+    npz_bytes: bytes,
+    plan_specs: list,
+    output_fps: int,
+    compress_output: bool,
+    _stage: Callable[[str, float], None],
+    _timings: dict[str, float],
+    t0: float,
+) -> str:
+    """Execute the post-generate stages of a plan (resample → IK → rig →
+    glb_export) against the HF-side implementations. Returns the FBX
+    filename written to OUTPUT_DIR."""
+    stages = _stages()
+    fbx_path: Path | None = None
+    bvh_bytes: bytes | None = None
+
+    # Kimodo emits a rig-ready BVH (SMPL-free rotation path), so its plan has no
+    # `ik` stage — the generated bytes ARE the BVH. Seed bvh_bytes directly so the
+    # rig stage consumes it; resample/ik simply don't appear in the plan.
+    if not any(spec.kind == "ik" for spec in plan_specs):
+        bvh_bytes = npz_bytes
+
+    for spec in plan_specs:
+        if spec.kind in ("generate", "generate_timeline"):
+            continue  # handled by the caller (GPU dispatch differs)
+
+        if spec.kind == "resample":
+            # Always run — even at equal rates it stamps the
+            # authoritative fps key downstream stages rely on.
+            _t = time.perf_counter()
+            in_fps = spec.params["input_fps"]
+            npz_bytes = stages.resample.resample_npz(
+                npz_bytes, in_fps, spec.params["output_fps"])
+            _timings["resample"] = time.perf_counter() - _t
+            log.info(
+                "[%s] resampled %d→%dfps (%d KB NPZ)",
+                job_id, in_fps, spec.params["output_fps"],
+                len(npz_bytes) // 1024,
+            )
+
+        elif spec.kind == "ik":
+            _stage("Inverse Kinematics…", 0.55)
+            _t = time.perf_counter()
+            retargeter = _get_retargeter()
+            # Pass the authoritative post-resample rate — the BVH Frame
+            # Time drives retarget_keemap's scene FPS and thus the final
+            # GLB timing.
+            bvh_bytes, ik_meta = retargeter.npz_to_bvh(npz_bytes, fps=output_fps)
+            _timings["ik"] = time.perf_counter() - _t
+            log.info(
+                "[%s] IK done: %d frames, %d joints",
+                job_id, ik_meta["num_frames"], ik_meta["num_joints"],
+            )
+
+            # Post-process slot intentionally empty — _get_post_funcs().
+
+            # Optional debug dump (off by default): persist per-stage
+            # intermediates. When on, /v1/files/{job_id}.{npz,bvh} become
+            # fetchable alongside .fbx (each artifact needs a single-dot
+            # extension — /v1/files splits on the last dot).
+            if os.environ.get("ANIMOFLOW_DEBUG_DUMP", "0").lower() in ("1", "true", "yes"):
+                try:
+                    (_OUTPUT_DIR / f"{job_id}.npz").write_bytes(npz_bytes)
+                    (_OUTPUT_DIR / f"{job_id}.bvh").write_bytes(bvh_bytes)
+                    log.info(
+                        "[%s] DEBUG_DUMP wrote .npz (%dKB) .bvh (%dKB, raw post-IK)",
+                        job_id, len(npz_bytes)//1024, len(bvh_bytes)//1024,
+                    )
+                except Exception:  # noqa: BLE001
+                    log.exception("DEBUG_DUMP failed (non-fatal)")
+
+        elif spec.kind == "rig":
+            if bvh_bytes is None:
+                raise RuntimeError("rig stage reached with no BVH (missing ik stage?)")
+            _stage("Rigging…", 0.80)
+            _t = time.perf_counter()
+            retargeter = _get_retargeter()
+            character = spec.params["character"]
+            chars_dir = Path(
+                os.environ.get("CHARACTERS_DIR", str(_COMFY_ROOT / "characters"))
+            )
+            fbx_template = chars_dir / f"{character}.fbx"
+            if not fbx_template.exists():
+                raise RuntimeError(
+                    f"Character template not found: {fbx_template}. "
+                    f"Available: {[p.stem for p in chars_dir.glob('*.fbx')]}"
+                )
+            fbx_bytes, _rig_meta = retargeter.bvh_to_fbx(
+                bvh_bytes, fbx_template=str(fbx_template)
+            )
+            _timings["retarget"] = time.perf_counter() - _t
+            log.info("[%s] retarget done: %d KB FBX", job_id, len(fbx_bytes) // 1024)
+
+            fbx_path = _OUTPUT_DIR / f"{job_id}.fbx"
+            fbx_path.write_bytes(fbx_bytes)
+
+        elif spec.kind == "glb_export":
+            if fbx_path is None:
+                raise RuntimeError("glb_export reached with no FBX written")
+            _stage("Post processing…", 0.95)
+            p = spec.params
+            character = p["character"]
+            traj = p.get("traj_restore") or {}
+            _t = time.perf_counter()
+            glb_path: Path | None = fbx_path.with_suffix(".glb")
+            snap_info: dict | None = None
+            snap_elapsed = 0.0
+            try:
+                options = stages.glb_export.GLBExportOptions(
+                    fbx_path=str(fbx_path),
+                    glb_path=str(glb_path),
+                    character=character,
+                    snap_to_ground=p["snap_to_ground"],
+                    characters_dir=os.environ.get(
+                        "CHARACTERS_DIR", str(_COMFY_ROOT / "characters")),
+                    cache_dir=str(_OUTPUT_DIR),
+                    comfy_root=str(_COMFY_ROOT),
+                    traj_theta=float(traj.get("theta_rad", 0.0)),
+                    traj_tx=float(traj.get("tx", 0.0)),
+                    traj_tz=float(traj.get("tz", 0.0)),
+                    keyframe_builder=p["keyframe_builder"],
+                    keyframe_builder_error_degrees=p["keyframe_builder_error_degrees"],
+                )
+                result = stages.glb_export.run_glb_export(options, timeout=120)
+                snap_info = result["snap_info"]
+                snap_elapsed = result["snap_elapsed_s"]
+            except Exception:  # noqa: BLE001
+                # GLB export is best-effort on the Space — the FBX is
+                # already written and downloadable. (The local ComfyUI
+                # node raises instead: there the GLB IS the terminal
+                # output.)
+                log.exception("GLB export failed (FBX still written)")
+                glb_path = None
+            _timings["glb"] = time.perf_counter() - _t
+
+            # Sidecar JSON the API layer reads and surfaces as
+            # JobResponse.snap_info.
+            if snap_info is None and not p["snap_to_ground"]:
+                snap_info = {"applied": False,
+                             "reason": "request snap_to_ground=false"}
+            if snap_info is not None:
+                try:
+                    (_OUTPUT_DIR / f"{job_id}.snap.json").write_text(
+                        json.dumps(snap_info))
+                except OSError:
+                    log.exception("Failed to write snap_info sidecar")
+            # Snap wall time runs inside the Blender subprocess; surface
+            # it separately and keep the timing sum honest.
+            if snap_elapsed > 0.0:
+                _timings["snap"] = snap_elapsed
+                _timings["glb"] = max(_timings["glb"] - snap_elapsed, 0.0)
+
+            # Embedded-texture downsize BEFORE gltfpack (alignment rules
+            # — see animoflow_stages/glb_post.py). No-op on textureless
+            # characters. Env-gated, default ON here — the Space's file
+            # serving is throttled ~100 KB/s.
+            if glb_path is not None and os.environ.get(
+                "ENABLE_TEXTURE_DOWNSIZE", "true"
+            ).lower() == "true":
+                _t = time.perf_counter()
+                stages.glb_post.downsize_glb_textures(glb_path)
+                _timings["glb_texresize"] = time.perf_counter() - _t
+
+            # gltfpack -cc. Two opt-outs: ENABLE_GLB_COMPRESSION env kill
+            # switch, and the per-request compress_output flag (the
+            # Blender addon opts out — Blender 5 rejects
+            # EXT_meshopt_compression). Failures raise — no silent
+            # fallback.
+            if (
+                glb_path is not None
+                and compress_output
+                and os.environ.get("ENABLE_GLB_COMPRESSION", "true").lower() == "true"
+            ):
+                _t = time.perf_counter()
+                stages.glb_post.compress_glb(glb_path)
+                _timings["glb_compress"] = time.perf_counter() - _t
+
+        else:
+            raise ValueError(f"Unknown stage kind {spec.kind!r}")
+
+    if fbx_path is None:
+        raise RuntimeError("plan finished without producing an FBX")
+
+    _timings["total"] = time.perf_counter() - t0
+    _timing_parts = " ".join(f"{k}={v:.2f}s" for k, v in _timings.items())
+    log.info("[STAGE_TIMINGS] job=%s %s", job_id, _timing_parts)
+    log.info(
+        "[%s] HF pipeline complete in %.1fs total → %s",
+        job_id, _timings["total"], fbx_path.name,
+    )
+    return fbx_path.name
+
+
+# ---------------------------------------------------------------------------
+# Public API — drop-in replacement for animoflow-api/api/pipeline.py
+# ---------------------------------------------------------------------------
+
+
+def run(
+    job_id: str,
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    character: str = "Y_bot",
+    model: str = "mdm",
+    on_progress: Callable[[float], None] | None = None,
+    on_stage: Callable[[str], None] | None = None,
+    preprocess_stages: list[dict] | None = None,
+    keyframe_builder: bool = False,
+    keyframe_builder_error_degrees: float = 3.0,
+    snap_to_ground: bool = True,
+    output_fps: int = 30,
+    cfg: float = 2.5,
+    curve_2d: list[list[float]] | None = None,
+    traj_restore: dict | None = None,
+    accel_frac: float = 0.25,
+    decel_frac: float = 0.25,
+    waypoints: list[dict] | None = None,
+    compress_output: bool = True,
+) -> str:
+    """HF replacement for animoflow-api/api/pipeline.py:run.
+
+    Returns the output filename (e.g. 'abc.fbx'). Same semantics: writes
+    to OUTPUT_DIR, raises on failure.
+
+    Conditioning args:
+      - accel_frac, decel_frac: priorMDM-only velocity-profile shaping.
+      - curve_2d: priorMDM (trajectory) or Kimodo (trajectory task — dense XZ
+        path; frame_indices are evenly distributed across num_frames).
+      - waypoints: Kimodo-only (waypoint task — sparse list of {x, z, t}
+        where t is a frame index in [0, num_frames). Wins over curve_2d
+        when both are set.
+    """
+    t0 = time.perf_counter()
+    log.info(
+        "[%s] HF pipeline run: model=%s prompt=%r num_frames=%d seed=%d character=%s",
+        job_id, model, prompt[:60], num_frames, seed, character,
+    )
+
+    _timings: dict[str, float] = {}
+    _stage = _make_stage_cb(on_progress, on_stage)
+    # Fire the first stage label before touching the stage library so
+    # callers see progress even when the checkout is missing/broken.
+    _stage("Generating…", 0.05)
+
+    stages = _stages()
+    plan_specs = stages.plan.build_plan(
+        model, character,
+        prompt=prompt,
+        num_frames=num_frames,
+        seed=seed,
+        output_fps=output_fps,
+        snap_to_ground=snap_to_ground,
+        keyframe_builder=keyframe_builder,
+        keyframe_builder_error_degrees=keyframe_builder_error_degrees,
+        traj_restore=traj_restore,
+        compress_output=compress_output,
+        curve_2d=curve_2d,
+        waypoints=waypoints,
+        accel_frac=accel_frac,
+        decel_frac=decel_frac,
+    )
+
+    # ── Stage 1: GPU inference ───────────────────────────────────────────
+    _t = time.perf_counter()
+    # Per-model conditioning kwargs come from the SHARED mapping — the
+    # same one the ComfyUI compiler uses for node inputs.
+    extra = stages.genparams.build_hf_gen_extra(
+        model,
+        num_frames=num_frames,
+        cfg=cfg,
+        curve_2d=curve_2d,
+        waypoints=waypoints,
+        accel_frac=accel_frac,
+        decel_frac=decel_frac,
+    )
+
+    # Dispatch to the appropriately-budgeted @spaces.GPU wrapper. Kimodo
+    # needs ~300 s for cold-start (LLaMA encoder warmup + model load);
+    # MDM/MoMask stay on the cheap 30 s slot so their daily ZeroGPU quota
+    # is unaffected.
+    gpu_fn = (
+        _run_inference_gpu_kimodo if model == "kimodo" else _run_inference_gpu_fast
+    )
+    # Guidance scale from the request (cfg), already clamped to the
+    # model's range by the API server. Was hardcoded None (each model's
+    # internal default) — passing it explicitly is what makes the /v1
+    # `cfg` field actually take effect for simple-mode tasks.
+    global _kimodo_warmed
+    try:
+        npz_bytes = gpu_fn(
+            model, prompt, num_frames, seed, guidance_param=cfg, **extra,
+        )
+        # Decode the sentinel-prefixed error payload if the GPU worker raised.
+        npz_bytes = _unwrap_gpu_result(npz_bytes)
+    except Exception as exc:
+        if model == "kimodo" and _kimodo_warmed and (
+                "timeout" in str(exc).lower() or "timed out" in str(exc).lower()
+                or "aborted" in str(exc).lower()):
+            # A warm-windowed run overran or was killed: drop back to the
+            # cold window so the NEXT call self-heals. Loud by design.
+            _kimodo_warmed = False
+            log.error("[kimodo-window] warm-window run failed (%s) — warm "
+                      "flag RESET, next call uses the %ss cold window",
+                      type(exc).__name__, _KIMODO_COLD_WINDOW_S)
+        raise
+    if model == "kimodo" and not _kimodo_warmed:
+        _kimodo_warmed = True
+        log.info("[kimodo-window] first successful inference — warm window "
+                 "(%ss) active for subsequent calls", _kimodo_window_s())
+    _timings["gpu"] = time.perf_counter() - _t
+    log.info(
+        "[%s] inference done in %.1fs (%d KB NPZ)",
+        job_id, _timings["gpu"], len(npz_bytes) // 1024,
+    )
+
+    return _run_tail(
+        job_id=job_id,
+        npz_bytes=npz_bytes,
+        plan_specs=plan_specs,
+        output_fps=output_fps,
+        compress_output=compress_output,
+        _stage=_stage,
+        _timings=_timings,
+        t0=t0,
+    )
+
+
+def run_timeline(
+    job_id: str,
+    segments: list[dict],
+    seed: int,
+    character: str = "Y_bot",
+    cfg: float = 2.5,
+    handshake_size: int = 10,
+    blend_len: int = 10,
+    on_progress: Callable[[float], None] | None = None,
+    on_stage: Callable[[str], None] | None = None,
+    keyframe_builder: bool = False,
+    keyframe_builder_error_degrees: float = 3.0,
+    snap_to_ground: bool = True,
+    output_fps: int = 30,
+    compress_output: bool = True,
+) -> str:
+    """HF replacement for animoflow-api/api/pipeline.py:run_timeline.
+
+    Drives priorMDM's double-take long-motion path. Each segment is
+    `{"prompt": str, "num_frames": int}` — frame counts are caller-resolved
+    against priorMDM's 20 fps native rate (api/main.py converts segment
+    duration → num_frames at _PRIORMDM_FPS=20).
+    """
+    t0 = time.perf_counter()
+    log.info(
+        "[%s] HF pipeline run_timeline: %d segments seed=%d character=%s",
+        job_id, len(segments), seed, character,
+    )
+
+    _timings: dict[str, float] = {}
+    _stage = _make_stage_cb(on_progress, on_stage)
+    _stage("Generating long motion…", 0.05)
+
+    stages = _stages()
+    plan_specs = stages.plan.build_timeline_plan(
+        segments, character,
+        seed=seed,
+        cfg=cfg,
+        handshake_size=handshake_size,
+        blend_len=blend_len,
+        output_fps=output_fps,
+        snap_to_ground=snap_to_ground,
+        keyframe_builder=keyframe_builder,
+        keyframe_builder_error_degrees=keyframe_builder_error_degrees,
+        compress_output=compress_output,
+    )
+
+    # ── Stage 1: GPU inference (priorMDM double-take) ────────────────────
+    _t = time.perf_counter()
+    npz_bytes = _run_timeline_gpu(
+        segments=segments,
+        seed=seed,
+        guidance_param=cfg,
+        handshake_size=handshake_size,
+        blend_len=blend_len,
+    )
+    npz_bytes = _unwrap_gpu_result(npz_bytes)
+    _timings["gpu"] = time.perf_counter() - _t
+    log.info(
+        "[%s] timeline inference done in %.1fs (%d KB NPZ)",
+        job_id, _timings["gpu"], len(npz_bytes) // 1024,
+    )
+
+    return _run_tail(
+        job_id=job_id,
+        npz_bytes=npz_bytes,
+        plan_specs=plan_specs,
+        output_fps=output_fps,
+        compress_output=compress_output,
+        _stage=_stage,
+        _timings=_timings,
+        t0=t0,
+    )
+
+
+# Boot pre-warm hook — module import happens once at Space startup (ui.py).
+# No-op unless KIMODO_PREWARM=1.
+start_kimodo_prewarm_if_enabled()

requirements.txt

@@ -0,0 +1,54 @@
+# Orchestrator + MDM family — single venv on HF Space.
+# Outlier models (Kimodo etc.) live in their own venvs (escape_hatch) and are
+# subprocess-called from inside @spaces.GPU.
+
+# Core orchestration.
+# NOTE: gradio is intentionally NOT pinned here. HF's Gradio SDK runtime
+# injects its own gradio version (currently 6.13.0); pinning a different
+# version causes a build conflict. For OSS-local dev we accept whatever
+# pip resolves alongside HF's other deps.
+fastapi>=0.115.6
+uvicorn[standard]>=0.32.1
+# gradio — injected by HF Gradio SDK runtime
+httpx>=0.27.0
+python-multipart>=0.0.20
+slowapi>=0.1.9
+websocket-client>=1.8.0
+pydantic>=2.10.4
+
+# HF Spaces ZeroGPU runtime — no-op in OSS mode
+# spaces — injected by HF Gradio SDK runtime
+
+# huggingface_hub — used at Docker build time to download baked-in model
+# checkpoints from AnimoFlow/animoflow-checkpoints. Also used at runtime
+# by transformers.
+huggingface_hub>=0.27.0
+
+# Numerics for IK + retarget pipeline (matches start-local.sh's pinned trio)
+# torch — injected by HF ZeroGPU runtime
+# torchvision — injected by HF ZeroGPU runtime
+numpy>=1.26.4
+scipy>=1.13.1
+matplotlib>=3.9.2
+
+# MDM-family deps (CLIP, transformers used by MDM/priorMDM/MoMask)
+transformers>=4.46.3
+ftfy>=6.3.1
+regex>=2024.11.6
+git+https://github.com/openai/CLIP.git
+# Pulled from comfyui-animoflow/containers/mdm/requirements.txt — adding here
+# rather than installing MDM container's reqs separately, because that file
+# pins torch==2.3.0 which downgrades us from 2.4.1 and removes the
+# torch.library.register_fake API the upstream MDM source code uses.
+einops>=0.8.0
+
+# Blender retarget pipeline support
+trimesh>=4.5.3
+
+# Multilingual prompt rewriter (animoflow-api/api/rewriter.py)
+sentence-transformers>=3.0
+accelerate>=1.0
+
+# Tests
+pytest>=8.3.4
+pytest-asyncio>=0.25.0

scripts/download_weights.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Best-effort MDM weight download.
+#
+# DELIBERATE: this script never aborts the entrypoint. Failures log a
+# warning + exit 0 so the orchestrator can boot in a "checkpoints missing"
+# state. /v1/health, /v1/tasks, and the Gradio UI all work without
+# weights; only actual inference requests fail (with a clear "checkpoint
+# missing at <path>" error).
+#
+# Manual fallback if the HF mirror URLs below ever break: grab the MDM
+# checkpoint from the upstream Google Drive link in
+# https://github.com/GuyTevet/motion-diffusion-model README and drop it at
+#   ${CHECKPOINTS_DIR:-/opt/checkpoints}/humanml_trans_enc_512/model000475000.pt
+# alongside its args.json. Same for priorMDM and MoMask.
+
+set -uo pipefail   # NOT -e — best-effort
+
+CHECKPOINTS_DIR="${CHECKPOINTS_DIR:-/opt/checkpoints}"
+mkdir -p "${CHECKPOINTS_DIR}"
+
+_warn() { echo "[weights] WARN: $*" >&2 ; }
+_ok()   { echo "[weights] $*" ; }
+
+# Fast-path: if the Docker build already baked the canonical 50-step MDM
+# checkpoint via `huggingface_hub.snapshot_download`, there's nothing to
+# fetch at runtime. Skip the legacy mirror dance entirely.
+if [ -f "${CHECKPOINTS_DIR}/humanml_enc_512_50steps/model000750000.pt" ]; then
+    _ok "MDM 50-step checkpoint already baked at ${CHECKPOINTS_DIR}/humanml_enc_512_50steps/ (skip)"
+    exit 0
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# MDM (humanml_trans_enc_512) — legacy fallback for OSS-local users who
+# build without the hf_token secret. Best-effort; failures don't abort.
+# ─────────────────────────────────────────────────────────────────────
+MDM_DIR="${CHECKPOINTS_DIR}/humanml_trans_enc_512"
+MDM_PT="${MDM_DIR}/model000475000.pt"
+MDM_ARGS="${MDM_DIR}/args.json"
+
+if [ -f "${MDM_PT}" ]; then
+    _ok "MDM already present at ${MDM_DIR} (skip)"
+else
+    _ok "downloading MDM humanml_trans_enc_512 → ${MDM_DIR}"
+    mkdir -p "${MDM_DIR}"
+
+    # Candidate mirror URLs. Add more as we learn what's reachable; first
+    # one that works wins. None of these are guaranteed — if all fail,
+    # the warning at the bottom tells the user how to drop weights manually.
+    _MIRRORS_PT=(
+        "https://huggingface.co/guytevet/motion-diffusion-model/resolve/main/save/humanml_trans_enc_512/model000475000.pt"
+        "https://huggingface.co/guytevet/MDM/resolve/main/humanml_trans_enc_512/model000475000.pt"
+    )
+    _MIRRORS_ARGS=(
+        "https://huggingface.co/guytevet/motion-diffusion-model/resolve/main/save/humanml_trans_enc_512/args.json"
+        "https://huggingface.co/guytevet/MDM/resolve/main/humanml_trans_enc_512/args.json"
+    )
+
+    _got_pt=0
+    for url in "${_MIRRORS_PT[@]}"; do
+        if curl -fsSL --max-time 300 "${url}" -o "${MDM_PT}.partial" 2>/dev/null; then
+            mv "${MDM_PT}.partial" "${MDM_PT}"
+            _got_pt=1
+            _ok "MDM .pt fetched from ${url}"
+            break
+        fi
+        rm -f "${MDM_PT}.partial" 2>/dev/null
+    done
+
+    if [ "${_got_pt}" = "1" ]; then
+        for url in "${_MIRRORS_ARGS[@]}"; do
+            if curl -fsSL --max-time 60 "${url}" -o "${MDM_ARGS}.partial" 2>/dev/null; then
+                mv "${MDM_ARGS}.partial" "${MDM_ARGS}"
+                _ok "MDM args.json fetched from ${url}"
+                break
+            fi
+            rm -f "${MDM_ARGS}.partial" 2>/dev/null
+        done
+    fi
+
+    if [ ! -f "${MDM_PT}" ]; then
+        _warn "all MDM mirror URLs failed."
+        _warn "To enable MDM inference, drop the checkpoint manually:"
+        _warn "  ${MDM_PT}"
+        _warn "  ${MDM_ARGS}"
+        _warn "Source: https://github.com/GuyTevet/motion-diffusion-model README → 'Get data and checkpoints' (Google Drive)."
+    fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────
+# t2m_mean / t2m_std symlinks
+# These are required for the HumanML3D normalization. They're checked
+# into comfyui-animoflow/containers/mdm/ and the upstream MDM code
+# expects them at $MDM_PATH/dataset/HumanML3D/.
+# ─────────────────────────────────────────────────────────────────────
+MDM_SRC="${MDM_PATH:-/opt/mdm-codes}"
+if [ -d "${MDM_SRC}" ]; then
+    mkdir -p "${MDM_SRC}/dataset/HumanML3D" 2>/dev/null
+    for npy in t2m_mean t2m_std; do
+        SRC="/opt/comfyui-animoflow/containers/mdm/${npy}.npy"
+        DST="${MDM_SRC}/dataset/HumanML3D/${npy}.npy"
+        if [ -f "${SRC}" ] && [ ! -e "${DST}" ]; then
+            ln -sfn "${SRC}" "${DST}" 2>/dev/null && _ok "linked ${npy}.npy"
+        fi
+    done
+fi
+
+_ok "done (best-effort)"
+exit 0

scripts/run_inference_kimodo.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python
+"""
+Kimodo escape-hatch runner.
+
+Contract (matches escape_hatch/invoke.py:invoke):
+  - Stdin:  JSON {prompt, num_frames, seed, guidance_param,
+                  num_denoising_steps?, cfg_text?, cfg_constraint?,
+                  root2d?: {"frame_indices": [int], "smooth_root_2d": [[x,z]]}}
+            num_frames is already in Kimodo's native 30 fps — animoflow-api
+            converts duration→frames upstream (api/main.py:623-633).
+            root2d is the unified XZ floor-plane constraint that powers both
+            "trajectory" (dense frames) and "waypoint" (sparse frames) tasks.
+            When omitted, Kimodo runs unconstrained text→motion.
+  - Stdout: BVH bytes (22-joint MoMask hierarchy) from the SMPL-free
+            rotation-carrying calibrated converter (container fmt="bvh22").
+            The rotations carry the pose, so the downstream HF pipeline skips
+            IK and consumes the BVH directly (retarget → GLB).
+  - Stderr: free-form logs (escape_hatch surfaces last 400 chars on failure).
+  - Exit:   0 success, non-zero on any failure.
+
+Per the no-silent-fallback policy: every failure raises. No placeholder.
+
+Runs from inside the Kimodo venv at $KIMODO_VENV_PYTHON. The orchestrator
+(animoflow-app) spawns this subprocess from inside @spaces.GPU.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+import traceback
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Stdout is reserved for NPZ bytes — everything else goes to stderr.
+# CRITICAL: kimodo / transformers / py-soma-x all print() to stdout
+# (model load banners, LLM2Vec patch messages, progress bars). Without
+# diversion those bytes would prepend to the NPZ payload and `np.load`
+# would fail with "Failed to interpret file as a pickle". We dup the
+# original stdout fd, redirect Python-level sys.stdout AND fd 1 to
+# stderr for the duration of the library calls, then restore the
+# saved fd only when we're ready to write the NPZ bytes.
+# ---------------------------------------------------------------------------
+
+_STDOUT_BACKUP_FD: int | None = None
+
+
+def _divert_stdout_to_stderr() -> None:
+    """Redirect sys.stdout AND raw fd 1 to stderr so library `print()`s
+    don't corrupt our binary stdout payload. Saves the original fd so
+    we can restore it just before writing the NPZ."""
+    global _STDOUT_BACKUP_FD
+    if _STDOUT_BACKUP_FD is not None:
+        return  # idempotent
+    sys.stdout.flush()
+    _STDOUT_BACKUP_FD = os.dup(1)
+    os.dup2(2, 1)  # point fd 1 at fd 2 (stderr)
+    sys.stdout = sys.stderr
+
+
+def _restore_stdout_for_npz() -> None:
+    """Restore the original stdout fd for the final NPZ write."""
+    global _STDOUT_BACKUP_FD
+    if _STDOUT_BACKUP_FD is None:
+        return
+    sys.stderr.flush()
+    os.dup2(_STDOUT_BACKUP_FD, 1)
+    os.close(_STDOUT_BACKUP_FD)
+    _STDOUT_BACKUP_FD = None
+    sys.stdout = os.fdopen(1, "wb", closefd=False)
+
+
+def _log(msg: str) -> None:
+    print(f"[kimodo-runner] {msg}", file=sys.stderr, flush=True)
+
+
+def _fail(msg: str, code: int = 1) -> "None":
+    _log(f"FAIL: {msg}")
+    sys.exit(code)
+
+
+# ---------------------------------------------------------------------------
+# Sentinel checks — defence-in-depth (escape_hatch.invoke gates first, but the
+# runner must also refuse to start if the venv build hasn't finished or failed).
+# ---------------------------------------------------------------------------
+
+_EXTERNAL_DIR = Path(
+    os.environ.get(
+        "ANIMOFLOW_EXTERNAL_DIR",
+        "/home/user/app/external"
+        if os.path.isdir("/home/user/app")
+        else str(Path(__file__).resolve().parent.parent / "external"),
+    )
+)
+_READY_SENTINEL = _EXTERNAL_DIR / ".kimodo_ready"
+_FAILED_SENTINEL = _EXTERNAL_DIR / ".kimodo_failed"
+
+
+def _check_sentinels() -> None:
+    if _FAILED_SENTINEL.is_file():
+        body = ""
+        try:
+            body = _FAILED_SENTINEL.read_text()[:1200]
+        except OSError:
+            pass
+        _fail(
+            f"Kimodo venv build previously failed:\n{body}\n"
+            f"Delete {_FAILED_SENTINEL} and restart the Space to retry."
+        )
+    if not _READY_SENTINEL.is_file():
+        _fail(
+            f"Kimodo venv not ready (sentinel missing: {_READY_SENTINEL}). "
+            "The bootstrap thread may still be running."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Import the AnimoFlow-owned helpers from comfyui-animoflow/containers/kimodo/app.py.
+#
+# The container's app.py constructs a FastAPI app at module top, but nothing
+# serves it — importing it has no runtime cost beyond the import statements.
+# We reuse its _patch_llm2vec_for_ungated_llama, _load_model, and
+# _motion_to_output helpers verbatim per [[Wrap, don't fork upstream
+# model repos]] (this file is AnimoFlow-authored, not upstream NVIDIA).
+# ---------------------------------------------------------------------------
+
+
+def _load_kimodo_app_module():
+    comfy_root = os.environ.get("COMFYUI_ANIMOFLOW_DIR")
+    if not comfy_root:
+        _fail(
+            "COMFYUI_ANIMOFLOW_DIR not set — the runner can't locate the "
+            "containers/kimodo/app.py helper module."
+        )
+    container_dir = Path(comfy_root) / "containers" / "kimodo"
+    app_py = container_dir / "app.py"
+    if not app_py.is_file():
+        _fail(f"containers/kimodo/app.py not found at {app_py}")
+
+    # Make `soma_smpl22_bvh` (a sibling module of app.py) importable.
+    if str(container_dir) not in sys.path:
+        sys.path.insert(0, str(container_dir))
+    # Make the Kimodo source tree importable.
+    kimodo_src = os.environ.get("KIMODO_SRC_DIR")
+    if kimodo_src and kimodo_src not in sys.path:
+        sys.path.insert(0, kimodo_src)
+
+    spec = importlib.util.spec_from_file_location("kimodo_helpers", app_py)
+    if spec is None or spec.loader is None:
+        _fail(f"importlib failed to build spec for {app_py}")
+    mod = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+    spec.loader.exec_module(mod)  # type: ignore[union-attr]
+    return mod
+
+
+# Memoize the loaded model across calls in the same subprocess. In practice
+# this is one call per @spaces.GPU subprocess, but cheap insurance.
+_KIMODO_MODEL = None
+_KIMODO_HELPERS = None
+
+
+def _ensure_model_loaded():
+    global _KIMODO_MODEL, _KIMODO_HELPERS
+    if _KIMODO_MODEL is not None:
+        return _KIMODO_MODEL, _KIMODO_HELPERS
+
+    _KIMODO_HELPERS = _load_kimodo_app_module()
+    _log(f"loaded helpers from containers/kimodo/app.py (device={_KIMODO_HELPERS.DEVICE})")
+
+    # _load_model populates the module-global _model AND patches LLM2Vec configs
+    # to point at the ungated LLaMA mirror. Idempotent.
+    _KIMODO_HELPERS._load_model()
+    _KIMODO_MODEL = _KIMODO_HELPERS._model
+    if _KIMODO_MODEL is None:
+        _fail("_load_model() returned but kimodo_helpers._model is still None")
+    _log(f"model ready: {type(_KIMODO_MODEL).__name__}")
+    return _KIMODO_MODEL, _KIMODO_HELPERS
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main() -> int:
+    _check_sentinels()
+
+    # Read stdin payload BEFORE diverting stdout (we don't write to stdout
+    # while reading).
+    try:
+        payload = json.loads(sys.stdin.read())
+    except Exception as exc:  # noqa: BLE001
+        _fail(f"could not parse stdin JSON: {exc}")
+        return 2  # unreachable — _fail exits, but keeps type-checkers happy
+
+    # From here on, every library print() must go to stderr until we're
+    # ready to dump the NPZ bytes. Kimodo / transformers / py-soma-x all
+    # print to stdout (model load banners, "[Kimodo] patching adapter_config"
+    # etc.) — without this diversion the NPZ payload is prepended with text
+    # and `np.load(BytesIO(stdout_bytes))` fails with "Failed to interpret
+    # file as a pickle".
+    _divert_stdout_to_stderr()
+
+    prompt = payload.get("prompt")
+    num_frames = payload.get("num_frames")
+    seed = payload.get("seed")
+    if not isinstance(prompt, str) or not prompt.strip():
+        _fail("payload.prompt missing or empty")
+    if not isinstance(num_frames, int) or num_frames <= 0:
+        _fail(f"payload.num_frames missing or non-positive: {num_frames!r}")
+    if not isinstance(seed, int):
+        _fail(f"payload.seed missing or not an int: {seed!r}")
+
+    num_denoising_steps = int(payload.get("num_denoising_steps", 100))
+    # Kimodo's cfg_weight is [cfg_text, cfg_constraint]. The animoflow-api UI
+    # exposes a single `cfg` knob which pipeline_hf maps to both. The runner
+    # accepts either explicit split values or the single guidance_param.
+    if "cfg_text" in payload or "cfg_constraint" in payload:
+        cfg_text = float(payload.get("cfg_text", 2.0))
+        cfg_constraint = float(payload.get("cfg_constraint", 2.0))
+    else:
+        gp = payload.get("guidance_param")
+        cfg = float(gp) if gp is not None else 2.0
+        cfg_text = cfg
+        cfg_constraint = cfg
+
+    # Unified root2d constraint covers both trajectory (dense) and waypoint
+    # (sparse) tasks. pipeline_hf builds the dict; we forward it to Kimodo's
+    # constraint loader. Fail-fast on malformed shapes — no silent fallback.
+    root2d = payload.get("root2d")
+    if root2d is not None:
+        if not isinstance(root2d, dict):
+            _fail(f"payload.root2d must be a dict, got {type(root2d).__name__}")
+        frame_indices = root2d.get("frame_indices")
+        smooth_root_2d = root2d.get("smooth_root_2d")
+        if not isinstance(frame_indices, list) or not frame_indices:
+            _fail("payload.root2d.frame_indices must be a non-empty list of ints")
+        if not isinstance(smooth_root_2d, list) or not smooth_root_2d:
+            _fail("payload.root2d.smooth_root_2d must be a non-empty list of [x,z] pairs")
+        if len(frame_indices) != len(smooth_root_2d):
+            _fail(
+                f"payload.root2d length mismatch: frame_indices={len(frame_indices)} "
+                f"vs smooth_root_2d={len(smooth_root_2d)}"
+            )
+        for i, p in enumerate(smooth_root_2d):
+            if not (isinstance(p, list) and len(p) == 2):
+                _fail(f"payload.root2d.smooth_root_2d[{i}] must be [x, z]; got {p!r}")
+        max_frame = max(frame_indices)
+        if max_frame >= num_frames or min(frame_indices) < 0:
+            _fail(
+                f"payload.root2d.frame_indices out of range [0, {num_frames}): "
+                f"min={min(frame_indices)} max={max_frame}"
+            )
+
+    model, helpers = _ensure_model_loaded()
+
+    # Match the container's _generate_worker call path (containers/kimodo/app.py:472-481).
+    import torch
+    from kimodo.tools import seed_everything
+
+    seed_everything(int(seed))
+
+    # Build the constraint_lst kwarg. load_constraints_lst takes either a JSON
+    # path or a list[dict] directly; we pass a list[dict] to avoid file I/O.
+    # See kimodo/constraints.py:566-593 (TYPE_TO_CLASS["root2d"] → Root2DConstraintSet).
+    constraint_lst: list = []
+    if root2d is not None:
+        from kimodo.constraints import load_constraints_lst
+        dev = next(model.parameters()).device if hasattr(model, "parameters") else None
+        constraint_lst = load_constraints_lst(
+            [{"type": "root2d",
+              "frame_indices": [int(f) for f in root2d["frame_indices"]],
+              "smooth_root_2d": [[float(x), float(z)] for (x, z) in root2d["smooth_root_2d"]]}],
+            model.skeleton,
+            device=dev,
+            dtype=torch.float32,
+        )
+        _log(
+            f"root2d constraint: {len(root2d['frame_indices'])} frames "
+            f"(min={min(root2d['frame_indices'])} max={max(root2d['frame_indices'])}) "
+            f"XZ range x=[{min(p[0] for p in root2d['smooth_root_2d']):.2f},"
+            f"{max(p[0] for p in root2d['smooth_root_2d']):.2f}] "
+            f"z=[{min(p[1] for p in root2d['smooth_root_2d']):.2f},"
+            f"{max(p[1] for p in root2d['smooth_root_2d']):.2f}]"
+        )
+
+    _log(
+        f"generating: prompt={prompt[:60]!r} num_frames={num_frames} "
+        f"seed={seed} steps={num_denoising_steps} cfg=[{cfg_text},{cfg_constraint}] "
+        f"constraints={len(constraint_lst)}"
+    )
+    with torch.no_grad():
+        output = model(
+            prompts=prompt,
+            num_frames=num_frames,
+            num_denoising_steps=num_denoising_steps,
+            cfg_weight=[cfg_text, cfg_constraint],
+            constraint_lst=constraint_lst,
+            return_numpy=False,
+            post_processing=False,
+        )
+
+    # SOMA → 22-joint rig-ready BVH (SMPL-free rotation-carrying calibrated path).
+    # The rotations carry the pose, so this feeds the rig stage directly — the
+    # orchestrator's plan skips IK for Kimodo.
+    data, is_npz = helpers._motion_to_output(output, model.output_skeleton, fmt="bvh22")
+    if is_npz:
+        _fail("_motion_to_output returned is_npz=True for fmt='bvh22' — expected a BVH string")
+    if not isinstance(data, str) or not data:
+        _fail(f"_motion_to_output returned empty/non-str BVH payload: {type(data)}")
+
+    # Defensive: sanity-check the BVH header before handing it to the rig stage.
+    bvh_bytes = data.encode()
+    nframes = next((int(l.split(":", 1)[1]) for l in data.splitlines()
+                    if l.startswith("Frames:")), None)
+    if "HIERARCHY" not in data or nframes is None:
+        _fail("bvh22 output missing HIERARCHY / Frames header")
+    _log(f"output: BVH {nframes} frames ({len(bvh_bytes)//1024} KB)")
+
+    # Restore the saved stdout fd and write the BVH payload as raw bytes.
+    _restore_stdout_for_npz()
+    os.write(1, bvh_bytes)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except SystemExit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        # Top-level guard so any uncaught error lands as a clear stderr trace
+        # rather than a silent non-zero exit. No silent fallback.
+        print(f"[kimodo-runner] FATAL UNCAUGHT: {type(exc).__name__}: {exc}", file=sys.stderr)
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(1)

spaces_compat.py

@@ -0,0 +1,74 @@
+"""
+ZeroGPU compatibility shim.
+
+In an HF Space with ZeroGPU, the `spaces` package is installed and
+`@spaces.GPU(duration=N)` allocates an H200 to the decorated function for
+its duration. Outside HF (any OSS local install, CI, tests), the package
+isn't present — we fall back to a pass-through decorator so the same code
+runs unchanged on any host.
+
+Usage:
+
+    from spaces_compat import GPU
+
+    @GPU(duration=30)
+    def run_inference(...):
+        ...
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from functools import wraps
+from typing import Any, Callable
+
+log = logging.getLogger(__name__)
+
+
+def _is_huggingface_space() -> bool:
+    """Heuristic: HF Spaces always set this env var."""
+    return bool(os.environ.get("SPACE_ID")) or bool(os.environ.get("SPACE_AUTHOR_NAME"))
+
+
+try:
+    import spaces  # type: ignore[import-not-found]
+
+    GPU = spaces.GPU  # re-export
+    HAVE_SPACES = True
+    if _is_huggingface_space():
+        log.info("ZeroGPU active — @spaces.GPU will allocate H200 per call")
+    else:
+        log.info("`spaces` importable but not in HF Space — decorator is best-effort")
+except ImportError:  # pragma: no cover — exercised in OSS local
+    HAVE_SPACES = False
+
+    def GPU(*decorator_args: Any, **decorator_kwargs: Any) -> Callable:  # type: ignore[no-redef]
+        """Pass-through decorator for non-HF environments.
+
+        Supports both forms:
+            @GPU
+            def fn(...): ...
+
+            @GPU(duration=30)
+            def fn(...): ...
+        """
+        # Bare-decorator form: @GPU on a function with no parens
+        if (
+            len(decorator_args) == 1
+            and callable(decorator_args[0])
+            and not decorator_kwargs
+        ):
+            return decorator_args[0]
+
+        # Parameterized form: @GPU(...) returns a decorator
+        def decorator(fn: Callable) -> Callable:
+            @wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                return fn(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    log.info("`spaces` package not installed — GPU decorator is a no-op pass-through")

tests/conftest.py

@@ -0,0 +1,70 @@
+"""
+Pytest fixtures shared across animoflow-app tests.
+
+Key constraint: tests must pass on a CPU laptop with no GPU, no model
+weights, and (ideally) no Blender. We mock model inference and skip
+end-to-end pipeline tests when blender / weights are absent.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+_HERE = Path(__file__).resolve().parent
+_REPO = _HERE.parent
+
+# Make app modules importable
+if str(_REPO) not in sys.path:
+    sys.path.insert(0, str(_REPO))
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _set_test_env():
+    """Set test-friendly env vars before any module imports.
+
+    Uses a well-known sub-path of /tmp instead of pytest's tmp_path_factory
+    because some FUSE-mounted sandboxes throw on rmdir of session tmpdirs,
+    sending pytest's cleanup into recursion. Stable per-test-run path is
+    safer and behaves identically across hosts.
+    """
+    test_root = Path("/tmp/animoflow-app-test")
+    os.environ["OUTPUT_DIR"] = str(test_root / "output")
+    os.environ.setdefault("WEB_DIR", "/nonexistent")
+    os.environ.setdefault("CHECKPOINTS_DIR", str(test_root / "checkpoints"))
+    os.environ.setdefault("HEALTH_POLL_INTERVAL", "999999")  # don't poll during tests
+    Path(os.environ["OUTPUT_DIR"]).mkdir(parents=True, exist_ok=True)
+    Path(os.environ["CHECKPOINTS_DIR"]).mkdir(parents=True, exist_ok=True)
+    yield
+
+
+def _can_import(name: str) -> bool:
+    try:
+        __import__(name)
+    except Exception:  # noqa: BLE001 — we want all import errors to count
+        return False
+    return True
+
+
+HAS_GRADIO = _can_import("gradio")
+HAS_FASTAPI = _can_import("fastapi")
+HAS_HTTPX = _can_import("httpx")
+HAS_TORCH = _can_import("torch")
+HAS_NUMPY = _can_import("numpy")
+
+ANIMOFLOW_API_API = Path(
+    os.environ.get("ANIMOFLOW_API_API_DIR", "/opt/animoflow-api/api")
+)
+HAS_ANIMOFLOW_API = ANIMOFLOW_API_API.is_dir()
+
+COMFYUI_ANIMOFLOW = Path(
+    os.environ.get("COMFYUI_ANIMOFLOW_DIR", "/opt/comfyui-animoflow")
+)
+HAS_COMFYUI_ANIMOFLOW = COMFYUI_ANIMOFLOW.is_dir()
+
+BLENDER_BIN = Path(os.environ.get("BLENDER_BIN", "/opt/blender/blender"))
+HAS_BLENDER = BLENDER_BIN.exists()
+

tests/test_app_imports.py

@@ -0,0 +1,67 @@
+"""
+Import-shape tests — verify app.py wires up without crashing on a CPU laptop.
+
+These tests skip cleanly when the sibling repos (animoflow-api,
+comfyui-animoflow) aren't cloned at the expected paths. On a real Docker
+build they're always present, so this is the canary that catches our own
+import-path mistakes.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+
+from .conftest import HAS_FASTAPI, HAS_GRADIO, HAS_HTTPX, HAS_ANIMOFLOW_API
+
+
+@pytest.mark.skipif(not HAS_GRADIO, reason="gradio not installed")
+def test_spaces_compat_imports():
+    """The compat shim must always import on its own, even without `spaces`."""
+    import importlib
+
+    import spaces_compat
+
+    importlib.reload(spaces_compat)
+    assert callable(spaces_compat.GPU)
+    assert isinstance(spaces_compat.HAVE_SPACES, bool)
+
+
+@pytest.mark.skipif(
+    not (HAS_FASTAPI and HAS_GRADIO and HAS_HTTPX and HAS_ANIMOFLOW_API),
+    reason="needs fastapi + gradio + httpx + a cloned animoflow-api at /opt/animoflow-api",
+)
+def test_app_module_imports():
+    """app.py should import without crashing — exercises the monkeypatch order."""
+    # This is the actual Docker boot path, just minus uvicorn.
+    import importlib
+
+    if "app" in sys.modules:
+        importlib.reload(sys.modules["app"])
+    else:
+        import app  # noqa: F401
+
+    import app
+
+    assert app.fastapi_app is not None
+    # Verify the monkeypatch happened
+    import pipeline as animoflow_api_pipeline
+    import pipeline_hf
+
+    assert animoflow_api_pipeline.run is pipeline_hf.run
+    assert animoflow_api_pipeline.run_timeline is pipeline_hf.run_timeline
+
+
+@pytest.mark.skipif(
+    not (HAS_FASTAPI and HAS_GRADIO and HAS_HTTPX and HAS_ANIMOFLOW_API),
+    reason="needs fastapi + gradio + httpx + animoflow-api",
+)
+def test_v1_health_route_exists():
+    """The /v1/health route from animoflow-api should still be present after
+    Gradio is mounted on '/'."""
+    import app
+
+    routes = [getattr(r, "path", None) for r in app.fastapi_app.routes]
+    assert "/v1/health" in routes, f"missing /v1/health, got: {routes}"

tests/test_pipeline_hf.py

@@ -0,0 +1,341 @@
+"""
+Pipeline tests — exercise the HF pipeline shape with mocked inference.
+
+We do NOT load real model weights here. The goal is to verify:
+  * The pipeline accepts the same call signature as animoflow-api/api/pipeline.py:run
+  * Errors propagate cleanly when deps are missing
+  * Stage callbacks fire in the expected order
+  * The escape-hatch routing logic recognizes outliers correctly
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+def test_signature_compat_with_animoflow_api_pipeline():
+    """The HF pipeline must accept every kwarg the original pipeline.run does.
+
+    If this drifts, animoflow-api/api/main.py:_run_pipeline will start
+    passing kwargs that pipeline_hf.run rejects.
+    """
+    import inspect
+
+    import pipeline_hf
+
+    sig = inspect.signature(pipeline_hf.run)
+    params = sig.parameters
+
+    # These are all the kwargs animoflow-api's main.py:_run_pipeline passes.
+    required = {
+        "job_id",
+        "prompt",
+        "num_frames",
+        "seed",
+        "character",
+        "model",
+        "on_progress",
+        "on_stage",
+        "preprocess_stages",
+        "keyframe_builder",
+        "keyframe_builder_error_degrees",
+        "output_fps",
+        "curve_2d",
+        "accel_frac",
+        "decel_frac",
+    }
+    missing = required - set(params.keys())
+    assert not missing, f"pipeline_hf.run is missing kwargs: {missing}"
+
+
+def test_run_timeline_signature():
+    import inspect
+
+    import pipeline_hf
+
+    sig = inspect.signature(pipeline_hf.run_timeline)
+    params = sig.parameters
+    required = {
+        "job_id",
+        "segments",
+        "seed",
+        "character",
+        "cfg",
+        "handshake_size",
+        "blend_len",
+        "on_progress",
+        "on_stage",
+        "keyframe_builder",
+        "keyframe_builder_error_degrees",
+        "output_fps",
+    }
+    missing = required - set(params.keys())
+    assert not missing, f"pipeline_hf.run_timeline is missing kwargs: {missing}"
+
+
+def _point_at_sibling_checkout(monkeypatch):
+    """Point pipeline_hf at the sibling comfyui-animoflow checkout so the
+    shared stage library loads on dev machines (the Space uses
+    /opt/comfyui-animoflow). Skip when neither exists."""
+    from pathlib import Path
+
+    import pipeline_hf
+
+    sibling = Path(__file__).resolve().parents[2] / "comfyui-animoflow"
+    if (sibling / "animoflow_stages" / "__init__.py").is_file():
+        monkeypatch.setattr(pipeline_hf, "_COMFY_ROOT", sibling)
+        monkeypatch.setattr(pipeline_hf, "_stage_lib", None)
+    elif not (pipeline_hf._COMFY_ROOT / "animoflow_stages" / "__init__.py").is_file():
+        pytest.skip("no comfyui-animoflow checkout with animoflow_stages available")
+
+
+def test_run_timeline_wires_to_priormdm(monkeypatch):
+    """run_timeline must call _run_timeline_gpu, unwrap the result, and
+    pass through to the shared post-processing tail. We mock both ends so
+    the test doesn't load real model weights or invoke Blender."""
+    import pipeline_hf
+
+    captured: dict = {}
+
+    def _fake_gpu(segments, seed, *, guidance_param=2.5,
+                  handshake_size=10, blend_len=10):
+        captured["segments"] = segments
+        captured["seed"] = seed
+        captured["guidance_param"] = guidance_param
+        captured["handshake_size"] = handshake_size
+        captured["blend_len"] = blend_len
+        return b"FAKE_NPZ_BYTES_NO_SENTINEL"
+
+    def _fake_postprocess(**kw):
+        captured["postprocess_kwargs"] = kw
+        return "fake.fbx"
+
+    monkeypatch.setattr(pipeline_hf, "_run_timeline_gpu", _fake_gpu)
+    monkeypatch.setattr(pipeline_hf, "_run_tail", _fake_postprocess)
+    _point_at_sibling_checkout(monkeypatch)
+    # The whole tail (incl. resample) is mocked out via _run_tail, so the
+    # fake NPZ bytes are never parsed.
+    out = pipeline_hf.run_timeline(
+        job_id="t1",
+        segments=[{"prompt": "wave", "num_frames": 80},
+                  {"prompt": "jump", "num_frames": 60}],
+        seed=42,
+        cfg=2.5,
+        output_fps=20,
+    )
+    assert out == "fake.fbx"
+    assert captured["segments"][0]["prompt"] == "wave"
+    assert captured["seed"] == 42
+    assert captured["guidance_param"] == 2.5
+    assert captured["postprocess_kwargs"]["npz_bytes"] == b"FAKE_NPZ_BYTES_NO_SENTINEL"
+
+
+def test_run_priormdm_forwards_curve_2d_to_gpu(monkeypatch):
+    """run(model='priormdm') must forward curve_2d + accel/decel_frac into
+    the GPU call's extra-kwargs so the priorMDM wrapper sees them."""
+    import pipeline_hf
+
+    captured: dict = {}
+
+    def _fake_gpu(model, prompt, num_frames, seed, *,
+                  guidance_param=None, **extra):
+        captured["model"] = model
+        captured["prompt"] = prompt
+        captured.update(extra)
+        return b"FAKE_NPZ_BYTES_NO_SENTINEL"
+
+    def _fake_postprocess(**kw):
+        return "fake.fbx"
+
+    monkeypatch.setattr(pipeline_hf, "_run_inference_gpu_fast", _fake_gpu)
+    monkeypatch.setattr(pipeline_hf, "_run_tail", _fake_postprocess)
+    _point_at_sibling_checkout(monkeypatch)
+    out = pipeline_hf.run(
+        job_id="p1",
+        prompt="walk forward",
+        num_frames=80,
+        seed=0,
+        character="Y_bot",
+        model="priormdm",
+        curve_2d=[[0.0, 0.0], [1.0, 1.0], [2.0, 0.0]],
+        accel_frac=0.2,
+        decel_frac=0.3,
+        output_fps=20,  # priormdm native, skip resample on the fake bytes
+    )
+    assert out == "fake.fbx"
+    assert captured["model"] == "priormdm"
+    assert captured["curve_2d"] == [[0.0, 0.0], [1.0, 1.0], [2.0, 0.0]]
+    assert captured["accel_frac"] == 0.2
+    assert captured["decel_frac"] == 0.3
+
+
+def test_escape_hatch_recognizes_outliers():
+    """Outlier registry should report unknown models as non-outliers."""
+    import escape_hatch
+
+    # The MDM family runs in-process (kimodo is the escape-hatch outlier)
+    assert escape_hatch.is_outlier("mdm") is False
+    assert escape_hatch.is_outlier("priormdm") is False
+    assert escape_hatch.is_outlier("not_a_real_model") is False
+
+
+def test_escape_hatch_raises_on_unregistered_invoke():
+    """invoke() on a non-outlier model must raise a clear RuntimeError."""
+    import escape_hatch
+
+    with pytest.raises(RuntimeError) as excinfo:
+        escape_hatch.invoke("mdm", prompt="test", num_frames=60, seed=0)
+    assert "outlier" in str(excinfo.value).lower()
+
+
+def test_numpy_compat_shim_installs_legacy_aliases():
+    """Shim must add np.float / np.int / np.bool / numpy.core.umath_tests
+    even on numpy 2.x. Idempotent."""
+    import sys
+
+    import numpy as np
+
+    import pipeline_hf
+
+    # Run twice to confirm idempotency
+    pipeline_hf._install_numpy_compat_shim()
+    pipeline_hf._install_numpy_compat_shim()
+
+    # Legacy aliases present
+    assert hasattr(np, "float")
+    assert hasattr(np, "int")
+    assert hasattr(np, "bool")
+    assert hasattr(np, "object")
+
+    # umath_tests stub is registered
+    import numpy.core.umath_tests as ut
+
+    # inner1d → element-wise dot product
+    a = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
+    b = np.array([[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]])
+    expected_inner1d = np.array([6.0, 30.0])
+    assert np.allclose(ut.inner1d(a, b), expected_inner1d), (
+        f"inner1d shim returned {ut.inner1d(a, b)!r}, expected {expected_inner1d!r}"
+    )
+
+    # matrix_multiply → np.matmul (stacked matrix mult)
+    M1 = np.array([[[1.0, 2.0], [3.0, 4.0]], [[2.0, 0.0], [0.0, 2.0]]])
+    M2 = np.array([[[5.0, 6.0], [7.0, 8.0]], [[1.0, 1.0], [1.0, 1.0]]])
+    expected_mm = np.matmul(M1, M2)
+    assert np.allclose(ut.matrix_multiply(M1, M2), expected_mm), (
+        "matrix_multiply shim diverged from np.matmul"
+    )
+
+    # innerwt → weighted inner product, sum_i a_i * b_i * w_i over last axis
+    w = np.array([[1.0, 2.0, 3.0], [3.0, 2.0, 1.0]])
+    # Row 0: 1·1·1 + 2·1·2 + 3·1·3 = 1+4+9 = 14
+    # Row 1: 4·2·3 + 5·2·2 + 6·2·1 = 24+20+12 = 56
+    expected_innerwt = np.array([14.0, 56.0])
+    assert np.allclose(ut.innerwt(a, b, w), expected_innerwt), (
+        f"innerwt shim returned {ut.innerwt(a, b, w)!r}, expected {expected_innerwt!r}"
+    )
+
+    # Module is in sys.modules
+    assert "numpy.core.umath_tests" in sys.modules
+
+
+def test_pipeline_run_propagates_callbacks(monkeypatch):
+    """Stage / progress callbacks should fire even when inference fails.
+
+    We monkeypatch _run_inference_gpu_fast (the MDM/MoMask GPU wrapper) so no
+    real model loads. The pipeline should call on_stage("Generating…") at
+    least once before failing.
+    """
+    import pipeline_hf
+
+    stages: list[str] = []
+
+    def _on_stage(s: str):
+        stages.append(s)
+
+    def _fake_inference(*args, **kwargs):  # noqa: ARG001
+        raise RuntimeError("synthetic — model not loaded")
+
+    monkeypatch.setattr(pipeline_hf, "_run_inference_gpu_fast", _fake_inference)
+    _point_at_sibling_checkout(monkeypatch)
+
+    with pytest.raises(RuntimeError):
+        pipeline_hf.run(
+            job_id="test-job-1",
+            prompt="test prompt",
+            num_frames=60,
+            seed=42,
+            character="Y_bot",
+            model="mdm",
+            on_stage=_on_stage,
+        )
+
+    assert "Generating…" in stages, f"expected 'Generating…' to fire, got {stages!r}"
+
+
+def test_safe_do_inference_passes_through_npz_bytes(monkeypatch):
+    """The sentinel wrapper must NOT modify successful return values."""
+    import pipeline_hf
+
+    monkeypatch.setattr(
+        pipeline_hf, "_do_inference",
+        lambda *a, **kw: b"FAKE_NPZ_BYTES_NO_SENTINEL",
+    )
+    out = pipeline_hf._safe_do_inference(
+        model="mdm", prompt="x", num_frames=60, seed=0,
+    )
+    assert out == b"FAKE_NPZ_BYTES_NO_SENTINEL"
+
+
+def test_safe_do_inference_serialises_exception_into_sentinel(monkeypatch):
+    """When _do_inference raises, the wrapper must emit a sentinel-prefixed
+    JSON payload — not propagate the exception. This is the fix for the
+    'AppError: \\'RuntimeError\\'' Space symptom where ZeroGPU strips
+    exception args across the worker boundary."""
+    import json
+
+    import pipeline_hf
+
+    def _boom(*a, **kw):  # noqa: ARG001
+        raise RuntimeError("Kimodo venv still warming up — please retry")
+
+    monkeypatch.setattr(pipeline_hf, "_do_inference", _boom)
+
+    out = pipeline_hf._safe_do_inference(
+        model="kimodo", prompt="x", num_frames=60, seed=0,
+    )
+
+    assert out.startswith(pipeline_hf._ERR_SENTINEL), (
+        "wrapper must prefix the error payload with _ERR_SENTINEL"
+    )
+    payload = json.loads(out[len(pipeline_hf._ERR_SENTINEL):].decode())
+    assert payload["error_class"] == "RuntimeError"
+    assert "warming up" in payload["message"]  # original message preserved
+    assert "traceback" in payload
+
+
+def test_unwrap_gpu_result_reraises_with_original_message():
+    """Inverse of _safe_do_inference: detect the sentinel and re-raise the
+    original message as a RuntimeError on the orchestrator side."""
+    import json
+
+    import pipeline_hf
+
+    payload = json.dumps({
+        "error_class": "RuntimeError",
+        "message": "Kimodo venv still warming up — please retry",
+        "traceback": "fake-traceback",
+    }).encode()
+    sentinel_blob = pipeline_hf._ERR_SENTINEL + payload
+
+    with pytest.raises(RuntimeError) as excinfo:
+        pipeline_hf._unwrap_gpu_result(sentinel_blob)
+    assert "warming up" in str(excinfo.value)
+
+
+def test_unwrap_gpu_result_passes_through_real_bytes():
+    """No sentinel → pass through unchanged."""
+    import pipeline_hf
+
+    real = b"PK\x03\x04...npz bytes..."  # any non-sentinel byte string
+    assert pipeline_hf._unwrap_gpu_result(real) is real

tests/test_spaces_compat.py

@@ -0,0 +1,82 @@
+"""
+Test the @spaces.GPU compat shim.
+
+Critical correctness: the decorator must work in BOTH forms (`@GPU` and
+`@GPU(duration=N)`) on a non-HF environment, transparently passing the
+function through. If this is wrong, every OSS local install breaks.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def test_GPU_parameterized_form_passes_through():
+    """`@GPU(duration=30)` should call the underlying function with all args."""
+    from spaces_compat import GPU
+
+    @GPU(duration=30)
+    def fn(a, b):
+        return a + b
+
+    assert fn(2, 3) == 5
+    assert fn(a=4, b=10) == 14
+
+
+def test_GPU_bare_form_passes_through():
+    """`@GPU` (no parens) should still work as a bare decorator."""
+    from spaces_compat import GPU
+
+    @GPU
+    def fn(x):
+        return x * 2
+
+    assert fn(7) == 14
+
+
+def test_GPU_kwargs_only_form():
+    """`@GPU(duration=30, ...)` accepts arbitrary kwargs without breaking."""
+    from spaces_compat import GPU
+
+    @GPU(duration=60, queue=False)
+    def fn():
+        return "ok"
+
+    assert fn() == "ok"
+
+
+def test_GPU_preserves_metadata():
+    """The decorated function should keep its name/docstring (functools.wraps)."""
+    from spaces_compat import GPU
+
+    @GPU(duration=10)
+    def my_function():
+        """An important docstring."""
+        return None
+
+    # In the spaces-installed branch we re-export spaces.GPU directly which
+    # may or may not preserve metadata depending on spaces' implementation.
+    # We only assert metadata preservation when the OSS fallback is active.
+    import spaces_compat
+
+    if not spaces_compat.HAVE_SPACES:
+        assert my_function.__name__ == "my_function"
+        assert "important" in (my_function.__doc__ or "")
+
+
+def test_GPU_does_not_swallow_exceptions():
+    """If the wrapped function raises, the wrapper must re-raise."""
+    from spaces_compat import GPU
+
+    class _Boom(Exception):
+        pass
+
+    @GPU(duration=5)
+    def bad():
+        raise _Boom("kaboom")
+
+    try:
+        bad()
+    except _Boom:
+        return
+    raise AssertionError("decorator swallowed the exception")

ui.py

@@ -0,0 +1,518 @@
+"""
+Gradio Blocks UI for the AnimoFlow HF Space.
+
+The UI is a thin client over the FastAPI /v1/jobs endpoint that the
+animoflow-api app already implements. We POST a job, poll for status,
+then download the resulting FBX/GLB.
+
+Same surface that the animoflow.ai webpage and Blender add-on consume.
+The UI itself uses no privileged path — anything you can do here, you
+can do via curl.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+import httpx
+
+log = logging.getLogger(__name__)
+
+# Usage analytics (animoflow-api module; on sys.path via app.py step 1).
+# No-op unless USAGE_LOG_* env vars are set — see usage_log.py docstring.
+try:
+    import usage_log
+except ImportError:  # bare ui.py import outside the Space wiring (tests)
+    usage_log = None
+    log.warning("usage_log not importable — usage analytics disabled")
+
+# Where animoflow-api's /v1 lives. In-process the FastAPI app is mounted at
+# the same root, so http://localhost:<port> works.
+_PORT = int(os.environ.get("PORT", "7860"))
+_API_BASE = os.environ.get("ANIMOFLOW_API_BASE", f"http://127.0.0.1:{_PORT}")
+_API_KEY = os.environ.get("ANIMOFLOW_API_KEY", "dev")
+
+_OUTPUT_DIR = Path(os.environ.get("OUTPUT_DIR", "/tmp/animoflow-output"))
+
+
+def _post_job_body(body: dict[str, Any], headers: dict[str, str] | None = None) -> str:
+    """POST /v1/jobs with a pre-built body → job_id. Raises on non-2xx.
+
+    ``headers`` lets callers add attribution (x-usage-actor) on the internal
+    loopback hop without touching the auth header.
+    """
+    r = httpx.post(
+        f"{_API_BASE}/v1/jobs",
+        json=body,
+        headers={"Authorization": f"Bearer {_API_KEY}", **(headers or {})},
+        timeout=15.0,
+    )
+    r.raise_for_status()
+    return r.json()["job_id"]
+
+
+def _submit_error(exc: httpx.HTTPStatusError) -> tuple[str, str]:
+    """(user_message, error_code) for a non-2xx POST /v1/jobs.
+
+    Prefer the API's own classified message (error_classify populates it on
+    clean failures); otherwise fall back to a neutral per-status message.
+    Never interpolate the raw exception — it carries internal URLs
+    (e.g. http://127.0.0.1:7860/v1/jobs) that must not reach users.
+    """
+    try:
+        err = exc.response.json().get("error", {})
+    except Exception:  # noqa: BLE001 — non-JSON body (e.g. bare 500 page)
+        err = {}
+    if not isinstance(err, dict):
+        # e.g. slowapi's stock 429 body was {"error": "<string>"} — main.py
+        # now owns that envelope, but stay robust to any legacy shape.
+        err = {}
+    if err.get("message"):
+        return err["message"], str(err.get("code") or exc.response.status_code)
+    if exc.response.status_code == 429:
+        return (
+            "Too many requests — please wait a minute and try again.",
+            "429",
+        )
+    return (
+        "The server had a problem starting this job — please try again.",
+        str(exc.response.status_code),
+    )
+
+
+def _post_job(prompt: str, model: str, character: str, duration: float, seed: int,
+              headers: dict[str, str] | None = None) -> str:
+    """POST /v1/jobs → job_id. Text-only convenience wrapper for the
+    legacy in-Space `_generate` handler. Browser callers use
+    `_generate_full` instead, which forwards the full GenerateRequest
+    body verbatim and so supports trajectory / waypoints / timeline."""
+    payload: dict[str, Any] = {
+        "input": {"type": "text", "prompt": prompt},
+        "model": model,
+        "character": character,
+        "duration": float(duration),
+    }
+    if seed >= 0:
+        payload["seed"] = int(seed)
+    return _post_job_body(payload, headers=headers)
+
+
+def _poll_job(job_id: str, max_wait: float = 180.0) -> dict:
+    """Poll /v1/jobs/{id} until done | failed | cancelled, or timeout."""
+    deadline = time.time() + max_wait
+    last_stage = None
+    while time.time() < deadline:
+        r = httpx.get(
+            f"{_API_BASE}/v1/jobs/{job_id}",
+            headers={"Authorization": f"Bearer {_API_KEY}"},
+            timeout=15.0,
+        )
+        r.raise_for_status()
+        body = r.json()
+        if body.get("stage") and body["stage"] != last_stage:
+            last_stage = body["stage"]
+            log.info("[%s] %s", job_id, last_stage)
+        if body["status"] in ("done", "failed", "cancelled"):
+            return body
+        time.sleep(1.5)
+    raise TimeoutError(f"Job {job_id} did not finish in {max_wait}s")
+
+
+def _generate(
+    prompt: str,
+    model: str,
+    character: str,
+    duration: float,
+    seed: int,
+    progress: gr.Progress = gr.Progress(),
+    request: gr.Request | None = None,
+) -> tuple[str, str, str]:
+    """Submit → poll → return (path-to-glb-or-fbx, status text, rewritten_prompt)."""
+    if not prompt or not prompt.strip():
+        raise gr.Error("Prompt is required")
+
+    # In-Space (hf.space iframe) visitors carry an HF-injected X-IP-Token;
+    # forward it across the loopback so ZeroGPU attributes their quota
+    # (see _zerogpu_attribution in animoflow-api main.py).
+    _ip_token = request.headers.get("x-ip-token") if request is not None else None
+    _fwd_headers = {"x-ip-token": _ip_token} if _ip_token else None
+
+    progress(0.05, desc="Submitting…")
+    try:
+        job_id = _post_job(prompt, model, character, duration, seed,
+                           headers=_fwd_headers)
+    except httpx.HTTPStatusError as exc:
+        # NB: the previous try/except here caught its own gr.Error, so the
+        # structured-message path never ran and everything collapsed to a
+        # raw "API error: {exc}" leak. _submit_error keeps parsing and
+        # raising separate.
+        message, _ = _submit_error(exc)
+        raise gr.Error(message) from exc
+
+    progress(0.10, desc="Generating…")
+    try:
+        job = _poll_job(job_id)
+    except TimeoutError as exc:
+        raise gr.Error(str(exc)) from exc
+
+    if job["status"] != "done":
+        # The backend's ``error`` field is the single user-facing string —
+        # populated by api.error_classify with a clean message. We render
+        # it verbatim; no client-side formatting or branching on
+        # error_info.code.
+        msg = job.get("error") or "Job did not complete."
+        raise gr.Error(msg)
+
+    download_url = job.get("download_url", "")  # /v1/files/<job_id>.fbx
+    if not download_url:
+        raise gr.Error("Job done but no download_url returned")
+
+    # The file is on disk in OUTPUT_DIR — return a local path so the
+    # Model3D widget loads it without a second HTTP roundtrip.
+    filename = download_url.rsplit("/", 1)[-1]
+    fbx_path = _OUTPUT_DIR / filename
+    glb_path = fbx_path.with_suffix(".glb")
+    out_path = glb_path if glb_path.exists() else fbx_path
+    if not out_path.exists():
+        raise gr.Error(f"Output file missing: {out_path}")
+
+    progress(1.0, desc="Done")
+    summary = (
+        f"Job {job_id} · model={model} · character={character} · "
+        f"duration={duration}s · seed={seed}"
+    )
+    # Surface the rewritten prompt so the user can see what was actually fed
+    # to the motion model. Empty string when the rewriter was skipped or the
+    # heuristic short-circuited (input was already HumanML3D-style English).
+    rewritten = job.get("rewritten_prompt") or ""
+    original = job.get("original_prompt") or ""
+    if rewritten and rewritten.strip() != (original or "").strip():
+        rewritten_display = rewritten
+    else:
+        rewritten_display = ""
+    return str(out_path), summary, rewritten_display
+
+
+def _generate_full(
+    request_json: str,
+    progress: gr.Progress = gr.Progress(),
+    request: gr.Request | None = None,
+):
+    """Submit → poll → yield (path, summary, rewritten) for any task type.
+
+    The browser-side `@gradio/client` calls this via
+    ``Client.predict("/generate_full", request_json=...)`` with the
+    full ``GenerateRequest`` body JSON-serialized as a string. Same
+    body shape as ``POST /v1/jobs`` accepts — see animoflow-api's
+    GenerateRequest schema (text / trajectory / waypoints / timeline
+    discriminated union). Routing all task types through this single
+    Gradio endpoint is what lets ZeroGPU's ``x-ip-token`` middleware
+    attribute quota to the signed-in user's HF account.
+
+    **Generator pattern intentionally.** Each ``yield`` emits a
+    ``process_generating`` SSE event over the simplified
+    ``/gradio_api/call/generate_full/<event_id>`` endpoint that the
+    browser-direct custom client consumes (the simple SSE endpoint
+    DROPS gr.Progress events, only forwards generator yields). The
+    intermediate yields use ``gr.update()`` for the Model3D + rewritten
+    textbox so the Gradio UI doesn't flicker the viewer between stages.
+    Browser-direct callers read the status string from the second tuple
+    slot and ignore the first/third on intermediate yields. Final yield
+    has the actual file path + summary + rewritten_display.
+
+    Output components: (Model3D, status Textbox, rewritten Textbox) —
+    matches Blocks wiring at the bottom of this file.
+    """
+    if not request_json or not request_json.strip():
+        raise gr.Error("request_json is required")
+
+    try:
+        body = json.loads(request_json)
+    except json.JSONDecodeError as exc:
+        raise gr.Error(f"request_json is not valid JSON: {exc}") from exc
+    if not isinstance(body, dict):
+        raise gr.Error("request_json must be a JSON object")
+
+    # Progress encoding: the second-slot status string carries a trailing
+    # "(NN%)" that the browser-direct client (web/app/gradio-client-custom.js
+    # → app.js:_generateViaGradio) parses to drive the spinner row's
+    # --progress CSS variable. The 4th slot is RESERVED for snap_info JSON
+    # on the final yield (per commit d14ae86 — per-gen snap receipt) — we
+    # keep it as gr.update() on every intermediate yield so the hidden
+    # snap_info textbox isn't clobbered mid-run.
+    # The simple SSE endpoint we call from the browser DROPS gr.Progress
+    # events, so the only reliable carrier is the yielded tuple itself
+    # (encode progress into a tuple slot).
+    # Attribution for usage analytics: hash the browser-direct caller's
+    # bearer token so the internal loopback /v1/jobs hop keeps the real
+    # identity instead of "dev". Never carries raw token material.
+    _actor = None
+    if usage_log is not None and request is not None:
+        try:
+            _actor = usage_log.actor_from_authorization(
+                request.headers.get("authorization"))
+            if _actor is None:
+                # Anonymous browser-direct caller: forward a hashed-IP
+                # identity so the fair-use overflow cap can key on them.
+                # Without this, anon loopback jobs collapse into the
+                # internal API key's identity (gap found 2026-07-07).
+                _ip = (request.headers.get("x-forwarded-for", "").split(",")[0].strip()
+                       or (request.client.host if request.client else ""))
+                _actor = usage_log.actor_from_ip(_ip)
+        except Exception:  # analytics must never break generation
+            _actor = None
+    _actor_headers = {usage_log.ACTOR_HEADER: _actor} if _actor else None
+    # ZeroGPU attribution: forward the caller's X-IP-Token JWT across the
+    # loopback hop. The spaces scheduler reads it from gradio's request
+    # context, which the internal /v1/jobs request severs — main.py
+    # replants it around the pipeline run (_zerogpu_attribution). Without
+    # this, every GPU call runs token-less on the shared pool.
+    _ip_token = request.headers.get("x-ip-token") if request is not None else None
+    if _ip_token:
+        _actor_headers = {**(_actor_headers or {}), "x-ip-token": _ip_token}
+
+    def _gradio_call_event(phase: str, **extra) -> None:
+        if usage_log is None:
+            return
+        kind, _, user = (_actor or "").partition(":")
+        usage_log.emit({
+            "event": "gradio_call", "phase": phase,
+            "user": user or "internal", "user_kind": kind or "internal",
+            "client": "browser-direct", **extra,
+        })
+
+    progress(0.05, desc="Submitting…")
+    yield gr.update(), "Submitting… (5%)", gr.update(), gr.update()
+    try:
+        job_id = _post_job_body(body, headers=_actor_headers)
+    except httpx.HTTPStatusError as exc:
+        message, code = _submit_error(exc)
+        _gradio_call_event(
+            "submit_rejected", job_id=None,
+            error_code=code,
+            error_message=message[:300],
+        )
+        raise gr.Error(message) from exc
+
+    _gradio_call_event("linked", job_id=job_id)
+
+    progress(0.10, desc="Generating…")
+    # Slot 3 carries the job_id early: gradio's simple /call SSE endpoint
+    # serializes error events as `data: null` (the gr.Error message is
+    # lost on the wire), so browser-direct callers need the job_id to
+    # fetch the real classified error via GET /v1/jobs/{id} when the
+    # stream errors out. The final yield reuses slot 3 for snap_info.
+    yield gr.update(), "Generating… (10%)", gr.update(), json.dumps({"job_id": job_id})
+
+    # Inline poll so we can yield each stage AND progress change.
+    # 0.4 s poll matches the legacy /v1/jobs poller in app.js — at 1.5 s
+    # short pipeline stages (e.g. IK, post-fix) flew past between polls
+    # and the second-slot yield stayed "Generating…" the whole run.
+    max_wait = 180.0
+    poll_interval = 0.4
+    deadline = time.time() + max_wait
+    last_stage = None
+    last_pct = -1
+    job = None
+    while time.time() < deadline:
+        try:
+            r = httpx.get(
+                f"{_API_BASE}/v1/jobs/{job_id}",
+                headers={"Authorization": f"Bearer {_API_KEY}"},
+                timeout=15.0,
+            )
+            r.raise_for_status()
+            body_resp = r.json()
+        except Exception as exc:  # transient HTTP / parse error — keep polling
+            log.warning("[%s] poll error: %s", job_id, exc)
+            time.sleep(poll_interval)
+            continue
+        cur_stage = body_resp.get("stage") or last_stage or "Running"
+        cur_progress = max(0.0, min(1.0, float(body_resp.get("progress") or 0.0)))
+        cur_pct = int(round(cur_progress * 100))
+        if cur_stage != last_stage or cur_pct != last_pct:
+            if cur_stage != last_stage:
+                log.info("[%s] %s (%d%%)", job_id, cur_stage, cur_pct)
+            last_stage = cur_stage
+            last_pct = cur_pct
+            yield gr.update(), f"{cur_stage} ({cur_pct}%)", gr.update(), gr.update()
+        if body_resp["status"] in ("done", "failed", "cancelled"):
+            job = body_resp
+            break
+        time.sleep(poll_interval)
+    if job is None:
+        _gradio_call_event("poll_timeout", job_id=job_id,
+                           error_code="gradio_poll_timeout",
+                           error_message=f"no terminal status within {max_wait}s")
+        raise gr.Error(f"Job {job_id} did not finish in {max_wait}s")
+
+    if job["status"] != "done":
+        msg = job.get("error") or "Job did not complete."
+        raise gr.Error(msg)
+
+    download_url = job.get("download_url", "")
+    if not download_url:
+        raise gr.Error("Job done but no download_url returned")
+
+    filename = download_url.rsplit("/", 1)[-1]
+    fbx_path = _OUTPUT_DIR / filename
+    glb_path = fbx_path.with_suffix(".glb")
+    out_path = glb_path if glb_path.exists() else fbx_path
+    if not out_path.exists():
+        raise gr.Error(f"Output file missing: {out_path}")
+
+    progress(1.0, desc="Done")
+
+    input_type = (body.get("input") or {}).get("type", "?")
+    model_name = body.get("model", "?")
+    duration_val = body.get("duration", "?")
+    summary = (
+        f"Job {job_id} · task={input_type} · model={model_name} · duration={duration_val}s"
+    )
+
+    rewritten = job.get("rewritten_prompt") or ""
+    original = job.get("original_prompt") or ""
+    if rewritten and rewritten.strip() != (original or "").strip():
+        rewritten_display = rewritten
+    else:
+        rewritten_display = ""
+    # JSON-serialise snap_info into a hidden textbox slot. Browser-direct
+    # callers (the AnimoFlow web app) read data[3]
+    # and surface it in the debug-response panel — same per-gen "did the
+    # snap run?" receipt that REST clients get via JobResponse.snap_info.
+    snap_info_json = json.dumps(job.get("snap_info"))
+    yield str(out_path), summary, rewritten_display, snap_info_json
+
+
+def _list_characters() -> list[str]:
+    """Best-effort character list from /v1/characters; fall back to filesystem."""
+    try:
+        r = httpx.get(
+            f"{_API_BASE}/v1/characters",
+            headers={"Authorization": f"Bearer {_API_KEY}"},
+            timeout=5.0,
+        )
+        r.raise_for_status()
+        names = r.json().get("characters", [])
+        if names:
+            return names
+    except Exception:  # noqa: BLE001 — best effort during boot
+        pass
+    chars_dir = Path(
+        os.environ.get("CHARACTERS_DIR", "/opt/comfyui-animoflow/characters")
+    )
+    if chars_dir.is_dir():
+        return sorted(p.stem for p in chars_dir.glob("*.fbx"))
+    return ["Y_bot"]
+
+
+def build_blocks() -> gr.Blocks:
+    """Construct the Gradio Blocks app. Called once at orchestrator startup."""
+    # Pull the character list once at boot. Refreshed on demand via the
+    # "↻" button next to the dropdown.
+    initial_chars = _list_characters() or ["Y_bot"]
+
+    with gr.Blocks(title="AnimoFlow Demo", theme=gr.themes.Soft()) as blocks:
+        gr.Markdown(
+            """
+            # AnimoFlow — Text → Motion → FBX
+
+            Type a description, pick a character, hit **Generate**.
+            Powered by [MDM](https://guytevet.github.io/mdm-page/) +
+            momask Joint2BVH IK + Blender retarget.
+
+            Same `/v1/jobs` API as the local OSS stack — you can also call
+            it from `gradio_client`, `@gradio/client` JS, or curl.
+            """
+        )
+        with gr.Row():
+            with gr.Column(scale=1):
+                prompt = gr.Textbox(
+                    label="Prompt",
+                    placeholder="a person walks forward and waves",
+                    lines=3,
+                )
+                model = gr.Dropdown(
+                    choices=["mdm", "momask", "kimodo"],
+                    value="mdm",
+                    label="Model",
+                )
+                character = gr.Dropdown(
+                    choices=initial_chars,
+                    value=initial_chars[0],
+                    label="Character",
+                )
+                duration = gr.Slider(
+                    minimum=1.0,
+                    maximum=10.0,
+                    value=4.0,
+                    step=0.5,
+                    label="Duration (seconds)",
+                )
+                seed = gr.Number(
+                    value=-1, label="Seed (-1 = random)", precision=0
+                )
+                submit = gr.Button("Generate", variant="primary")
+            with gr.Column(scale=2):
+                viewer = gr.Model3D(
+                    label="Preview", display_mode="solid", clear_color=[0, 0, 0, 0]
+                )
+                status = gr.Textbox(label="Job", interactive=False, lines=2)
+                # Surfaces the rewritten prompt when the multilingual rewriter
+                # actually fires (non-empty + different from the original). The
+                # textbox stays blank for English-HumanML3D-style inputs that
+                # the cheap skip heuristic short-circuits. Original/rewritten
+                # are also in /v1/jobs/{id} for API consumers.
+                rewritten_box = gr.Textbox(
+                    label="Rewritten as (what the model actually saw)",
+                    interactive=False,
+                    lines=2,
+                    placeholder="(your prompt was kept as-is)",
+                )
+
+        submit.click(
+            fn=_generate,
+            inputs=[prompt, model, character, duration, seed],
+            outputs=[viewer, status, rewritten_box],
+            # Stable named endpoint so the browser-side @gradio/client
+            # in animoflow-api can call Client.predict("/generate", ...).
+            api_name="generate",
+        )
+
+        # Hidden API-only endpoint that accepts the full GenerateRequest
+        # body as a JSON string. Used by animoflow-api's browser-side
+        # @gradio/client for all four task types (text / trajectory /
+        # waypoints / timeline). Not visible in the Space's own UI —
+        # external callers reach it via Client.predict("/generate_full", ...).
+        request_json_in = gr.Textbox(visible=False)
+        snap_info_box = gr.Textbox(visible=False)
+        submit_full = gr.Button(visible=False)
+        submit_full.click(
+            fn=_generate_full,
+            inputs=[request_json_in],
+            outputs=[viewer, status, rewritten_box, snap_info_box],
+            api_name="generate_full",
+        )
+
+        gr.Markdown(
+            """
+            ### API access
+
+            ```bash
+            curl -X POST $API/v1/jobs \\
+              -H "Authorization: Bearer dev" \\
+              -H "Content-Type: application/json" \\
+              -d '{"input":{"type":"text","prompt":"a person walks"},"model":"mdm","duration":4}'
+            ```
+
+            Then poll `/v1/jobs/{id}` until `status=done` and download
+            `/v1/files/{id}.fbx` (or `.glb`).
+            """
+        )
+    return blocks