motion-intelligence 0.2.0

Author, build & deploy Python models for the Motion inference platform

motion-cli (Python)

Build and deploy Docker images for models on the Motion inference platform.

pip install -e /path/to/cli-py    # gives the `motion` command
export MOTION_API_KEY=motion_live_<your_key>

Quick start

A model is a folder with motion.yml + predict.py:

# predict.py
from motion import BasePredictor, Input, Path

class MyPredictor(BasePredictor):
    def setup(self):
        self.model = load_model(...)

    def predict(self, video: Path = Input(description="Input clip")) -> Path:
        out = "/tmp/out.mp4"
        self.model.run(video, out)
        return Path(out)

# motion.yml
name: lingbot-map
predict: predict.py:MyPredictor
description: Streaming 3D reconstruction

# Where the model appears in GET /api/v1/motion/models
category: reconstruction          # required for catalog listing
inference_model: lingbot-map      # optional; defaults to `name`
input_type: video                 # video | image | text
output_type: mp4

# Used by `motion deploy` to measure CPU/RAM via docker stats
sample: demo_files/input.mp4

build:
  gpu: true
  cuda: "11.8"
  python_version: "3.11"
  system_packages: [ffmpeg]
  python_packages: ["torch>=2.4.0"]

# Optional — overrides auto-profiling
compute:
  cpu: 4
  memory_mib: 16384
  gpu: true

weights:
  - path: weights/model.pt
    url: https://example.com/model.pt
    dest: weights/model.pt

Commands

motion build

Uploads local weights to S3 (via MOTION_API_KEY, no AWS creds on your machine), generates .motion/Dockerfile, and builds motion-<name>:latest.

motion build .                  # build image
motion build . --dry-run        # print Dockerfile only
motion build . --tag myimg:dev  # custom tag

Requires: MOTION_API_KEY when weights: has local files to upload.

Large weights (≥64 MiB) use multipart S3 upload automatically.

motion deploy

Profiles the local image, pushes to ECR, and registers the model in the platform.

motion deploy .
motion deploy . --no-profile              # skip docker stats measurement
motion deploy . --sample tests/clip.mp4   # override profiling input
motion deploy . --profile-timeout 300     # longer profiling window

Flow:

1. Parse motion.yml (including category, sample, compute)
2. Profile — run the container locally, poll docker stats, derive cpu_vcpus + memory_mib
   • Skipped if compute: is set in motion.yml (compute_source=declared)
   • Skipped with --no-profile
   • Skipped if no sample file is found
3. Push image to ECR (backend issues a short-lived docker login token)
4. Register — POST /api/v1/motion/models/register with:
   • model_code = <namespace>/<name> (e.g. saurav/lingbot-map)
   • category_code, inference_model_slug, compute profile, predict params

Requires: MOTION_API_KEY, local image from motion build.

Category codes: list with GET /api/v1/motion/models — e.g. reconstruction, hand-tracking, mesh, 3d-object.

After deploy, submit jobs with:

POST /api/v1/motion/submit   model_name=<namespace>/<name>

Environment

Variable	Purpose
MOTION_API_KEY	Auth for build (weight upload) and deploy (ECR + register)
MOTION_API_URL	Backend base URL (default: Motion App Runner prod)

Image contract

Every built image exposes: GET /health, GET /schema, POST /predict.

Weights declared in motion.yml are fetched from S3 at container startup — not baked into the image.