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.
@@ -0,0 +1,8 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Framework-independent robot policy deployment runtime."""
5
+
6
+ from importlib.metadata import version
7
+
8
+ __version__ = version("motrix-deploy")
@@ -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()