simulo 0.31.2__tar.gz → 0.32.0__tar.gz

{simulo-0.31.2/src/simulo.egg-info → simulo-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.31.2
+Version: 0.32.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.23,>=0.22.0
+Requires-Dist: simulo-interfaces<0.24,>=0.23.0
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=26.5
@@ -115,7 +115,7 @@ See the repository README for setup and usage.
 
 ```bash
 simulo jobs                       # list submitted jobs and status
-simulo logs --follow              # stream the latest job's logs
+simulo logs --follow              # stream logs from your most recent job you submitted (train, play, preview or eval)
 simulo result                     # read the job's result
 simulo policy list                # list training policies and checkpoints
 simulo policy get policy_x:best   # download a verified checkpoint
@@ -126,8 +126,8 @@ simulo view                       # view a running --viewstream job in 3D
 simulo cancel                     # stop a queued or running job
 ```
 
-Commands that accept a job ID default to the latest job and tell you which job
-they selected.
+Commands that accept a job ID default to the latest user-submitted job
+(`train`, `play`, `preview`, or `eval`) and tell you its ID and type.
 
 ## Use versioned robot assets
 

{simulo-0.31.2 → simulo-0.32.0}/PYPI.md

@@ -59,7 +59,7 @@ See the repository README for setup and usage.
 
 ```bash
 simulo jobs                       # list submitted jobs and status
-simulo logs --follow              # stream the latest job's logs
+simulo logs --follow              # stream logs from your most recent job you submitted (train, play, preview or eval)
 simulo result                     # read the job's result
 simulo policy list                # list training policies and checkpoints
 simulo policy get policy_x:best   # download a verified checkpoint
@@ -70,8 +70,8 @@ simulo view                       # view a running --viewstream job in 3D
 simulo cancel                     # stop a queued or running job
 ```
 
-Commands that accept a job ID default to the latest job and tell you which job
-they selected.
+Commands that accept a job ID default to the latest user-submitted job
+(`train`, `play`, `preview`, or `eval`) and tell you its ID and type.
 
 ## Use versioned robot assets
 

{simulo-0.31.2 → simulo-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.31.2"
+version = "0.32.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.22.0,<0.23",
+    "simulo-interfaces>=0.23.0,<0.24",
     "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.31.2 → simulo-0.32.0}/src/simulo/__init__.py

@@ -277,6 +277,7 @@ __all__ = [
     "Trainer",
     "Visual",
     "World",
+    "evaluate",
     "preview",
     "save_output",
 ]
@@ -381,6 +382,7 @@ 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 evaluate as evaluate
     from simulo._client.facades import preview as preview
     from simulo.interfaces.authoring import SceneProtocol
     from simulo.interfaces.runtime import (

{simulo-0.31.2 → simulo-0.32.0}/src/simulo/_client/_runner.py

@@ -92,6 +92,7 @@ class JobHandle:
         token: Optional[str] = None,
         job_type: Optional[JobType] = None,
         input_checkpoint: Optional[str] = None,
+        compare_checkpoint: Optional[str] = None,
         deferred_stdout: str = "",
         deferred_stderr: str = "",
     ) -> None:
@@ -104,6 +105,7 @@ class JobHandle:
         self._token = token
         self._job_type = job_type
         self._input_checkpoint = input_checkpoint
+        self._compare_checkpoint = compare_checkpoint
         self._deferred_stdout = deferred_stdout
         self._deferred_stderr = deferred_stderr
 
@@ -152,6 +154,11 @@ class JobHandle:
         """Policy checkpoint requested with ``simulo run --from``."""
         return self._input_checkpoint
 
+    @property
+    def compare_checkpoint(self) -> Optional[str]:
+        """Policy checkpoint requested with ``simulo run --compare``."""
+        return self._compare_checkpoint
+
     @property
     def deferred_stdout(self) -> str:
         """Submit-time output held until the cloud job header is printed."""

{simulo-0.31.2 → simulo-0.32.0}/src/simulo/_client/app.py

@@ -160,6 +160,7 @@ def viewstream_requested(enabled: bool) -> Iterator[None]:
 
 _INPUT_CHECKPOINT_REF: Optional[str] = None
 _INPUT_CHECKPOINT_FLAG = "--from"
+_COMPARE_CHECKPOINT_REF: Optional[str] = None
 
 
 class InputCheckpointRequiresCloudError(RuntimeError):
@@ -188,6 +189,18 @@ def input_checkpoint_requested(checkpoint_ref: Optional[str], *, flag: str = "--
         _INPUT_CHECKPOINT_FLAG = previous_flag
 
 
+@contextlib.contextmanager
+def compare_checkpoint_requested(checkpoint_ref: Optional[str]) -> Iterator[None]:
+    """Scope ``--compare``'s second checkpoint for one ``simulo run`` submit."""
+    global _COMPARE_CHECKPOINT_REF
+    previous = _COMPARE_CHECKPOINT_REF
+    _COMPARE_CHECKPOINT_REF = checkpoint_ref
+    try:
+        yield
+    finally:
+        _COMPARE_CHECKPOINT_REF = previous
+
+
 # ---------------------------------------------------------------------------
 # Asset-pin ambient signals — `simulo run --frozen` / `--strict-assets` scope
 # these for one submit, exactly like `--viewstream` / `--from` above and for the
@@ -302,6 +315,17 @@ def _require_no_input_checkpoint_for_local_submit(reason: str) -> None:
     )
 
 
+def _require_no_compare_checkpoint_for_local_submit(reason: str) -> None:
+    """Refuse a local-disk submit that would drop ``--compare``."""
+    if _COMPARE_CHECKPOINT_REF is None:
+        return
+    raise InputCheckpointRequiresCloudError(
+        f"--compare {_COMPARE_CHECKPOINT_REF!r} needs a cloud control plane to resolve the checkpoint, but {reason}. "
+        "A local-disk submit only writes the package and cannot compare policy checkpoints. Log in first "
+        "(`simulo login`) or point SIMULO_API_URL/SIMULO_ENV at a control plane (and unset SIMULO_SUBMIT=local)."
+    )
+
+
 @dataclass
 class JobSpec:
     """Recorded metadata for one ``@app.job``-decorated function."""
@@ -491,6 +515,7 @@ def _spawn_cloud(
     *,
     viewstream: bool = False,
     input_checkpoint: Optional[str] = None,
+    compare_checkpoint: Optional[str] = None,
     frozen_assets: bool = False,
     strict_assets: bool = False,
     skip_preflight: bool = False,
@@ -683,6 +708,7 @@ def _spawn_cloud(
         args=args,
         viewstream=viewstream,
         input_checkpoint=input_checkpoint,
+        compare_checkpoint=compare_checkpoint,
         assets=asset_pins,
         app_name=app_name,
         system=system,
@@ -716,6 +742,7 @@ def _spawn_cloud(
         token=token,
         job_type=job_type,
         input_checkpoint=input_checkpoint,
+        compare_checkpoint=compare_checkpoint,
         deferred_stdout=deferred_stdout,
         deferred_stderr=deferred_stderr,
     )
@@ -807,6 +834,7 @@ class JobFunction:
         # local-disk submit must never depend on the network succeeding.
         if config.is_submit_forced_local():
             _require_no_input_checkpoint_for_local_submit("SIMULO_SUBMIT=local forces a local-disk submit")
+            _require_no_compare_checkpoint_for_local_submit("SIMULO_SUBMIT=local forces a local-disk submit")
             handle: JobHandle = _spawn_local(self._spec.name, package_path)
         else:
             creds = credentials.try_get_valid_credentials()
@@ -819,6 +847,7 @@ class JobFunction:
                         creds,
                         viewstream=_VIEWSTREAM_REQUESTED,
                         input_checkpoint=_INPUT_CHECKPOINT_REF,
+                        compare_checkpoint=_COMPARE_CHECKPOINT_REF,
                         frozen_assets=_FROZEN_ASSETS_REQUESTED,
                         strict_assets=_STRICT_ASSETS_REQUESTED,
                         skip_preflight=_SKIP_PREFLIGHT_REQUESTED,
@@ -850,6 +879,7 @@ class JobFunction:
                     )
             else:
                 _require_no_input_checkpoint_for_local_submit("no cloud target is configured")
+                _require_no_compare_checkpoint_for_local_submit("no cloud target is configured")
                 handle = _spawn_local(self._spec.name, package_path)
         _record_spawn(handle)
         return handle
@@ -1430,11 +1460,11 @@ class App:
         raise AttributeError(f"{type(self).__name__!s} object has no attribute {name!r}")
 
     def success(self, fn: F) -> F:
-        """Register an evaluation success predicate for CLI validation.
+        """Register an evaluation success rule.
 
-        Evaluation execution is implemented in a later milestone. This
-        decorator records the function only, so discovery can enforce that an
-        eval file has exactly one and every other job type has none.
+        The client only records the function, so discovery can enforce that an
+        eval file has exactly one and every other job type has none; the
+        evaluation job calls it on each episode's last step.
         """
         self._success_functions.append(fn)
         return fn
@@ -1449,8 +1479,6 @@ class App:
         spec = self._jobs[job_name]
         where = location or f"app {self.name!r}"
         successes = self.success_functions
-        if spec.job_type is JobType.EVAL and not successes:
-            raise JobDeclarationError("evaluation isn't available yet. Use a train job for now.")
         if spec.job_type is JobType.EVAL:
             if len(successes) != 1:
                 names = ", ".join(fn.__name__ for fn in successes) or "none"
@@ -1474,8 +1502,6 @@ class App:
                     "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.ASSET_VALIDATION:
             raise JobDeclarationError("Asset validation runs when you publish an asset: simulo asset publish.")
         if spec.job_type is JobType.EXPORT:

{simulo-0.31.2 → simulo-0.32.0}/src/simulo/_client/bundle.py

@@ -4,9 +4,9 @@ Shared by ``simulo run`` (the CLI) and ``JobFunction.spawn`` — the *submit* pa
 discover the app's metadata and write the package (manifest + source bundle) to
 disk. The manifest builder reads only the public ``App`` surface, so it works in
 discovery mode (where submit runs). ``ensure_bundle`` memoises the written package
-per *submission* — ``(app, job_name, args)`` — so re-submitting the same job with
-the same args reuses the package, while a second spawn with a different job or
-different args writes a distinct package (no clobber).
+per *submission* — ``(app, entry_file, job_name, args)`` — so re-submitting the
+same file and job with the same args reuses the package, while a second spawn with
+a different entry file, job, or args writes a distinct package (no clobber).
 
 Submit NEVER executes a job and NEVER invokes the backend — it only writes the
 package. This module imports no heavy library; it stays on the torch-free side of
@@ -16,11 +16,17 @@ package it writes.
 
 from __future__ import annotations
 
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, Any, Optional, Sequence
 
 from simulo._client.asset import Asset
-from simulo._client.packaging import assert_credentials_outside_project, canonical_args, package, read_bundle_package_id
+from simulo._client.packaging import (
+    assert_credentials_outside_project,
+    canonical_args,
+    package,
+    project_relative_entry_file,
+    read_bundle_package_id,
+)
 from simulo._client.volume import Volume
 from simulo.interfaces.platform import is_platform_pinned
 from simulo.interfaces.platform.manifest import Manifest
@@ -33,10 +39,10 @@ if TYPE_CHECKING:  # typing-only; avoids any import cycle with app.py at runtime
 DEFAULT_OUT_SUBPATH = (".simulo", "packages")
 
 # Memoise the built bundle per *submission* (per process). Keyed on
-# ``(id(app), job_name, canonical_json(args))`` — an App lives for the whole run,
-# so identity reuse is not a concern, and keying on the job + args means multiple
-# programmatic spawns each write their own package instead of the first one being
-# reused for all.
+# ``(id(app), entry_file, job_name, canonical_json(args))`` — an App lives for
+# the whole run, so identity reuse is not a concern, and keying on the selected
+# file + job + args means multiple programmatic spawns each write their own
+# package instead of the first one being reused for all.
 #
 # Each entry stores ``(bundle_dir, package_id)`` — the package_id the bundle
 # was written for when THIS process cached it — not just the path. The local
@@ -48,15 +54,15 @@ DEFAULT_OUT_SUBPATH = (".simulo", "packages")
 # rmtree+rewrites whatever it finds there). ``ensure_bundle`` re-verifies the
 # manifest on every cache hit before trusting it (see below) — turning a
 # prefix collision into a redundant rebuild, never a silently wrong package.
-#: Cache key's 4th element is the sorted, de-duplicated URIs of every
+#: Cache key's 5th element is the sorted, de-duplicated URIs of every
 #: ambiently-CAPTURED asset visible at this ``ensure_bundle`` call (construction-
 #: capture — see ``asset.py``) — included so a LATER spawn() in the same process,
 #: after user code has constructed MORE assets since an earlier spawn() with
-#: the identical ``(app, job_name, args)``, is never served a stale cached bundle
+#: the identical ``(app, entry_file, job_name, args)``, is never served a stale cached bundle
 #: whose ``resources`` predates those constructions (``package_id`` itself never
 #: changes with the asset set — see the package-hash-invariance rule — so the
 #: `package_id` re-check below cannot by itself catch this staleness).
-_BUNDLE_CACHE: dict[tuple[int, str, str, tuple[str, ...]], tuple[Path, str]] = {}
+_BUNDLE_CACHE: dict[tuple[int, str, str, str, tuple[str, ...]], tuple[Path, str]] = {}
 
 
 def _mount_ref(mount: object) -> dict[str, Any]:
@@ -133,8 +139,8 @@ def build_manifest(
     runtime's compiled camera-sensor bindings in ways undiagnosable from the
     job's own traceback, so this raises — it never skips-and-warns.
     """
-    rel = app_file.resolve().relative_to(project_root)
-    module = ".".join(rel.with_suffix("").parts)
+    entry_file = project_relative_entry_file(app_file, project_root)
+    module = ".".join(PurePosixPath(entry_file).with_suffix("").parts)
 
     volumes: dict[str, Any] = {}
     resource_by_uri: dict[str, dict[str, Any]] = {}
@@ -166,7 +172,7 @@ def build_manifest(
         # ``local_entrypoint`` remains the stable v2 wire key. The backend
         # runner reads only ``entrypoint.module``, but the complete v2 bytes are
         # pinned by ``test_manifest_wire_stability.py``.
-        entrypoint={"file": rel.as_posix(), "module": module, "local_entrypoint": None},
+        entrypoint={"file": entry_file, "module": module, "local_entrypoint": None},
         runtime_env=dict(getattr(runtime, "runtime_env", {})),
         jobs={name: _job_entry(spec) for name, spec in app.jobs.items()},
         resources=resources,
@@ -191,9 +197,9 @@ def ensure_bundle(
     This is the *submit* primitive: the manifest is built from the live app object
     (no second discovery import) with the submitted job's ``args`` recorded, and
     the source tree is written to ``<out>/<bundle_dir_name(package_id)>/`` — the
-    per-submission directory keyed on source + ``job_name`` + ``args`` (named by
+    per-submission directory keyed on source + entry file + ``job_name`` + ``args`` (named by
     the id's short, filesystem-safe form; see ``packaging.bundle_dir_name``).
-    Memoised per submission (``(id(app), job_name, canonical_json(args), sorted
+    Memoised per submission (``(id(app), entry_file, job_name, canonical_json(args), sorted
     extra_assets uris)``) so re-submitting the same job with the same args AND the
     same captured-asset set reuses the package, while a different job, different
     args, or a DIFFERENT captured-asset set (more constructions since an earlier
@@ -212,8 +218,9 @@ def ensure_bundle(
     submission), never served as a silently wrong package.
     """
     assert_credentials_outside_project(project_root)
+    entry_file = project_relative_entry_file(app_file, project_root)
     extra_asset_uris = tuple(sorted({asset.uri for asset in extra_assets}))
-    cache_key = (id(app), job_name, canonical_args(args), extra_asset_uris)
+    cache_key = (id(app), entry_file, job_name, canonical_args(args), extra_asset_uris)
     cached = _BUNDLE_CACHE.get(cache_key)
     if cached is not None:
         cached_dir, cached_package_id = cached