motionmcp-sdk 0.1.0__py3-none-any.whl

motionmcp/__init__.py

@@ -0,0 +1,76 @@
+"""motionmcp — Python SDK for the Motion Model Context Protocol (MMCP).
+
+Build a vendor-neutral motion-generation HTTP server in ~30 lines:
+
+    from motionmcp import Backbone, ModelSpec, GenerateRequest, MotionResult, serve
+
+    class MyBackbone(Backbone):
+        def capabilities(self) -> ModelSpec:
+            return ModelSpec(
+                id="my-model",
+                fps=30.0,
+                supports_retargeting=False,
+                supported_constraints=["pose_keyframe"],
+                canonical_skeleton=load_skeleton(),
+            )
+
+        async def generate(self, req: GenerateRequest) -> MotionResult:
+            ...
+            return MotionResult(rotations=..., root_translations=...)
+
+    if __name__ == "__main__":
+        serve(MyBackbone())
+"""
+
+from .backbone import Backbone, ModelSpec, MotionResult
+from .errors import ProtocolError
+from .protocol import (
+    PROTOCOL_VERSION,
+    SUPPORTED_CONSTRAINTS,
+    SUPPORTED_GUIDANCE_TYPES,
+    DEFAULT_LIMITS,
+)
+from .schemas import (
+    Constraint,
+    EffectorTargetConstraint,
+    GenerateRequest,
+    Guidance,
+    Joint,
+    Options,
+    PoseKeyframeConstraint,
+    RootPathConstraint,
+    Segment,
+    Skeleton,
+    TextSegment,
+    Timing,
+    UnconditionedSegment,
+)
+from .server import build_app, serve
+
+__all__ = [
+    "Backbone",
+    "Constraint",
+    "DEFAULT_LIMITS",
+    "EffectorTargetConstraint",
+    "GenerateRequest",
+    "Guidance",
+    "Joint",
+    "ModelSpec",
+    "MotionResult",
+    "Options",
+    "PROTOCOL_VERSION",
+    "PoseKeyframeConstraint",
+    "ProtocolError",
+    "RootPathConstraint",
+    "SUPPORTED_CONSTRAINTS",
+    "SUPPORTED_GUIDANCE_TYPES",
+    "Segment",
+    "Skeleton",
+    "TextSegment",
+    "Timing",
+    "UnconditionedSegment",
+    "build_app",
+    "serve",
+]
+
+__version__ = "0.1.0"

motionmcp/backbone.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Backbone abstraction — what users implement to plug their model into MMCP.
+
+Two pieces:
+
+* :class:`ModelSpec` — the per-model metadata served at ``GET /capabilities``.
+* :class:`Backbone` — the ABC users subclass; defines :meth:`Backbone.capabilities`
+  and :meth:`Backbone.generate`.
+
+A :class:`MotionResult` is what :meth:`Backbone.generate` returns: per-sample
+quaternion rotations, root translations, and optional foot-contact masks. The
+SDK encodes this to glTF for you.
+"""
+
+from __future__ import annotations
+
+import abc
+import inspect
+from dataclasses import dataclass, field
+from typing import Awaitable, Sequence
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict, Field
+
+from .protocol import (
+    DEFAULT_LIMITS,
+    SUPPORTED_GUIDANCE_TYPES,
+)
+from .schemas import GenerateRequest, Skeleton
+
+
+# ---- ModelSpec — published at /capabilities --------------------------------
+
+class Limits(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    max_duration_seconds: float = float(DEFAULT_LIMITS["max_duration_seconds"])
+    max_num_samples: int = int(DEFAULT_LIMITS["max_num_samples"])
+    max_constraints_per_request: int = int(DEFAULT_LIMITS["max_constraints_per_request"])
+    max_prompt_length: int = int(DEFAULT_LIMITS["max_prompt_length"])
+    max_request_bytes: int = int(DEFAULT_LIMITS["max_request_bytes"])
+
+
+class ModelSpec(BaseModel):
+    """Per-model entry under ``/capabilities.models[]``.
+
+    All fields except ``id``, ``fps``, and ``canonical_skeleton`` have spec
+    defaults — you only have to fill in what differs from the conservative
+    baseline.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(..., min_length=1)
+    fps: float = Field(..., gt=0)
+    canonical_skeleton: Skeleton
+
+    supports_retargeting: bool = False
+    supports_async: bool = False
+
+    supported_constraints: list[str] = Field(default_factory=list)
+    supported_guidance_types: list[str] = Field(
+        default_factory=lambda: list(SUPPORTED_GUIDANCE_TYPES)
+    )
+    predicted_contact_joints: list[str] = Field(default_factory=list)
+
+    native_clip_seconds: float = 10.0
+    chunking: str = Field("none", pattern=r"^(none|stitched)$")
+    recommended_max_duration_seconds: float = 12.0
+
+    limits: Limits = Field(default_factory=Limits)
+
+
+# ---- MotionResult — what generate() returns --------------------------------
+
+@dataclass
+class MotionResult:
+    """The output of :meth:`Backbone.generate`.
+
+    Shape conventions (B = num_samples, T = num_frames, J = num_joints):
+
+    * ``rotations``: ``(B, T, J, 4)`` quaternions ``(x, y, z, w)``, local-to-parent.
+    * ``root_translations``: ``(B, T, 3)`` world-space root positions.
+    * ``joint_names``: optional ``(J,)`` list. Defaults to the request skeleton's
+      joint order. Provide this only if your model retargeted internally and
+      you need to declare a different output order — the SDK will validate
+      that ``joint_names`` matches the request skeleton (or your declared
+      ``canonical_to_request`` map).
+    * ``foot_contacts``: optional ``{joint_name: (B, T) bool array}``. Joint
+      names must exist in the request skeleton.
+    * ``chunk_boundaries``: optional per-sample list of frame indices where
+      the server stitched internal chunks. Empty / None means no stitching.
+    * ``canonical_to_request``: optional ``{canonical_joint: request_joint}``
+      map echoed in the response extension. Only populate when the server
+      actually retargeted.
+    """
+
+    rotations: np.ndarray
+    root_translations: np.ndarray
+    joint_names: Sequence[str] | None = None
+    foot_contacts: dict[str, np.ndarray] = field(default_factory=dict)
+    chunk_boundaries: Sequence[Sequence[int]] | None = None
+    canonical_to_request: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        r = self.rotations
+        if r.ndim != 4 or r.shape[-1] != 4:
+            raise ValueError(
+                f"rotations must be (B, T, J, 4); got {r.shape}"
+            )
+        B, T, J, _ = r.shape
+        t = self.root_translations
+        if t.shape != (B, T, 3):
+            raise ValueError(
+                f"root_translations must be ({B}, {T}, 3); got {t.shape}"
+            )
+        for joint, mask in self.foot_contacts.items():
+            if mask.shape != (B, T):
+                raise ValueError(
+                    f"foot_contacts[{joint!r}] must be ({B}, {T}); "
+                    f"got {mask.shape}"
+                )
+
+    @property
+    def num_samples(self) -> int:
+        return int(self.rotations.shape[0])
+
+    @property
+    def num_frames(self) -> int:
+        return int(self.rotations.shape[1])
+
+    @property
+    def num_joints(self) -> int:
+        return int(self.rotations.shape[2])
+
+
+# ---- Backbone ABC ----------------------------------------------------------
+
+class Backbone(abc.ABC):
+    """The contract a user implements to plug their motion model into MMCP.
+
+    Subclasses MUST implement:
+
+    * :meth:`capabilities` — returns a :class:`ModelSpec` describing the model.
+    * :meth:`generate` — runs the model on a validated :class:`GenerateRequest`
+      and returns a :class:`MotionResult`.
+
+    :meth:`generate` may be ``async def`` or a regular function — the SDK
+    handles both. Async is preferred when the underlying model has any I/O or
+    benefits from yielding (queueing on a GPU worker, awaiting a remote call).
+
+    Raise :class:`~motionmcp.errors.ProtocolError` (or one of its convenience
+    constructors in :mod:`motionmcp.errors`) for protocol-level failures —
+    the SDK converts them to the standard error envelope. Any other exception
+    becomes a generic ``500 internal_error``.
+    """
+
+    @abc.abstractmethod
+    def capabilities(self) -> ModelSpec:
+        """Return the per-model entry that goes under ``/capabilities.models[]``."""
+
+    @abc.abstractmethod
+    def generate(self, request: GenerateRequest) -> MotionResult | Awaitable[MotionResult]:
+        """Run motion generation for one validated request.
+
+        May be implemented as either ``def`` or ``async def``.
+        """
+
+    # Optional hook: called once at server startup. Use it to load model
+    # weights, allocate GPU buffers, warm caches.
+    def setup(self) -> None:  # pragma: no cover - default no-op
+        return
+
+    # Optional hook: called once at server shutdown.
+    def teardown(self) -> None:  # pragma: no cover - default no-op
+        return
+
+
+def is_async_generate(backbone: Backbone) -> bool:
+    """Return True if the backbone's ``generate`` is an async coroutine function."""
+    return inspect.iscoroutinefunction(backbone.generate)

motionmcp/errors.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MMCP error envelope and protocol-level exceptions.
+
+The wire format is a single shape::
+
+    {"error": {"code": "...", "message": "...", "details": {...}}}
+
+Backbone code raises :class:`ProtocolError` (or one of the typed subclasses)
+to signal a failure; the SDK's FastAPI layer maps it to the right HTTP status
+via :data:`STATUS_FOR` and serialises the envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+# Code → HTTP status. The set is closed at v1.0; new codes go in minor versions.
+STATUS_FOR: dict[str, int] = {
+    "schema_validation":           422,
+    "unknown_model":               400,
+    "retargeting_unsupported":     400,
+    "unsupported_constraint":      400,
+    "unknown_joint":               400,
+    "invalid_skeleton":            400,
+    "frame_out_of_range":          400,
+    "invalid_options":             400,
+    "version_unsupported":         400,
+    "unauthorized":                401,
+    "forbidden":                   403,
+    "payload_too_large":           413,
+    "rate_limited":                429,
+    "internal_error":              500,
+    "resource_exhausted":          503,
+    "model_unavailable":           503,
+    "timeout":                     504,
+}
+
+
+class ProtocolError(Exception):
+    """Raised by handlers to signal a protocol-level failure.
+
+    The FastAPI app catches this and serialises it to the MMCP error envelope.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ):
+        if code not in STATUS_FOR:
+            raise ValueError(f"unknown protocol error code: {code!r}")
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    @property
+    def status_code(self) -> int:
+        return STATUS_FOR[self.code]
+
+    def to_envelope(self) -> dict[str, Any]:
+        return {
+            "error": {
+                "code": self.code,
+                "message": self.message,
+                "details": self.details,
+            }
+        }
+
+
+# ---- Convenience constructors for common cases ---------------------------
+
+def unknown_model(model_id: str, available: list[str]) -> ProtocolError:
+    return ProtocolError(
+        "unknown_model",
+        f"model {model_id!r} is not registered with this server",
+        details={"available_models": available},
+    )
+
+
+def unsupported_constraint(
+    constraint_type: str, supported: list[str]
+) -> ProtocolError:
+    return ProtocolError(
+        "unsupported_constraint",
+        f"constraint type {constraint_type!r} is not supported by this model",
+        details={"supported_constraints": supported},
+    )
+
+
+def unknown_joint(joint: str, skeleton_joints: list[str]) -> ProtocolError:
+    return ProtocolError(
+        "unknown_joint",
+        f"joint {joint!r} is not in the request skeleton",
+        details={"skeleton_joints": skeleton_joints},
+    )
+
+
+def frame_out_of_range(frame: int, total_frames: int) -> ProtocolError:
+    return ProtocolError(
+        "frame_out_of_range",
+        f"frame {frame} is outside [0, {total_frames - 1}]",
+        details={"frame": frame, "total_frames": total_frames},
+    )
+
+
+def retargeting_unsupported() -> ProtocolError:
+    return ProtocolError(
+        "retargeting_unsupported",
+        "this model does not support retargeting; send the canonical "
+        "skeleton verbatim from /capabilities",
+    )
+
+
+def version_unsupported(requested: str, supported_majors: list[str]) -> ProtocolError:
+    return ProtocolError(
+        "version_unsupported",
+        f"protocol_version {requested!r} is not supported by this server",
+        details={"supported_majors": supported_majors},
+    )