simulo 0.13.2__tar.gz → 0.14.0__tar.gz

{simulo-0.13.2/src/simulo.egg-info → simulo-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.13.2
+Version: 0.14.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,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.6,>=0.5
+Requires-Dist: simulo-interfaces<0.7,>=0.6
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=25.5

{simulo-0.13.2 → simulo-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.13.2"
+version = "0.14.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"
@@ -26,7 +26,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.5,<0.6",
+    "simulo-interfaces>=0.6,<0.7",
     "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.13.2 → simulo-0.14.0}/src/simulo/_client/bundle.py

@@ -23,6 +23,7 @@ from simulo._client.asset import Asset
 from simulo._client.manifest import Manifest
 from simulo._client.packaging import canonical_args, package, read_bundle_package_id
 from simulo._client.volume import Volume
+from simulo.interfaces.platform import is_platform_pinned
 
 if TYPE_CHECKING:  # typing-only; avoids any import cycle with app.py at runtime
     from simulo._client.app import App, JobSpec
@@ -122,6 +123,16 @@ def build_manifest(
     setup (``runner._setup_mounts``, also keyed off ``resources``) see it — an
     unmounted §7.1 handle must never resolve to a silent zero-pin submit (freeze
     doc "PR-9 amendments").
+
+    **Submit-time denylist gate:** every package name declared via the
+    runtime's ``pip_install()`` is checked against
+    ``simulo.interfaces.platform.is_platform_pinned`` — a layer naming a
+    package the Simulo base runtime already provides (torch, numpy, the CUDA
+    wheels, the ``simulo`` distributions) fails the whole submit here with a
+    ``SystemExit`` listing the offenders, before any package is written or
+    uploaded. Fast-fail by design: a shadowing layer version once broke the
+    runtime's compiled camera-sensor bindings in ways undiagnosable from the
+    job's own traceback (#285), so this raises — it never skips-and-warns.
     """
     rel = app_file.resolve().relative_to(project_root)
     module = ".".join(rel.with_suffix("").parts)
@@ -140,13 +151,26 @@ def build_manifest(
     resources: list[Any] = list(resource_by_uri.values())
 
     runtime = app.runtime
+    pip_dependencies = [dict(layer) for layer in getattr(runtime, "pip_dependencies", [])]
+    pinned = list(
+        dict.fromkeys(  # de-duplicate across layers, preserving declaration order
+            spec for layer in pip_dependencies for spec in layer.get("packages", []) if is_platform_pinned(str(spec))
+        )
+    )
+    if pinned:
+        raise SystemExit(
+            "Cannot pip_install these — the Simulo base runtime already provides them: "
+            f"{', '.join(pinned)}. Remove them; the base image includes them."
+        )
     return Manifest(
         source_digest="",  # stamped by package()
         runtime_id=str(getattr(runtime, "runtime_id", "")),
         entrypoint={"file": rel.as_posix(), "module": module, "local_entrypoint": local_entrypoint},
+        runtime_env=dict(getattr(runtime, "runtime_env", {})),
         jobs={name: _job_entry(spec) for name, spec in app.jobs.items()},
         resources=resources,
         volumes=volumes,
+        pip_dependencies=pip_dependencies,
         args=dict(args or {}),
     )
 

{simulo-0.13.2 → simulo-0.14.0}/src/simulo/_client/manifest.py

@@ -2,8 +2,12 @@
 
 A frozen, JSON-serialisable description of a packaged app: the content digest of
 its source, the submission's package identity, the entrypoint, the picked Simulo
-runtime, declared jobs, and mounts. The backend runner reads only named fields.
-Kept deliberately stdlib-only and decoupled from the runner.
+runtime, the guarded runtime customisation (``runtime_env`` — the user's
+``env()`` overrides; ``pip_dependencies`` — the declared public-PyPI layers),
+declared jobs, and mounts. The backend runner reads only named fields, so the
+additive ``runtime_env`` / ``pip_dependencies`` fields are ignored by a runner
+that predates them (no break). Kept deliberately stdlib-only and decoupled from
+the runner.
 
 Two distinct identities are recorded:
 
@@ -32,9 +36,11 @@ class Manifest:
     runtime_id: str
     package_id: str = ""
     entrypoint: dict[str, Any] = field(default_factory=dict)
+    runtime_env: dict[str, str] = field(default_factory=dict)
     jobs: dict[str, Any] = field(default_factory=dict)
     resources: list[Any] = field(default_factory=list)
     volumes: dict[str, Any] = field(default_factory=dict)
+    pip_dependencies: list[dict[str, Any]] = field(default_factory=list)
     args: dict[str, Any] = field(default_factory=dict)
     manifest_version: int = 1
 

simulo-0.14.0/src/simulo/_client/runtime.py

@@ -0,0 +1,185 @@
+"""``Runtime`` — a Simulo-curated runtime (implements ``RuntimeProtocol``).
+
+Simulo owns the runtime: every job executes in a prebuilt, Simulo-managed
+environment that ships everything a robotics training job needs — the
+simulation engine, GPU stack, and the scientific-Python toolchain. You never
+bring your own image or registry; you *pick* a Simulo runtime (today there is
+one, :data:`DEFAULT_RUNTIME`, and it is the default — the common path writes
+nothing) and may layer a guarded set of extras on top: :meth:`Runtime.env`
+merges environment variables into the job's execution environment, and
+:meth:`Runtime.pip_install` declares additional **public-PyPI** packages the
+Simulo image builder installs on top of the base runtime. There is no
+private-registry, URL, VCS, or local-path install surface — a package the
+base runtime already provides cannot be overridden (see
+``simulo.interfaces.platform.is_platform_pinned``).
+
+Locally this class is a lean metadata recorder: ``from_registry`` names the
+Simulo runtime, ``env`` accumulates environment overrides, ``pip_install``
+records ordered public-PyPI dependency layers, ``torch_jit`` is a no-op
+marker at submit (and real ``torch.jit.script`` on the worker), and
+``imports`` is the remote-only-import boundary (Rule #3) — a real
+``nullcontext`` in execution mode, a stub-installing context manager in
+discovery mode. Nothing is ever installed on your machine at submit.
+"""
+
+import copy
+import importlib
+from contextlib import AbstractContextManager, nullcontext
+from typing import Any, Callable, Mapping, TypeVar, cast
+
+from simulo._client.discovery import stub_import_context
+from simulo._client.mode import DISCOVERY, EXECUTION, current_mode
+from simulo.interfaces.platform import canonical_pypi_name
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def _reject_non_pypi_spec(spec: str) -> None:
+    """Raise ``SystemExit`` if *spec* is not a plain public-PyPI requirement.
+
+    Delegates the actual grammar check to
+    ``simulo.interfaces.platform.canonical_pypi_name`` — the SAME positive
+    allowlist ``is_platform_pinned`` fails closed on — rather than
+    duplicating a rule in this package too (review round 2, critic MINOR: a
+    duplicated rule is how one copy gets hardened and the other doesn't).
+    Here the reject happens at CALL time with a message naming the actual
+    problem (not a misleading "platform-pinned" one at submit time).
+    """
+    if canonical_pypi_name(spec) is None:
+        raise SystemExit(f"pip_install accepts PyPI package specs only — not URLs, paths, or VCS refs: {spec}")
+
+
+class Runtime:
+    """A Simulo-curated runtime a job executes in. Torch-free metadata recorder.
+
+    You normally never construct one: every :class:`simulo.App` defaults to
+    :data:`DEFAULT_RUNTIME`. Pick a Simulo runtime by name and layer your own
+    environment variables and public-PyPI packages on top::
+
+        runtime = (
+            simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")
+            .pip_install("wandb==0.17.0")
+            .env({"WANDB_PROJECT": "cartpole"})
+        )
+        app = simulo.App("cartpole", runtime=runtime)
+
+    Nothing is installed on your machine — the runtime is Simulo-built and
+    lives in the cloud; submit only records which runtime the app picked plus
+    the declared env/dependency layers, and the cloud materialises them at
+    execution time.
+    """
+
+    def __init__(self, runtime_id: str) -> None:
+        self._runtime_id = runtime_id
+        self._env: dict[str, str] = {}
+        self._remote_imports: list[str] = []
+        self._torch_jit_marks: list[str] = []
+        self._pip_layers: list[dict[str, Any]] = []
+
+    @classmethod
+    def from_registry(cls, image: str) -> "Runtime":
+        """Pick a Simulo runtime by name (e.g. ``"simulo/gpu-rl:2026.06"``)."""
+        return cls(runtime_id=image)
+
+    @property
+    def runtime_id(self) -> str:
+        """The Simulo runtime name passed to :meth:`from_registry`."""
+        return self._runtime_id
+
+    @property
+    def runtime_env(self) -> Mapping[str, str]:
+        """The accumulated :meth:`env` overrides (a copy)."""
+        return dict(self._env)
+
+    @property
+    def pip_dependencies(self) -> list[dict[str, Any]]:
+        """Ordered public-PyPI dependency layers (defensive deep copy).
+
+        Each layer is ``{"packages": [...], "pre": bool}`` — one entry per
+        :meth:`pip_install` call, in call order. The Simulo image builder
+        installs these on top of the base runtime; submit only records them.
+        """
+        return copy.deepcopy(self._pip_layers)
+
+    def env(self, variables: Mapping[str, str]) -> "Runtime":
+        """Merge environment variables into the job's execution environment.
+
+        Later calls win on key conflicts. Returns ``self`` for chaining.
+        Guarded: runner/worker-owned keys
+        (``simulo.interfaces.platform.RESERVED_RUNTIME_ENV_KEYS`` /
+        ``RESERVED_RUNTIME_ENV_PREFIXES``) are never honoured at execution —
+        enforcement lives at the runner/worker, which also sanitises the pip
+        environment so no variable declared here can redirect the image
+        builder's package installs.
+        """
+        self._env.update(variables)
+        return self
+
+    def pip_install(self, *packages: str, pre: bool = False) -> "Runtime":
+        """Declare public-PyPI packages to add on top of the Simulo runtime.
+
+        Each *package* is a plain PyPI requirement — ``name``, optionally
+        with extras and a version specifier (``"wandb==0.17.0"``,
+        ``"transformers[torch]>=4.40"``). URLs, VCS refs
+        (``git+...``), local paths, and PEP 508 direct references
+        (``name @ url``) are rejected: the Simulo image builder installs from
+        public PyPI only. ``pre=True`` allows pre-release versions for this
+        layer.
+
+        Each call appends an **ordered layer**; the builder installs the
+        layers in order on top of the base runtime. Submit only *records* the
+        layers — nothing is installed locally. A package the base runtime
+        already provides (torch, numpy, the CUDA wheels, the ``simulo``
+        distributions — ``simulo.interfaces.platform.PLATFORM_PINNED_PACKAGES``)
+        cannot be re-declared here; submit fails fast if one is.
+
+        Called with no *packages* (``pip_install()``), this is a no-op — no
+        layer is recorded — rather than appending a vacuous empty layer for
+        every downstream consumer (the manifest, the worker) to special-case.
+
+        Returns ``self`` for chaining.
+        """
+        for spec in packages:
+            _reject_non_pypi_spec(spec)
+        if packages:
+            self._pip_layers.append({"packages": list(packages), "pre": pre})
+        return self
+
+    def torch_jit(self, fn: F) -> F:
+        """Record the function's qualname; JIT-compile only on the worker.
+
+        In discovery (submit) this is a no-op marker — it records the qualname and
+        returns ``fn`` unchanged, so no ``torch`` import happens locally. In
+        execution mode (the backend runner, which has the heavy runtime) it
+        replaces ``@torch.jit.script``: ``torch`` is imported lazily inside the
+        method so module load stays lean.
+        """
+        self._torch_jit_marks.append(fn.__qualname__)
+        if current_mode() == EXECUTION:
+            # Lazy import via importlib (only the worker has torch). importlib keeps
+            # module load lean AND avoids a static ``import torch`` that a torch-free
+            # type-check would flag.
+            script = getattr(importlib.import_module("torch.jit"), "script")
+            return cast(F, script(fn))
+        return fn
+
+    def imports(self) -> AbstractContextManager[None]:
+        """Remote-only-import boundary.
+
+        In execution mode this is a plain ``nullcontext`` (the imports really
+        happen). In discovery mode it installs a stub import finder that records
+        the deferred top-level imports without resolving them — how heavy
+        libraries (``torch`` and friends) stay off your machine at submit.
+        """
+        if current_mode() == DISCOVERY:
+            return stub_import_context(self._remote_imports)
+        return nullcontext()
+
+
+#: The Simulo runtime every :class:`simulo.App` executes in unless it picks a
+#: different one. Simulo-owned and prebuilt — it ships the full simulation +
+#: GPU training stack, so the common path declares no runtime at all. Shared
+#: across every App that omits ``runtime=``: an app that wants its own
+#: ``env()`` / ``pip_install()`` layers should construct its own Runtime via
+#: :meth:`Runtime.from_registry` rather than mutating this shared default.
+DEFAULT_RUNTIME = Runtime.from_registry("simulo/gpu-rl:2026.06")

{simulo-0.13.2 → simulo-0.14.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.13.2
+Version: 0.14.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,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.6,>=0.5
+Requires-Dist: simulo-interfaces<0.7,>=0.6
 Requires-Dist: mcap<2,>=1.3
 Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: usd-core<27,>=25.5

{simulo-0.13.2 → simulo-0.14.0}/src/simulo.egg-info/requires.txt

@@ -1,4 +1,4 @@
-simulo-interfaces<0.6,>=0.5
+simulo-interfaces<0.7,>=0.6
 mcap<2,>=1.3
 defusedxml>=0.7.1
 usd-core<27,>=25.5

simulo-0.13.2/src/simulo/_client/runtime.py

@@ -1,90 +0,0 @@
-"""``Runtime`` — a Simulo-curated runtime (implements ``RuntimeProtocol``).
-
-Simulo owns the runtime: every job executes in a prebuilt, Simulo-managed
-environment that ships everything a robotics training job needs — the
-simulation engine, GPU stack, and the scientific-Python toolchain. You never
-bring your own image, dependencies, or registry; you *pick* a Simulo runtime
-(today there is one, :data:`DEFAULT_RUNTIME`, and it is the default — the
-common path writes nothing).
-
-Locally this class is a lean metadata recorder: ``from_registry`` names the
-Simulo runtime, ``torch_jit`` is a no-op marker at submit (and real
-``torch.jit.script`` on the worker), and ``imports`` is the remote-only-import
-boundary (Rule #3) — a real ``nullcontext`` in execution mode, a
-stub-installing context manager in discovery mode.
-"""
-
-import importlib
-from contextlib import AbstractContextManager, nullcontext
-from typing import Callable, TypeVar, cast
-
-from simulo._client.discovery import stub_import_context
-from simulo._client.mode import DISCOVERY, EXECUTION, current_mode
-
-F = TypeVar("F", bound=Callable[..., object])
-
-
-class Runtime:
-    """A Simulo-curated runtime a job executes in. Torch-free metadata recorder.
-
-    You normally never construct one: every :class:`simulo.App` defaults to
-    :data:`DEFAULT_RUNTIME`. As the curated lineup grows, pick a different
-    Simulo runtime by name::
-
-        runtime = simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")
-        app = simulo.App("cartpole", runtime=runtime)
-
-    Nothing is installed on your machine — the runtime is Simulo-built and
-    lives in the cloud; submit only records which one the app picked.
-    """
-
-    def __init__(self, runtime_id: str) -> None:
-        self._runtime_id = runtime_id
-        self._remote_imports: list[str] = []
-        self._torch_jit_marks: list[str] = []
-
-    @classmethod
-    def from_registry(cls, image: str) -> "Runtime":
-        """Pick a Simulo runtime by name (e.g. ``"simulo/gpu-rl:2026.06"``)."""
-        return cls(runtime_id=image)
-
-    @property
-    def runtime_id(self) -> str:
-        """The Simulo runtime name passed to :meth:`from_registry`."""
-        return self._runtime_id
-
-    def torch_jit(self, fn: F) -> F:
-        """Record the function's qualname; JIT-compile only on the worker.
-
-        In discovery (submit) this is a no-op marker — it records the qualname and
-        returns ``fn`` unchanged, so no ``torch`` import happens locally. In
-        execution mode (the backend runner, which has the heavy runtime) it
-        replaces ``@torch.jit.script``: ``torch`` is imported lazily inside the
-        method so module load stays lean.
-        """
-        self._torch_jit_marks.append(fn.__qualname__)
-        if current_mode() == EXECUTION:
-            # Lazy import via importlib (only the worker has torch). importlib keeps
-            # module load lean AND avoids a static ``import torch`` that a torch-free
-            # type-check would flag.
-            script = getattr(importlib.import_module("torch.jit"), "script")
-            return cast(F, script(fn))
-        return fn
-
-    def imports(self) -> AbstractContextManager[None]:
-        """Remote-only-import boundary.
-
-        In execution mode this is a plain ``nullcontext`` (the imports really
-        happen). In discovery mode it installs a stub import finder that records
-        the deferred top-level imports without resolving them — how heavy
-        libraries (``torch`` and friends) stay off your machine at submit.
-        """
-        if current_mode() == DISCOVERY:
-            return stub_import_context(self._remote_imports)
-        return nullcontext()
-
-
-#: The Simulo runtime every :class:`simulo.App` executes in unless it picks a
-#: different one. Simulo-owned and prebuilt — it ships the full simulation +
-#: GPU training stack, so the common path declares no runtime at all.
-DEFAULT_RUNTIME = Runtime.from_registry("simulo/gpu-rl:2026.06")