initial: Gradio API server (Kimodo-SOMA-RP-v1.1) + constraints schema

Dockerfile

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Forked from nvidia/Kimodo. We replace the Viser entrypoint (kimodo_demo)
+# with a thin Gradio API server (server.py) that exposes /gradio_api/call/kimodo_motion
+# for the GengaMachines webapp.
+
+FROM nvcr.io/nvidia/pytorch:24.10-py3
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/data/.huggingface \
+    XDG_CACHE_HOME=/data/.cache \
+    PIP_CACHE_DIR=/data/.cache/pip
+
+WORKDIR /workspace
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates \
+      cmake build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN rm -f /usr/local/bin/cmake || true
+
+COPY requirements.txt /workspace/requirements.txt
+ARG GITHUB_TOKEN=
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    --mount=type=secret,id=GITHUB_TOKEN,mode=0444,required=false \
+    python -m pip install --upgrade pip \
+ && python -m pip install -r requirements.txt;
+
+# Our custom files: replace the Viser demo with a Gradio API.
+COPY server.py /workspace/server.py
+COPY constraints_schema.py /workspace/constraints_schema.py
+COPY start.sh /start.sh
+RUN chmod +x /start.sh
+
+EXPOSE 7860
+ENTRYPOINT ["/start.sh"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,10 +1,60 @@
 ---
 title: Genga Kimodo
-emoji: 📉
+emoji: 🐉
 colorFrom: yellow
-colorTo: green
+colorTo: pink
 sdk: docker
+app_port: 7860
 pinned: false
+license: apache-2.0
+short_description: API-only Kimodo motion backend for GengaMachines.
+models:
+- nvidia/Kimodo-SOMA-RP-v1
+- nvidia/Kimodo-SOMA-RP-v1.1
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Genga × Kimodo
+
+API-only Hugging Face Space backing the GengaMachines webapp's `/motion`
+flow. Wraps NVIDIA Kimodo-SOMA-RP-v1.1 with a thin Gradio API.
+
+The official interactive Kimodo demo (Viser) lives at
+[nvidia/Kimodo](https://huggingface.co/spaces/nvidia/Kimodo). This Space is
+deliberately **not** that — we expose `/gradio_api/call/kimodo_motion` so the
+webapp can submit prompts + constraints and receive structured motion JSON.
+
+## API
+
+```
+POST /gradio_api/call/kimodo_motion
+Content-Type: application/json
+Authorization: Bearer ${HF_TOKEN}
+
+{ "data": [prompt, num_frames, seed, cfg, num_steps, constraints_json] }
+```
+
+Then poll `/gradio_api/call/kimodo_motion/<event_id>` for the SSE stream
+(complete / error / heartbeat events).
+
+Result envelope:
+
+```json
+{
+  "status": "ok",
+  "numFrames": 90,
+  "fps": 30,
+  "rootTranslation": [[x, y, z], ...],
+  "jointRotMats":    [[ [[..3..]], ...30 ], ...90 ],
+  "footContacts":    [[lh, lt, rh, rt], ...] | null,
+  "summary": "..."
+}
+```
+
+`jointRotMats` is row-major `[N, 30, 3, 3]` — local-space SOMA joint rotations.
+The webapp converts to quaternions in `SomaCharacterMesh.tsx`.
+
+## Constraints
+
+`constraints_json` is a JSON-stringified list. See `constraints_schema.py`.
+Coordinates: Y-up, meters, character-local. Supported types: `root2d`,
+`fullbody`, `left-hand`, `right-hand`, `left-foot`, `right-foot`, `end-effector`.

constraints_schema.py

@@ -0,0 +1,110 @@
+"""Pydantic schema for the Kimodo constraint payload accepted by server.py.
+
+Mirrors the JSON shape produced by the NVIDIA authoring demo so we can fall
+back on the official kimodo.constraints classes for inference. The webapp
+sends a JSON-stringified list of these objects in the Gradio `constraints_json`
+arg.
+
+Coordinates: Y-up, meters, character-local. Frame indices are 0-based within
+the generated clip. The root is canonicalized to the XZ origin at frame 0.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional, Tuple, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+Vec2 = Tuple[float, float]
+Vec3 = Tuple[float, float, float]
+
+
+class Root2DConstraint(BaseModel):
+    type: Literal["root2d"]
+    frame_indices: List[int]
+    smooth_root_2d: List[Vec2]
+    global_root_heading: Optional[List[Vec2]] = None
+
+    @field_validator("frame_indices")
+    @classmethod
+    def _frames_match_length(cls, v, info):
+        # We can only sanity-check inside this constraint; cross-list checks
+        # happen in server.py once num_frames is known.
+        if not v:
+            raise ValueError("root2d constraint must have at least one frame_index")
+        return v
+
+
+class FullBodyConstraint(BaseModel):
+    type: Literal["fullbody"]
+    frame_indices: List[int]
+    root_positions: List[Vec3]
+    local_joints_rot: List[List[Vec3]]
+    smooth_root_2d: Optional[List[Vec2]] = None
+
+
+class EndEffectorConstraint(BaseModel):
+    type: Literal[
+        "left-hand",
+        "right-hand",
+        "left-foot",
+        "right-foot",
+        "end-effector",
+    ]
+    frame_indices: List[int]
+    root_positions: List[Vec3]
+    local_joints_rot: List[List[Vec3]]
+    smooth_root_2d: Optional[List[Vec2]] = None
+    joint_names: Optional[List[str]] = None  # required when type == "end-effector"
+
+    @field_validator("joint_names")
+    @classmethod
+    def _names_required_for_custom(cls, v, info):
+        if info.data.get("type") == "end-effector" and not v:
+            raise ValueError(
+                "type='end-effector' requires `joint_names`; use a typed variant "
+                "(left-hand, right-hand, left-foot, right-foot) otherwise."
+            )
+        return v
+
+
+KimodoConstraint = Union[Root2DConstraint, FullBodyConstraint, EndEffectorConstraint]
+
+
+def parse_constraints(payload: List[dict], num_frames: int) -> List[KimodoConstraint]:
+    """Validate the JSON payload from the webapp and bound-check frame indices.
+
+    Returns a list of typed Pydantic objects ready to feed kimodo's sampler.
+    Raises ValueError on the first violation; the caller surfaces the error to
+    the SSE stream so the webapp toast renders it.
+    """
+    if not isinstance(payload, list):
+        raise ValueError("constraints must be a JSON list")
+    out: List[KimodoConstraint] = []
+    for i, raw in enumerate(payload):
+        if not isinstance(raw, dict) or "type" not in raw:
+            raise ValueError(f"constraints[{i}]: must be a dict with a 'type' field")
+        t = raw["type"]
+        cls = {
+            "root2d": Root2DConstraint,
+            "fullbody": FullBodyConstraint,
+            "left-hand": EndEffectorConstraint,
+            "right-hand": EndEffectorConstraint,
+            "left-foot": EndEffectorConstraint,
+            "right-foot": EndEffectorConstraint,
+            "end-effector": EndEffectorConstraint,
+        }.get(t)
+        if cls is None:
+            raise ValueError(f"constraints[{i}]: unknown type '{t}'")
+        try:
+            obj = cls(**raw)
+        except Exception as e:
+            raise ValueError(f"constraints[{i}] ({t}): {e}") from e
+        for f in obj.frame_indices:
+            if f < 0 or f >= num_frames:
+                raise ValueError(
+                    f"constraints[{i}] ({t}): frame_index {f} is out of range "
+                    f"[0, {num_frames - 1}]"
+                )
+        out.append(obj)
+    return out

requirements.txt

@@ -0,0 +1,375 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# 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
+kimodo @ git+https://github.com/nv-tlabs/kimodo.git
+viser @ git+https://github.com/nv-tlabs/kimodo-viser.git
+py-soma-x @ git+https://github.com/NVlabs/SOMA-X.git
+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
+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

server.py

@@ -0,0 +1,225 @@
+"""Gradio API replacing kimodo_demo's Viser entrypoint.
+
+Exposes a single endpoint at `/gradio_api/call/kimodo_motion` that accepts:
+    (prompt, num_frames, seed, cfg, num_steps, constraints_json)
+
+and returns a JSON envelope:
+    {
+      "status": "ok",
+      "numFrames": int,
+      "fps": 30,
+      "rootTranslation": [[x,y,z], ...],     # [N, 3]
+      "jointRotMats":    [[[[...]]]],        # [N, 30, 3, 3]
+      "footContacts":    [[lh, lt, rh, rt]], # [N, 4]  (optional)
+      "summary": str
+    }
+
+The webapp's src/lib/services/kimodo.ts polls
+`/gradio_api/call/kimodo_motion/<event_id>` for the SSE event stream.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import traceback
+
+import gradio as gr
+import numpy as np
+import torch
+
+from constraints_schema import parse_constraints
+
+# Lazy imports of kimodo so import-time failures (e.g. missing CUDA on the
+# Space build container) don't kill `python server.py --help`.
+_model = None
+_skeleton = None
+_device = None
+
+
+def _load_model():
+    global _model, _skeleton, _device
+    if _model is not None:
+        return _model, _skeleton, _device
+    print("[server] loading Kimodo-SOMA-RP-v1.1 ...", file=sys.stderr, flush=True)
+    from kimodo import load_model
+
+    _device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    print(f"[server] device = {_device}", file=sys.stderr, flush=True)
+
+    model, resolved = load_model(
+        "Kimodo-SOMA-RP-v1.1",
+        device=_device,
+        default_family="Kimodo",
+        return_resolved_name=True,
+    )
+    print(f"[server] resolved model = {resolved}", file=sys.stderr, flush=True)
+    _model = model
+    _skeleton = model.skeleton
+    return _model, _skeleton, _device
+
+
+def kimodo_motion(
+    prompt: str,
+    num_frames: int,
+    seed: int,
+    cfg: float,
+    num_steps: int,
+    constraints_json: str,
+    progress: gr.Progress = gr.Progress(),  # noqa: B008 — Gradio convention
+) -> dict:
+    """Generate one SOMA motion sample. Heavy work runs on the GPU; constraint
+    parsing on the CPU. Returns the JSON envelope the webapp expects."""
+    try:
+        if not prompt or not prompt.strip():
+            return {"status": "error", "error": "prompt is empty"}
+        n = int(num_frames)
+        if n < 1 or n > 300:
+            return {
+                "status": "error",
+                "error": f"num_frames must be in [1, 300]; got {n}",
+            }
+
+        # Validate the constraints payload up front so a bad request doesn't
+        # waste GPU time. We accept the same JSON the kimodo CLI accepts —
+        # extra cross-list validation in constraints_schema bounds-checks frame
+        # indices against num_frames.
+        try:
+            raw = json.loads(constraints_json) if constraints_json else []
+            parse_constraints(raw, n)  # validates shape + bounds
+        except (ValueError, json.JSONDecodeError) as e:
+            return {"status": "error", "error": f"constraint validation: {e}"}
+
+        progress(0.02, desc="Loading model...")
+        model, skeleton, device = _load_model()
+
+        # Convert the JSON list of dicts into kimodo constraint objects via
+        # the official loader — accepts a list-of-dicts directly.
+        from kimodo.constraints import load_constraints_lst
+
+        constraint_lst = load_constraints_lst(raw, skeleton, device=device)
+
+        if seed is not None and int(seed) >= 0:
+            from kimodo.tools import seed_everything
+
+            seed_everything(int(seed))
+
+        progress(0.10, desc=f"Diffusion ({int(num_steps)} steps)...")
+        cfg_kwargs = {"cfg_type": "regular", "cfg_weight": float(cfg)}
+        # Single sample, single prompt. If you want multi-prompt later, this is
+        # where you'd thread it through.
+        output = model(
+            [prompt.strip()],
+            [n],
+            constraint_lst=constraint_lst,
+            num_denoising_steps=int(num_steps),
+            num_samples=1,
+            multi_prompt=True,
+            num_transition_frames=20,
+            return_numpy=True,
+            **cfg_kwargs,
+        )
+
+        progress(0.92, desc="Serializing...")
+
+        # Output keys we know exist (per generate.py): posed_joints, global_rot_mats.
+        # Shapes: posed_joints [n_samples, T, J, 3], global_rot_mats [n_samples, T, J, 3, 3].
+        if "posed_joints" not in output or "global_rot_mats" not in output:
+            return {
+                "status": "error",
+                "error": f"unexpected model output keys: {list(output.keys())}",
+            }
+        posed_joints = output["posed_joints"]
+        global_rot_mats = output["global_rot_mats"]
+        if posed_joints.ndim != 4 or global_rot_mats.ndim != 5:
+            return {
+                "status": "error",
+                "error": (
+                    f"unexpected shapes: posed_joints={posed_joints.shape}, "
+                    f"global_rot_mats={global_rot_mats.shape}"
+                ),
+            }
+
+        # Convert global rotation matrices → local (parent-relative) so the
+        # client can apply per-bone rotations directly without doing inverse
+        # FK in the browser.
+        from kimodo.skeleton import global_rots_to_local_rots
+
+        joints_pos_t = torch.from_numpy(posed_joints[0]).to(device)
+        joints_rot_t = torch.from_numpy(global_rot_mats[0]).to(device)
+        local_rot_mats_t = global_rots_to_local_rots(joints_rot_t, skeleton)
+        local_rot_mats = local_rot_mats_t.detach().cpu().numpy().astype(np.float32)
+
+        # Root translation = posed_joints at the root joint index.
+        root_idx = int(getattr(skeleton, "root_idx", 0))
+        root_translation = (
+            joints_pos_t[:, root_idx, :].detach().cpu().numpy().astype(np.float32)
+        )
+
+        # Spot-check the SOMA shape: 30 joints expected for SOMA-RP-v1.1.
+        T, J = local_rot_mats.shape[0], local_rot_mats.shape[1]
+        if (T, J) != (n, 30):
+            return {
+                "status": "error",
+                "error": (
+                    f"expected ({n}, 30, 3, 3) for local_rot_mats, got "
+                    f"{local_rot_mats.shape}"
+                ),
+            }
+
+        # Optional foot_contacts if the model emitted them.
+        foot_contacts_out = None
+        if "foot_contacts" in output:
+            fc = output["foot_contacts"]
+            # Drop the leading sample dim if present
+            if fc.ndim == 3:
+                fc = fc[0]
+            foot_contacts_out = np.asarray(fc, dtype=np.float32).tolist()
+
+        progress(1.0, desc="Done")
+        return {
+            "status": "ok",
+            "numFrames": int(T),
+            "fps": int(getattr(model, "fps", 30)),
+            "rootTranslation": root_translation.tolist(),
+            "jointRotMats": local_rot_mats.tolist(),
+            "footContacts": foot_contacts_out,
+            "summary": prompt.strip(),
+        }
+    except Exception as e:
+        traceback.print_exc()
+        return {"status": "error", "error": f"{type(e).__name__}: {e}"}
+
+
+with gr.Blocks(title="Genga Kimodo") as demo:
+    gr.Markdown(
+        "# Genga × Kimodo\n"
+        "API-only Space. Inference endpoint at `/gradio_api/call/kimodo_motion`.\n\n"
+        "This Space backs the GengaMachines webapp and is not a public sandbox. "
+        "For the official interactive Kimodo demo, see "
+        "[nvidia/Kimodo](https://huggingface.co/spaces/nvidia/Kimodo)."
+    )
+    in_prompt = gr.Textbox(label="Prompt", value="A person waves hello with their right hand.")
+    in_frames = gr.Slider(30, 300, value=90, step=6, label="num_frames (30 fps)")
+    in_seed = gr.Number(value=42, label="seed (use -1 to skip seeding)", precision=0)
+    in_cfg = gr.Slider(1.0, 10.0, value=5.0, step=0.5, label="cfg_weight")
+    in_steps = gr.Slider(10, 50, value=30, step=1, label="num_denoising_steps")
+    in_constraints = gr.Textbox(label="constraints_json", value="[]", lines=4)
+    btn = gr.Button("Generate")
+    out = gr.JSON(label="result")
+
+    btn.click(
+        fn=kimodo_motion,
+        inputs=[in_prompt, in_frames, in_seed, in_cfg, in_steps, in_constraints],
+        outputs=out,
+        api_name="kimodo_motion",
+    )
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=4).launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+        show_api=True,
+    )

start.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+# Forked: replaces the upstream `kimodo_demo` Viser launch with a Gradio API
+# (server.py) used programmatically by the GengaMachines webapp.
+set -euo pipefail
+
+cd /workspace
+
+# pre-download checkpoints. We use SOMA-RP-v1.1 (per the integration plan); v1
+# is downloaded too for parity with upstream.
+python - <<'PY'
+from huggingface_hub import snapshot_download
+for repo in ("nvidia/Kimodo-SOMA-RP-v1", "nvidia/Kimodo-SOMA-RP-v1.1"):
+    print(f"snapshot_download({repo}) ...")
+    snapshot_download(repo)
+print("Checkpoint download complete.")
+PY
+
+# launch text encoder (internal-only, port 9550)
+echo "Starting text-encoder on :9550 ..."
+kimodo_textencoder &
+TEXT_ENCODER_PID=$!
+
+cleanup() {
+  echo "Shutting down text-encoder (pid=${TEXT_ENCODER_PID}) ..."
+  kill "${TEXT_ENCODER_PID}" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+# wait for the text encoder to be healthy
+echo "Waiting for text-encoder health ..."
+for i in $(seq 1 1200); do
+  if curl -fsS "http://127.0.0.1:9550/" >/dev/null 2>&1; then
+    echo "Text-encoder is up."
+    break
+  fi
+  sleep 1
+  if [[ $i -eq 1200 ]]; then
+    echo "ERROR: text-encoder did not become healthy on http://127.0.0.1:9550/ within 1200s" >&2
+    exit 1
+  fi
+done
+
+# launch our Gradio API in place of kimodo_demo
+echo "Starting Gradio API on :7860 ..."
+exec python -u /workspace/server.py