simulo 0.29.0__tar.gz → 0.31.0__tar.gz

{simulo-0.29.0/src/simulo.egg-info → simulo-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.29.0
+Version: 0.31.0
 Summary: Python SDK and CLI for cloud-native robotics simulation, reinforcement learning, and robot policy training on managed GPUs.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -31,7 +31,7 @@ Classifier: Topic :: System :: Distributed Computing
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.22,>=0.21.0
+Requires-Dist: simulo-interfaces<0.23,>=0.22.0
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=26.5
@@ -92,14 +92,17 @@ Simulo requires Python 3.11 or newer. One installation provides both the
 simulo create mybot
 simulo login
 cd mybot
+simulo run preview.py --frozen --strict-assets
 simulo run train.py --frozen --strict-assets
+simulo run play.py --policy policy_<job>:best --frozen --strict-assets
 ```
 
 `simulo create` writes a complete starter application to your machine without
-requiring a login or network connection. It creates `task.py`, `train.py`, and
-`.simuloignore`; the default application trains a PPO policy on a validated cartpole
-asset. `simulo run` packages the source, resolves
-and pins its assets, submits the job, and follows its cloud logs.
+requiring a login or network connection. It creates `task.py`, `preview.py`,
+`train.py`, `play.py`, and `.simuloignore`. Run `preview.py` first as a separate
+job to check the validated cartpole asset in its task, run `train.py` to train a
+PPO policy, then pass that policy to `play.py`. `simulo run` packages the source,
+resolves and pins its assets, submits the job, and follows its cloud logs.
 
 ## Explore robotics samples
 

{simulo-0.29.0 → simulo-0.31.0}/PYPI.md

@@ -36,14 +36,17 @@ Simulo requires Python 3.11 or newer. One installation provides both the
 simulo create mybot
 simulo login
 cd mybot
+simulo run preview.py --frozen --strict-assets
 simulo run train.py --frozen --strict-assets
+simulo run play.py --policy policy_<job>:best --frozen --strict-assets
 ```
 
 `simulo create` writes a complete starter application to your machine without
-requiring a login or network connection. It creates `task.py`, `train.py`, and
-`.simuloignore`; the default application trains a PPO policy on a validated cartpole
-asset. `simulo run` packages the source, resolves
-and pins its assets, submits the job, and follows its cloud logs.
+requiring a login or network connection. It creates `task.py`, `preview.py`,
+`train.py`, `play.py`, and `.simuloignore`. Run `preview.py` first as a separate
+job to check the validated cartpole asset in its task, run `train.py` to train a
+PPO policy, then pass that policy to `play.py`. `simulo run` packages the source,
+resolves and pins its assets, submits the job, and follows its cloud logs.
 
 ## Explore robotics samples
 

{simulo-0.29.0 → simulo-0.31.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.29.0"
+version = "0.31.0"
 description = "Python SDK and CLI for cloud-native robotics simulation, reinforcement learning, and robot policy training on managed GPUs."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -59,7 +59,7 @@ classifiers = [
 # mcap: used by `simulo recordings` to read back a downloaded recording and
 # verify it (message count) — MIT-licensed, deps only lz4+zstandard.
 dependencies = [
-    "simulo-interfaces>=0.21.0,<0.22",
+    "simulo-interfaces>=0.22.0,<0.23",
     "mcap>=1.3,<2",
     # Hardened XML parsing for URDF ingestion (USD Asset Catalogs, PR-12 fix
     # loop 2, security NIT): stdlib xml.etree.ElementTree relies on

{simulo-0.29.0 → simulo-0.31.0}/src/simulo/__init__.py

@@ -92,6 +92,7 @@ from simulo.interfaces import (
     OrganizationId,
     OutputPublicId,
     PackageId,
+    PolicyNetworkProtocol,
     PolicyPublicId,
     ProjectId,
     RecordingPublicId,
@@ -141,6 +142,7 @@ from simulo.interfaces.authoring import (
     GroundPlane,
     LightConfig,
     PointMarker,
+    PolicyCheckpoint,
     PrimitiveShape,
     RigidPhysics,
     RoughTerrain,
@@ -185,6 +187,7 @@ __all__ = [
     "JobType",
     "JobPublicId",
     "PolicyPublicId",
+    "PolicyNetworkProtocol",
     "RecordingPublicId",
     "OutputPublicId",
     "parse_job_public_id",
@@ -251,7 +254,8 @@ __all__ = [
     "ParallelGripperActuator",
     "Physics",
     "Player",
-    "Policy",
+    "PolicyCheckpoint",
+    "PolicyNetwork",
     "Pose",
     "Prop",
     "RLPlayer",
@@ -273,6 +277,7 @@ __all__ = [
     "Trainer",
     "Visual",
     "World",
+    "preview",
     "save_output",
 ]
 
@@ -288,6 +293,7 @@ def __getattr__(name: str) -> object:
     if name in _LEARNING_NAMES:
         return _resolve_learning(name)
     removed_hints = {
+        "Policy": "simulo.Policy was removed. Load a checkpoint with checkpoint.load(), which returns a simulo.PolicyNetwork.",
         "Scenario": "simulo.Scenario was removed. Use a typed @app.job instead.",
         "run": "simulo.run was removed. Use `simulo run train.py` instead.",
     }
@@ -375,11 +381,12 @@ if TYPE_CHECKING:
     from simulo._client.facades import RLPlayer as RLPlayer
     from simulo._client.facades import RLTrainer as RLTrainer
     from simulo._client.facades import Robot as Robot
+    from simulo._client.facades import preview as preview
     from simulo.interfaces.authoring import SceneProtocol
     from simulo.interfaces.runtime import (
         ObservationComponentProtocol,
         PlayerProtocol,
-        PolicyProtocol,
+        PolicyNetworkProtocol,
         RewardComponentProtocol,
         TaskProtocol,
         TerminationConditionProtocol,
@@ -389,7 +396,7 @@ if TYPE_CHECKING:
     # Subclassable names alias their Protocol so ``class X(simulo.Task)`` is checked
     # against ``TaskProtocol``.
     Task = TaskProtocol
-    Policy = PolicyProtocol
+    PolicyNetwork = PolicyNetworkProtocol
     Player = PlayerProtocol
     Trainer = TrainerProtocol
     ObservationComponent = ObservationComponentProtocol

{simulo-0.29.0 → simulo-0.31.0}/src/simulo/_client/app.py

@@ -23,9 +23,11 @@ import atexit
 import contextlib
 import functools
 import hashlib
+import inspect
 import io
 import json
 import os
+import re
 import shlex
 import sys
 import types
@@ -157,6 +159,7 @@ def viewstream_requested(enabled: bool) -> Iterator[None]:
 # ---------------------------------------------------------------------------
 
 _INPUT_CHECKPOINT_REF: Optional[str] = None
+_INPUT_CHECKPOINT_FLAG = "--from"
 
 
 class InputCheckpointRequiresCloudError(RuntimeError):
@@ -171,15 +174,18 @@ class InputCheckpointRequiresCloudError(RuntimeError):
 
 
 @contextlib.contextmanager
-def input_checkpoint_requested(checkpoint_ref: Optional[str]) -> Iterator[None]:
-    """Scope ``--from``'s checkpoint reference for one ``simulo run`` submit call."""
-    global _INPUT_CHECKPOINT_REF
+def input_checkpoint_requested(checkpoint_ref: Optional[str], *, flag: str = "--from") -> Iterator[None]:
+    """Scope one checkpoint flag's reference for one ``simulo run`` submit call."""
+    global _INPUT_CHECKPOINT_REF, _INPUT_CHECKPOINT_FLAG
     previous = _INPUT_CHECKPOINT_REF
+    previous_flag = _INPUT_CHECKPOINT_FLAG
     _INPUT_CHECKPOINT_REF = checkpoint_ref
+    _INPUT_CHECKPOINT_FLAG = flag
     try:
         yield
     finally:
         _INPUT_CHECKPOINT_REF = previous
+        _INPUT_CHECKPOINT_FLAG = previous_flag
 
 
 # ---------------------------------------------------------------------------
@@ -283,15 +289,16 @@ class PreflightBlockedError(RuntimeError):
 
 
 def _require_no_input_checkpoint_for_local_submit(reason: str) -> None:
-    """Refuse a local-disk submit that carries an ambient ``--from`` checkpoint."""
+    """Refuse a local-disk submit that carries an ambient checkpoint reference."""
     if _INPUT_CHECKPOINT_REF is None:
         return
+    retry = "" if _INPUT_CHECKPOINT_FLAG == "--policy" else f", or drop {_INPUT_CHECKPOINT_FLAG}"
     raise InputCheckpointRequiresCloudError(
-        f"--from {_INPUT_CHECKPOINT_REF!r} needs a cloud control plane to resolve the checkpoint, but "
-        f"{reason}. A local-disk submit only writes the package and cannot continue from a policy "
-        "checkpoint, so the run would silently start fresh instead. Log in first "
+        f"{_INPUT_CHECKPOINT_FLAG} {_INPUT_CHECKPOINT_REF!r} needs a cloud control plane to resolve the checkpoint, but "
+        f"{reason}. A local-disk submit only writes the package and cannot use a policy "
+        "checkpoint, so the run would not honor the selected policy. Log in first "
         "(`simulo login`) or point SIMULO_API_URL/SIMULO_ENV at a control plane (and unset "
-        "SIMULO_SUBMIT=local), or drop --from for a fresh local run."
+        f"SIMULO_SUBMIT=local){retry}."
     )
 
 
@@ -304,6 +311,7 @@ class JobSpec:
     qualname: str
     fn: Callable[..., object]
     job_type: JobType
+    policy_param: Optional[str] = None
     resources: dict[str, Any] = field(default_factory=dict)
     timeout: Optional[int] = None
     retries: int = 0
@@ -311,6 +319,26 @@ class JobSpec:
     mounts: dict[str, Mount] = field(default_factory=dict)
 
 
+_POLICY_CHECKPOINT_ANNOTATION = re.compile(r"\bPolicyCheckpoint\b")
+
+
+def _is_policy_checkpoint_annotation(annotation: object) -> bool:
+    """Whether an annotation names the runner-injected checkpoint type."""
+    if annotation is inspect.Parameter.empty:
+        return False
+    text = annotation if isinstance(annotation, str) else repr(annotation)
+    return bool(_POLICY_CHECKPOINT_ANNOTATION.search(text))
+
+
+def _policy_checkpoint_declaration_error(func: Callable[..., object], job_type: JobType) -> JobDeclarationError:
+    label = "Play" if job_type is JobType.PLAY else "Eval"
+    return JobDeclarationError(
+        f"{label} job {func.__name__!r} in {Path(func.__code__.co_filename).name} must take one "
+        "simulo.PolicyCheckpoint parameter, for example `def play(policy: simulo.PolicyCheckpoint, "
+        "episodes: int = 3)`."
+    )
+
+
 def _app_source_location(module_name: str) -> tuple[Path, Path]:
     """Resolve the on-disk app file (and its directory) for a job's module.
 
@@ -361,7 +389,7 @@ def _skip_preflight_hint(blocking: "Sequence[PreflightFinding]") -> str:
     docstring rule ("a blocking finding can never become an unbypassable
     wall") is unchanged.
 
-    ``runtime_not_available`` is the one exception, and only the ADVICE
+    ``runtime_not_available`` is one of two exceptions, and only the ADVICE
     changes, not the flag's behavior. The generic hint's two stated reasons
     to bypass are "preflight is wrong about your app" and "the platform is
     unreachable" — this finding is neither: it fires only when the
@@ -388,8 +416,17 @@ def _skip_preflight_hint(blocking: "Sequence[PreflightFinding]") -> str:
     the whole raise even when an ordinary, safely-bypassable finding is also
     blocking alongside it — bypassing would still re-enable that finding's
     harm too.
+
+    ``intake_paused`` comes first, ahead of ``runtime_not_available``:
+    while Simulo staff have paused job intake, ``--skip-preflight`` only
+    uploads the package before ``create_job`` refuses with the same
+    ``intake_paused``, so the hint says to try again later and never
+    names the flag.
     """
-    from simulo._client.preflight_render import RUNTIME_NOT_AVAILABLE_CODE
+    from simulo._client.preflight_render import INTAKE_PAUSED_CODE, RUNTIME_NOT_AVAILABLE_CODE
+
+    if any(finding.code == INTAKE_PAUSED_CODE for finding in blocking):
+        return "Simulo has paused new jobs, so skipping preflight won't help until intake resumes; try again later."
 
     if any(finding.code == RUNTIME_NOT_AVAILABLE_CODE for finding in blocking):
         return (
@@ -828,6 +865,20 @@ class JobFunction:
         return self.spawn(**kwargs).job_id
 
 
+def _policy_checkpoint_parameters(fn: Callable[..., object]) -> list[str]:
+    """Names of ``fn``'s parameters annotated with ``simulo.PolicyCheckpoint``.
+
+    Matched on the annotation's text, not its identity: the annotation may be a
+    string (``from __future__ import annotations``) that discovery never
+    evaluates, and an ``Optional[...]`` or ``| None`` spelling still names it.
+    """
+    names = []
+    for parameter in inspect.signature(fn).parameters.values():
+        if _is_policy_checkpoint_annotation(parameter.annotation):
+            names.append(parameter.name)
+    return names
+
+
 def _cli_redirect_message() -> str:
     """The ONE stderr message for a direct ``python app.py`` run — both guard paths.
 
@@ -1327,12 +1378,34 @@ class App:
             if system is not None:
                 resources["system"] = system.value
             resources.update(extra)
+            policy_params = [
+                name
+                for name, parameter in inspect.signature(func).parameters.items()
+                if _is_policy_checkpoint_annotation(parameter.annotation)
+            ]
+            policy_param: Optional[str] = None
+            if resolved_job_type in (JobType.PLAY, JobType.EVAL):
+                if len(policy_params) != 1:
+                    raise _policy_checkpoint_declaration_error(func, resolved_job_type)
+                policy_param = policy_params[0]
+                policy_parameter = inspect.signature(func).parameters[policy_param]
+                if policy_parameter.default is not inspect.Parameter.empty or policy_parameter.kind not in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.KEYWORD_ONLY,
+                ):
+                    raise _policy_checkpoint_declaration_error(func, resolved_job_type)
+            elif policy_params and resolved_job_type is not JobType.PREVIEW:
+                raise JobDeclarationError(
+                    f"{resolved_job_type.value.title()} job {func.__name__!r} in {location} cannot take a "
+                    "simulo.PolicyCheckpoint parameter. Only play and eval jobs receive a policy checkpoint."
+                )
             spec = JobSpec(
                 name=func.__name__,
                 module=func.__module__,
                 qualname=func.__qualname__,
                 fn=func,
                 job_type=resolved_job_type,
+                policy_param=policy_param,
                 resources=resources,
                 timeout=timeout,
                 retries=retries,
@@ -1393,11 +1466,16 @@ class App:
             )
 
         if spec.job_type is JobType.PREVIEW:
-            raise JobDeclarationError("preview isn't available yet. Use a train job for now.")
+            policy_parameters = _policy_checkpoint_parameters(spec.fn)
+            if policy_parameters:
+                names = ", ".join(policy_parameters)
+                raise JobDeclarationError(
+                    f"Preview job {job_name!r} in {where} has a simulo.PolicyCheckpoint parameter ({names}), "
+                    "but a preview job takes no policy. Remove it; a policy goes to a play or eval file "
+                    "with --policy."
+                )
         if spec.job_type is JobType.EVAL:
             raise JobDeclarationError("evaluation isn't available yet. Use a train job for now.")
-        if spec.job_type is JobType.PLAY:
-            raise JobDeclarationError("play isn't available yet. It arrives with --policy.")
         if spec.job_type is JobType.ASSET_VALIDATION:
             raise JobDeclarationError("Asset validation runs when you publish an asset: simulo asset publish.")
         if spec.job_type is JobType.EXPORT: