Cloud Run encoder wiring + startup resilience

Dockerfile

@@ -0,0 +1,45 @@
+FROM nvcr.io/nvidia/pytorch:24.10-py3
+
+# Avoid some interactive prompts + make pip quieter/reproducible-ish
+ENV DEBIAN_FRONTEND=noninteractive \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# Where your code will live inside the container
+WORKDIR /workspace
+
+# System deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates \
+      cmake build-essential \
+      gosu \
+    && rm -rf /var/lib/apt/lists/*
+
+# Some base images ship a broken `/usr/local/bin/cmake` shim (from a partial pip install),
+# which shadows `/usr/bin/cmake` and breaks builds that invoke `cmake` (e.g. MotionCorrection).
+# Prefer the system cmake.
+RUN rm -f /usr/local/bin/cmake || true
+
+# Install from docker_requirements.txt: kimodo editable (-e .),
+# but MotionCorrection non-editable (./MotionCorrection). The -e . line ensures [project.scripts]
+# from pyproject.toml are installed (kimodo_gen, kimodo_demo, kimodo_textencoder).
+# SKIP_MOTION_CORRECTION_IN_SETUP=1 so setup.py does not bundle motion_correction; it is
+# installed separately from ./MotionCorrection in the requirements file (non-editable).
+COPY docker_requirements.txt /workspace/docker_requirements.txt
+COPY setup.py /workspace/setup.py
+COPY pyproject.toml /workspace/pyproject.toml
+COPY kimodo /workspace/kimodo
+COPY MotionCorrection /workspace/MotionCorrection
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    python -m pip install --upgrade pip \
+ && SKIP_MOTION_CORRECTION_IN_SETUP=1 python -m pip install -r docker_requirements.txt
+
+# Use the docker-entrypoint script, to allow the docker to run as the actual user instead of root
+COPY kimodo/scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint
+RUN chmod +x /usr/local/bin/docker-entrypoint
+
+# Default command (change to your entrypoint if you have one)
+ENTRYPOINT ["docker-entrypoint"]
+CMD ["bash"]

README.md

@@ -1,37 +1,284 @@
----
-title: Movimento
-emoji: 🎬
-colorFrom: blue
-colorTo: green
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.12'
-app_file: app.py
-pinned: true
-license: apache-2.0
-short_description: Text-driven multi-character motion planning workspace
----
+<p align="center">
+  <img src="./assets/banner.png" alt="Banner" width="100%">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-76B900.svg" alt="License"></a>
+  <a href="https://research.nvidia.com/labs/sil/projects/kimodo/"><img src="https://img.shields.io/badge/Project-Page-blue" alt="Project Page"></a>
+  <a href="https://research.nvidia.com/labs/sil/projects/kimodo/docs/index.html"><img src="https://img.shields.io/badge/docs-online-green.svg" alt="Documentation"></a>
+</p>
+
+## Overview
+
+Kimodo is a **ki**nematic **mo**tion **d**iffusi**o**n model trained on a large-scale (700 hours) commercially-friendly optical motion capture dataset. The model generates high-quality 3D human and robot motions, and is controlled through text prompts and an extensive set of constraints such as full-body pose keyframes, end-effector positions/rotations, 2D paths, and 2D waypoints. Full details of the model architecture and training are available in the [technical report](https://research.nvidia.com/labs/sil/projects/kimodo/assets/kimodo_tech_report.pdf).
+
+This repository provides:
+- **Inference**: code and CLI to generate motions on both human and robot skeletons
+- **Interactive Demo**: easily author motions with a timeline interface of text prompts and kinematic controls
+- **Annotations**: [additional text descriptions](https://huggingface.co/datasets/nvidia/SEED-Timeline-Annotations) for the [BONES-SEED](https://huggingface.co/datasets/bones-studio/seed) dataset, including fine-grained temporal descriptions
+- _[Coming Soon]_ **Benchmark**: test cases and evaluation code built on the [BONES-SEED](https://huggingface.co/datasets/bones-studio/seed) dataset to evaluate motion generation models based on text and constraint-following abilities
+
+<div align="center">
+  <img src="assets/teaser.gif" width="1280">
+</div>
+
+## News
+
+See the [full changelog](CHANGELOG.md) for a detailed list of all changes.
+
+- **[2026-03-19]** **Breaking:** Model inputs/outputs now use the SOMA 77-joint skeleton (`somaskel77`).
+- **[2026-03-16]** Initial open-source release of Kimodo with five model variants (SOMA, G1, SMPL-X), CLI, interactive demo, and timeline annotations for BONES-SEED.
+
+
+## Kimodo Models
+
+Several variations of Kimodo-v1 are available trained on various skeletons and datasets. All models support text-to-motion and kinematic controls.
+
+> Note: models will be downloaded automatically when attempting to generate from the CLI or Interactive Demo, so there is no need to download them manually
+
+| Model | Skeleton | Training Data | Release Date | Hugging Face | License |
+|:-------|:-------------|:------:|:------:|:-------------:|:-------------:|
+| **Kimodo-SOMA-RP-v1** | [SOMA](https://github.com/NVlabs/SOMA-X) | [Bones Rigplay 1](https://bones.studio/datasets#rp01) | March 16, 2026 | [Link](https://huggingface.co/nvidia/Kimodo-SOMA-RP-v1) | [NVIDIA Open Model](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) |
+| **Kimodo-G1-RP-v1** | [Unitree G1](https://github.com/unitreerobotics/unitree_mujoco/tree/main/unitree_robots/g1) | [Bones Rigplay 1](https://bones.studio/datasets#rp01) | March 16, 2026  | [Link](https://huggingface.co/nvidia/Kimodo-G1-RP-v1) | [NVIDIA Open Model](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) |
+| **Kimodo-SOMA-SEED-v1** | [SOMA](https://github.com/NVlabs/SOMA-X) | [BONES-SEED](https://huggingface.co/datasets/bones-studio/seed) | March 16, 2026  | [Link](https://huggingface.co/nvidia/Kimodo-SOMA-SEED-v1) | [NVIDIA Open Model](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) |
+| **Kimodo-G1-SEED-v1** | [Unitree G1](https://github.com/unitreerobotics/unitree_mujoco/tree/main/unitree_robots/g1) | [BONES-SEED](https://huggingface.co/datasets/bones-studio/seed) | March 16, 2026  | [Link](https://huggingface.co/nvidia/Kimodo-G1-SEED-v1) | [NVIDIA Open Model](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) |
+| **Kimodo-SMPLX-RP-v1** | [SMPL-X](https://github.com/vchoutas/smplx) | [Bones Rigplay 1](https://bones.studio/datasets#rp01) | March 16, 2026  | [Link](https://huggingface.co/nvidia/Kimodo-SMPLX-RP-v1) | [NVIDIA R&D Model](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-internal-scientific-research-and-development-model-license/) |
+
+By default, we recommend using the models trained on the full Bones Rigplay 1 dataset (700 hours of mocap) for your motion generation needs.
+The models trained on BONES-SEED use 288 hours of [publicly available mocap data](https://huggingface.co/datasets/bones-studio/seed) so are less capable, but are useful for comparing your own trained models on the same dataset. Soon, we will be releasing a benchmark to make it easy to compare motion generation models trained on BONES-SEED.
+
+## Getting Started
+
+Please see the full documentation for detailed installation instructions, how to use the CLI and Interactive Demo, and other practical tips for generating motions with Kimodo:
+
+**[Full Documentation](https://research.nvidia.com/labs/sil/projects/kimodo/docs)**
+- [Quick Start Guide](https://research.nvidia.com/labs/sil/projects/kimodo/docs/getting_started/quick_start.html)
+- [Installation Instructions](https://research.nvidia.com/labs/sil/projects/kimodo/docs/getting_started/installation.html)
+- [Interactive Motion Authoring Demo](https://research.nvidia.com/labs/sil/projects/kimodo/docs/interactive_demo/index.html)
+- [Command-Line Interface](https://research.nvidia.com/labs/sil/projects/kimodo/docs/user_guide/cli.html)
+- [API Reference](https://research.nvidia.com/labs/sil/projects/kimodo/docs/api_reference/index.html)
+
+Some notes on installation environment:
+- Kimodo requires ~17GB of VRAM to generate locally, primarily due to the text embedding model
+- The model has been most extensively tested on GeForce RTX 3090, GeForce RTX 4090, and NVIDIA A100 GPUs, but should work on other recent cards with sufficient VRAM
+- This repo was developed on Linux, though Windows should work especially if using Docker
+
+Before getting started with motion generation, please review the [best practices](https://research.nvidia.com/labs/sil/projects/kimodo/docs/key_concepts/limitations.html) and be aware of [model limitations](https://research.nvidia.com/labs/sil/projects/kimodo/docs/key_concepts/limitations.html#limitations).
+
+## Interactive Motion Authoring Demo
+
+<div align="center">
+  <img src="assets/demo_screenshot.png" width="1000">
+</div>
+
+</br>
+
+**[Demo Documentation and Tutorial](https://research.nvidia.com/labs/sil/projects/kimodo/docs/interactive_demo/index.html)**
+
+The web-based interactive demo provides an intuitive interface for generating motions with any of the Kimodo model variations. After installation, the demo can be launched with the `kimodo_demo` command. It runs locally on http://127.0.0.1:7860. Open this URL in your browser to access the interface (or use port forwarding if set up on a server).
+
+### Demo Features
+- **Multiple Characters**: Supports generating with the SOMA, G1, and SMPL-X versions of Kimodo
+- **Text Prompts**: Enter one or more natural language descriptions of desired motions on the timeline
+- **Timeline Editor**: Add and edit keyframes and constrained intervals on multiple constraint tracks
+- **Constraint Types**:
+  - Full-Body: Complete joint position constraints at specific frames
+  - 2D Root: Define waypoints or full paths to follow on the ground plane
+  - End-Effectors: Control hands and feet positions/rotations
+- **Constraint Editing**: Editing mode allows for re-posing of constraints or adjusting waypoints
+- **3D Visualization**: Real-time rendering of generated motions with skeleton and skinned mesh options
+- **Playback Controls**: Preview generated motions with adjustable playback speed
+- **Multiple Samples**: Generate and compare multiple motion variations
+- **Examples**: Load pre-existing examples to better understand Kimodo's capabilities
+- **Export**: Save constraints and generated motions for later use
+
+## Command-Line Interface
+
+**[CLI Documentation and Examples](https://research.nvidia.com/labs/sil/projects/kimodo/docs/user_guide/cli.html)**
+
+Motions can also be generated directly from the command line with the `kimodo_gen` command or by running `python -m kimodo.scripts.generate` directly.
+
+**Key Arguments:**
+- `prompt`: A single text description or sequence of texts for the desired motion (required)
+- `--model`: Which Kimodo model to use for generation
+- `--duration`: Motion duration in seconds
+- `--num_samples`: Number of motion variations to generate
+- `--constraints`: Constraint file to control the generated motion (e.g., saved from the web demo)
+- `--diffusion_steps`: Number of denoising steps
+- `--cfg_type` / `--cfg_weight`: Classifier-free guidance (`nocfg`, `regular` with one weight, or `separated` with two weights for text vs. constraints); see the [CLI docs](https://research.nvidia.com/labs/sil/projects/kimodo/docs/user_guide/cli.html#classifier-free-guidance-cfg)
+- `--no-postprocess`: Flag to disable foot skate and constraint cleanup post-processing
+- `--seed`: Random seed for reproducible results
+
+The script supports different output formats depending on which skeleton is used. By default, a custom NPZ format is saved that is compatible with the web demo.
+For Kimodo-G1 models, the motion can be saved in the standard MuJoCo qpos CSV format.
+For Kimodo-SMPLX, motion can be saved in the standard AMASS npz format for compability with existing pipelines.
+
+### Default NPZ Output Format
+Generated motions are saved as NPZ files containing:
+- `posed_joints`: Global joint positions `[T, J, 3]`
+- `global_rot_mats`: Global joint rotation matrices `[T, J, 3, 3]`
+- `local_rot_mats`: Local (parent-relative) joint rotation matrices `[T, J, 3, 3]`
+- `foot_contacts`: Foot contact labels [left heel, left toe, right heel, right toes] `[T, 4]`
+- `smooth_root_pos`: Smoothed root representations outputted from the model `[T, 3]`
+- `root_positions`: The (non-smoothed) trajectory of the actual root joint (e.g., pelvis) `[T, 3]`
+- `global_root_heading`: The heading direction output from the model `[T, 2]`
+
+`T` the number of frames and `J` the number of joints.
+
+## Low-Level Python API
+
+**[Model API Documentation](https://research.nvidia.com/labs/sil/projects/kimodo/docs/api_reference/model.html#kimodo.model.kimodo_model.Kimodo.__call__)**
+
+For maximum flexibility, the low-level model inference API can be called directly, rather than going through our high-level CLI.
+This allows for advanced model configuration including classifier-free guidance weights and parameters related to transitions in multi-prompt sequences.
+
+## Downstream Robotics Applications of Kimodo
+
+### Visualizing G1 Motions with MuJoCo
+
+<div align="center">
+  <img src="assets/mujoco_result.gif" width="800">
+</div>
+
+After generating motions on the G1 robot skeleton and saving to the MuJoCo qpos CSV file format, they can be easily used and visualized within MuJoCo.
+A minimal visualization script is available with:
+```
+python -m kimodo.scripts.mujoco_load
+```
+Make sure to edit the script to correctly point to your CSV file and install Mujoco before running this.
+
+### Tracking Generated Motions with ProtoMotions
+
+<div align="center">
+  <img src="assets/protomotions_results.gif" width="1280">
+</div>
 
-Movimento is a hackathon Space for multi-character motion planning and orchestration.
-
-This Space currently runs a lightweight but feature-complete frontend shell for planning, execution trace, and playback controls.
-
-Implemented pipeline milestones:
-- Card 0: environment readiness gate
-- Card 1: scope lock
-- Card 2: service contracts
-- Card 3: shared state deterministic loop
-- Card 4: Qwen planner adapter
-- Card 5: BONES-SEED ingestion flow
-- Card 6: script-to-Kimodo mapping
-- Card 7: blend quality guardrails
-- Card 8: multi-character scheduler runtime
-- Card 9: AMD runtime bootstrap and health checks
-- Card 10: Gradio Space frontend shell
-
-Next milestone:
-- Card 11: notebook workflow and research pack
-
-Runtime notes:
-- HF bucket data is available for assets and repo snapshots.
-- STL meshes are hosted in dataset `lablab-ai-amd-developer-hackathon/movimento-stl-assets`.
+[ProtoMotions](https://github.com/NVlabs/ProtoMotions) is a GPU-accelerated simulation and learning framework for training physically simulated digital humans and humanoid robots. The Kimodo NPZ and CSV output formats are both compatible with ProtoMotions making it easy to train physics-based policies with generated motions from Kimodo. ProtoMotions supports outputs on both the SOMA skeleton and Unitree G1
+
+After generating motions with Kimodo, head over to the [ProtoMotions docs](https://github.com/NVlabs/ProtoMotions?tab=readme-ov-file#-motion-authoring-with-kimodo) to see how to import them.
+
+### Retargeting Motions to Other Robots with GMR
+
+<div align="center">
+  <img src="assets/gmr_results.gif" width="1280">
+</div>
+
+Motions generated by Kimodo-SMPLX can be retargeted to other robots using [General Motion Retargeting (GMR)](https://github.com/YanjieZe/GMR).
+GMR supports the AMASS NPZ format out of the box, so simply generate motions with Kimodo and use `--output` to save; the AMASS NPZ is written to `stem_amass.npz` (single sample) or in the output folder (multiple samples). Then, use the [SMPL-X to Robot script](https://github.com/YanjieZe/GMR?tab=readme-ov-file#retargeting-from-smpl-x-amass-omomo-to-robot) in GMR to retarget to any supported robot. For example:
+```
+# run within GMR codebase
+python scripts/smplx_to_robot.py --smplx_file /path/to/saved/amass_format.npz --robot booster_t1
+```
+
+## Timeline Annotations for BONES-SEED
+
+As detailed in the [tech report](https://research.nvidia.com/labs/sil/projects/kimodo/assets/kimodo_tech_report.pdf), Kimodo is trained using fine-grained temporal text annotations of mocap clips.
+While the full [Rigplay 1](https://bones.studio/datasets#rp01) dataset is proprietary, we have released the temporal segmentations for the public [BONES-SEED](https://huggingface.co/datasets/bones-studio/seed) subset.
+These annotations are already included in the BONES-SEED dataset, but the standalone labels and additional information about them is [available on HuggingFace](https://huggingface.co/datasets/nvidia/SEED-Timeline-Annotations).
+
+## AMD Backend Orchestration (Hackathon Submission)
+
+For hackathon submission workflows, this repository includes an AMD-oriented orchestration pack:
+
+- Kubernetes manifests: [orchestration/amd/k8s](orchestration/amd/k8s)
+- Slurm batch templates: [orchestration/amd/slurm](orchestration/amd/slurm)
+- Deployment script: [orchestration/amd/deploy_k8s.sh](orchestration/amd/deploy_k8s.sh)
+- Validation script: [orchestration/amd/validate_orchestration.sh](orchestration/amd/validate_orchestration.sh)
+- Fireworks AMD planner helper: [orchestration/amd/fireworks_quickstart.sh](orchestration/amd/fireworks_quickstart.sh)
+
+Quick start:
+
+```bash
+bash orchestration/amd/deploy_k8s.sh
+bash orchestration/amd/validate_orchestration.sh
+```
+
+The AMD runtime path is controlled through `KIMODO_DEVICE=amd` (with strict/non-strict fallback support in the runtime health checks).
+
+To route Qwen planning through Fireworks on AMD MI300X, run:
+
+```bash
+export FIREWORKS_API_KEY=<your_key>
+bash orchestration/amd/fireworks_quickstart.sh
+FIREWORKS_VALIDATE_ONLY=false FIREWORKS_DEPLOYMENT_ID=kimodo-amd-planner bash orchestration/amd/fireworks_quickstart.sh
+
+export KIMODO_PLANNER_PROVIDER=fireworks
+export KIMODO_PLANNER_MODELS=accounts/<account-id>/deployments/<deployment-id>
+```
+
+## Deployment Matrix (Cloud Run)
+
+Use these profiles as recommended defaults for rollout strictness.
+
+| Profile | Goal | Recommended Flags | Notes |
+|---|---|---|---|
+| Public demo | Fast public access for hackathon/demo traffic | `PROJECT_ID=movimento-text-encoder REGION=europe-west1 ALLOW_UNAUTHENTICATED=true HF_SECRET_NAME=hf-token GPU_TYPE=nvidia-l4 GPU_COUNT=1 ./cloud-run/deploy.sh` | Enables `allUsers` invoker on encoder/demo services. |
+| Private staging | Internal validation before public rollout | `PROJECT_ID=movimento-text-encoder REGION=europe-west1 ALLOW_UNAUTHENTICATED=false HF_SECRET_NAME=hf-token GPU_TYPE=nvidia-l4 GPU_COUNT=1 ./cloud-run/deploy.sh` | Keeps services private; run integration checks via authenticated callers only. |
+| Stricter production | Controlled release with explicit policy + dependency gates | `PROJECT_ID=movimento-text-encoder REGION=europe-west1 ALLOW_UNAUTHENTICATED=false HF_SECRET_NAME=hf-token GPU_TYPE=nvidia-l4 GPU_COUNT=1 ./cloud-run/deploy.sh` | Health gate blocks downstream deploy when encoder is not ready; use IAM and network policy controls before enabling public traffic. |
+
+Notes:
+- For H200-style CUDA environments, keep the CUDA runtime path and set `GPU_TYPE` to the supported Cloud Run GPU type for your project/region.
+- The deploy flow enforces secret placeholder substitution and encoder readiness before demo rollout.
+
+### Health Gate (Required)
+
+Run the encoder health gate before downstream deployment:
+
+```bash
+PROJECT_ID=movimento-text-encoder REGION=europe-west1 ./cloud-run/health_gate_text_encoder.sh
+```
+
+If the result is `[PASS]`, proceed:
+
+```bash
+PROJECT_ID=movimento-text-encoder REGION=europe-west1 ./cloud-run/deploy.sh
+```
+
+## Runtime Technology Stack
+
+- Motion generation runtime: Kimodo diffusion models (PyTorch/CUDA)
+- Planning layer: Qwen planner adapter (optional Fireworks deployment for AMD workflows)
+- Model and artifact registry: Hugging Face Hub (token-gated model access for text encoder assets)
+- Text encoding service: Cloud Run service `movimento-text-encoder`
+- UI surfaces: Gradio Space frontend and Kimodo demo service
+- Deployment targets in repo: Cloud Run (primary), HF Space integration, AMD orchestration manifests (Kubernetes/Slurm)
+
+
+## Related Humanoid Work at NVIDIA
+Kimodo is part of a larger effort to enable humanoid motion data for robotics, physical AI, and other applications.
+
+Check out these related works:
+* [SOMA Body Model](https://github.com/NVlabs/SOMA-X) - a unified parameteric human body model
+* [BONES-SEED Dataset](https://huggingface.co/datasets/bones-studio/seed) - a large scale human(oid) motion capture dataset in SOMA and G1 format
+* [ProtoMotions](https://github.com/NVlabs/ProtoMotions) - simulation and learning framework for training physically simulated human(oid)s
+* [SOMA Retargeter](https://github.com/NVIDIA/soma-retargeter) - SOMA to G1 retargeting tool
+* [GEM](https://github.com/NVlabs/GEM-X) - human motion reconstruction from video
+* [GEAR SONIC](https://github.com/NVlabs/GR00T-WholeBodyControl) - humanoid behavior foundation model for physical robots
+
+## Citation
+
+If you use this code in your research, please cite:
+
+```bibtex
+@article{Kimodo2026,
+  title={Kimodo: Scaling Controllable Human Motion Generation},
+  author={Rempe, Davis and Petrovich, Mathis and Yuan, Ye and Zhang, Haotian and Peng, Xue Bin and Jiang, Yifeng and Wang, Tingwu and Iqbal, Umar and Minor, David and de Ruyter, Michael and Li, Jiefeng and Tessler, Chen and Lim, Edy and Jeong, Eugene and Wu, Sam and Hassani, Ehsan and Huang, Michael and Yu, Jin-Bey and Chung, Chaeyeon and Song, Lina and Dionne, Olivier and Kautz, Jan and Yuen, Simon and Fidler, Sanja},
+  journal={arXiv:2603.15546},
+  year={2026}
+}
+```
+
+## License
+
+This codebase is licensed under [Apache-2.0](LICENSE). Note that model checkpoints and data are licensed separately as indicated on the HuggingFace download pages.
+
+This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.
+
+## Acknowledgments
+
+This project builds upon excellent open-source projects:
+- [Viser](https://github.com/nerfstudio-project/viser) for 3D motion authoring demo
+- [LLM2Vec](https://github.com/McGill-NLP/llm2vec) for text encoding
+
+## Contact
+
+For questions or issues, plese open an issue on this repository or reach out directly to the authors.
+
+---

cloud-run/demo.yaml

@@ -0,0 +1,68 @@
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: kimodo-demo
+  annotations:
+    run.googleapis.com/launch-stage: GA
+spec:
+  template:
+    metadata:
+      annotations:
+        autoscaling.knative.dev/minScale: "1"
+        autoscaling.knative.dev/maxScale: "1"
+        run.googleapis.com/execution-environment: gen2
+        run.googleapis.com/gpu-type: GPU_TYPE_PLACEHOLDER
+        run.googleapis.com/gpu-zonal-redundancy-disabled: "true"
+    spec:
+      containerConcurrency: 1
+      timeoutSeconds: 3600
+      containers:
+        - image: REGION-docker.pkg.dev/PROJECT_ID/kimodo/kimodo:latest
+          command: ["python", "-m", "kimodo.demo"]
+          ports:
+            - containerPort: 7860
+          resources:
+            limits:
+              cpu: "8"
+              memory: 24Gi
+              nvidia.com/gpu: "GPU_COUNT_PLACEHOLDER"
+          env:
+            - name: SERVER_NAME
+              value: "0.0.0.0"
+            - name: TEXT_ENCODER_URL
+              value: TEXT_ENCODER_URL_PLACEHOLDER
+            - name: TEXT_ENCODER_MODE
+              value: "api"
+            - name: HF_MODE
+              value: "false"
+            - name: HF_HOME
+              value: /workspace/.cache/huggingface
+            - name: LOCAL_CACHE
+              value: "true"
+            - name: PYTHONUNBUFFERED
+              value: "1"
+            - name: HF_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HUGGING_FACE_HUB_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HF_HUB_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HUGGINGFACEHUB_API_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: KIMODO_DEFER_MODEL_LOAD
+              value: "true"
+  traffic:
+    - percent: 100
+      latestRevision: true

cloud-run/deploy.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Deploy kimodo Cloud Run services.
+# Usage:
+#   REGION=europe-west1 PROJECT_ID=my-project ./cloud-run/deploy.sh
+#   REGION=europe-west1 PROJECT_ID=my-project ALLOW_UNAUTHENTICATED=false ./cloud-run/deploy.sh
+#   REGION=europe-west1 PROJECT_ID=my-project GPU_TYPE=nvidia-h200-141gb GPU_COUNT=1 ./cloud-run/deploy.sh
+set -euo pipefail
+
+: "${REGION:?Set REGION (e.g. us-central1)}"
+: "${PROJECT_ID:?Set PROJECT_ID}"
+HF_SECRET_NAME="${HF_SECRET_NAME:-hf-token}"
+ALLOW_UNAUTHENTICATED="${ALLOW_UNAUTHENTICATED:-true}"
+GPU_TYPE="${GPU_TYPE:-nvidia-l4}"
+GPU_COUNT="${GPU_COUNT:-1}"
+
+IMAGE_TAG="$REGION-docker.pkg.dev/$PROJECT_ID/kimodo/kimodo:latest"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GCLOUD_BIN="${GCLOUD_BIN:-}"
+if [[ -z "$GCLOUD_BIN" ]]; then
+  if command -v gcloud >/dev/null 2>&1; then
+    GCLOUD_BIN="$(command -v gcloud)"
+  elif [[ -x "/workspaces/kimodo/.tools/google-cloud-sdk/bin/gcloud" ]]; then
+    GCLOUD_BIN="/workspaces/kimodo/.tools/google-cloud-sdk/bin/gcloud"
+  else
+    echo "gcloud not found. Set GCLOUD_BIN or install gcloud CLI."
+    exit 1
+  fi
+fi
+
+# ── Substitute image path into manifests ────────────────────────────────────
+IMAGE_DIGEST=$("$GCLOUD_BIN" artifacts docker images list "$REGION-docker.pkg.dev/$PROJECT_ID/kimodo/kimodo" \
+  --include-tags \
+  --filter="tags:latest" \
+  --format="value(version)" \
+  --limit=1)
+
+if [[ -z "$IMAGE_DIGEST" ]]; then
+  echo "Could not resolve digest for image tag: $IMAGE_TAG"
+  exit 1
+fi
+
+IMAGE="$REGION-docker.pkg.dev/$PROJECT_ID/kimodo/kimodo@$IMAGE_DIGEST"
+echo "Deploying image: $IMAGE"
+echo "Auth policy (allUsers invoker): $ALLOW_UNAUTHENTICATED"
+echo "GPU profile: type=$GPU_TYPE count=$GPU_COUNT"
+
+sed \
+  -e "s|REGION-docker.pkg.dev/PROJECT_ID/kimodo/kimodo:latest|$IMAGE|g" \
+  -e "s|HF_TOKEN_SECRET_NAME|$HF_SECRET_NAME|g" \
+  -e "s|GPU_TYPE_PLACEHOLDER|$GPU_TYPE|g" \
+  -e "s|GPU_COUNT_PLACEHOLDER|$GPU_COUNT|g" \
+  "$SCRIPT_DIR/text-encoder.yaml" > /tmp/text-encoder-rendered.yaml
+
+sed \
+  -e "s|REGION-docker.pkg.dev/PROJECT_ID/kimodo/kimodo:latest|$IMAGE|g" \
+  -e "s|HF_TOKEN_SECRET_NAME|$HF_SECRET_NAME|g" \
+  -e "s|GPU_TYPE_PLACEHOLDER|$GPU_TYPE|g" \
+  -e "s|GPU_COUNT_PLACEHOLDER|$GPU_COUNT|g" \
+  "$SCRIPT_DIR/demo.yaml" > /tmp/demo-rendered.yaml
+
+if grep -q 'HF_TOKEN_SECRET_NAME' /tmp/text-encoder-rendered.yaml; then
+  echo "Secret placeholder HF_TOKEN_SECRET_NAME still present in rendered text-encoder manifest"
+  exit 1
+fi
+
+if grep -q 'GPU_TYPE_PLACEHOLDER\|GPU_COUNT_PLACEHOLDER' /tmp/text-encoder-rendered.yaml; then
+  echo "GPU placeholders still present in rendered text-encoder manifest"
+  exit 1
+fi
+
+if grep -q 'GPU_TYPE_PLACEHOLDER\|GPU_COUNT_PLACEHOLDER' /tmp/demo-rendered.yaml; then
+  echo "GPU placeholders still present in rendered demo manifest"
+  exit 1
+fi
+
+if grep -q 'HF_TOKEN_SECRET_NAME' /tmp/demo-rendered.yaml; then
+  echo "Secret placeholder HF_TOKEN_SECRET_NAME still present in rendered demo manifest"
+  exit 1
+fi
+
+# ── 1. Deploy text-encoder ───────────────────────────────────────────────────
+echo "Deploying movimento-text-encoder to $REGION..."
+"$GCLOUD_BIN" run services replace /tmp/text-encoder-rendered.yaml \
+  --region "$REGION" \
+  --project "$PROJECT_ID"
+
+if [[ "$ALLOW_UNAUTHENTICATED" == "true" ]]; then
+  "$GCLOUD_BIN" run services add-iam-policy-binding movimento-text-encoder \
+    --region "$REGION" \
+    --project "$PROJECT_ID" \
+    --member "allUsers" \
+    --role "roles/run.invoker" 2>/dev/null || true
+fi
+
+TEXT_ENCODER_URL=$("$GCLOUD_BIN" run services describe movimento-text-encoder \
+  --region "$REGION" \
+  --project "$PROJECT_ID" \
+  --format "value(status.url)")
+
+echo "Text-encoder URL: $TEXT_ENCODER_URL"
+
+if [[ -z "$TEXT_ENCODER_URL" ]]; then
+  echo "Text encoder URL is empty. Blocking downstream deployment."
+  exit 1
+fi
+
+echo "Running encoder health gate before deploying downstream services..."
+PROJECT_ID="$PROJECT_ID" \
+REGION="$REGION" \
+SERVICE_NAME="movimento-text-encoder" \
+HF_SECRET_NAME="$HF_SECRET_NAME" \
+DEMO_SERVICE_NAME="kimodo-demo" \
+"$SCRIPT_DIR/health_gate_text_encoder.sh"
+
+# ── 2. Inject text-encoder URL into demo manifest and deploy ─────────────────
+sed -i "s|TEXT_ENCODER_URL_PLACEHOLDER|$TEXT_ENCODER_URL/|g" /tmp/demo-rendered.yaml
+
+if grep -q 'TEXT_ENCODER_URL_PLACEHOLDER' /tmp/demo-rendered.yaml; then
+  echo "TEXT_ENCODER_URL_PLACEHOLDER still present in demo manifest"
+  exit 1
+fi
+
+echo "Deploying kimodo-demo to $REGION..."
+"$GCLOUD_BIN" run services replace /tmp/demo-rendered.yaml \
+  --region "$REGION" \
+  --project "$PROJECT_ID"
+
+if [[ "$ALLOW_UNAUTHENTICATED" == "true" ]]; then
+  "$GCLOUD_BIN" run services add-iam-policy-binding kimodo-demo \
+    --region "$REGION" \
+    --project "$PROJECT_ID" \
+    --member "allUsers" \
+    --role "roles/run.invoker" 2>/dev/null || true
+fi
+
+DEMO_URL=$("$GCLOUD_BIN" run services describe kimodo-demo \
+  --region "$REGION" \
+  --project "$PROJECT_ID" \
+  --format "value(status.url)")
+
+echo "Re-running encoder health gate to verify dependency contract after demo deploy..."
+PROJECT_ID="$PROJECT_ID" \
+REGION="$REGION" \
+SERVICE_NAME="movimento-text-encoder" \
+HF_SECRET_NAME="$HF_SECRET_NAME" \
+DEMO_SERVICE_NAME="kimodo-demo" \
+"$SCRIPT_DIR/health_gate_text_encoder.sh"
+
+echo ""
+echo "✓ Deployment complete."
+echo "  Text-encoder: $TEXT_ENCODER_URL"
+echo "  Demo UI:      $DEMO_URL"

cloud-run/deploy_text_encoder.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Deploy movimento text encoder service to Cloud Run.
+# Usage:
+#   PROJECT_ID=movimento-text-encoder REGION=europe-west1 HF_TOKEN=hf_xxx ./cloud-run/deploy_text_encoder.sh
+#   PROJECT_ID=movimento-text-encoder REGION=europe-west1 HF_SECRET_NAME=hf-token ALLOW_UNAUTHENTICATED=false ./cloud-run/deploy_text_encoder.sh
+#   PROJECT_ID=movimento-text-encoder REGION=europe-west1 GPU_TYPE=nvidia-h200-141gb GPU_COUNT=1 ./cloud-run/deploy_text_encoder.sh
+set -euo pipefail
+
+: "${PROJECT_ID:?Set PROJECT_ID (e.g. movimento-text-encoder)}"
+REGION="${REGION:-europe-west1}"
+SERVICE_NAME="${SERVICE_NAME:-movimento-text-encoder}"
+REPO_NAME="${REPO_NAME:-kimodo}"
+IMAGE_NAME="${IMAGE_NAME:-kimodo}"
+IMAGE_TAG="${IMAGE_TAG:-latest}"
+HF_SECRET_NAME="${HF_SECRET_NAME:-hf-token}"
+ALLOW_UNAUTHENTICATED="${ALLOW_UNAUTHENTICATED:-true}"
+GPU_TYPE="${GPU_TYPE:-nvidia-l4}"
+GPU_COUNT="${GPU_COUNT:-1}"
+
+if ! command -v gcloud >/dev/null 2>&1; then
+  echo "gcloud CLI not found. Run this script from Cloud Shell or install gcloud."
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+IMAGE_URI="$REGION-docker.pkg.dev/$PROJECT_ID/$REPO_NAME/$IMAGE_NAME:$IMAGE_TAG"
+
+echo "[deploy] project=$PROJECT_ID region=$REGION service=$SERVICE_NAME image=$IMAGE_URI"
+echo "[deploy] auth policy (allUsers invoker): $ALLOW_UNAUTHENTICATED"
+echo "[deploy] gpu profile: type=$GPU_TYPE count=$GPU_COUNT"
+gcloud config set project "$PROJECT_ID" >/dev/null
+
+echo "[deploy] enabling required APIs"
+gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com >/dev/null
+
+if ! gcloud artifacts repositories describe "$REPO_NAME" --location="$REGION" >/dev/null 2>&1; then
+  echo "[deploy] creating Artifact Registry repo: $REPO_NAME"
+  gcloud artifacts repositories create "$REPO_NAME" \
+    --repository-format=docker \
+    --location="$REGION" \
+    --description="Movimento container images"
+fi
+
+if [[ -n "${HF_TOKEN:-}" ]]; then
+  if ! gcloud secrets describe "$HF_SECRET_NAME" >/dev/null 2>&1; then
+    echo "[deploy] creating secret: $HF_SECRET_NAME"
+    gcloud secrets create "$HF_SECRET_NAME" --replication-policy="automatic" >/dev/null
+  fi
+  echo "[deploy] updating secret version: $HF_SECRET_NAME"
+  printf '%s' "$HF_TOKEN" | gcloud secrets versions add "$HF_SECRET_NAME" --data-file=- >/dev/null
+else
+  echo "[deploy] HF_TOKEN env var not set; expecting existing secret '$HF_SECRET_NAME'"
+  gcloud secrets describe "$HF_SECRET_NAME" >/dev/null
+fi
+
+PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
+RUNTIME_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
+
+echo "[deploy] granting Secret Manager access to runtime SA: $RUNTIME_SA"
+gcloud secrets add-iam-policy-binding "$HF_SECRET_NAME" \
+  --member="serviceAccount:$RUNTIME_SA" \
+  --role="roles/secretmanager.secretAccessor" >/dev/null
+
+echo "[deploy] building image: $IMAGE_URI"
+gcloud builds submit "$REPO_ROOT" --config "$REPO_ROOT/cloudbuild.yaml" --substitutions="_IMAGE=$IMAGE_URI"
+
+echo "[deploy] rendering Cloud Run manifest"
+RENDERED_MANIFEST="/tmp/${SERVICE_NAME}-rendered.yaml"
+sed \
+  -e "s|REGION-docker.pkg.dev/PROJECT_ID/kimodo/kimodo:latest|$IMAGE_URI|g" \
+  -e "s|HF_TOKEN_SECRET_NAME|$HF_SECRET_NAME|g" \
+  -e "s|GPU_TYPE_PLACEHOLDER|$GPU_TYPE|g" \
+  -e "s|GPU_COUNT_PLACEHOLDER|$GPU_COUNT|g" \
+  "$REPO_ROOT/cloud-run/text-encoder.yaml" > "$RENDERED_MANIFEST"
+
+if grep -q 'HF_TOKEN_SECRET_NAME\|GPU_TYPE_PLACEHOLDER\|GPU_COUNT_PLACEHOLDER' "$RENDERED_MANIFEST"; then
+  echo "[deploy] rendered manifest still contains placeholders"
+  exit 1
+fi
+
+echo "[deploy] applying Cloud Run service"
+gcloud run services replace "$RENDERED_MANIFEST" --region "$REGION" --project "$PROJECT_ID"
+
+if [[ "$ALLOW_UNAUTHENTICATED" == "true" ]]; then
+  echo "[deploy] allowing unauthenticated invoke"
+  gcloud run services add-iam-policy-binding "$SERVICE_NAME" \
+    --region "$REGION" \
+    --project "$PROJECT_ID" \
+    --member "allUsers" \
+    --role "roles/run.invoker" >/dev/null || true
+fi
+
+SERVICE_URL="$(gcloud run services describe "$SERVICE_NAME" --region "$REGION" --project "$PROJECT_ID" --format 'value(status.url)')"
+echo "[deploy] text encoder url: ${SERVICE_URL}/"

cloud-run/health_gate_text_encoder.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# Cloud Run health gate for movimento-text-encoder.
+# Usage:
+#   PROJECT_ID=my-project REGION=europe-west1 ./cloud-run/health_gate_text_encoder.sh
+#   PROJECT_ID=my-project REGION=europe-west1 SERVICE_NAME=movimento-text-encoder ./cloud-run/health_gate_text_encoder.sh
+
+set -euo pipefail
+
+: "${PROJECT_ID:?Set PROJECT_ID}"
+REGION="${REGION:-europe-west1}"
+SERVICE_NAME="${SERVICE_NAME:-movimento-text-encoder}"
+DEMO_SERVICE_NAME="${DEMO_SERVICE_NAME:-kimodo-demo}"
+HF_SECRET_NAME="${HF_SECRET_NAME:-hf-token}"
+GATE_TIMEOUT_SEC="${GATE_TIMEOUT_SEC:-120}"
+GATE_RETRY_INTERVAL_SEC="${GATE_RETRY_INTERVAL_SEC:-5}"
+
+if ! command -v gcloud >/dev/null 2>&1; then
+  echo "FAIL: gcloud CLI not found"
+  exit 2
+fi
+
+ENCODER_JSON="$(gcloud run services describe "$SERVICE_NAME" \
+  --region "$REGION" \
+  --project "$PROJECT_ID" \
+  --format=json)"
+
+readarray -t ENCODER_FIELDS < <(python - <<'PY' "$ENCODER_JSON" "$HF_SECRET_NAME"
+import json
+import sys
+
+service = json.loads(sys.argv[1])
+expected_secret = sys.argv[2]
+
+conditions = service.get("status", {}).get("conditions", [])
+ready = "Unknown"
+for cond in conditions:
+    if cond.get("type") == "Ready":
+        ready = cond.get("status", "Unknown")
+        break
+
+url = service.get("status", {}).get("url", "")
+latest_ready = service.get("status", {}).get("latestReadyRevisionName", "")
+
+traffic = service.get("status", {}).get("traffic", [])
+latest_receives_traffic = "False"
+for item in traffic:
+    if item.get("latestRevision") is True and int(item.get("percent", 0)) > 0:
+        latest_receives_traffic = "True"
+        break
+
+spec_env = service.get("spec", {}).get("template", {}).get("spec", {}).get("containers", [{}])[0].get("env", [])
+secret_names = []
+for env in spec_env:
+    value_from = env.get("valueFrom") or {}
+    key_ref = value_from.get("secretKeyRef") or {}
+    name = key_ref.get("name")
+    if name:
+        secret_names.append(name)
+
+secret_wiring = "PASS" if expected_secret in secret_names and "HF_TOKEN_SECRET_NAME" not in secret_names else "FAIL"
+
+print(ready)
+print(url)
+print(latest_ready)
+print(latest_receives_traffic)
+print(secret_wiring)
+PY
+)
+
+READY_STATUS="${ENCODER_FIELDS[0]}"
+ENCODER_URL="${ENCODER_FIELDS[1]}"
+LATEST_READY_REV="${ENCODER_FIELDS[2]}"
+LATEST_TRAFFIC="${ENCODER_FIELDS[3]}"
+SECRET_WIRING="${ENCODER_FIELDS[4]}"
+
+if [[ -z "$ENCODER_URL" ]]; then
+  echo "Service Ready: ${READY_STATUS}"
+  echo "Revision Traffic: ${LATEST_TRAFFIC}"
+  echo "Encoder URL Check: FAIL (missing URL)"
+  echo "Secret Wiring: ${SECRET_WIRING}"
+  echo "Failure Logs: FAIL"
+  echo "Dependency Contract: FAIL"
+  echo "[FAIL] Encoder service URL is empty"
+  exit 1
+fi
+
+deadline=$((SECONDS + GATE_TIMEOUT_SEC))
+endpoint_ok="false"
+latency_ms=""
+
+while (( SECONDS < deadline )); do
+  if latency_ms=$(python - <<'PY' "$ENCODER_URL"
+import sys
+import time
+import urllib.request
+
+url = sys.argv[1]
+start = time.time()
+with urllib.request.urlopen(url, timeout=10) as resp:
+    if resp.status < 500:
+        elapsed = int((time.time() - start) * 1000)
+        print(elapsed)
+    else:
+        raise RuntimeError(f"status={resp.status}")
+PY
+ 2>/dev/null); then
+    endpoint_ok="true"
+    break
+  fi
+  sleep "$GATE_RETRY_INTERVAL_SEC"
+done
+
+demo_contract="SKIPPED"
+if gcloud run services describe "$DEMO_SERVICE_NAME" --region "$REGION" --project "$PROJECT_ID" >/dev/null 2>&1; then
+  DEMO_JSON="$(gcloud run services describe "$DEMO_SERVICE_NAME" --region "$REGION" --project "$PROJECT_ID" --format=json)"
+  demo_url_match=$(python - <<'PY' "$DEMO_JSON" "$ENCODER_URL"
+import json
+import sys
+
+service = json.loads(sys.argv[1])
+encoder_url = sys.argv[2].rstrip('/') + '/'
+
+envs = service.get("spec", {}).get("template", {}).get("spec", {}).get("containers", [{}])[0].get("env", [])
+configured = None
+for env in envs:
+    if env.get("name") == "TEXT_ENCODER_URL":
+        configured = (env.get("value") or "").rstrip('/') + '/'
+        break
+
+if configured == encoder_url:
+    print("PASS")
+else:
+    print("FAIL")
+PY
+)
+  demo_contract="$demo_url_match"
+fi
+
+echo "Service Ready: ${READY_STATUS}"
+echo "Latest Ready Revision: ${LATEST_READY_REV}"
+echo "Revision Traffic: ${LATEST_TRAFFIC}"
+if [[ "$endpoint_ok" == "true" ]]; then
+  echo "Encoder URL Check: PASS (${latency_ms}ms)"
+else
+  echo "Encoder URL Check: FAIL (timeout after ${GATE_TIMEOUT_SEC}s)"
+fi
+echo "Secret Wiring: ${SECRET_WIRING}"
+if [[ "$READY_STATUS" == "True" && "$LATEST_TRAFFIC" == "True" ]]; then
+  echo "Failure Logs: PASS"
+else
+  echo "Failure Logs: FAIL"
+fi
+echo "Dependency Contract: ${demo_contract}"
+
+if [[ "$READY_STATUS" != "True" || "$LATEST_TRAFFIC" != "True" || "$endpoint_ok" != "true" || "$SECRET_WIRING" != "PASS" ]]; then
+  echo "[FAIL] Cloud Run encoder health gate failed"
+  exit 1
+fi
+
+if [[ "$demo_contract" == "FAIL" ]]; then
+  echo "[FAIL] Demo TEXT_ENCODER_URL does not match encoder URL"
+  exit 1
+fi
+
+echo "[PASS] Cloud Run encoder health gate passed"

cloud-run/hf_sync_filters.txt

@@ -0,0 +1,15 @@
+exclude .git/**
+exclude .pytest_cache/**
+exclude .mypy_cache/**
+exclude .ruff_cache/**
+exclude .nox/**
+exclude .tox/**
+exclude .venv/**
+exclude .tools/**
+exclude **/__pycache__/**
+exclude **/*.pyc
+exclude kimodo.egg-info/**
+exclude docs/_build/**
+exclude dist/**
+exclude *.log
+exclude nohup.out

cloud-run/sync_hf_bucket.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Sync local repository content to a Hugging Face bucket.
+#
+# Usage examples:
+#   HF_TOKEN=hf_xxx ./cloud-run/sync_hf_bucket.sh
+#   ./cloud-run/sync_hf_bucket.sh --source ./kimodo --dry-run
+#   ./cloud-run/sync_hf_bucket.sh --dest hf://buckets/rydlrKE/movimento-bucket --include-build
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEST="hf://buckets/rydlrKE/movimento-bucket/kimodo"
+SOURCE="."
+DRY_RUN=false
+INCLUDE_BUILD=false
+VERBOSE=false
+DELETE_MISSING=false
+FILTER_FILE="$SCRIPT_DIR/hf_sync_filters.txt"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dest)
+      DEST="$2"
+      shift 2
+      ;;
+    --source)
+      SOURCE="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --include-build)
+      INCLUDE_BUILD=true
+      shift
+      ;;
+    --verbose)
+      VERBOSE=true
+      shift
+      ;;
+    --delete)
+      DELETE_MISSING=true
+      shift
+      ;;
+    --filter-file)
+      FILTER_FILE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      cat <<'EOF'
+Sync local files to a Hugging Face bucket.
+
+Options:
+  --source <path>         Local source directory (default: .)
+  --dest <hf://...>       HF bucket destination (default: hf://buckets/rydlrKE/movimento-bucket)
+  --dry-run               Print planned actions without uploading
+  --include-build         Include build/ artifacts (excluded by default)
+  --verbose               Enable verbose sync output
+  --delete                Delete destination files missing from source
+  --filter-file <path>    Use custom include/exclude filter file
+  -h, --help              Show this help
+EOF
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! -d "$SOURCE" ]]; then
+  echo "Source directory not found: $SOURCE" >&2
+  exit 1
+fi
+
+if ! command -v hf >/dev/null 2>&1; then
+  echo "Installing Hugging Face CLI..."
+  curl -LsSf https://hf.co/cli/install.sh | bash
+fi
+
+echo "Using HF CLI: $(command -v hf)"
+hf --version
+
+TOKEN="${HF_TOKEN:-${HUGGING_FACE_HUB_TOKEN:-${HF_HUB_TOKEN:-${HUGGINGFACEHUB_API_TOKEN:-}}}}"
+SYNC_ARGS=()
+
+if [[ -n "$TOKEN" ]]; then
+  SYNC_ARGS+=(--token "$TOKEN")
+else
+  if ! hf auth whoami >/dev/null 2>&1; then
+    echo "No valid HF authentication found." >&2
+    echo "Set HF_TOKEN (or compatible HF token env var), or run: hf auth login --force" >&2
+    exit 1
+  fi
+fi
+
+SYNC_ARGS+=(
+  --exclude ".git/**"
+  --exclude ".pytest_cache/**"
+  --exclude ".mypy_cache/**"
+  --exclude ".ruff_cache/**"
+  --exclude ".nox/**"
+  --exclude ".tox/**"
+  --exclude ".venv/**"
+  --exclude ".tools/**"
+  --exclude "__pycache__/**"
+  --exclude "*/__pycache__/**"
+  --exclude "**/__pycache__/**"
+  --exclude "*.pyc"
+  --exclude "**/*.pyc"
+  --exclude "kimodo.egg-info/**"
+  --exclude "dist/**"
+  --exclude "docs/_build/**"
+)
+
+if [[ -n "$FILTER_FILE" ]]; then
+  if [[ ! -f "$FILTER_FILE" ]]; then
+    echo "Filter file not found: $FILTER_FILE" >&2
+    exit 1
+  fi
+  SYNC_ARGS+=(--filter-from "$FILTER_FILE")
+fi
+
+if [[ "$INCLUDE_BUILD" == "false" ]]; then
+  SYNC_ARGS+=(--exclude "build/**")
+fi
+
+if [[ "$DELETE_MISSING" == "true" ]]; then
+  SYNC_ARGS+=(--delete)
+fi
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  SYNC_ARGS+=(--dry-run)
+fi
+
+if [[ "$VERBOSE" == "true" ]]; then
+  SYNC_ARGS+=(--verbose)
+fi
+
+echo "Syncing source: $SOURCE"
+echo "Syncing destination: $DEST"
+if [[ -n "$FILTER_FILE" ]]; then
+  echo "Using filter file: $FILTER_FILE"
+fi
+hf sync "$SOURCE" "$DEST" "${SYNC_ARGS[@]}"
+
+echo "Sync complete."

cloud-run/text-encoder.yaml

@@ -0,0 +1,62 @@
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: movimento-text-encoder
+  annotations:
+    run.googleapis.com/launch-stage: GA
+spec:
+  template:
+    metadata:
+      annotations:
+        autoscaling.knative.dev/minScale: "1"
+        autoscaling.knative.dev/maxScale: "1"
+        run.googleapis.com/execution-environment: gen2
+        run.googleapis.com/gpu-type: GPU_TYPE_PLACEHOLDER
+        run.googleapis.com/gpu-zonal-redundancy-disabled: "true"
+    spec:
+      containerConcurrency: 1
+      timeoutSeconds: 900
+      containers:
+        - image: REGION-docker.pkg.dev/PROJECT_ID/kimodo/kimodo:latest
+          command: ["python", "-m", "kimodo.scripts.run_text_encoder_server"]
+          ports:
+            - containerPort: 9550
+          resources:
+            limits:
+              cpu: "8"
+              memory: 24Gi
+              nvidia.com/gpu: "GPU_COUNT_PLACEHOLDER"
+          env:
+            - name: GRADIO_SERVER_NAME
+              value: "0.0.0.0"
+            - name: TEXT_ENCODER
+              value: "llm2vec"
+            - name: LOCAL_CACHE
+              value: "true"
+            - name: HF_HOME
+              value: /workspace/.cache/huggingface
+            - name: PYTHONUNBUFFERED
+              value: "1"
+            - name: HF_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HUGGING_FACE_HUB_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HF_HUB_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+            - name: HUGGINGFACEHUB_API_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: HF_TOKEN_SECRET_NAME
+                  key: latest
+  traffic:
+    - percent: 100
+      latestRevision: true

docker_requirements.in

@@ -0,0 +1,49 @@
+#
+# Human-maintained direct dependencies (top-level).
+# Use `uv` to compile this into a fully pinned `requirements.txt` lockfile.
+#
+# IMPORTANT:
+# - We intentionally do NOT list `torch` here because the Docker image base
+#   (`nvcr.io/nvidia/pytorch`) already provides it. Installing torch via pip
+#   during image build is slow and can lead to ABI/CUDA mismatches.
+# - If you are NOT using Docker, install an appropriate PyTorch build separately.
+#
+
+# Config / wiring
+hydra-core>=1.3
+omegaconf>=2.3
+
+# Core numerics
+numpy>=1.23,<2
+scipy>=1.10,<2
+
+# Model / embeddings
+# NOTE: `kimodo/model/llm2vec` is has only been tested with transformers==5.1.0
+transformers==5.1.0
+urllib3>=2.6.3
+boto3
+peft>=0.12
+einops>=0.7
+
+# Misc
+tqdm>=4.0
+packaging>=21.0
+pydantic>=2.0
+
+# UI / client
+filelock>=3.20.3
+gradio>=6.8.0
+gradio_client>=1.0
+
+# Visualization
+trimesh>=3.21.7
+scenepic>=1.1.0
+pillow>=9.0
+av>=16.1.0
+
+py-soma-x @ git+https://github.com/NVlabs/SOMA-X.git
+
+# Local packages (editable installs for viser and kimodo; MotionCorrection non-editable)
+./MotionCorrection
+-e .
+viser @ git+https://github.com/nv-tlabs/kimodo-viser.git

docker_requirements.txt

@@ -0,0 +1,377 @@
+# This file was autogenerated by uv via the following command:
+# NOTE: `torch` (and its CUDA wheels) are intentionally omitted from this lockfile.
+# The Docker base image (nvcr.io/nvidia/pytorch) already provides a tested PyTorch build.
+#
+#    uv pip compile docker_requirements.in -o docker_requirements.txt --python-version 3.10 --python-platform x86_64-manylinux2014
+-e .
+    # via -r docker_requirements.in
+viser @ git+https://github.com/nv-tlabs/kimodo-viser.git
+    # via -r docker_requirements.in
+py-soma-x @ git+https://github.com/NVlabs/SOMA-X.git
+    # via -r docker_requirements.in
+accelerate==1.13.0
+    # via peft
+aiofiles==24.1.0
+    # via gradio
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+antlr4-python3-runtime==4.9.3
+    # via
+    #   hydra-core
+    #   omegaconf
+anyio==4.12.1
+    # via
+    #   gradio
+    #   httpx
+    #   starlette
+attrs==25.4.0
+    # via
+    #   jsonschema
+    #   referencing
+av==16.1.0
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+boto3==1.42.66
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+botocore==1.42.66
+    # via
+    #   boto3
+    #   s3transfer
+brotli==1.2.0
+    # via gradio
+certifi==2026.2.25
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+charset-normalizer==3.4.5
+    # via
+    #   requests
+    #   trimesh
+click==8.3.1
+    # via
+    #   typer
+    #   uvicorn
+colorlog==6.10.1
+    # via trimesh
+einops==0.8.2
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+embreex==2.17.7.post7
+    # via trimesh
+exceptiongroup==1.3.1
+    # via anyio
+fastapi==0.135.1
+    # via gradio
+ffmpy==1.0.0
+    # via gradio
+filelock==3.25.2
+    # via
+    #   -r docker_requirements.in
+    #   huggingface-hub
+    #   kimodo
+    #   torch
+fsspec==2026.2.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+    #   torch
+gradio==6.9.0
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+gradio-client==2.3.0
+    # via
+    #   -r docker_requirements.in
+    #   gradio
+    #   kimodo
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-xet==1.4.0
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   safehttpx
+    #   trimesh
+huggingface-hub==1.6.0
+    # via
+    #   accelerate
+    #   gradio
+    #   gradio-client
+    #   peft
+    #   tokenizers
+    #   transformers
+hydra-core==1.3.2
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+imageio==2.37.3
+    # via viser
+jinja2==3.1.6
+    # via
+    #   gradio
+    #   torch
+jmespath==1.1.0
+    # via
+    #   boto3
+    #   botocore
+jsonschema==4.26.0
+    # via trimesh
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+lxml==6.0.2
+    # via
+    #   trimesh
+    #   yourdfpy
+manifold3d==3.4.0
+    # via trimesh
+mapbox-earcut==2.0.0
+    # via trimesh
+markdown-it-py==4.0.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+mdurl==0.1.2
+    # via markdown-it-py
+./MotionCorrection
+    # via -r docker_requirements.in
+msgspec==0.20.0
+    # via viser
+nodeenv==1.10.0
+    # via viser
+numpy==1.26.4
+    # via
+    #   -r docker_requirements.in
+    #   accelerate
+    #   embreex
+    #   gradio
+    #   imageio
+    #   kimodo
+    #   manifold3d
+    #   mapbox-earcut
+    #   motion-correction
+    #   pandas
+    #   peft
+    #   pycollada
+    #   scenepic
+    #   scipy
+    #   shapely
+    #   transformers
+    #   trimesh
+    #   vhacdx
+    #   viser
+    #   yourdfpy
+omegaconf==2.3.0
+    # via
+    #   -r docker_requirements.in
+    #   hydra-core
+    #   kimodo
+orjson==3.11.7
+    # via gradio
+packaging==26.0
+    # via
+    #   -r docker_requirements.in
+    #   accelerate
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   hydra-core
+    #   kimodo
+    #   peft
+    #   transformers
+pandas==2.3.3
+    # via gradio
+peft==0.18.1
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+pillow==12.1.1
+    # via
+    #   -r docker_requirements.in
+    #   gradio
+    #   imageio
+    #   kimodo
+    #   scenepic
+    #   trimesh
+psutil==7.2.2
+    # via
+    #   accelerate
+    #   peft
+pycollada==0.9.3
+    # via trimesh
+pydantic==2.12.5
+    # via
+    #   -r docker_requirements.in
+    #   fastapi
+    #   gradio
+    #   kimodo
+pydantic-core==2.41.5
+    # via pydantic
+pydub==0.25.1
+    # via gradio
+pygments==2.19.2
+    # via rich
+python-dateutil==2.9.0.post0
+    # via
+    #   botocore
+    #   pandas
+    #   pycollada
+python-multipart==0.0.22
+    # via gradio
+pytz==2026.1.post1
+    # via
+    #   gradio
+    #   pandas
+pyyaml==6.0.3
+    # via
+    #   accelerate
+    #   gradio
+    #   huggingface-hub
+    #   omegaconf
+    #   peft
+    #   transformers
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+regex==2026.2.28
+    # via transformers
+requests==2.32.5
+    # via viser
+rich==14.3.3
+    # via
+    #   typer
+    #   viser
+rpds-py==0.30.0
+    # via
+    #   jsonschema
+    #   referencing
+rtree==1.4.1
+    # via trimesh
+s3transfer==0.16.0
+    # via boto3
+safehttpx==0.1.7
+    # via gradio
+safetensors==0.7.0
+    # via
+    #   accelerate
+    #   peft
+    #   transformers
+scenepic==1.1.2
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+scipy==1.15.3
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+    #   scenepic
+    #   trimesh
+semantic-version==2.10.0
+    # via gradio
+shapely==2.1.2
+    # via trimesh
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via
+    #   python-dateutil
+    #   yourdfpy
+starlette==0.52.1
+    # via
+    #   fastapi
+    #   gradio
+svg-path==7.0
+    # via trimesh
+tokenizers==0.22.2
+    # via transformers
+tomlkit==0.13.3
+    # via gradio
+tqdm==4.67.3
+    # via
+    #   -r docker_requirements.in
+    #   huggingface-hub
+    #   kimodo
+    #   peft
+    #   transformers
+    #   viser
+transformers==5.1.0
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+    #   peft
+trimesh==4.11.3
+    # via
+    #   -r docker_requirements.in
+    #   kimodo
+    #   viser
+    #   yourdfpy
+typer==0.24.1
+    # via
+    #   gradio
+    #   huggingface-hub
+    #   typer-slim
+typer-slim==0.24.0
+    # via transformers
+typing-extensions==4.15.0
+    # via
+    #   anyio
+    #   exceptiongroup
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   pydantic
+    #   pydantic-core
+    #   referencing
+    #   starlette
+    #   torch
+    #   typing-inspection
+    #   uvicorn
+    #   viser
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+tzdata==2025.3
+    # via pandas
+urllib3==2.6.3
+    # via
+    #   -r docker_requirements.in
+    #   botocore
+    #   kimodo
+    #   requests
+uvicorn==0.41.0
+    # via gradio
+vhacdx==0.0.10
+    # via trimesh
+websockets==15.0.1
+    # via viser
+xxhash==3.6.0
+    # via trimesh
+yourdfpy==0.0.60
+    # via viser

kimodo/demo/app.py

@@ -61,8 +61,17 @@ class Demo:
         if resolved not in MODEL_NAMES:
             raise ValueError(f"Unknown model '{default_model_name}'. Expected one of: {MODEL_NAMES}")
         self.default_model_name = resolved
+        self.defer_model_load = os.getenv("KIMODO_DEFER_MODEL_LOAD", "true").strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
         self.ensure_examples_layout()
-        self.load_model(self.default_model_name)
+        if self.defer_model_load:
+            print("Deferring model load until first active client session.")
+        else:
+            self.load_model(self.default_model_name)
 
         # Serialize GPU-bound generation across all clients
         self._generation_lock = threading.Lock()