motrix-rl 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.
Files changed (44) hide show
  1. motrix_rl/__init__.py +22 -0
  2. motrix_rl/backend_runtime.py +67 -0
  3. motrix_rl/checkpoints.py +281 -0
  4. motrix_rl/cli.py +56 -0
  5. motrix_rl/commands/__init__.py +4 -0
  6. motrix_rl/commands/export_deploy.py +66 -0
  7. motrix_rl/commands/export_onnx.py +57 -0
  8. motrix_rl/commands/play.py +130 -0
  9. motrix_rl/commands/searchpath.py +26 -0
  10. motrix_rl/commands/train.py +55 -0
  11. motrix_rl/config.py +129 -0
  12. motrix_rl/configs/__init__.py +4 -0
  13. motrix_rl/configs/algo_base/motrix.fastsac.yaml +130 -0
  14. motrix_rl/configs/algo_base/rslrl.ppo.yaml +88 -0
  15. motrix_rl/configs/algo_base/skrl.ppo.yaml +108 -0
  16. motrix_rl/configs/export_deploy.yaml +20 -0
  17. motrix_rl/configs/export_onnx.yaml +20 -0
  18. motrix_rl/configs/play.yaml +18 -0
  19. motrix_rl/configs/train.yaml +33 -0
  20. motrix_rl/console.py +889 -0
  21. motrix_rl/contracts.py +256 -0
  22. motrix_rl/deploy/__init__.py +132 -0
  23. motrix_rl/deploy/api.py +132 -0
  24. motrix_rl/deploy/onnx.py +119 -0
  25. motrix_rl/deploy/onnx_validation.py +88 -0
  26. motrix_rl/deploy/service.py +100 -0
  27. motrix_rl/deploy/source_rollout.py +72 -0
  28. motrix_rl/device.py +22 -0
  29. motrix_rl/frameworks.py +217 -0
  30. motrix_rl/method.py +30 -0
  31. motrix_rl/metrics.py +515 -0
  32. motrix_rl/numa.py +473 -0
  33. motrix_rl/plugins.py +21 -0
  34. motrix_rl/py.typed +0 -0
  35. motrix_rl/result.py +50 -0
  36. motrix_rl/runner.py +207 -0
  37. motrix_rl/runs.py +270 -0
  38. motrix_rl/system_metrics.py +552 -0
  39. motrix_rl/training_logger.py +91 -0
  40. motrix_rl/utils.py +93 -0
  41. motrix_rl-0.4.0.dist-info/METADATA +215 -0
  42. motrix_rl-0.4.0.dist-info/RECORD +44 -0
  43. motrix_rl-0.4.0.dist-info/WHEEL +4 -0
  44. motrix_rl-0.4.0.dist-info/licenses/LICENSE +204 -0
motrix_rl/__init__.py ADDED
@@ -0,0 +1,22 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from .contracts import (
5
+ AgentProvider,
6
+ AgentRegistration,
7
+ RlFramework,
8
+ TrainerBase,
9
+ TrainerContext,
10
+ TrainerHandle,
11
+ )
12
+ from .frameworks import register_framework
13
+
14
+ __all__ = [
15
+ "AgentProvider",
16
+ "AgentRegistration",
17
+ "RlFramework",
18
+ "TrainerBase",
19
+ "TrainerContext",
20
+ "TrainerHandle",
21
+ "register_framework",
22
+ ]
@@ -0,0 +1,67 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from motrix_rl import frameworks, utils
5
+ from motrix_rl.method import RlMethod
6
+
7
+ BACKEND_PREFERENCE = ("jax", "torch")
8
+
9
+
10
+ def resolve_train_backend(
11
+ env_name: str,
12
+ method: RlMethod,
13
+ requested_backend: str | None,
14
+ device_supports: utils.DeviceSupports,
15
+ ) -> str:
16
+ """Resolve the training backend for an RL method.
17
+
18
+ Args:
19
+ env_name: Registered environment name.
20
+ method: Requested RL method.
21
+ requested_backend: Backend requested by the user, or None for auto selection.
22
+ device_supports: Runtime support information for built-in backends.
23
+ """
24
+ if requested_backend is not None:
25
+ _validate_backend(method, requested_backend, device_supports)
26
+ return requested_backend
27
+
28
+ framework = frameworks.get_framework(method.rllib)
29
+ candidates = [
30
+ backend
31
+ for backend in framework.supported_train_backends(method.algo)
32
+ if _backend_available(backend, device_supports)
33
+ ]
34
+ if not candidates:
35
+ raise ValueError(
36
+ f"No available train backend for environment '{env_name}', RL method '{method.rllib}.{method.algo}'."
37
+ )
38
+ return _choose_preferred_backend(candidates)
39
+
40
+
41
+ def _validate_backend(
42
+ method: RlMethod,
43
+ backend: str,
44
+ device_supports: utils.DeviceSupports,
45
+ ) -> None:
46
+ provider = frameworks.get_agent_provider(method.rllib, method.algo, backend)
47
+ if provider is None:
48
+ raise ValueError(
49
+ f"No trainer found for RL framework '{method.rllib}', train backend '{backend}', algorithm '{method.algo}'."
50
+ )
51
+ if not _backend_available(backend, device_supports):
52
+ raise ValueError(f"Train backend '{backend}' is not available on this device.")
53
+
54
+
55
+ def _backend_available(backend: str, device_supports: utils.DeviceSupports) -> bool:
56
+ if backend == "jax":
57
+ return device_supports.jax
58
+ if backend == "torch":
59
+ return device_supports.torch
60
+ return True
61
+
62
+
63
+ def _choose_preferred_backend(candidates: list[str]) -> str:
64
+ for preferred in BACKEND_PREFERENCE:
65
+ if preferred in candidates:
66
+ return preferred
67
+ return sorted(candidates)[0]
@@ -0,0 +1,281 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ import json
5
+ import logging
6
+ import os
7
+ from dataclasses import dataclass, field
8
+ from enum import Enum
9
+ from pathlib import Path
10
+
11
+ from motrix_rl.runs import CHECKPOINTS_DIRNAME, RunMetadata, read_metadata
12
+
13
+ logger = logging.getLogger(__name__)
14
+
15
+ MANIFEST_FILENAME = "manifest.json"
16
+ BEST_POLICY = "best_policy"
17
+ LATEST_TRAINING_STATE = "latest_training_state"
18
+
19
+
20
+ class CheckpointArtifactKind(str, Enum):
21
+ """Built-in checkpoint artifact kinds understood by MotrixLab."""
22
+
23
+ POLICY = "policy"
24
+ TRAINING_STATE = "training_state"
25
+
26
+
27
+ TRAINING_STATE = CheckpointArtifactKind.TRAINING_STATE
28
+ POLICY = CheckpointArtifactKind.POLICY
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class CheckpointArtifact:
33
+ """A checkpoint artifact recorded in checkpoints/manifest.json.
34
+
35
+ Attributes:
36
+ path: Checkpoint file path. Relative paths are stored from the
37
+ directory containing ``manifest.json``.
38
+ kind: Artifact semantics, such as ``policy`` for playback/export or
39
+ ``training_state`` for resume.
40
+ format: Optional checkpoint storage format, such as ``pt`` or ``pickle``.
41
+ """
42
+
43
+ path: Path
44
+ kind: CheckpointArtifactKind
45
+ format: str | None = None
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class CheckpointManifest:
50
+ """Run-local checkpoint manifest.
51
+
52
+ Artifact paths are stored relative to checkpoints/manifest.json.
53
+ """
54
+
55
+ version: int = 1
56
+ artifacts: dict[str, CheckpointArtifact] = field(default_factory=dict)
57
+
58
+
59
+ def manifest_path(run_dir: Path | str) -> Path:
60
+ """Return the standard checkpoint manifest path for a run directory.
61
+
62
+ Args:
63
+ run_dir: Root directory of a training run.
64
+ """
65
+ return Path(run_dir) / CHECKPOINTS_DIRNAME / MANIFEST_FILENAME
66
+
67
+
68
+ def standard_checkpoint_dir(run_dir: Path | str) -> Path:
69
+ """Return the standard checkpoint artifact directory for a run directory.
70
+
71
+ Args:
72
+ run_dir: Root directory of a training run.
73
+ """
74
+ return Path(run_dir) / CHECKPOINTS_DIRNAME
75
+
76
+
77
+ def read_manifest(run_dir: Path | str) -> CheckpointManifest:
78
+ """Read checkpoints/manifest.json from a run directory.
79
+
80
+ Args:
81
+ run_dir: Root directory of a training run.
82
+ """
83
+ data = json.loads(manifest_path(run_dir).read_text(encoding="utf-8"))
84
+ artifacts = {name: _artifact_from_dict(artifact) for name, artifact in data.get("artifacts", {}).items()}
85
+ return CheckpointManifest(version=data.get("version", 1), artifacts=artifacts)
86
+
87
+
88
+ def write_manifest(run_dir: Path | str, manifest: CheckpointManifest) -> Path:
89
+ """Write checkpoints/manifest.json for a run directory.
90
+
91
+ Args:
92
+ run_dir: Root directory of a training run.
93
+ manifest: Manifest content to serialize.
94
+ """
95
+ path = manifest_path(run_dir)
96
+ path.parent.mkdir(parents=True, exist_ok=True)
97
+ data = {
98
+ "version": manifest.version,
99
+ "artifacts": {name: _artifact_to_dict(artifact) for name, artifact in manifest.artifacts.items()},
100
+ }
101
+ path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
102
+ return path
103
+
104
+
105
+ def record_checkpoint_artifact(
106
+ run_dir: Path | str,
107
+ name: str,
108
+ path: Path | str,
109
+ kind: CheckpointArtifactKind,
110
+ checkpoint_format: str | None = None,
111
+ ) -> Path:
112
+ """Record a checkpoint artifact in the run-local manifest.
113
+
114
+ Args:
115
+ run_dir: Root directory of a training run.
116
+ name: Logical artifact name, such as ``best_policy`` or ``latest_training_state``.
117
+ path: Checkpoint file path to record.
118
+ kind: Artifact kind, such as ``CheckpointArtifactKind.POLICY``.
119
+ checkpoint_format: Optional storage format. If omitted, the file suffix is used.
120
+ """
121
+ manifest = _read_manifest_or_empty(run_dir)
122
+ artifacts = dict(manifest.artifacts)
123
+ artifacts[name] = CheckpointArtifact(
124
+ path=_relative_to_manifest(run_dir, path),
125
+ kind=kind,
126
+ format=_normalize_checkpoint_format(checkpoint_format or Path(path).suffix),
127
+ )
128
+ return write_manifest(run_dir, CheckpointManifest(version=manifest.version, artifacts=artifacts))
129
+
130
+
131
+ def final_checkpoint_path(checkpoint_format_or_metadata: RunMetadata | str, run_dir: Path | str) -> Path:
132
+ """Return the standard final training-state checkpoint path for a run.
133
+
134
+ Args:
135
+ checkpoint_format_or_metadata: Checkpoint format suffix, or run metadata
136
+ providing the checkpoint format.
137
+ run_dir: Root directory of a training run.
138
+ """
139
+ if isinstance(checkpoint_format_or_metadata, RunMetadata):
140
+ checkpoint_format = checkpoint_format_or_metadata.checkpoint_format
141
+ else:
142
+ checkpoint_format = checkpoint_format_or_metadata
143
+ return standard_checkpoint_dir(run_dir) / f"latest.{checkpoint_format.lstrip('.')}"
144
+
145
+
146
+ def best_policy(metadata: RunMetadata, run_dir: Path | str) -> Path:
147
+ """Resolve the best playable policy for a run.
148
+
149
+ Args:
150
+ metadata: Run metadata for the run being queried.
151
+ run_dir: Root directory of a training run.
152
+ """
153
+ run_dir = Path(run_dir)
154
+ manifest_policy = _artifact_path(run_dir, BEST_POLICY) or _artifact_path(run_dir, LATEST_TRAINING_STATE)
155
+ if manifest_policy is not None:
156
+ return manifest_policy
157
+
158
+ raise FileNotFoundError(
159
+ f"No '{BEST_POLICY}' or '{LATEST_TRAINING_STATE}' artifact found in {manifest_path(run_dir)} "
160
+ f"for {metadata.rllib}.{metadata.algo} ({metadata.train_backend})."
161
+ )
162
+
163
+
164
+ def resume_checkpoint(run_dir: Path | str, metadata: RunMetadata | None = None) -> Path:
165
+ """Resolve the checkpoint to use when resuming from a run directory.
166
+
167
+ Args:
168
+ run_dir: Root directory of a training run.
169
+ metadata: Optional run metadata.
170
+ """
171
+ run_dir = Path(run_dir)
172
+ resume_path = _artifact_path(run_dir, LATEST_TRAINING_STATE) or _artifact_path(run_dir, BEST_POLICY)
173
+ if resume_path is not None:
174
+ return resume_path
175
+
176
+ metadata = metadata or read_metadata(run_dir)
177
+ raise FileNotFoundError(
178
+ f"No '{LATEST_TRAINING_STATE}' or '{BEST_POLICY}' artifact found in {manifest_path(run_dir)} "
179
+ f"for {metadata.rllib}.{metadata.algo} ({metadata.train_backend})."
180
+ )
181
+
182
+
183
+ def resolve_checkpoint_path(checkpoint_or_run_dir: Path | str, metadata: RunMetadata | None = None) -> Path:
184
+ """Resolve a policy checkpoint file or run directory to a concrete policy file.
185
+
186
+ Args:
187
+ checkpoint_or_run_dir: Existing checkpoint file path, or run directory to resolve.
188
+ metadata: Optional run metadata used when ``checkpoint_or_run_dir`` is a run directory.
189
+ """
190
+ path = Path(checkpoint_or_run_dir)
191
+ if path.is_file():
192
+ return path
193
+ if not path.exists():
194
+ raise FileNotFoundError(f"Checkpoint path does not exist: {path}")
195
+ if not path.is_dir():
196
+ raise FileNotFoundError(f"Checkpoint path is neither a file nor a run directory: {path}")
197
+
198
+ run_metadata = metadata or read_metadata(path)
199
+ return best_policy(run_metadata, path)
200
+
201
+
202
+ def resolve_resume_checkpoint_path(checkpoint_or_run_dir: Path | str, metadata: RunMetadata | None = None) -> Path:
203
+ """Resolve a resume checkpoint file or run directory to a concrete training-state file.
204
+
205
+ Args:
206
+ checkpoint_or_run_dir: Existing checkpoint file path, or run directory to resolve.
207
+ metadata: Optional run metadata used when ``checkpoint_or_run_dir`` is a run directory.
208
+ """
209
+ path = Path(checkpoint_or_run_dir)
210
+ if path.is_file():
211
+ return path
212
+ if not path.exists():
213
+ raise FileNotFoundError(f"Checkpoint path does not exist: {path}")
214
+ if not path.is_dir():
215
+ raise FileNotFoundError(f"Checkpoint path is neither a file nor a run directory: {path}")
216
+ return resume_checkpoint(path, metadata=metadata)
217
+
218
+
219
+ def _read_manifest_or_empty(run_dir: Path | str) -> CheckpointManifest:
220
+ try:
221
+ return read_manifest(run_dir)
222
+ except (FileNotFoundError, OSError, json.JSONDecodeError, TypeError, ValueError):
223
+ return CheckpointManifest()
224
+
225
+
226
+ def _artifact_path(run_dir: Path, name: str) -> Path | None:
227
+ try:
228
+ manifest = read_manifest(run_dir)
229
+ except (FileNotFoundError, OSError, json.JSONDecodeError, TypeError, ValueError):
230
+ return None
231
+
232
+ artifact = manifest.artifacts.get(name)
233
+ if artifact is None:
234
+ return None
235
+
236
+ path = _artifact_abs_path(run_dir, artifact)
237
+ if path.exists():
238
+ return path
239
+ logger.warning("Checkpoint artifact %s points to missing file: %s", name, path)
240
+ return None
241
+
242
+
243
+ def _artifact_abs_path(run_dir: Path | str, artifact: CheckpointArtifact) -> Path:
244
+ path = artifact.path
245
+ if path.is_absolute():
246
+ return path
247
+ return manifest_path(run_dir).parent / path
248
+
249
+
250
+ def _relative_to_manifest(run_dir: Path | str, path: Path | str) -> Path:
251
+ artifact_path = Path(path)
252
+ if not artifact_path.is_absolute():
253
+ artifact_path = (Path.cwd() / artifact_path).resolve()
254
+ manifest_dir = manifest_path(run_dir).parent.resolve()
255
+ try:
256
+ return artifact_path.relative_to(manifest_dir)
257
+ except ValueError:
258
+ return Path(os.path.relpath(artifact_path, manifest_dir))
259
+
260
+
261
+ def _artifact_from_dict(data: dict) -> CheckpointArtifact:
262
+ return CheckpointArtifact(
263
+ path=Path(data["path"]),
264
+ kind=CheckpointArtifactKind(data["kind"]),
265
+ format=data.get("format"),
266
+ )
267
+
268
+
269
+ def _artifact_to_dict(artifact: CheckpointArtifact) -> dict:
270
+ return {
271
+ "path": str(artifact.path),
272
+ "kind": artifact.kind.value,
273
+ "format": artifact.format,
274
+ }
275
+
276
+
277
+ def _normalize_checkpoint_format(checkpoint_format: str | None) -> str | None:
278
+ if checkpoint_format is None:
279
+ return None
280
+ normalized = checkpoint_format.lstrip(".").lower()
281
+ return normalized or None
motrix_rl/cli.py ADDED
@@ -0,0 +1,56 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Helpers for Hydra-based train/play/view command-line entry points."""
5
+
6
+ import logging
7
+ import sys
8
+ from collections.abc import Callable
9
+ from pathlib import Path
10
+ from typing import TypeVar
11
+
12
+ from hydra.core.plugins import Plugins
13
+ from omegaconf import DictConfig, OmegaConf
14
+
15
+ from motrix_rl.commands.searchpath import ProjectConfigSearchPath
16
+
17
+ logger = logging.getLogger(__name__)
18
+
19
+ CfgT = TypeVar("CfgT")
20
+
21
+
22
+ def run_cli(command: Callable[[], None]) -> None:
23
+ """Use the launch directory's configs unless Hydra receives an explicit path.
24
+
25
+ Pass the directory through Hydra's native --config-dir handling so package
26
+ configs remain available and Hydra controls composition and diagnostics.
27
+ """
28
+ Plugins.instance().register(ProjectConfigSearchPath)
29
+ args = sys.argv[1:]
30
+ explicit_path = any(
31
+ arg in ("--config-dir", "--config-path", "-cp") or arg.startswith(("--config-dir=", "--config-path=", "-cp="))
32
+ for arg in args
33
+ )
34
+ config_dir = Path.cwd() / "configs"
35
+ if explicit_path or not config_dir.is_dir():
36
+ command()
37
+ return
38
+ original_argv = sys.argv
39
+ sys.argv = [original_argv[0], "--config-dir", str(config_dir), *args]
40
+ try:
41
+ command()
42
+ finally:
43
+ sys.argv = original_argv
44
+
45
+
46
+ def to_typed_config(cfg: DictConfig, expected_type: type[CfgT]) -> CfgT:
47
+ """Convert a Hydra ``DictConfig`` to its registered dataclass schema.
48
+
49
+ Hydra always calls ``@hydra.main`` with a ``DictConfig``. This helper keeps
50
+ that dynamic value at the CLI boundary and gives the rest of the application
51
+ a real dataclass with static field types.
52
+ """
53
+ obj = OmegaConf.to_object(cfg)
54
+ if not isinstance(obj, expected_type):
55
+ raise TypeError(f"Expected {expected_type.__name__}, got {type(obj).__name__}")
56
+ return obj
@@ -0,0 +1,4 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Installed training and playback command-line entry points."""
@@ -0,0 +1,66 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Export a metadata-backed training run to a deployment artifact."""
5
+
6
+ import json
7
+ from pathlib import Path
8
+
9
+ import hydra
10
+ from omegaconf import DictConfig
11
+
12
+ from motrix_deploy.profile import build_deployment_profile
13
+ from motrix_rl.cli import run_cli, to_typed_config
14
+ from motrix_rl.config import DeploymentExportConfig
15
+ from motrix_rl.deploy import export_deploy_run
16
+ from motrix_rl.runs import latest_metadata_run, open_run_context
17
+
18
+
19
+ def run(cfg: DeploymentExportConfig) -> None:
20
+ """Export one training run using its environment deployment profile."""
21
+ run_dir, env_name = _resolve_run(cfg)
22
+ output = Path(cfg.output) if cfg.output is not None else Path("artifacts") / f"{env_name}.deploy"
23
+ result = export_deploy_run(
24
+ run_dir,
25
+ output,
26
+ profile_builder=build_deployment_profile,
27
+ validation_seed=cfg.validation.seed,
28
+ validation_samples=cfg.validation.samples,
29
+ atol=cfg.validation.atol,
30
+ rtol=cfg.validation.rtol,
31
+ )
32
+ print(
33
+ json.dumps(
34
+ {
35
+ "artifact": str(result.artifact.root),
36
+ "run": str(run_dir),
37
+ "validation_samples": result.validation_samples,
38
+ "max_abs_error": result.max_abs_error,
39
+ },
40
+ indent=2,
41
+ sort_keys=True,
42
+ )
43
+ )
44
+
45
+
46
+ def _resolve_run(cfg: DeploymentExportConfig) -> tuple[Path, str]:
47
+ if (cfg.env is None) == (cfg.run_dir is None):
48
+ raise ValueError("Exactly one of env and run_dir must be configured")
49
+ if cfg.run_dir is not None:
50
+ context = open_run_context(cfg.run_dir)
51
+ return context.run_dir, context.metadata.env_name
52
+ assert cfg.env is not None
53
+ selected = latest_metadata_run(cfg.env)
54
+ if selected is None:
55
+ raise FileNotFoundError(f"No metadata-backed training runs found for environment {cfg.env!r}")
56
+ run_dir, metadata = selected
57
+ return run_dir, metadata.env_name
58
+
59
+
60
+ @hydra.main(version_base=None, config_path="pkg://motrix_rl.configs", config_name="export_deploy")
61
+ def _hydra_main(cfg: DictConfig) -> None:
62
+ run(to_typed_config(cfg, DeploymentExportConfig))
63
+
64
+
65
+ def main() -> None:
66
+ run_cli(_hydra_main)
@@ -0,0 +1,57 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Export a metadata-backed MotrixLab policy to ONNX."""
5
+
6
+ import json
7
+
8
+ import hydra
9
+ from omegaconf import DictConfig
10
+
11
+ from motrix_rl.cli import run_cli, to_typed_config
12
+ from motrix_rl.config import OnnxExportConfig
13
+ from motrix_rl.deploy import export_onnx
14
+
15
+
16
+ def run(cfg: OnnxExportConfig) -> None:
17
+ """Export one metadata-backed run and print its persisted report."""
18
+ result = export_onnx(
19
+ cfg.run_dir,
20
+ cfg.output,
21
+ opset=cfg.opset,
22
+ validation_seed=cfg.parity.seed,
23
+ validation_samples=cfg.parity.samples,
24
+ atol=cfg.parity.atol,
25
+ rtol=cfg.parity.rtol,
26
+ )
27
+ print(
28
+ json.dumps(
29
+ {
30
+ "output": str(result.path),
31
+ "input": {
32
+ "name": result.report.input_spec.name,
33
+ "shape": result.report.input_spec.shape,
34
+ "dtype": result.report.input_spec.dtype,
35
+ },
36
+ "output_tensor": {
37
+ "name": result.report.output_spec.name,
38
+ "shape": result.report.output_spec.shape,
39
+ "dtype": result.report.output_spec.dtype,
40
+ },
41
+ "validation_samples": result.report.parity.samples,
42
+ "max_abs_error": result.report.parity.max_abs_error,
43
+ "max_rel_error": result.report.parity.max_rel_error,
44
+ },
45
+ indent=2,
46
+ sort_keys=True,
47
+ )
48
+ )
49
+
50
+
51
+ @hydra.main(version_base=None, config_path="pkg://motrix_rl.configs", config_name="export_onnx")
52
+ def _hydra_main(cfg: DictConfig) -> None:
53
+ run(to_typed_config(cfg, OnnxExportConfig))
54
+
55
+
56
+ def main() -> None:
57
+ run_cli(_hydra_main)
@@ -0,0 +1,130 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ import logging
5
+ from dataclasses import dataclass, replace
6
+ from pathlib import Path
7
+
8
+ import hydra
9
+ from omegaconf import DictConfig
10
+
11
+ from motrix_env_core.renderer import RenderConfig
12
+ from motrix_rl import checkpoints, runner, runs
13
+ from motrix_rl.cli import run_cli, to_typed_config
14
+ from motrix_rl.config import PlayConfig
15
+ from motrix_rl.runs import find_metadata_for_policy, latest_metadata_run
16
+
17
+ logger = logging.getLogger(__name__)
18
+
19
+ DEFAULT_ENV_NAME = "cartpole"
20
+ PLAY_RECORDING_FPS = 60
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class PlayTarget:
25
+ run: runs.RunContext
26
+ policy_path: Path
27
+
28
+
29
+ def _latest_play_target(env_name: str, rllib: str | None = None) -> PlayTarget:
30
+ metadata_run = latest_metadata_run(env_name, rllib=rllib)
31
+ if metadata_run is not None:
32
+ run_dir, metadata = metadata_run
33
+ logger.info(f"Auto-discovered RL run: {run_dir}")
34
+ return PlayTarget(
35
+ run=runs.open_run_context(run_dir, metadata),
36
+ policy_path=checkpoints.best_policy(metadata, run_dir),
37
+ )
38
+
39
+ if rllib is not None:
40
+ raise FileNotFoundError(
41
+ f"No metadata-backed training runs found for framework '{rllib}' and environment '{env_name}'"
42
+ )
43
+ raise FileNotFoundError(f"No metadata-backed training runs found for environment '{env_name}' in runs/{env_name}")
44
+
45
+
46
+ def _policy_play_target(
47
+ policy_path: str | Path,
48
+ requested_env_name: str | None,
49
+ sim: str | None = None,
50
+ ) -> PlayTarget:
51
+ policy_path = Path(policy_path)
52
+ logger.info(f"Using specified policy: {policy_path}")
53
+ metadata_result = find_metadata_for_policy(policy_path)
54
+ if metadata_result is None:
55
+ raise FileNotFoundError(
56
+ f"No metadata.json found for policy {policy_path}. Pass a policy from a metadata-backed run."
57
+ )
58
+
59
+ run_dir, metadata = metadata_result
60
+ if requested_env_name is not None and requested_env_name != metadata.env_name:
61
+ raise ValueError(f"env={requested_env_name!r} does not match policy metadata env {metadata.env_name!r}")
62
+ if sim is not None:
63
+ metadata = replace(metadata, sim=sim)
64
+ logger.info(f"Using policy metadata: {metadata.rllib}.{metadata.algo} ({metadata.train_backend})")
65
+ return PlayTarget(run=runs.open_run_context(run_dir, metadata), policy_path=policy_path)
66
+
67
+
68
+ def _resolve_play_target(cfg: PlayConfig) -> PlayTarget:
69
+ if cfg.policy is not None:
70
+ return _policy_play_target(cfg.policy, cfg.env, sim=cfg.sim)
71
+
72
+ rllib = cfg.rllib
73
+ if rllib is not None:
74
+ logger.warning("rllib= is deprecated for play and is only used to filter metadata-backed runs.")
75
+ logger.info(f"Using specified RL framework: {rllib}")
76
+
77
+ target = _latest_play_target(cfg.env or DEFAULT_ENV_NAME, rllib=rllib)
78
+ logger.info(f"Auto-discovered best policy: {target.policy_path}")
79
+ if cfg.sim is not None:
80
+ metadata = replace(target.run.metadata, sim=cfg.sim)
81
+ target = replace(target, run=runs.open_run_context(target.run.run_dir, metadata))
82
+ return target
83
+
84
+
85
+ def _play_render_config(target: PlayTarget, cfg: PlayConfig) -> RenderConfig:
86
+ if not cfg.record_video:
87
+ return RenderConfig()
88
+ if cfg.record_seconds <= 0.0:
89
+ raise ValueError(f"record_seconds must be positive, got {cfg.record_seconds}")
90
+ if cfg.record_width <= 0:
91
+ raise ValueError(f"record_width must be positive, got {cfg.record_width}")
92
+ if cfg.record_height <= 0:
93
+ raise ValueError(f"record_height must be positive, got {cfg.record_height}")
94
+ path = target.run.run_dir / "play_video.mp4"
95
+ num_frames = max(1, int(round(cfg.record_seconds * PLAY_RECORDING_FPS)))
96
+ return RenderConfig(
97
+ headless=True,
98
+ path=path,
99
+ fps=PLAY_RECORDING_FPS,
100
+ num_frames=num_frames,
101
+ width=cfg.record_width,
102
+ height=cfg.record_height,
103
+ )
104
+
105
+
106
+ def run(cfg: PlayConfig) -> None:
107
+ try:
108
+ target = _resolve_play_target(cfg)
109
+ render = _play_render_config(target, cfg)
110
+ trainer = runner.create_run_handle(
111
+ target.run,
112
+ cfg_override=cfg.rl,
113
+ play_num_envs=cfg.num_envs,
114
+ seed=cfg.seed,
115
+ randomize_seed=cfg.rand_seed,
116
+ render=render,
117
+ )
118
+ trainer.play(str(target.policy_path))
119
+ except (FileNotFoundError, ValueError) as e:
120
+ logger.error(f"Error: {e}")
121
+ logger.error("Please train a model first or specify a metadata-backed policy path")
122
+
123
+
124
+ @hydra.main(version_base=None, config_path="pkg://motrix_rl.configs", config_name="play")
125
+ def _hydra_main(cfg: DictConfig) -> None:
126
+ run(to_typed_config(cfg, PlayConfig))
127
+
128
+
129
+ def main() -> None:
130
+ run_cli(_hydra_main)