motrix-deploy 0.4.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- motrix_deploy/__init__.py +8 -0
- motrix_deploy/artifact/__init__.py +26 -0
- motrix_deploy/artifact/io.py +172 -0
- motrix_deploy/artifact/schema.py +340 -0
- motrix_deploy/cli.py +124 -0
- motrix_deploy/config/__init__.py +109 -0
- motrix_deploy/config/deploy.yaml +18 -0
- motrix_deploy/config/inspect.yaml +12 -0
- motrix_deploy/config/runtime/sim.yaml +4 -0
- motrix_deploy/contracts.py +302 -0
- motrix_deploy/env.py +40 -0
- motrix_deploy/errors.py +32 -0
- motrix_deploy/policy/__init__.py +112 -0
- motrix_deploy/policy/processing.py +36 -0
- motrix_deploy/profile.py +115 -0
- motrix_deploy/py.typed +0 -0
- motrix_deploy/robot/__init__.py +4 -0
- motrix_deploy/robot/interface.py +59 -0
- motrix_deploy/runtime/__init__.py +41 -0
- motrix_deploy/runtime/base.py +151 -0
- motrix_deploy/runtime/config.py +80 -0
- motrix_deploy/runtime/context.py +22 -0
- motrix_deploy/runtime/control.py +301 -0
- motrix_deploy/runtime/factory.py +82 -0
- motrix_deploy/runtime/hardware.py +57 -0
- motrix_deploy/runtime/lifecycle.py +36 -0
- motrix_deploy/runtime/result.py +68 -0
- motrix_deploy/runtime/scheduler.py +70 -0
- motrix_deploy/task.py +104 -0
- motrix_deploy-0.4.0.dist-info/METADATA +75 -0
- motrix_deploy-0.4.0.dist-info/RECORD +33 -0
- motrix_deploy-0.4.0.dist-info/WHEEL +4 -0
- motrix_deploy-0.4.0.dist-info/licenses/LICENSE +204 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Versioned, self-contained deployment artifacts."""
|
|
5
|
+
|
|
6
|
+
from motrix_deploy.artifact.io import Artifact, inspect_artifact, read_artifact, sha256_bytes, write_artifact
|
|
7
|
+
from motrix_deploy.artifact.schema import (
|
|
8
|
+
ControlSpec,
|
|
9
|
+
DeploymentManifest,
|
|
10
|
+
PolicySpec,
|
|
11
|
+
SourceSpec,
|
|
12
|
+
TaskSpec,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"Artifact",
|
|
17
|
+
"ControlSpec",
|
|
18
|
+
"DeploymentManifest",
|
|
19
|
+
"PolicySpec",
|
|
20
|
+
"SourceSpec",
|
|
21
|
+
"TaskSpec",
|
|
22
|
+
"inspect_artifact",
|
|
23
|
+
"read_artifact",
|
|
24
|
+
"sha256_bytes",
|
|
25
|
+
"write_artifact",
|
|
26
|
+
]
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Safe and atomic artifact filesystem I/O."""
|
|
5
|
+
|
|
6
|
+
import hashlib
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import shutil
|
|
10
|
+
import tempfile
|
|
11
|
+
from collections.abc import Mapping
|
|
12
|
+
from dataclasses import dataclass
|
|
13
|
+
from pathlib import Path, PurePosixPath
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from motrix_deploy.artifact.schema import DeploymentManifest
|
|
17
|
+
from motrix_deploy.errors import ArtifactError, ValidationError
|
|
18
|
+
|
|
19
|
+
MANIFEST_NAME = "manifest.json"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def sha256_bytes(payload: bytes) -> str:
|
|
23
|
+
"""Return the lowercase SHA-256 digest of payload bytes."""
|
|
24
|
+
return hashlib.sha256(payload).hexdigest()
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _safe_relative_path(value: str, *, field_path: str) -> PurePosixPath:
|
|
28
|
+
if not isinstance(value, str) or not value or "\\" in value:
|
|
29
|
+
raise ValidationError(field_path, "a non-empty POSIX relative path", value)
|
|
30
|
+
path = PurePosixPath(value)
|
|
31
|
+
if path.is_absolute() or any(part in ("", ".", "..") for part in path.parts):
|
|
32
|
+
raise ValidationError(field_path, "a normalized relative path without '..'", value)
|
|
33
|
+
return path
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _payload_path(root: Path, relative: PurePosixPath) -> Path:
|
|
37
|
+
candidate = root.joinpath(*relative.parts)
|
|
38
|
+
current = root
|
|
39
|
+
for part in relative.parts:
|
|
40
|
+
current = current / part
|
|
41
|
+
if current.is_symlink():
|
|
42
|
+
raise ArtifactError(f"artifact payload must not contain symlinks: {relative}")
|
|
43
|
+
resolved_root = root.resolve()
|
|
44
|
+
resolved_candidate = candidate.resolve()
|
|
45
|
+
if not resolved_candidate.is_relative_to(resolved_root):
|
|
46
|
+
raise ArtifactError(f"artifact payload escapes root: {relative}")
|
|
47
|
+
return candidate
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass(frozen=True)
|
|
51
|
+
class Artifact:
|
|
52
|
+
"""A validated artifact root and its parsed manifest."""
|
|
53
|
+
|
|
54
|
+
root: Path
|
|
55
|
+
manifest: DeploymentManifest
|
|
56
|
+
|
|
57
|
+
@property
|
|
58
|
+
def policy_path(self) -> Path:
|
|
59
|
+
relative = _safe_relative_path(self.manifest.policy.payload_path, field_path="policy.payload_path")
|
|
60
|
+
return _payload_path(self.root, relative)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def write_artifact(
|
|
64
|
+
output: str | Path,
|
|
65
|
+
manifest: DeploymentManifest,
|
|
66
|
+
payloads: Mapping[str, bytes],
|
|
67
|
+
) -> Artifact:
|
|
68
|
+
"""Validate and atomically write a new artifact directory."""
|
|
69
|
+
target = Path(output).absolute()
|
|
70
|
+
if target.exists():
|
|
71
|
+
raise ArtifactError(f"refusing to overwrite existing artifact: {target}")
|
|
72
|
+
parent = target.parent
|
|
73
|
+
parent.mkdir(parents=True, exist_ok=True)
|
|
74
|
+
expected_path = _safe_relative_path(manifest.policy.payload_path, field_path="policy.payload_path")
|
|
75
|
+
expected_payloads = {str(expected_path): manifest.policy.sha256}
|
|
76
|
+
for payload in manifest.payloads:
|
|
77
|
+
relative = _safe_relative_path(payload.path, field_path="payloads.path")
|
|
78
|
+
expected_payloads[str(relative)] = payload.sha256
|
|
79
|
+
if set(payloads) != set(expected_payloads):
|
|
80
|
+
raise ArtifactError(f"payload keys must be exactly {sorted(expected_payloads)}, got {sorted(payloads)!r}")
|
|
81
|
+
for relative, expected_sha in expected_payloads.items():
|
|
82
|
+
if not isinstance(payloads[relative], bytes):
|
|
83
|
+
raise ArtifactError(f"payload {relative} must be bytes")
|
|
84
|
+
digest = sha256_bytes(payloads[relative])
|
|
85
|
+
if digest != expected_sha:
|
|
86
|
+
raise ArtifactError(f"sha256 mismatch for payload {relative}: expected {expected_sha}, got {digest}")
|
|
87
|
+
|
|
88
|
+
staging = Path(tempfile.mkdtemp(prefix=f".{target.name}.staging-", dir=parent))
|
|
89
|
+
try:
|
|
90
|
+
for relative in sorted(expected_payloads):
|
|
91
|
+
payload_path = _payload_path(staging, PurePosixPath(relative))
|
|
92
|
+
payload_path.parent.mkdir(parents=True, exist_ok=True)
|
|
93
|
+
payload_path.write_bytes(payloads[relative])
|
|
94
|
+
manifest_path = staging / MANIFEST_NAME
|
|
95
|
+
manifest_path.write_text(
|
|
96
|
+
json.dumps(manifest.to_dict(), indent=2, sort_keys=True, allow_nan=False) + "\n",
|
|
97
|
+
encoding="utf-8",
|
|
98
|
+
)
|
|
99
|
+
os.replace(staging, target)
|
|
100
|
+
except Exception:
|
|
101
|
+
shutil.rmtree(staging, ignore_errors=True)
|
|
102
|
+
raise
|
|
103
|
+
return read_artifact(target)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def read_artifact(root: str | Path) -> Artifact:
|
|
107
|
+
"""Read and fully validate an artifact without loading its policy runtime."""
|
|
108
|
+
artifact_root = Path(root).absolute()
|
|
109
|
+
if not artifact_root.is_dir():
|
|
110
|
+
raise ArtifactError(f"artifact root is not a directory: {artifact_root}")
|
|
111
|
+
manifest_path = artifact_root / MANIFEST_NAME
|
|
112
|
+
if manifest_path.is_symlink() or not manifest_path.is_file():
|
|
113
|
+
raise ArtifactError(f"artifact manifest is missing or unsafe: {manifest_path}")
|
|
114
|
+
try:
|
|
115
|
+
raw_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
|
|
116
|
+
except (OSError, UnicodeError, json.JSONDecodeError) as error:
|
|
117
|
+
raise ArtifactError(f"cannot parse artifact manifest {manifest_path}: {error}") from error
|
|
118
|
+
manifest = DeploymentManifest.from_dict(raw_manifest)
|
|
119
|
+
for payload in manifest.payloads:
|
|
120
|
+
relative = _safe_relative_path(payload.path, field_path="payloads.path")
|
|
121
|
+
payload_file = _payload_path(artifact_root, relative)
|
|
122
|
+
if not payload_file.is_file():
|
|
123
|
+
raise ArtifactError(f"artifact payload is missing: {relative}")
|
|
124
|
+
digest = hashlib.sha256(payload_file.read_bytes()).hexdigest()
|
|
125
|
+
if digest != payload.sha256:
|
|
126
|
+
raise ArtifactError(f"payload sha256 mismatch for {relative}: expected {payload.sha256}, got {digest}")
|
|
127
|
+
relative = _safe_relative_path(manifest.policy.payload_path, field_path="policy.payload_path")
|
|
128
|
+
policy_path = _payload_path(artifact_root, relative)
|
|
129
|
+
if not policy_path.is_file():
|
|
130
|
+
raise ArtifactError(f"artifact payload is missing: {relative}")
|
|
131
|
+
digest = hashlib.sha256(policy_path.read_bytes()).hexdigest()
|
|
132
|
+
if digest != manifest.policy.sha256:
|
|
133
|
+
raise ArtifactError(f"policy.sha256 mismatch: expected {manifest.policy.sha256}, got {digest}")
|
|
134
|
+
return Artifact(root=artifact_root, manifest=manifest)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def inspect_artifact(root: str | Path) -> dict[str, Any]:
|
|
138
|
+
"""Return a machine-readable static summary without opening a backend or policy runtime."""
|
|
139
|
+
artifact = read_artifact(root)
|
|
140
|
+
manifest = artifact.manifest
|
|
141
|
+
return {
|
|
142
|
+
"valid": True,
|
|
143
|
+
"schema_version": manifest.schema_version,
|
|
144
|
+
"source": manifest.source.to_dict(),
|
|
145
|
+
"policy": {
|
|
146
|
+
"component_version": manifest.policy.component_version,
|
|
147
|
+
"input": _tensor_summary(
|
|
148
|
+
manifest.policy.input.name,
|
|
149
|
+
manifest.policy.input.shape,
|
|
150
|
+
manifest.policy.input.dtype,
|
|
151
|
+
),
|
|
152
|
+
"output": _tensor_summary(
|
|
153
|
+
manifest.policy.output.name,
|
|
154
|
+
manifest.policy.output.shape,
|
|
155
|
+
manifest.policy.output.dtype,
|
|
156
|
+
),
|
|
157
|
+
"sha256": manifest.policy.sha256,
|
|
158
|
+
},
|
|
159
|
+
"robot": {
|
|
160
|
+
"base_link_name": manifest.robot.base_link_name,
|
|
161
|
+
"joint_count": manifest.robot.joint_count,
|
|
162
|
+
"joint_names": list(manifest.robot.joint_names),
|
|
163
|
+
},
|
|
164
|
+
"task": manifest.task.to_dict(),
|
|
165
|
+
"observation_size": manifest.policy.input.shape[1],
|
|
166
|
+
"action_size": manifest.policy.output.shape[1],
|
|
167
|
+
"control_period_s": manifest.control.period_s,
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _tensor_summary(name: str, shape: tuple[int, ...], dtype: str) -> dict[str, Any]:
|
|
172
|
+
return {"name": name, "shape": list(shape), "dtype": dtype}
|
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Schema v1 for the deployment manifest."""
|
|
5
|
+
|
|
6
|
+
import re
|
|
7
|
+
from abc import ABC
|
|
8
|
+
from collections.abc import Mapping
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import Any, ClassVar
|
|
11
|
+
|
|
12
|
+
import numpy as np
|
|
13
|
+
from pydantic import BaseModel, ConfigDict
|
|
14
|
+
from pydantic import ValidationError as PydanticValidationError
|
|
15
|
+
|
|
16
|
+
from motrix_deploy.contracts import JointControlMode, RobotSpec, TensorSpec
|
|
17
|
+
from motrix_deploy.errors import ValidationError
|
|
18
|
+
|
|
19
|
+
SCHEMA_VERSION = "motrix-deploy/v1"
|
|
20
|
+
POLICY_COMPONENT_VERSION = "onnx/v1"
|
|
21
|
+
_TASK_NAME_PATTERN = re.compile(r"[^/\s]+/v[1-9][0-9]*")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _mapping(value: object, path: str) -> Mapping[str, Any]:
|
|
25
|
+
if not isinstance(value, Mapping):
|
|
26
|
+
raise ValidationError(path, "an object", type(value).__name__)
|
|
27
|
+
return value
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _keys(value: Mapping[str, Any], *, path: str, required: set[str], optional: set[str] | None = None) -> None:
|
|
31
|
+
missing = sorted(required - value.keys())
|
|
32
|
+
if missing:
|
|
33
|
+
raise ValidationError(path, f"required fields {sorted(required)}", f"missing {missing}")
|
|
34
|
+
allowed = required | (optional or set())
|
|
35
|
+
unknown = sorted(value.keys() - allowed)
|
|
36
|
+
if unknown:
|
|
37
|
+
raise ValidationError(path, f"only fields {sorted(allowed)}", f"unknown {unknown}")
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _string(value: object, path: str) -> str:
|
|
41
|
+
if not isinstance(value, str) or not value:
|
|
42
|
+
raise ValidationError(path, "a non-empty string", value)
|
|
43
|
+
return value
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _validate_positive_number(value: object, path: str) -> None:
|
|
47
|
+
if isinstance(value, bool) or not isinstance(value, (int, float)) or not np.isfinite(value) or value <= 0:
|
|
48
|
+
raise ValidationError(path, "a positive finite number", value)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _tensor_to_dict(value: TensorSpec) -> dict[str, Any]:
|
|
52
|
+
return {"name": value.name, "shape": list(value.shape), "dtype": value.dtype}
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _tensor_from_dict(value: object, path: str) -> TensorSpec:
|
|
56
|
+
data = _mapping(value, path)
|
|
57
|
+
_keys(data, path=path, required={"name", "shape", "dtype"})
|
|
58
|
+
shape = data["shape"]
|
|
59
|
+
if not isinstance(shape, list):
|
|
60
|
+
raise ValidationError(f"{path}.shape", "an array of positive integers", shape)
|
|
61
|
+
try:
|
|
62
|
+
return TensorSpec(name=data["name"], shape=tuple(shape), dtype=data["dtype"])
|
|
63
|
+
except ValidationError as error:
|
|
64
|
+
suffix = error.path.removeprefix("tensor")
|
|
65
|
+
raise ValidationError(f"{path}{suffix}", error.expected, error.actual) from error
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class SourceSpec:
|
|
70
|
+
"""Traceability information for the training source."""
|
|
71
|
+
|
|
72
|
+
framework: str
|
|
73
|
+
run_id: str
|
|
74
|
+
checkpoint: str
|
|
75
|
+
|
|
76
|
+
def __post_init__(self) -> None:
|
|
77
|
+
for field_name in ("framework", "run_id", "checkpoint"):
|
|
78
|
+
_string(getattr(self, field_name), f"source.{field_name}")
|
|
79
|
+
|
|
80
|
+
def to_dict(self) -> dict[str, Any]:
|
|
81
|
+
return {"framework": self.framework, "run_id": self.run_id, "checkpoint": self.checkpoint}
|
|
82
|
+
|
|
83
|
+
@classmethod
|
|
84
|
+
def from_dict(cls, value: object) -> "SourceSpec":
|
|
85
|
+
data = _mapping(value, "source")
|
|
86
|
+
_keys(data, path="source", required={"framework", "run_id", "checkpoint"})
|
|
87
|
+
return cls(framework=data["framework"], run_id=data["run_id"], checkpoint=data["checkpoint"])
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@dataclass(frozen=True)
|
|
91
|
+
class PolicySpec:
|
|
92
|
+
"""One self-contained deterministic policy payload."""
|
|
93
|
+
|
|
94
|
+
component_version: str
|
|
95
|
+
payload_path: str
|
|
96
|
+
sha256: str
|
|
97
|
+
input: TensorSpec
|
|
98
|
+
output: TensorSpec
|
|
99
|
+
|
|
100
|
+
def __post_init__(self) -> None:
|
|
101
|
+
if self.component_version != POLICY_COMPONENT_VERSION:
|
|
102
|
+
raise ValidationError("policy.component_version", POLICY_COMPONENT_VERSION, self.component_version)
|
|
103
|
+
_string(self.payload_path, "policy.payload_path")
|
|
104
|
+
if len(self.sha256) != 64 or any(character not in "0123456789abcdef" for character in self.sha256):
|
|
105
|
+
raise ValidationError("policy.sha256", "64 lowercase hexadecimal characters", self.sha256)
|
|
106
|
+
|
|
107
|
+
def to_dict(self) -> dict[str, Any]:
|
|
108
|
+
return {
|
|
109
|
+
"component_version": self.component_version,
|
|
110
|
+
"payload_path": self.payload_path,
|
|
111
|
+
"sha256": self.sha256,
|
|
112
|
+
"input": _tensor_to_dict(self.input),
|
|
113
|
+
"output": _tensor_to_dict(self.output),
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
@classmethod
|
|
117
|
+
def from_dict(cls, value: object) -> "PolicySpec":
|
|
118
|
+
data = _mapping(value, "policy")
|
|
119
|
+
required = {"component_version", "payload_path", "sha256", "input", "output"}
|
|
120
|
+
_keys(data, path="policy", required=required)
|
|
121
|
+
return cls(
|
|
122
|
+
component_version=data["component_version"],
|
|
123
|
+
payload_path=data["payload_path"],
|
|
124
|
+
sha256=data["sha256"],
|
|
125
|
+
input=_tensor_from_dict(data["input"], "policy.input"),
|
|
126
|
+
output=_tensor_from_dict(data["output"], "policy.output"),
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _robot_to_dict(value: RobotSpec) -> dict[str, Any]:
|
|
131
|
+
return {
|
|
132
|
+
"base_link_name": value.base_link_name,
|
|
133
|
+
"joint_names": list(value.joint_names),
|
|
134
|
+
"default_joint_position": value.default_joint_position.tolist(),
|
|
135
|
+
"position_lower": value.position_lower.tolist(),
|
|
136
|
+
"position_upper": value.position_upper.tolist(),
|
|
137
|
+
"torque_limit": value.torque_limit.tolist(),
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _robot_from_dict(value: object) -> RobotSpec:
|
|
142
|
+
data = _mapping(value, "robot")
|
|
143
|
+
required = {
|
|
144
|
+
"base_link_name",
|
|
145
|
+
"joint_names",
|
|
146
|
+
"default_joint_position",
|
|
147
|
+
"position_lower",
|
|
148
|
+
"position_upper",
|
|
149
|
+
"torque_limit",
|
|
150
|
+
}
|
|
151
|
+
_keys(data, path="robot", required=required)
|
|
152
|
+
joint_names = data["joint_names"]
|
|
153
|
+
if not isinstance(joint_names, list):
|
|
154
|
+
raise ValidationError("robot.joint_names", "an array of strings", joint_names)
|
|
155
|
+
try:
|
|
156
|
+
return RobotSpec(
|
|
157
|
+
base_link_name=data["base_link_name"],
|
|
158
|
+
joint_names=tuple(joint_names),
|
|
159
|
+
default_joint_position=np.asarray(data["default_joint_position"], dtype=np.float32),
|
|
160
|
+
position_lower=np.asarray(data["position_lower"], dtype=np.float32),
|
|
161
|
+
position_upper=np.asarray(data["position_upper"], dtype=np.float32),
|
|
162
|
+
torque_limit=np.asarray(data["torque_limit"], dtype=np.float32),
|
|
163
|
+
)
|
|
164
|
+
except ValidationError:
|
|
165
|
+
raise
|
|
166
|
+
except (TypeError, ValueError) as error:
|
|
167
|
+
raise ValidationError("robot", "numeric arrays matching joint_names", str(error)) from error
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _task_validation_error(error: PydanticValidationError) -> ValidationError:
|
|
171
|
+
"""Translate model diagnostics into the deployment artifact field namespace."""
|
|
172
|
+
detail = error.errors(include_url=False)[0]
|
|
173
|
+
location = ".".join(str(part) for part in detail["loc"])
|
|
174
|
+
path = f"task.config.{location}" if location else "task.config"
|
|
175
|
+
if detail["type"] == "missing":
|
|
176
|
+
return ValidationError(
|
|
177
|
+
path, "a required task field (re-export artifacts using an older task schema)", "missing"
|
|
178
|
+
)
|
|
179
|
+
return ValidationError(path, detail["msg"], detail.get("input"))
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
class TaskSpec(BaseModel, ABC):
|
|
183
|
+
"""Typed task configuration, resolved through an installed versioned task class.
|
|
184
|
+
|
|
185
|
+
Concrete implementations declare ``task_name`` as a ClassVar and use
|
|
186
|
+
Pydantic fields and validators for configuration semantics. YAML composition
|
|
187
|
+
and interpolation resolution belong to the caller, not the artifact codec.
|
|
188
|
+
"""
|
|
189
|
+
|
|
190
|
+
model_config = ConfigDict(strict=True, extra="forbid", frozen=True, allow_inf_nan=False, validate_default=True)
|
|
191
|
+
task_name: ClassVar[str]
|
|
192
|
+
|
|
193
|
+
@property
|
|
194
|
+
def name(self) -> str:
|
|
195
|
+
return self.task_name
|
|
196
|
+
|
|
197
|
+
def to_dict(self) -> dict[str, Any]:
|
|
198
|
+
# Frozen models may still contain mutable lists. Revalidate a fresh
|
|
199
|
+
# mapping so mutations cannot bypass the artifact serialization boundary.
|
|
200
|
+
try:
|
|
201
|
+
spec = type(self).model_validate(self.model_dump())
|
|
202
|
+
except PydanticValidationError as error:
|
|
203
|
+
raise _task_validation_error(error) from error
|
|
204
|
+
return {"name": self.name, "config": spec.model_dump(mode="json")}
|
|
205
|
+
|
|
206
|
+
@classmethod
|
|
207
|
+
def from_dict(cls, value: object) -> "TaskSpec":
|
|
208
|
+
data = _mapping(value, "task")
|
|
209
|
+
_keys(data, path="task", required={"name", "config"})
|
|
210
|
+
name = data["name"]
|
|
211
|
+
if not isinstance(name, str) or _TASK_NAME_PATTERN.fullmatch(name) is None:
|
|
212
|
+
raise ValidationError("task.name", "a versioned task identifier such as go2_walk/v1", name)
|
|
213
|
+
config = _mapping(data["config"], "task.config")
|
|
214
|
+
# Lazy import: the runtime contract itself depends on TaskSpec.
|
|
215
|
+
from motrix_deploy.task import load_task_type
|
|
216
|
+
|
|
217
|
+
try:
|
|
218
|
+
spec_type = getattr(load_task_type(name), "spec_type", None)
|
|
219
|
+
except Exception as error:
|
|
220
|
+
raise ValidationError("task.name", "an available installed task class plugin", str(error)) from error
|
|
221
|
+
if (
|
|
222
|
+
not isinstance(spec_type, type)
|
|
223
|
+
or not issubclass(spec_type, TaskSpec)
|
|
224
|
+
or getattr(spec_type, "task_name", None) != name
|
|
225
|
+
):
|
|
226
|
+
raise ValidationError("task.name", "a TaskSpec BaseModel with matching task_name", name)
|
|
227
|
+
try:
|
|
228
|
+
return spec_type.model_validate(config)
|
|
229
|
+
except PydanticValidationError as error:
|
|
230
|
+
raise _task_validation_error(error) from error
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
@dataclass(frozen=True)
|
|
234
|
+
class ControlSpec:
|
|
235
|
+
"""Timing and coordinate conventions shared by runtime and backend."""
|
|
236
|
+
|
|
237
|
+
period_s: float
|
|
238
|
+
state_timeout_s: float
|
|
239
|
+
quaternion_order: str = "xyzw"
|
|
240
|
+
base_orientation: str = "body_to_world"
|
|
241
|
+
angular_velocity_frame: str = "body"
|
|
242
|
+
mode: JointControlMode = JointControlMode.SERVO
|
|
243
|
+
|
|
244
|
+
def __post_init__(self) -> None:
|
|
245
|
+
try:
|
|
246
|
+
object.__setattr__(self, "mode", JointControlMode(self.mode))
|
|
247
|
+
except (TypeError, ValueError) as error:
|
|
248
|
+
raise ValidationError("control.mode", "joint_servo or joint_torque", self.mode) from error
|
|
249
|
+
_validate_positive_number(self.period_s, "control.period_s")
|
|
250
|
+
_validate_positive_number(self.state_timeout_s, "control.state_timeout_s")
|
|
251
|
+
if self.quaternion_order != "xyzw":
|
|
252
|
+
raise ValidationError("control.quaternion_order", "xyzw", self.quaternion_order)
|
|
253
|
+
if self.base_orientation != "body_to_world":
|
|
254
|
+
raise ValidationError("control.base_orientation", "body_to_world", self.base_orientation)
|
|
255
|
+
if self.angular_velocity_frame != "body":
|
|
256
|
+
raise ValidationError("control.angular_velocity_frame", "body", self.angular_velocity_frame)
|
|
257
|
+
|
|
258
|
+
def to_dict(self) -> dict[str, Any]:
|
|
259
|
+
return {
|
|
260
|
+
"mode": self.mode.value,
|
|
261
|
+
"period_s": self.period_s,
|
|
262
|
+
"state_timeout_s": self.state_timeout_s,
|
|
263
|
+
"quaternion_order": self.quaternion_order,
|
|
264
|
+
"base_orientation": self.base_orientation,
|
|
265
|
+
"angular_velocity_frame": self.angular_velocity_frame,
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
@classmethod
|
|
269
|
+
def from_dict(cls, value: object) -> "ControlSpec":
|
|
270
|
+
data = _mapping(value, "control")
|
|
271
|
+
required = {
|
|
272
|
+
"mode",
|
|
273
|
+
"period_s",
|
|
274
|
+
"state_timeout_s",
|
|
275
|
+
"quaternion_order",
|
|
276
|
+
"base_orientation",
|
|
277
|
+
"angular_velocity_frame",
|
|
278
|
+
}
|
|
279
|
+
_keys(data, path="control", required=required)
|
|
280
|
+
return cls(**data)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
@dataclass(frozen=True)
|
|
284
|
+
class PayloadSpec:
|
|
285
|
+
"""A task-owned binary payload (e.g. a motion-clip NPZ) with its checksum."""
|
|
286
|
+
|
|
287
|
+
path: str
|
|
288
|
+
sha256: str
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
@dataclass(frozen=True)
|
|
292
|
+
class DeploymentManifest:
|
|
293
|
+
"""Top-level deployment manifest with strict v1 component versions."""
|
|
294
|
+
|
|
295
|
+
schema_version: str
|
|
296
|
+
source: SourceSpec
|
|
297
|
+
policy: PolicySpec
|
|
298
|
+
robot: RobotSpec
|
|
299
|
+
task: TaskSpec
|
|
300
|
+
control: ControlSpec
|
|
301
|
+
payloads: tuple[PayloadSpec, ...] = ()
|
|
302
|
+
|
|
303
|
+
def __post_init__(self) -> None:
|
|
304
|
+
if self.schema_version != SCHEMA_VERSION:
|
|
305
|
+
raise ValidationError("schema_version", SCHEMA_VERSION, self.schema_version)
|
|
306
|
+
for field_name in ("input", "output"):
|
|
307
|
+
shape = getattr(self.policy, field_name).shape
|
|
308
|
+
if len(shape) != 2 or shape[0] != 1:
|
|
309
|
+
raise ValidationError(f"policy.{field_name}.shape", "(1, size): a single batch-1 vector", shape)
|
|
310
|
+
|
|
311
|
+
def to_dict(self) -> dict[str, Any]:
|
|
312
|
+
return {
|
|
313
|
+
"schema_version": self.schema_version,
|
|
314
|
+
"source": self.source.to_dict(),
|
|
315
|
+
"policy": self.policy.to_dict(),
|
|
316
|
+
"robot": _robot_to_dict(self.robot),
|
|
317
|
+
"task": self.task.to_dict(),
|
|
318
|
+
"control": self.control.to_dict(),
|
|
319
|
+
"payloads": [payload.__dict__ for payload in self.payloads],
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
@classmethod
|
|
323
|
+
def from_dict(cls, value: object) -> "DeploymentManifest":
|
|
324
|
+
data = _mapping(value, "manifest")
|
|
325
|
+
required = {"schema_version", "source", "policy", "robot", "task", "control"}
|
|
326
|
+
_keys(data, path="manifest", required=required, optional={"payloads"})
|
|
327
|
+
payloads = []
|
|
328
|
+
for entry in data.get("payloads", ()):
|
|
329
|
+
payload = _mapping(entry, "manifest.payloads")
|
|
330
|
+
_keys(payload, path="manifest.payloads", required={"path", "sha256"})
|
|
331
|
+
payloads.append(PayloadSpec(path=payload["path"], sha256=payload["sha256"]))
|
|
332
|
+
return cls(
|
|
333
|
+
schema_version=data["schema_version"],
|
|
334
|
+
source=SourceSpec.from_dict(data["source"]),
|
|
335
|
+
policy=PolicySpec.from_dict(data["policy"]),
|
|
336
|
+
robot=_robot_from_dict(data["robot"]),
|
|
337
|
+
task=TaskSpec.from_dict(data["task"]),
|
|
338
|
+
control=ControlSpec.from_dict(data["control"]),
|
|
339
|
+
payloads=tuple(payloads),
|
|
340
|
+
)
|
motrix_deploy/cli.py
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Copyright Motphys Technology Co., Ltd. 2025, 2026
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Hydra deployment rollout and artifact inspection entry points."""
|
|
5
|
+
|
|
6
|
+
import json
|
|
7
|
+
import math
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
import hydra
|
|
12
|
+
import numpy as np
|
|
13
|
+
from omegaconf import DictConfig, OmegaConf
|
|
14
|
+
from omegaconf.errors import OmegaConfBaseException
|
|
15
|
+
|
|
16
|
+
from motrix_deploy.artifact.io import inspect_artifact, read_artifact
|
|
17
|
+
from motrix_deploy.config import DeployRunConfig, SimRuntimeCfg
|
|
18
|
+
from motrix_deploy.errors import ArtifactError, ValidationError
|
|
19
|
+
from motrix_deploy.runtime.control import ControlSession
|
|
20
|
+
from motrix_deploy.runtime.factory import RuntimeCreateContext, create_hardware_runtime, create_simulation_runtime
|
|
21
|
+
from motrix_deploy.task import create_task, load_task_type
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def run(cfg: DeployRunConfig) -> int:
|
|
25
|
+
"""Run one deployment rollout from typed application configuration."""
|
|
26
|
+
from motrix_deploy.policy import OnnxPolicy
|
|
27
|
+
|
|
28
|
+
artifact = read_artifact(Path(cfg.artifact))
|
|
29
|
+
manifest = artifact.manifest
|
|
30
|
+
task_type = load_task_type(manifest.task.name)
|
|
31
|
+
default_duration_s = task_type.default_duration_s(manifest.task, manifest.control.period_s)
|
|
32
|
+
duration_s = cfg.duration_s if cfg.duration_s is not None else default_duration_s
|
|
33
|
+
steps = _duration_steps(duration_s, manifest.control.period_s)
|
|
34
|
+
if default_duration_s is not None and duration_s > default_duration_s + 1e-9:
|
|
35
|
+
raise ValueError("duration_s exceeds the task's finite playback budget")
|
|
36
|
+
policy = OnnxPolicy(artifact.policy_path, manifest.policy.input, manifest.policy.output)
|
|
37
|
+
task = create_task(manifest.task, manifest.robot, policy, steps=steps, artifact=artifact)
|
|
38
|
+
simulation = isinstance(cfg.runtime, SimRuntimeCfg)
|
|
39
|
+
spawn_pose = cfg.runtime.robot_init_key_pose if simulation else None
|
|
40
|
+
if simulation:
|
|
41
|
+
runtime = create_simulation_runtime(cfg.runtime.backend, cfg.runtime.build_runtime_config())
|
|
42
|
+
else:
|
|
43
|
+
runtime = create_hardware_runtime(
|
|
44
|
+
cfg.runtime.backend,
|
|
45
|
+
cfg.runtime,
|
|
46
|
+
RuntimeCreateContext(
|
|
47
|
+
robot=manifest.robot,
|
|
48
|
+
control=manifest.control,
|
|
49
|
+
),
|
|
50
|
+
)
|
|
51
|
+
robot = runtime.robot
|
|
52
|
+
device = runtime.keyboard or runtime.gamepad
|
|
53
|
+
try:
|
|
54
|
+
manifest.robot.validate_compatible(robot.spec)
|
|
55
|
+
command_binding = task.prepare(simulation=simulation, device=device, spawn_pose=spawn_pose)
|
|
56
|
+
session = ControlSession(
|
|
57
|
+
controller=task,
|
|
58
|
+
robot=robot,
|
|
59
|
+
command_binding=command_binding,
|
|
60
|
+
period_s=manifest.control.period_s,
|
|
61
|
+
state_timeout_s=manifest.control.state_timeout_s,
|
|
62
|
+
)
|
|
63
|
+
runtime.bind_session(session)
|
|
64
|
+
except (ValidationError, ValueError):
|
|
65
|
+
runtime.close()
|
|
66
|
+
raise
|
|
67
|
+
if task.operator_hint:
|
|
68
|
+
print(task.operator_hint)
|
|
69
|
+
with runtime:
|
|
70
|
+
result = runtime.run()
|
|
71
|
+
print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
|
|
72
|
+
return 0 if result.success else 1
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _duration_steps(duration_s: float | None, control_period_s: float) -> int | None:
|
|
76
|
+
"""Convert a control-time duration to a tick budget, not a wall-clock timeout."""
|
|
77
|
+
if duration_s is None:
|
|
78
|
+
return None
|
|
79
|
+
if isinstance(duration_s, bool) or not isinstance(duration_s, (int, float)):
|
|
80
|
+
raise ValueError(f"duration_s must be a positive finite number, got {duration_s!r}")
|
|
81
|
+
if not np.isfinite(duration_s) or duration_s <= 0:
|
|
82
|
+
raise ValueError(f"duration_s must be a positive finite number, got {duration_s!r}")
|
|
83
|
+
return math.ceil(duration_s / control_period_s)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _run_config(cfg: DictConfig) -> None:
|
|
87
|
+
try:
|
|
88
|
+
typed_cfg = OmegaConf.to_object(OmegaConf.merge(OmegaConf.structured(DeployRunConfig), cfg))
|
|
89
|
+
if not isinstance(typed_cfg, DeployRunConfig):
|
|
90
|
+
raise TypeError(f"Expected DeployRunConfig, got {type(typed_cfg).__name__}")
|
|
91
|
+
exit_code = run(typed_cfg)
|
|
92
|
+
except (ArtifactError, OmegaConfBaseException, RuntimeError, TypeError, ValidationError, ValueError) as error:
|
|
93
|
+
print(json.dumps({"valid": False, "error": str(error)}, sort_keys=True), file=sys.stderr)
|
|
94
|
+
raise SystemExit(2) from error
|
|
95
|
+
if exit_code:
|
|
96
|
+
raise SystemExit(exit_code)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
_hydra_main = hydra.main(version_base=None, config_path="pkg://motrix_deploy.config", config_name="deploy")(_run_config)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def inspect(cfg: DictConfig) -> None:
|
|
103
|
+
"""Validate one deployment artifact without opening a backend."""
|
|
104
|
+
print(json.dumps(inspect_artifact(Path(cfg.artifact)), indent=2, sort_keys=True))
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@hydra.main(version_base=None, config_path="pkg://motrix_deploy.config", config_name="inspect")
|
|
108
|
+
def _hydra_inspect_main(cfg: DictConfig) -> None:
|
|
109
|
+
try:
|
|
110
|
+
inspect(cfg)
|
|
111
|
+
except (ArtifactError, OmegaConfBaseException, RuntimeError, ValidationError, ValueError) as error:
|
|
112
|
+
print(json.dumps({"valid": False, "error": str(error)}, sort_keys=True), file=sys.stderr)
|
|
113
|
+
raise SystemExit(2) from error
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def main() -> None:
|
|
117
|
+
"""Adapt ``mxlab deploy`` arguments to the deployment Hydra commands."""
|
|
118
|
+
if sys.argv[1:2] == ["inspect"]:
|
|
119
|
+
sys.argv = [f"{sys.argv[0]} inspect", *sys.argv[2:]]
|
|
120
|
+
_hydra_inspect_main()
|
|
121
|
+
return
|
|
122
|
+
if not sys.argv[1:]:
|
|
123
|
+
sys.argv.append("--help")
|
|
124
|
+
_hydra_main()
|