motrix-rl 0.4.0b0__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_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,26 @@
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
+ from typing import TypeVar
8
+
9
+ from omegaconf import DictConfig, OmegaConf
10
+
11
+ logger = logging.getLogger(__name__)
12
+
13
+ CfgT = TypeVar("CfgT")
14
+
15
+
16
+ def to_typed_config(cfg: DictConfig, expected_type: type[CfgT]) -> CfgT:
17
+ """Convert a Hydra ``DictConfig`` to its registered dataclass schema.
18
+
19
+ Hydra always calls ``@hydra.main`` with a ``DictConfig``. This helper keeps
20
+ that dynamic value at the CLI boundary and gives the rest of the application
21
+ a real dataclass with static field types.
22
+ """
23
+ obj = OmegaConf.to_object(cfg)
24
+ if not isinstance(obj, expected_type):
25
+ raise TypeError(f"Expected {expected_type.__name__}, got {type(obj).__name__}")
26
+ return obj
motrix_rl/config.py ADDED
@@ -0,0 +1,140 @@
1
+ # Copyright Motphys Technology Co., Ltd. 2025, 2026
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Structured configuration types shared by CLI and runtime code."""
5
+
6
+ import math
7
+ from dataclasses import dataclass, field
8
+ from typing import Any
9
+
10
+ from hydra.core.config_store import ConfigStore
11
+ from omegaconf import MISSING
12
+
13
+
14
+ @dataclass
15
+ class LoggingConfig:
16
+ """Framework-neutral training log settings."""
17
+
18
+ backend: str = MISSING
19
+ interval: int = MISSING
20
+
21
+
22
+ @dataclass
23
+ class CheckpointConfig:
24
+ """Framework-neutral periodic checkpoint settings."""
25
+
26
+ interval: int = MISSING
27
+
28
+
29
+ @dataclass
30
+ class OnnxParityConfig:
31
+ """Numerical parity settings applied to every exported ONNX policy."""
32
+
33
+ seed: int = 1
34
+ samples: int = 32
35
+ atol: float = 1e-4
36
+ rtol: float = 1e-5
37
+
38
+ def __post_init__(self) -> None:
39
+ if self.samples <= 0:
40
+ raise ValueError(f"validation samples must be positive, got {self.samples}")
41
+ if not math.isfinite(self.atol) or not math.isfinite(self.rtol) or self.atol < 0 or self.rtol < 0:
42
+ raise ValueError(f"validation tolerances must be non-negative, got atol={self.atol}, rtol={self.rtol}")
43
+
44
+
45
+ @dataclass
46
+ class OnnxExportConfig:
47
+ """Typed Hydra configuration for the ONNX export CLI."""
48
+
49
+ run_dir: str = MISSING
50
+ output: str | None = None
51
+ opset: int = 18
52
+ parity: OnnxParityConfig = field(default_factory=OnnxParityConfig)
53
+
54
+
55
+ @dataclass
56
+ class DeploymentExportConfig:
57
+ """Typed Hydra configuration for deployment artifact export."""
58
+
59
+ env: str | None = None
60
+ run: str | None = None
61
+ output: str | None = None
62
+ validation: OnnxParityConfig = field(
63
+ default_factory=lambda: OnnxParityConfig(atol=1e-5),
64
+ )
65
+
66
+
67
+ @dataclass
68
+ class TaskMeta:
69
+ """Method and environment selected by one Hydra task recipe."""
70
+
71
+ env: str = MISSING
72
+ rllib: str = MISSING
73
+ algo: str = MISSING
74
+ train_backend: str | None = None
75
+
76
+
77
+ @dataclass
78
+ class TaskConfig:
79
+ """A composed task recipe with runtime policy and algorithm config."""
80
+
81
+ task: TaskMeta = MISSING
82
+ num_envs: int = MISSING
83
+ play_num_envs: int = MISSING
84
+ seed: int | None = MISSING
85
+ logging: LoggingConfig = MISSING
86
+ checkpoint: CheckpointConfig = MISSING
87
+ # The selected algo base supplies the concrete provider-owned dataclass.
88
+ algo: Any = MISSING
89
+
90
+
91
+ @dataclass
92
+ class TrainConfig(TaskConfig):
93
+ """Top-level schema for ``scripts/train.py``."""
94
+
95
+ render: bool = False
96
+ play: bool = False
97
+ sim: str | None = None
98
+ resume: str | None = None
99
+
100
+
101
+ @dataclass
102
+ class PlayConfig:
103
+ """Top-level schema for ``scripts/play.py``."""
104
+
105
+ env: str | None = None
106
+ sim: str | None = None
107
+ policy: str | None = None
108
+ num_envs: int | None = None
109
+ seed: int | None = None
110
+ rand_seed: bool = False
111
+ record_video: bool = False
112
+ record_seconds: float = 10.0
113
+ record_width: int = 256
114
+ record_height: int = 256
115
+ # Deprecated for play; only used to filter metadata-backed runs.
116
+ rllib: str | None = None
117
+ rl: Any = field(default_factory=dict)
118
+
119
+
120
+ @dataclass
121
+ class ViewConfig:
122
+ """Top-level schema for ``scripts/view.py``."""
123
+
124
+ env: str | None = None
125
+ robot: str | None = None
126
+ sim: str | None = None
127
+ num_envs: int = 1
128
+
129
+
130
+ def register_configs() -> None:
131
+ """Register CLI schemas in Hydra's ConfigStore. Idempotent."""
132
+ cs = ConfigStore.instance()
133
+ cs.store(name="train_schema", node=TrainConfig)
134
+ cs.store(name="play_schema", node=PlayConfig)
135
+ cs.store(name="view_schema", node=ViewConfig)
136
+ cs.store(name="export_onnx_schema", node=OnnxExportConfig)
137
+ cs.store(name="export_deploy_schema", node=DeploymentExportConfig)
138
+
139
+
140
+ register_configs()