simulo 0.12.0__tar.gz → 0.13.0__tar.gz

{simulo-0.12.0/src/simulo.egg-info → simulo-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.12.0
+Version: 0.13.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,8 +15,11 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.5,>=0.4
+Requires-Dist: simulo-interfaces<0.6,>=0.5
 Requires-Dist: mcap<2,>=1.3
+Requires-Dist: defusedxml>=0.7.1
+Provides-Extra: assets
+Requires-Dist: usd-core<27,>=25.5; extra == "assets"
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: isort>=5.13; extra == "dev"
@@ -52,7 +55,7 @@ The fastest way to start: scaffold a runnable app.
 
 ```bash
 simulo create mybot
-# Created mybot/app.py and mybot/.simuloignore (training app).
+# Created training app in mybot/ (app.py + .simuloignore).
 cd mybot
 ```
 
@@ -69,8 +72,7 @@ run it.
 # app.py
 import simulo
 
-runtime = simulo.Runtime.from_registry("simulo/python-cpu:3.11")
-app = simulo.App("hello", runtime=runtime)
+app = simulo.App("hello")
 
 
 @app.job(timeout=5 * 60)
@@ -100,4 +102,19 @@ no-op. To continue training from an earlier job's checkpoint instead, pass
 `--from <job-ref>[:best|:latest]`. Job ids, and their unambiguous prefixes (`>=4` characters),
 work anywhere the CLI takes a job id.
 
+## Monitor jobs and retrieve results
+
+```bash
+simulo jobs                      # your jobs and their statuses
+simulo logs --follow             # stream the latest job's logs live
+simulo result                    # the completed job's result JSON
+simulo models                    # list / download trained checkpoints (sha256-verified)
+simulo recordings                # download MCAP flight recordings
+simulo view                      # watch the live 3D scene (jobs submitted with --viewstream)
+simulo cancel                    # cancel a queued or running job
+```
+
+Commands that take a job id default to the latest job, announcing what they
+resolved to on stderr.
+
 Learn more at [simulo.ai](https://simulo.ai).

{simulo-0.12.0 → simulo-0.13.0}/PYPI.md

@@ -20,7 +20,7 @@ The fastest way to start: scaffold a runnable app.
 
 ```bash
 simulo create mybot
-# Created mybot/app.py and mybot/.simuloignore (training app).
+# Created training app in mybot/ (app.py + .simuloignore).
 cd mybot
 ```
 
@@ -37,8 +37,7 @@ run it.
 # app.py
 import simulo
 
-runtime = simulo.Runtime.from_registry("simulo/python-cpu:3.11")
-app = simulo.App("hello", runtime=runtime)
+app = simulo.App("hello")
 
 
 @app.job(timeout=5 * 60)
@@ -68,4 +67,19 @@ no-op. To continue training from an earlier job's checkpoint instead, pass
 `--from <job-ref>[:best|:latest]`. Job ids, and their unambiguous prefixes (`>=4` characters),
 work anywhere the CLI takes a job id.
 
+## Monitor jobs and retrieve results
+
+```bash
+simulo jobs                      # your jobs and their statuses
+simulo logs --follow             # stream the latest job's logs live
+simulo result                    # the completed job's result JSON
+simulo models                    # list / download trained checkpoints (sha256-verified)
+simulo recordings                # download MCAP flight recordings
+simulo view                      # watch the live 3D scene (jobs submitted with --viewstream)
+simulo cancel                    # cancel a queued or running job
+```
+
+Commands that take a job id default to the latest job, announcing what they
+resolved to on stderr.
+
 Learn more at [simulo.ai](https://simulo.ai).

{simulo-0.12.0 → simulo-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.12.0"
+version = "0.13.0"
 description = "Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -25,9 +25,32 @@ classifiers = [
 # guard, resolved only at job-execution time — never in this distribution.
 # 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.4,<0.5", "mcap>=1.3,<2"]
+dependencies = [
+    "simulo-interfaces>=0.5,<0.6",
+    "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
+    # libexpat's own (practical-but-not-contractual) entity-expansion
+    # defaults to stay XXE/billion-laughs-safe; defusedxml pins that
+    # protection explicitly. Pure Python, zero transitive dependencies,
+    # ~25 KB — genuinely "cheap": adding it does not compromise the
+    # featherweight/no-USD-extra promise below (that promise is about
+    # avoiding usd-core's tens of MB, not about being literally
+    # zero-dependency).
+    "defusedxml>=0.7.1",
+]
 
 [project.optional-dependencies]
+# `assets` — the FIRST user-facing extras group: USD package inspection for
+# `simulo asset publish`/`validate` of USD trees (dependency closure + entry
+# detection via pxr.UsdUtils). usd-core is simulator-free but tens of MB, so
+# it must never tax users who don't publish USD: the import is lazy, ONLY in
+# the USD inspection path (`_client/asset_package.py::_load_pxr_usdutils`),
+# and a missing extra fails with the copyable `pip install "simulo[assets]"`.
+# URDF publishing needs no OPT-IN extra (defusedxml + path math, both tiny
+# always-installed base dependencies above — see that dependency's own
+# comment).
+assets = ["usd-core>=25.5,<27"]
 dev = ["black>=24.0", "isort>=5.13", "ruff>=0.5", "mypy>=1.10", "pytest>=8.2", "build>=1.2", "twine>=5.1"]
 # `dev` carries build/twine but deliberately not commitizen; `release` below
 # adds commitizen for cutting version bumps without a second build/twine copy.
@@ -71,6 +94,7 @@ addopts = "--import-mode=importlib"
 markers = [
     "isaac: requires NVIDIA Isaac Sim / IsaacLab (skipped on dev machines and in PR CI)",
     "gpu: requires a CUDA GPU (skipped on dev machines and in PR CI)",
+    "requires_execution_backend: end-to-end test that needs a live execution backend in the loop; skipped in CPU/unit runs",
 ]
 
 [tool.isort]

{simulo-0.12.0 → simulo-0.13.0}/src/simulo/_client/app.py

@@ -34,6 +34,7 @@ from typing import Any, Callable, Iterator, Mapping, Optional, Sequence, TypeVar
 
 from simulo._client import config, credentials, registry
 from simulo._client._runner import JobFailedError, JobHandle, JobResultUnavailable
+from simulo._client.runtime import DEFAULT_RUNTIME
 from simulo.interfaces.ids import JobId
 from simulo.interfaces.platform import JobCallbackProtocol, Mount
 from simulo.interfaces.platform.enums import ResumePolicy
@@ -135,6 +136,44 @@ def seed_from_requested(seed_ref: Optional[str]) -> Iterator[None]:
         _SEED_FROM_REF = previous
 
 
+# ---------------------------------------------------------------------------
+# Asset-pin ambient signals — `simulo run --frozen` / `--strict-assets` scope
+# these for one submit, exactly like `--viewstream` / `--from` above and for the
+# same "the spawn() is deep inside the user's @app.local_entrypoint" reason. They
+# govern submit-time asset pin RESOLUTION (§6), which — like viewstream/seed —
+# happens only on the cloud path (a local-disk submit has no control plane to
+# resolve against) and NEVER touches `args` or the manifest, so they can't move
+# `package_id`'s sha256.
+# ---------------------------------------------------------------------------
+
+_FROZEN_ASSETS_REQUESTED = False
+_STRICT_ASSETS_REQUESTED = False
+
+
+@contextlib.contextmanager
+def frozen_assets_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--frozen`` (fail on any unpinned asset ref) for one submit call."""
+    global _FROZEN_ASSETS_REQUESTED
+    previous = _FROZEN_ASSETS_REQUESTED
+    _FROZEN_ASSETS_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _FROZEN_ASSETS_REQUESTED = previous
+
+
+@contextlib.contextmanager
+def strict_assets_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--strict-assets`` (asset warnings become errors) for one submit call."""
+    global _STRICT_ASSETS_REQUESTED
+    previous = _STRICT_ASSETS_REQUESTED
+    _STRICT_ASSETS_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _STRICT_ASSETS_REQUESTED = previous
+
+
 def _require_no_seed_for_local_submit(reason: str) -> None:
     """Refuse a local-disk submit that carries an ambient ``--from`` seed."""
     if _SEED_FROM_REF is None:
@@ -210,6 +249,8 @@ def _spawn_cloud(
     *,
     viewstream: bool = False,
     seed_from: Optional[str] = None,
+    frozen_assets: bool = False,
+    strict_assets: bool = False,
 ) -> JobHandle:
     """Tar the bundle, upload it, create the job, and return a cloud JobHandle.
 
@@ -227,7 +268,16 @@ def _spawn_cloud(
     full source-job UUID — the confirmation that a typed prefix resolved to
     the job the user meant); when an older server ignores it, ``create_job``
     raises rather than let a fresh run masquerade as a seeded one.
+
+    Registry-asset pins (§6) follow the SAME sibling-of-``args`` rule. Every
+    ``Asset.from_registry`` ref the app mounted is resolved to an exact
+    version in one batch BEFORE the package is uploaded — so a bad/missing/
+    unpinned ref fails in seconds rather than after the upload — the
+    ``Resolved assets:`` block is printed, ``--frozen`` / ``--strict-assets``
+    are enforced, and the resolved ``[{ref, digest}]`` pins ride the
+    job-create call's top-level ``assets`` field, never ``args``.
     """
+    from simulo._client.asset_pins import DEFAULT_ASSET_RUNTIME, collect_asset_refs, resolve_and_pin_assets
     from simulo._client.packaging import MANIFEST_FILENAME, ensure_tar
     from simulo._client.submit_api import SubmitApiClient
 
@@ -261,6 +311,18 @@ def _spawn_cloud(
     token = creds["access_token"] if creds else os.environ.get("SIMULO_API_TOKEN")
     client = SubmitApiClient(base_url, token=token)
 
+    # Resolve every mounted registry-asset ref to an exact pin FIRST — before the
+    # package is uploaded — so a missing/unpinned/unvalidated ref fails in seconds
+    # (§6). Returns the top-level `assets: [{ref, digest}]` for create_job; `[]`
+    # when the app mounts no registry assets (no resolve call is made then).
+    asset_pins = resolve_and_pin_assets(
+        client,
+        collect_asset_refs(manifest),
+        runtime=DEFAULT_ASSET_RUNTIME,
+        frozen=frozen_assets,
+        strict=strict_assets,
+    )
+
     client.create_package(
         package_id=package_id,
         source_digest=source_digest,
@@ -275,6 +337,7 @@ def _spawn_cloud(
         args=args,
         viewstream=viewstream,
         seed_from_job_id=seed_from,
+        assets=asset_pins,
     )
 
     if seed_from is not None:
@@ -291,7 +354,13 @@ def _spawn_cloud(
 
 
 class JobFunction:
-    """Proxy returned by ``@app.job`` — superset of ``JobFunctionProtocol``."""
+    """What ``@app.job`` returns: the original function, wrapped for submission.
+
+    Calling it runs the body in-process, exactly as if it were undecorated (that
+    is also how the platform invokes it on a worker). :meth:`spawn` and
+    :meth:`submit` package and submit it instead. You never construct one
+    yourself — decorate a function and use it from your ``@app.local_entrypoint``.
+    """
 
     def __init__(self, app: "App", spec: JobSpec) -> None:
         self._app = app
@@ -307,32 +376,47 @@ class JobFunction:
         return self._spec.fn(*args, **kwargs)
 
     def spawn(self, **kwargs: Any) -> JobHandle:
-        """Submit this job: write the package to disk, then submit it.
+        """Submit this job to the Simulo cloud (once logged in), or write it locally.
 
         Submitting writes the manifest + source bundle (memoised once per app),
-        recording this job's name and ``kwargs`` into the manifest so the executor
-        can invoke ``fn(**kwargs)`` later.
+        recording this job's name and ``kwargs`` into the manifest so the job can
+        be run later with ``fn(**kwargs)``.
 
-        **Cloud mode** — credentials exist, or ``SIMULO_API_URL``/``SIMULO_ENV``
-        names a target (and ``SIMULO_SUBMIT`` is not ``local``): the package is
-        tarred, uploaded, and a job is created on the control plane. The
-        returned :class:`JobHandle` carries the SERVER-assigned ``job_id`` and
-        ``.get()`` streams the real result.
+        **Cloud mode** — credentials exist (``simulo login``), or
+        ``SIMULO_API_URL``/``SIMULO_ENV`` names a target (and ``SIMULO_SUBMIT`` is
+        not ``local``): the package is tarred, uploaded, and a job is created on
+        the Simulo cloud. The returned :class:`JobHandle` carries the
+        SERVER-assigned ``job_id`` and ``.get()`` streams the real result.
 
         **Local-disk mode** (the default with no cloud signal present): NEVER
-        trains and NEVER invokes the backend — the handle exposes only
-        ``.package_path`` / ``.job_id`` (a locally-derived id); execution is a
-        separate step (``simulo-backend run-package <package> --job <name>``).
+        trains and never runs the job — the handle exposes only
+        ``.package_path`` / ``.job_id`` (a locally-derived id), and ``.get()``
+        raises, pointing you at ``simulo login`` to submit to the cloud instead.
 
         Positional arguments are rejected: a job body receives only the keyword
         arguments recorded in the manifest.
         """
         # Lazy import keeps app.py free of a module-scope dependency on the
         # packager (and any import cycle); spawn is a runtime call.
+        from simulo._client.asset import current_captured_assets
         from simulo._client.bundle import ensure_bundle
 
         app_file, project_root = _app_source_location(self._spec.module)
-        package_path = ensure_bundle(self._app, app_file, project_root, job_name=self._spec.name, args=dict(kwargs))
+        # Construction-capture (freeze doc "PR-9 amendments"): every Asset
+        # constructed so far in the active `simulo run` capture scope (armed
+        # around the whole discovery import + entrypoint run — see cli.py) is
+        # unioned into this bundle's `resources`, even when never explicitly
+        # mounted via App(mounts=...) — an unmounted §7.1 handle
+        # (`forklift = simulo.Asset.from_registry(...)`, used only via
+        # `Robot(asset=forklift)`) must still get resolved and pinned.
+        package_path = ensure_bundle(
+            self._app,
+            app_file,
+            project_root,
+            job_name=self._spec.name,
+            args=dict(kwargs),
+            extra_assets=current_captured_assets(),
+        )
 
         # SIMULO_SUBMIT=local is checked FIRST, before touching credentials at
         # all — the escape hatch must short-circuit even when the saved token
@@ -351,6 +435,8 @@ class JobFunction:
                     creds,
                     viewstream=_VIEWSTREAM_REQUESTED,
                     seed_from=_SEED_FROM_REF,
+                    frozen_assets=_FROZEN_ASSETS_REQUESTED,
+                    strict_assets=_STRICT_ASSETS_REQUESTED,
                 )
             else:
                 _require_no_seed_for_local_submit("no cloud target is configured")
@@ -444,19 +530,50 @@ def _arm_nothing_submitted_hint(app: "App") -> None:
 
 
 class App:
-    """User-facing job container: ``app = simulo.App(name, runtime=...)``."""
+    """The user-facing job container — declare it once, at module scope.
+
+    An app names your project and (optionally) mounts assets/volumes into
+    every job. Its jobs execute in a Simulo-curated runtime —
+    :data:`~simulo._client.runtime.DEFAULT_RUNTIME` unless the app picks a
+    different Simulo runtime via ``runtime=``. Decorate functions with
+    :meth:`job` to make them submittable, and one function with
+    :meth:`local_entrypoint` to define what ``simulo run app.py`` does::
+
+        import simulo
+
+        app = simulo.App("cartpole")
+
+        @app.job(gpu="A10G")
+        def train(iterations: int = 1000):
+            ...
+
+        @app.local_entrypoint
+        def main(iterations: int = 1000):
+            train.spawn(iterations=iterations)
+
+    Args:
+        name: Non-empty app name, recorded in the package manifest.
+        runtime: Optionally pick a different Simulo runtime for this app's
+            jobs (``simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")``).
+            Omitted means the platform default.
+        mounts: Optional mapping of mount name to :class:`simulo.Asset` /
+            :class:`simulo.Volume`, shared by every job of this app.
+
+    Raises:
+        ValueError: if ``name`` is empty or whitespace-only.
+    """
 
     def __init__(
         self,
         name: str,
         *,
-        runtime: object,
+        runtime: Optional[object] = None,
         mounts: Optional[Mapping[str, Mount]] = None,
     ) -> None:
         if not name or not name.strip():
             raise ValueError("App name must be a non-empty string.")
         self._name = name
-        self._runtime = runtime
+        self._runtime = runtime if runtime is not None else DEFAULT_RUNTIME
         self._mounts: dict[str, Mount] = dict(mounts or {})
         self._jobs: dict[str, JobSpec] = {}
         self._local_entrypoints: dict[str, Callable[..., object]] = {}
@@ -467,22 +584,27 @@ class App:
 
     @property
     def name(self) -> str:
+        """The app's name, as passed at construction."""
         return self._name
 
     @property
     def runtime(self) -> Any:
+        """The Simulo runtime this app's jobs execute in (the default unless picked)."""
         return self._runtime
 
     @property
     def mounts(self) -> Mapping[str, Mount]:
+        """The assets/volumes mounted into every job of this app, by mount name (a copy)."""
         return dict(self._mounts)
 
     @property
     def jobs(self) -> Mapping[str, JobSpec]:
+        """The registered job specs, by job name (a copy)."""
         return dict(self._jobs)
 
     @property
     def local_entrypoint_names(self) -> tuple[str, ...]:
+        """Names of the functions registered with ``@app.local_entrypoint``."""
         return tuple(self._local_entrypoints)
 
     @overload
@@ -511,7 +633,52 @@ class App:
         retries: int = 0,
         **extra: Any,
     ) -> Union[JobFunction, Callable[[F], JobFunction]]:
-        """Register a job function. Records metadata; never runs the body."""
+        """Register a function as a job of this app. Records metadata; never runs the body.
+
+        Usable bare (``@app.job``) or with options (``@app.job(gpu="A10G")``).
+        Returns a :class:`JobFunction` wrapping the original function — calling
+        it still runs the body in-process; ``.spawn()`` / ``.submit()`` submit it
+        to the platform instead.
+
+        Args:
+            fn: The function being decorated (bare-decorator form only — never
+                pass it alongside keyword options).
+            callbacks: Lifecycle callbacks from :mod:`simulo.callbacks` (e.g.
+                ``ResumableCheckpoint``), recorded into the package manifest and
+                honored at execution.
+            resume: How the job resumes from a discovered checkpoint
+                (:class:`~simulo.interfaces.platform.enums.ResumePolicy`,
+                default ``AUTO``).
+            gpu: GPU resource request (e.g. ``"A10G"``), recorded in the job's
+                resource spec.
+            timeout: Wall-clock limit for one managed execution, in seconds
+                (a positive integer; validated HERE, at decoration time — a
+                zero, negative, or non-integer value raises ``ValueError``
+                immediately rather than failing later at run time on the
+                worker). Enforced by the platform worker: a job still
+                running at the limit is killed and reported ``failed`` with
+                reason ``timeout``. When omitted (``None``, the default),
+                the platform ceiling applies (1 hour by default); a declared
+                value larger than the ceiling is clamped down to it. The
+                ceiling is an operator knob on the worker
+                (``MAX_JOB_TIMEOUT_S=<seconds>``) for long unattended
+                training.
+            retries: Automatic re-attempts after a failure (default 0). All
+                attempts share one ``timeout`` budget.
+            **extra: Additional resource requests, recorded verbatim in the
+                job's resource spec.
+
+        Raises:
+            ValueError: ``timeout`` is not ``None`` and is not a positive
+                integer (mirrors the worker's own
+                ``worker._effective_job_timeout_s`` guard — bare ``bool`` is
+                excluded even though it is an ``int`` subclass).
+        """
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, int) or timeout < 1):
+            raise ValueError(
+                "@app.job(timeout=...) must be a positive integer (seconds), or omitted/None to "
+                f"use the platform ceiling — got {timeout!r}."
+            )
 
         def decorate(func: F) -> JobFunction:
             resources: dict[str, Any] = {}