motion-intelligence 0.2.0__py3-none-any.whl

motion/cli.py

@@ -0,0 +1,503 @@
+"""The `motion` command (Python).
+
+`motion build` — uploads weights to S3 then packages the model into a Docker image.
+`motion deploy` — profile compute (docker stats), push image to ECR, register model.
+
+Weight upload flow:
+  1. For each weight with a local `path` in motion.yml, call the Motion backend
+     for presigned S3 upload URLs (no AWS credentials needed on the developer machine).
+  2. Small files: single HTTP PUT. Large files (≥64 MiB): S3 multipart upload
+     (init → per-part PUT with fresh URLs → complete).
+  3. Write a weights.json manifest into the image with the final S3 URL.
+  4. The container fetches weights from S3 at startup using the MotionBatchJobRole
+     IAM role — users never touch AWS credentials.
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+from .categories import resolve_category_id
+from .config import MotionConfig
+from .dockerfile import generate_dockerfile
+from .profile import resolve_compute_profile
+from .weight_upload import upload_weight_via_backend
+
+_PKG_DIR = os.path.dirname(os.path.abspath(__file__))
+_RUNTIME_FILES = ("__init__.py", "predictor.py", "server.py", "batch.py")
+_DEFAULT_API_URL = "https://adwrzdrdes.us-east-1.awsapprunner.com"
+
+
+def _c(msg, code="36"):
+    return f"\033[{code}m{msg}\033[0m"
+
+
+def _api_url():
+    return os.environ.get("MOTION_API_URL", _DEFAULT_API_URL).rstrip("/")
+
+
+def cmd_build(args):
+    project_dir = os.path.abspath(args.path)
+    print(_c(f"▶ motion build  ({project_dir})"))
+
+    # 1. Parse and validate motion.yml
+    cfg = MotionConfig.load(project_dir)
+    cfg.validate_files()
+    cat_label = ""
+    if cfg.category_id is not None:
+        cat_label = f"  category_id={cfg.category_id}"
+    elif cfg.category:
+        cat_label = f"  category={cfg.category}"
+    print(f"  ✓ {_c('motion.yml')}  name={cfg.name}  gpu={cfg.build.gpu}{cat_label}")
+    print(f"  ✓ predictor    {cfg.predict}")
+
+    # 2. Vendor runtime into .motion/runtime/motion/
+    motion_dir = os.path.join(project_dir, ".motion")
+    if os.path.exists(motion_dir):
+        shutil.rmtree(motion_dir)
+    staging = os.path.join(motion_dir, "runtime", "motion")
+    os.makedirs(staging)
+    for fn in _RUNTIME_FILES:
+        shutil.copy(os.path.join(_PKG_DIR, fn), os.path.join(staging, fn))
+    print("  ✓ vendored runtime → .motion/runtime/motion")
+
+    # 3. Weights — upload local files to S3, write manifest, exclude from image
+    if cfg.weights:
+        api_key = os.environ.get("MOTION_API_KEY", "")
+
+        if not args.dry_run and not api_key:
+            print(_c("  ✗ MOTION_API_KEY not set — required to upload weights.", "31"))
+            print("    Get your key from the Motion dashboard and run:")
+            print("    export MOTION_API_KEY=<your_key>")
+            return 1
+
+        manifest = []
+        for w in cfg.weights:
+            local = os.path.join(project_dir, w.get("path", w["dest"]))
+            if not args.dry_run and os.path.exists(local):
+                # Upload local file → S3 via backend presigned URL
+                s3_url = upload_weight_via_backend(
+                    local,
+                    cfg.name,
+                    api_key,
+                    api_url=_api_url(),
+                    log_ok=lambda m: _c(m, "32"),
+                    log_warn=lambda m: _c(m, "33"),
+                    log_err=lambda m: _c(m, "31"),
+                )
+                if s3_url is None:
+                    return 1
+                manifest.append({"url": s3_url, "dest": w["dest"]})
+            else:
+                # No local file — weight already hosted at declared url
+                if not args.dry_run:
+                    print(f"  • {w.get('path', w['dest'])} not found locally — using declared url: {w['url']}")
+                manifest.append({"url": w["url"], "dest": w["dest"]})
+
+        # Manifest the container reads at startup to fetch weights
+        with open(os.path.join(motion_dir, "weights.json"), "w") as f:
+            json.dump(manifest, f, indent=2)
+
+        # Exclude local weight files from the Docker build context (not baked in)
+        ignore_lines = [w["dest"] for w in cfg.weights] + ["__pycache__", "*.pyc"]
+        with open(os.path.join(motion_dir, "Dockerfile.dockerignore"), "w") as f:
+            f.write("\n".join(ignore_lines) + "\n")
+
+        names = ", ".join(w["dest"] for w in cfg.weights)
+        action = "declared (dry-run)" if args.dry_run else "uploaded"
+        print(f"  ✓ weights      {len(cfg.weights)} {action} — fetched at container startup: {names}")
+
+    # 4. Generate .motion/Dockerfile
+    dockerfile = generate_dockerfile(cfg)
+    df_path = os.path.join(motion_dir, "Dockerfile")
+    with open(df_path, "w") as f:
+        f.write(dockerfile)
+    print("  ✓ generated     .motion/Dockerfile")
+
+    if args.dry_run:
+        print(_c("\n--- Dockerfile (dry run, not built) ---", "33"))
+        print(dockerfile)
+        return 0
+
+    # 5. docker build — always target linux/amd64 so the image runs on AWS Batch
+    #    (x86_64 instances).  BuildKit / Rosetta handles the cross-compilation
+    #    transparently on Apple Silicon.
+    tag = args.tag or cfg.image_tag
+    print(_c(f"\n▶ docker build --platform linux/amd64 -t {tag}"))
+    proc = subprocess.run([
+        "docker", "build",
+        "--platform", "linux/amd64",
+        "-f", df_path, "-t", tag, project_dir,
+    ])
+    if proc.returncode != 0:
+        print(_c("✗ docker build failed", "31"), file=sys.stderr)
+        return proc.returncode
+
+    print(_c(f"\n✓ built image: {tag}", "32"))
+    print(f"  test locally:  docker run --rm -p 8000:8000 {tag}")
+    print("  next step:     motion deploy   (push to ECR + create endpoint)")
+    return 0
+
+
+def cmd_deploy(args):
+    import base64
+    import requests
+
+    project_dir = os.path.abspath(args.path)
+    print(_c(f"▶ motion deploy  ({project_dir})"))
+
+    # 1. Parse motion.yml
+    cfg = MotionConfig.load(project_dir)
+    cfg.validate_files()
+    cat_label = ""
+    if cfg.category_id is not None:
+        cat_label = f"  category_id={cfg.category_id}"
+    elif cfg.category:
+        cat_label = f"  category={cfg.category}"
+    print(f"  ✓ {_c('motion.yml')}  name={cfg.name}  gpu={cfg.build.gpu}{cat_label}")
+
+    api_key = os.environ.get("MOTION_API_KEY", "")
+    if not api_key:
+        print(_c("  ✗ MOTION_API_KEY not set.", "31"))
+        print("    export MOTION_API_KEY=<your_key>")
+        return 1
+
+    local_tag = args.tag or cfg.image_tag
+
+    # 2. Confirm image exists locally
+    result = subprocess.run(
+        ["docker", "image", "inspect", local_tag],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        print(_c(f"  ✗ image '{local_tag}' not found locally. Run `motion build` first.", "31"))
+        return 1
+    print(f"  ✓ image         {local_tag} found")
+
+    # 3. Profile compute (docker stats) before push — optional
+    compute_profile = resolve_compute_profile(
+        image=local_tag,
+        project_dir=project_dir,
+        is_gpu=cfg.build.gpu,
+        declared_compute=cfg.compute.as_dict() if cfg.compute else None,
+        sample_hint=cfg.sample,
+        sample_override=args.sample,
+        no_profile=args.no_profile,
+        timeout=args.profile_timeout,
+        log=lambda m: print(f"  ▸ {m}"),
+        log_warn=lambda m: print(_c(f"  ⚠ {m}", "33")),
+    )
+
+    # 4. Get ECR push info (tag + login token) from backend — no AWS creds needed
+    print("  → requesting ECR push credentials …")
+    try:
+        r = requests.post(
+            f"{_api_url()}/api/v1/motion/deploy-info",
+            json={"model_name": cfg.name},
+            headers={"X-API-Key": api_key},
+            timeout=30,
+        )
+        r.raise_for_status()
+    except Exception as e:
+        print(_c(f"  ✗ could not get deploy info: {e}", "31"))
+        return 1
+
+    info = r.json()
+    ecr_registry: str = info["ecr_registry"]
+    ecr_image: str = info["ecr_image"]
+    ecr_token: str = info["ecr_token"]
+    user_id: int = info["user_id"]
+    namespace: str = info["namespace"]                  # e.g. "jay"
+    model_code: str = f"{namespace}/{cfg.name}"         # e.g. "jay/pose-estimation"
+    model_display: str = f"{namespace}/{_slug_to_title(cfg.name)}"
+    print(f"  ✓ ECR target    {ecr_image}")
+    print(f"  ✓ model_code    {model_code}")
+
+    # 5. docker login to ECR using the backend-issued token
+    decoded = base64.b64decode(ecr_token).decode()
+    _, ecr_password = decoded.split(":", 1)
+    login = subprocess.run(
+        ["docker", "login", "--username", "AWS", "--password-stdin", ecr_registry],
+        input=ecr_password.encode(),
+        capture_output=True,
+    )
+    if login.returncode != 0:
+        print(_c(f"  ✗ docker login failed: {login.stderr.decode()}", "31"))
+        return 1
+    print("  ✓ docker login  ECR OK")
+
+    # 6. Push to ECR — cross-build if local image is arm64
+    #    On Apple Silicon `docker build --platform linux/amd64` still stores the
+    #    image locally as arm64 in the default builder.  Pushing that directly to
+    #    ECR would give Batch a CannotPullContainerError on amd64 instances.
+    #    When we detect arm64, we use `docker buildx build --platform linux/amd64
+    #    --push` (container-driver buildx) to build a fresh amd64 image and push
+    #    it straight to ECR — no local load required.
+    local_arch = subprocess.run(
+        ["docker", "image", "inspect", local_tag, "--format", "{{.Architecture}}"],
+        capture_output=True, text=True,
+    ).stdout.strip()
+
+    df_path = os.path.join(project_dir, ".motion", "Dockerfile")
+    need_cross_build = (local_arch == "arm64") and os.path.exists(df_path)
+
+    if need_cross_build:
+        print(f"  ⚠ local image is arm64 — cross-building linux/amd64 with buildx")
+        # Ensure a container-driver builder exists
+        subprocess.run(
+            ["docker", "buildx", "create", "--name", "cross-builder",
+             "--driver", "docker-container", "--use"],
+            capture_output=True,
+        )
+        print(_c(f"\n▶ docker buildx build --platform linux/amd64 --push → {ecr_image}"))
+        push = subprocess.run([
+            "docker", "buildx", "build",
+            "--platform", "linux/amd64",
+            "--builder", "cross-builder",
+            "-f", df_path,
+            "-t", ecr_image,
+            "--push",
+            project_dir,
+        ])
+    else:
+        subprocess.run(["docker", "tag", local_tag, ecr_image], check=True)
+        print(_c(f"\n▶ docker push {ecr_image}"))
+        push = subprocess.run(["docker", "push", ecr_image])
+
+    if push.returncode != 0:
+        print(_c("  ✗ docker push failed", "31"), file=sys.stderr)
+        return push.returncode
+    print(_c(f"\n  ✓ pushed  {ecr_image}", "32"))
+
+    # 7. Parse predict.py Input fields → params list
+    params = _parse_predict_inputs(project_dir, cfg)
+    print(f"  ✓ parsed        {len(params)} input param(s) from {cfg.predict_file}")
+
+    try:
+        resolved_category_id = resolve_category_id(
+            category_id=cfg.category_id,
+            category_code=cfg.category,
+        )
+    except ValueError as e:
+        print(_c(f"  ✗ {e}", "31"))
+        return 1
+
+    # 8. Register model in backend DB
+    print("  → registering model in Motion platform …")
+    register_payload = {
+        "model_name": model_display,
+        "model_code": model_code,
+        "description": cfg.description or "",
+        "gpu": compute_profile.get("gpu", cfg.build.gpu),
+        "input_type": cfg.input_type,
+        "output_type": cfg.output_type,
+        "ecr_image": ecr_image,
+        "params": params,
+        "inference_model_slug": cfg.inference_model_slug,
+        "cpu_vcpus": compute_profile.get("cpu_vcpus"),
+        "memory_mib": compute_profile.get("memory_mib"),
+        "compute_source": compute_profile.get("compute_source"),
+    }
+    if resolved_category_id is not None:
+        register_payload["category_id"] = resolved_category_id
+    elif cfg.category:
+        register_payload["category_code"] = cfg.category
+    if getattr(args, "service_type", None):
+        register_payload["service_type"] = args.service_type
+
+    try:
+        reg = requests.post(
+            f"{_api_url()}/api/v1/motion/models/register",
+            json=register_payload,
+            headers={"X-API-Key": api_key},
+            timeout=30,
+        )
+        reg.raise_for_status()
+    except Exception as e:
+        detail = ""
+        if hasattr(e, "response") and e.response is not None:
+            try:
+                detail = e.response.json().get("detail", "")
+            except Exception:
+                detail = e.response.text[:300]
+        msg = f"{e}" + (f" — {detail}" if detail else "")
+        print(_c(f"  ✗ model registration failed: {msg}", "31"))
+        return 1
+
+    reg_data = reg.json()
+    action = "registered" if reg_data["created"] else "updated"
+    print(_c(f"\n✓ model {action}: {model_code}  (id={reg_data['model_type_id']})", "32"))
+    print(f"  ECR image:  {reg_data['ecr_image']}")
+    print(f"  model_code: {reg_data['model_code']}")
+    if resolved_category_id is not None:
+        print(f"  category:   id={resolved_category_id}")
+    elif cfg.category:
+        print(f"  category:   {cfg.category}")
+    if reg_data.get("cpu_vcpus") or reg_data.get("memory_mib"):
+        print(
+            f"  compute:    cpu={reg_data.get('cpu_vcpus')}  "
+            f"mem={reg_data.get('memory_mib')} MiB  "
+            f"gpu={reg_data.get('gpu')}  "
+            f"source={reg_data.get('compute_source')}"
+        )
+    if reg_data.get("service_type"):
+        print(f"  runs on:    {reg_data['service_type']}")
+    print(f"\n  Submit a job:  POST /api/v1/motion/submit  model_name={model_code}")
+    return 0
+
+
+def _slug_to_title(slug: str) -> str:
+    """Convert 'pose-estimation' → 'Pose Estimation'."""
+    return " ".join(w.capitalize() for w in slug.replace("-", " ").replace("_", " ").split())
+
+
+def _parse_predict_inputs(project_dir: str, cfg: "MotionConfig") -> list:
+    """Parse the predict method signature in predict.py and extract Input() fields.
+
+    Returns a list of param dicts compatible with RegisterModelRequest.params.
+    Each Input() annotation in the predict() method signature becomes one param.
+
+    Replicate-style:
+        def predict(self, video: Path = Input(description="…"), steps: int = Input(default=20)):
+    """
+    import ast
+
+    predict_path = os.path.join(project_dir, cfg.predict_file)
+    try:
+        with open(predict_path) as f:
+            tree = ast.parse(f.read())
+    except Exception:
+        return []
+
+    params = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        if node.name != cfg.predict_class:
+            continue
+        for item in node.body:
+            if not isinstance(item, ast.FunctionDef) or item.name != "predict":
+                continue
+            for i, arg in enumerate(item.args.args):
+                if arg.arg == "self":
+                    continue
+                # Determine type annotation
+                annotation = item.args.annotations.get(arg.arg) if hasattr(item.args, "annotations") else None
+                type_name = ""
+                if arg.annotation:
+                    if isinstance(arg.annotation, ast.Name):
+                        type_name = arg.annotation.id
+                    elif isinstance(arg.annotation, ast.Attribute):
+                        type_name = arg.annotation.attr
+
+                # Map Python type to field_type
+                field_type = _python_type_to_field(type_name)
+
+                # Parse Input() default for description / default_value / constraints
+                default_info = _extract_input_default(item, arg.arg)
+
+                params.append({
+                    "param_key": arg.arg,
+                    "label": arg.arg.replace("_", " ").capitalize(),
+                    "field_type": field_type,
+                    "default_value": default_info.get("default"),
+                    "description": default_info.get("description"),
+                    "min_value": default_info.get("ge") or default_info.get("min_value"),
+                    "max_value": default_info.get("le") or default_info.get("max_value"),
+                    "step": default_info.get("step"),
+                    "is_required": default_info.get("default") is None,
+                    "display_order": i,
+                })
+    return params
+
+
+def _python_type_to_field(type_name: str) -> str:
+    return {
+        "int": "number",
+        "float": "range",
+        "str": "text",
+        "bool": "toggle",
+        "Path": "text",
+        "": "text",
+    }.get(type_name, "text")
+
+
+def _extract_input_default(func_node, arg_name: str) -> dict:
+    """Walk defaults in the function AST to find Input(description=…, default=…, ge=…, le=…)."""
+    import ast
+
+    args = func_node.args.args
+    # Align defaults (they're right-aligned in args.defaults)
+    offset = len(args) - len(func_node.args.defaults)
+    for idx, a in enumerate(args):
+        if a.arg != arg_name:
+            continue
+        def_idx = idx - offset
+        if def_idx < 0 or def_idx >= len(func_node.args.defaults):
+            break
+        default_node = func_node.args.defaults[def_idx]
+        if not isinstance(default_node, ast.Call):
+            break
+        info = {}
+        for kw in default_node.keywords:
+            val = kw.value
+            if isinstance(val, ast.Constant):
+                info[kw.arg] = val.value
+            elif isinstance(val, ast.UnaryOp) and isinstance(val.op, ast.USub):
+                if isinstance(val.operand, ast.Constant):
+                    info[kw.arg] = -val.operand.value
+        # Normalise key names
+        if "default" in info:
+            info["default"] = str(info["default"])
+        return info
+    return {}
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="motion", description="Build & deploy models for Motion inference")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    b = sub.add_parser("build", help="upload weights to S3 + build model Docker image")
+    b.add_argument("path", nargs="?", default=".", help="path to model folder (has motion.yml)")
+    b.add_argument("--tag", help="image tag (default motion-<name>:latest)")
+    b.add_argument("--dry-run", action="store_true", help="print the Dockerfile, skip upload and build")
+    b.set_defaults(func=cmd_build)
+
+    d = sub.add_parser(
+        "deploy",
+        help="profile compute, push image to ECR, register model in platform",
+    )
+    d.add_argument("path", nargs="?", default=".")
+    d.add_argument("--tag", help="local image tag to push (default motion-<name>:latest)")
+    d.add_argument(
+        "--no-profile",
+        action="store_true",
+        help="skip docker stats profiling; only send gpu flag from motion.yml",
+    )
+    d.add_argument(
+        "--profile-timeout",
+        type=int,
+        default=120,
+        help="max seconds to run the container during profiling (default 120)",
+    )
+    d.add_argument(
+        "--sample",
+        help="sample input file for profiling (overrides motion.yml `sample:`)",
+    )
+    d.add_argument(
+        "--service-type",
+        choices=["batch", "inference_instance", "dedicated_instance"],
+        help="how this model's jobs run: batch (default), inference_instance "
+             "(warm host), or dedicated_instance (disabled for now). "
+             "Omit to keep the default/existing value.",
+    )
+    d.set_defaults(func=cmd_deploy)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

motion/config.py

@@ -0,0 +1,148 @@
+"""Parse and validate motion.yml into a typed config object."""
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    raise SystemExit("PyYAML is required: pip install pyyaml")
+
+
+@dataclass
+class BuildSpec:
+    gpu: bool = False
+    cuda: str = "11.8"
+    python_version: str = "3.10"
+    system_packages: List[str] = field(default_factory=list)
+    python_packages: List[str] = field(default_factory=list)
+    # extra `pip install -f <url>` wheel indexes (e.g. OpenMMLab CPU wheels)
+    python_find_links: List[str] = field(default_factory=list)
+    # replace the default PyPI index (e.g. https://download.pytorch.org/whl/cpu)
+    python_index_url: str = ""
+
+
+@dataclass
+class ComputeSpec:
+    cpu: Optional[int] = None
+    memory_mib: Optional[int] = None
+    gpu: Optional[bool] = None
+
+    def as_dict(self) -> dict:
+        out = {}
+        if self.cpu is not None:
+            out["cpu"] = self.cpu
+        if self.memory_mib is not None:
+            out["memory_mib"] = self.memory_mib
+        if self.gpu is not None:
+            out["gpu"] = self.gpu
+        return out
+
+
+@dataclass
+class MotionConfig:
+    name: str
+    predict: str                       # "predict.py:ClassName"
+    description: str = ""
+    category: str = ""                 # category_code (mapped to id locally)
+    category_id: Optional[int] = None  # explicit id; wins over category code
+    inference_model: str = ""          # inference_model slug; defaults to `name`
+    sample: str = ""                   # sample input used by deploy profiling
+    input_type: str = "video"          # video | image | text
+    output_type: str = "mp4"           # mp4 | glb | ...
+    build: BuildSpec = field(default_factory=BuildSpec)
+    compute: Optional[ComputeSpec] = None
+    # large weights pulled at startup (NOT baked into the image). Each item:
+    # {"url": "s3://... or https://...", "dest": "relative/path/in/src"}
+    weights: List[dict] = field(default_factory=list)
+    project_dir: str = "."             # absolute dir containing motion.yml
+
+    @property
+    def predict_file(self) -> str:
+        return self.predict.split(":", 1)[0]
+
+    @property
+    def predict_class(self) -> str:
+        return self.predict.split(":", 1)[1]
+
+    @property
+    def image_tag(self) -> str:
+        return f"motion-{self.name}:latest"
+
+    @property
+    def inference_model_slug(self) -> str:
+        return self.inference_model or self.name
+
+    @classmethod
+    def load(cls, project_dir: str) -> "MotionConfig":
+        path = os.path.join(project_dir, "motion.yml")
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"No motion.yml found in {project_dir}")
+        with open(path) as f:
+            raw = yaml.safe_load(f) or {}
+
+        errors = []
+        if not raw.get("name"):
+            errors.append("`name` is required")
+        predict = raw.get("predict")
+        if not predict or ":" not in str(predict):
+            errors.append("`predict` is required and must be 'file.py:ClassName'")
+        weights = []
+        for w in (raw.get("weights", []) or []):
+            if not w.get("url") or not w.get("dest"):
+                errors.append("each `weights` entry needs both `url` and `dest`")
+            else:
+                # `path` = local source to upload at build time (defaults to dest)
+                weights.append({
+                    "url": str(w["url"]),
+                    "dest": str(w["dest"]),
+                    "path": str(w.get("path", w["dest"])),
+                })
+        if errors:
+            raise ValueError("Invalid motion.yml:\n  - " + "\n  - ".join(errors))
+
+        b = raw.get("build", {}) or {}
+        build = BuildSpec(
+            gpu=bool(b.get("gpu", False)),
+            cuda=str(b.get("cuda", "11.8")),
+            python_version=str(b.get("python_version", "3.10")),
+            system_packages=list(b.get("system_packages", []) or []),
+            python_packages=list(b.get("python_packages", []) or []),
+            python_find_links=list(b.get("python_find_links", []) or []),
+            python_index_url=str(b.get("python_index_url", "") or ""),
+        )
+
+        compute = None
+        c = raw.get("compute")
+        if isinstance(c, dict) and c:
+            cpu = c.get("cpu") if c.get("cpu") is not None else c.get("cpu_vcpus")
+            mem = c.get("memory_mib") if c.get("memory_mib") is not None else c.get("memory")
+            gpu = c.get("gpu")
+            compute = ComputeSpec(
+                cpu=int(cpu) if cpu is not None else None,
+                memory_mib=int(mem) if mem is not None else None,
+                gpu=bool(gpu) if gpu is not None else None,
+            )
+
+        return cls(
+            name=raw["name"],
+            predict=predict,
+            description=raw.get("description", ""),
+            category=str(raw.get("category", "") or "").strip(),
+        category_id=int(raw["category_id"]) if raw.get("category_id") is not None else None,
+            inference_model=str(raw.get("inference_model", "") or "").strip(),
+            sample=str(raw.get("sample", "") or "").strip(),
+            input_type=str(raw.get("input_type", "video") or "video"),
+            output_type=str(raw.get("output_type", "mp4") or "mp4"),
+            build=build,
+            compute=compute,
+            weights=weights,
+            project_dir=os.path.abspath(project_dir),
+        )
+
+    def validate_files(self) -> None:
+        pf = os.path.join(self.project_dir, self.predict_file)
+        if not os.path.exists(pf):
+            raise FileNotFoundError(
+                f"predict file '{self.predict_file}' not found in {self.project_dir}"
+            )