simulo-interfaces 0.20.2__tar.gz → 0.22.0__tar.gz

{simulo_interfaces-0.20.2/src/simulo_interfaces.egg-info → simulo_interfaces-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.20.2
+Version: 0.22.0
 Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -47,7 +47,7 @@ Requires-Dist: twine>=5.1; extra == "release"
 shared by the [Simulo SDK](https://pypi.org/project/simulo/) and its managed
 cloud robotics simulation runtime. It defines protocols, enums, identifiers,
 and dataclasses for robot-learning tasks, environments, policies, trainers,
-applications, jobs, assets, checkpoints, and trained models.
+applications, jobs, assets, policies, checkpoints, and policy exports.
 
 ## Install Simulo
 

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/PYPI.md

@@ -4,7 +4,7 @@
 shared by the [Simulo SDK](https://pypi.org/project/simulo/) and its managed
 cloud robotics simulation runtime. It defines protocols, enums, identifiers,
 and dataclasses for robot-learning tasks, environments, policies, trainers,
-applications, jobs, assets, checkpoints, and trained models.
+applications, jobs, assets, policies, checkpoints, and policy exports.
 
 ## Install Simulo
 

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.20.2"
+version = "0.22.0"
 description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/__init__.py

@@ -5,11 +5,11 @@ torch / numpy / gymnasium / Isaac / AWS / HTTP / DB installed. Two parts:
 
 * **Part A — ``simulo.interfaces.runtime``**: tensor-library-agnostic structural
   Protocols mirroring the ``simulo.core`` runtime surface (Task, Policy,
-  Trainer, Player, LearningEnv, Scenario, and the observation/reward/termination
+  Trainer, Player, LearningEnv, and the observation/reward/termination
   components).
 * **Part B — ``simulo.interfaces.platform``**: platform/workspace domain
   contracts — wire-stable enums, frozen domain dataclasses (Project, Package,
-  Job, Resource, Checkpoint, TrainedModel, Tag), and the cloud-execution
+  Job, Resource, Checkpoint, Tag), and the cloud-execution
   Protocols (App, Runtime, Asset, Volume, callbacks, and
   debug/replay/visualization sessions).
 
@@ -19,6 +19,7 @@ namespace that ``simulo-backend`` also contributes to; it ships NO
 """
 
 from simulo.interfaces import platform, runtime
+from simulo.interfaces.authoring import PolicyCheckpoint
 from simulo.interfaces.exceptions import (
     ContractViolationError,
     ImportResolutionError,
@@ -29,29 +30,36 @@ from simulo.interfaces.exceptions import (
 )
 from simulo.interfaces.ids import (
     CheckpointId,
+    CheckpointRefIsJobError,
     Digest,
     JobId,
     JobPublicId,
-    ModelPublicId,
     OrganizationId,
     OutputPublicId,
     PackageId,
+    PolicyPublicId,
     ProjectId,
     RecordingPublicId,
     ResourceId,
     ResourceUri,
     TagId,
-    TrainedModelId,
+    checkpoint_ref_is_job_hint,
+    parse_checkpoint_ref,
     parse_job_public_id,
-    parse_model_public_id,
     parse_output_public_id,
     parse_recording_public_id,
+    policy_id_for_job,
 )
+from simulo.interfaces.platform.enums import JobType
+from simulo.interfaces.runtime import PolicyNetworkProtocol
 
 __all__ = [
     # subpackages
     "platform",
     "runtime",
+    "JobType",
+    "PolicyCheckpoint",
+    "PolicyNetworkProtocol",
     # exception hierarchy
     "SimuloError",
     "ContractViolationError",
@@ -65,16 +73,18 @@ __all__ = [
     "PackageId",
     "JobId",
     "JobPublicId",
-    "ModelPublicId",
+    "PolicyPublicId",
     "RecordingPublicId",
     "OutputPublicId",
     "parse_job_public_id",
-    "parse_model_public_id",
+    "parse_checkpoint_ref",
+    "policy_id_for_job",
+    "checkpoint_ref_is_job_hint",
+    "CheckpointRefIsJobError",
     "parse_recording_public_id",
     "parse_output_public_id",
     "ResourceId",
     "CheckpointId",
-    "TrainedModelId",
     "TagId",
     "ResourceUri",
     "Digest",

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/__init__.py

@@ -41,13 +41,14 @@ waves add the remaining RELOCATE-classified types and MIRROR Protocols.
 **R-C3 is the hard constraint on everything that lands here:** no module in
 this package — or anywhere else in ``simulo-interfaces`` — may import
 ``simulo.core``, ``simulo.backend``, or the thin client's private internal
-package, at import time or at call time (the ``Scene`` trap: zero torch
-imports, but call-time imports of torch-coupled ``core`` modules deep inside a
-method body). Guarded by ``tests/test_no_core_dependency.py`` in this package —
-both a static import-statement guard and a runtime ``sys.modules`` check that
-imports every submodule AND instantiates/calls the relocated API, because the
-static guard alone cannot see ``from simulo import core``, dynamic access, or a
-call-time-only import buried in a method body.
+package at import time. Calls must remain dependency-free too (the ``Scene``
+trap), with one explicit execution-only bridge: ``PolicyCheckpoint.load()``
+lazily imports ``simulo.core.policy.load_policy_network`` inside a job and
+raises the documented submit-time error when the backend is absent. Guarded by
+``tests/test_no_core_dependency.py`` in this package — both a static
+import-statement guard and isolated runtime checks that exercise the relocated
+API, prove ordinary imports remain backend-free, and prove the loader fails
+clearly in a submit-only installation.
 
 Two relocation mechanisms select which types land here and how (see the derived
 plan for the full worked example and rejected alternatives):
@@ -87,6 +88,7 @@ docstring, is the source of truth for what lands here and when.
 
 from simulo.interfaces.authoring.actuator import ActuatorProtocol
 from simulo.interfaces.authoring.asset import AssetSource, URDFAsset, USDAsset
+from simulo.interfaces.authoring.checkpoint import PolicyCheckpoint
 from simulo.interfaces.authoring.entity import AssetEntity, Entity
 from simulo.interfaces.authoring.light import DistantLight, DomeLight, Light, LightConfig
 from simulo.interfaces.authoring.materials import Material, SurfaceMaterial
@@ -171,6 +173,8 @@ __all__ = [
     # record (RELOCATED Wave C4 — the MCAP recording config; its helper
     # functions stay importable from ``simulo.interfaces.authoring.record``)
     "RecordConfig",
+    # injected policy input (dependency-free; loading is deferred to execution)
+    "PolicyCheckpoint",
     # visual
     "VisualMarkerBase",
     "AxesMarker",

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/asset.py

@@ -40,7 +40,7 @@ class USDAsset(AssetSource):
     """USD file asset.
 
     Attributes:
-        path: Path to USD file (supports file://, nucleus:// schemes). The
+        path: Path to a local or supported remote USD file. The
             legacy simulo:// path alias is REMOVED — 'simulo/...' is a catalog
             ref ([publisher/]kind/name[:vN], 'simulo' = the global-catalog
             publisher), resolved through

simulo_interfaces-0.22.0/src/simulo/interfaces/authoring/checkpoint.py

@@ -0,0 +1,84 @@
+"""Dependency-free handle for a policy checkpoint injected into a job."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import Any, cast
+
+from simulo.interfaces.runtime.policy import PolicyNetworkProtocol
+
+
+@dataclass(frozen=True)
+class PolicyCheckpoint:
+    """A resolved policy checkpoint supplied to a play or evaluation job.
+
+    The contract contains only standard-library values. Loading the policy is
+    deliberately deferred until execution, where ``simulo-backend`` provides
+    the concrete policy-network loader.
+    """
+
+    checkpoint: str
+    policy_id: str
+    kind: str
+    path: Path
+    meta: Mapping[str, Any]
+
+    @property
+    def iteration(self) -> int:
+        """Training iteration stored in the checkpoint sidecar."""
+
+        return cast(int, self.meta["completed_iterations"])
+
+    @property
+    def max_iterations(self) -> int:
+        """Configured training limit stored in the checkpoint sidecar."""
+
+        return cast(int, self.meta["max_iterations"])
+
+    @property
+    def reward(self) -> float | None:
+        """Best-checkpoint reward, or ``None`` when the sidecar has none."""
+
+        return cast(float | None, self.meta.get("reward"))
+
+    @property
+    def obs_dim(self) -> int:
+        """Observation width used to train the checkpoint."""
+
+        return cast(int, self.meta["obs_dim"])
+
+    @property
+    def act_dim(self) -> int:
+        """Action width produced by the checkpoint."""
+
+        return cast(int, self.meta["act_dim"])
+
+    @property
+    def task_name(self) -> str:
+        """Name of the task class used for training, if the sidecar has it."""
+
+        return cast(str, self.meta.get("task_name", "unknown"))
+
+    @property
+    def task_digest(self) -> str:
+        """Digest of the file that defined the training task, if available."""
+
+        return cast(str, self.meta.get("task_digest", "unknown"))
+
+    def load(self, device: str = "cuda") -> PolicyNetworkProtocol:
+        """Load the checkpoint as a policy network inside a Simulo job."""
+
+        try:
+            policy_module = import_module("simulo.core.policy")
+        except ImportError as exc:
+            raise RuntimeError(
+                "PolicyCheckpoint.load() runs inside a job on Simulo; it is not available at submit."
+            ) from exc
+        loader = getattr(policy_module, "load_policy_network")
+        return cast(PolicyNetworkProtocol, loader(self, device=device))
+
+
+__all__ = ["PolicyCheckpoint"]

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/primitives.py

@@ -100,8 +100,6 @@ class Transform:
         scene.add(t2, at="/World/Origin2")
         ```
 
-    Backend Mapping:
-        IsaacLab: Maps to Xform prim with translation
     """
 
     def __init__(

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/record.py

@@ -194,7 +194,7 @@ class RecordConfig:
     mitigation depends on the tri-state.
     """
 
-    output_path: Union[str, "os.PathLike[str]", Path]
+    output_path: Optional[Union[str, "os.PathLike[str]", Path]] = None
 
     # Identity
     run_id: Optional[str] = None

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/scene.py

@@ -5,8 +5,7 @@ the ``Scene`` implementation itself stays in the backend package — it is the
 backend adapter (it writes backend-private state and drives engine-private
 methods when the simulation flushes), so its *implementation* cannot live in a
 zero-dependency package. What CAN live here is its declared public surface:
-these Protocols name exactly what authoring code — a ``build(scene)`` method in
-a task or scenario — may rely on.
+these Protocols name exactly what a task's ``build(scene)`` method may rely on.
 
 The backend's concrete ``Scene`` / ``SceneGroup`` classes explicitly inherit
 these Protocols (nominal conformance, the same pattern the ``runtime``

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/terrain.py

@@ -87,7 +87,7 @@ class RoughTerrain(TerrainConfig):
 
     This terrain type generates a grid of sub-terrains with various
     difficulty levels, suitable for curriculum learning in locomotion
-    tasks. Equivalent to IsaacLab's TerrainImporterCfg with TerrainGeneratorCfg.
+    tasks.
 
     Attributes:
         num_rows: Number of terrain rows (sub-terrain grid rows)
@@ -104,7 +104,7 @@ class RoughTerrain(TerrainConfig):
         ```python
         import simulo
 
-        # Create rough terrain matching IsaacLab's H1 configuration
+        # Create a rough terrain configuration
         terrain = simulo.Terrain.rough(
             name="terrain",
             num_rows=10,
@@ -254,7 +254,6 @@ class Terrain:
 
         This creates a grid of sub-terrains with varying difficulty,
         suitable for curriculum learning in locomotion tasks.
-        Equivalent to IsaacLab's TerrainGeneratorCfg with TerrainImporterCfg.
 
         Args:
             name: Terrain name

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/authoring/world.py

@@ -28,9 +28,7 @@ class USDWorld:
     Attributes:
         name: World name
         pose: Pose in space (usually identity for USD scenes)
-        path: Path to USD file. Supports:
-            - Local paths: "/path/to/scene.usd"
-            - Nucleus paths: "nucleus://Isaac/Environments/..."
+        path: Path to a local or supported remote USD file.
             A catalog world (USD Asset Catalogs) is referenced via
             simulo.Asset.from_registry("simulo/world/<name>:v1") and mounted
             like any other asset — a "simulo://" path scheme is not
@@ -43,7 +41,7 @@ class USDWorld:
         # Load warehouse for inference
         warehouse = simulo.World.usd(
             name="warehouse",
-            path="nucleus://Isaac/Environments/Simple_Warehouse/warehouse.usd",
+            path="/path/to/warehouse.usd",
         )
         scene.add(warehouse, at="/World", per_environment=False)
         ```
@@ -80,9 +78,7 @@ class World:
 
         Args:
             name: World name
-            path: Path to USD file. Supports:
-                - Local paths: "/path/to/scene.usd"
-                - Nucleus paths: "nucleus://Isaac/Environments/..."
+            path: Path to a local or supported remote USD file.
             pose: Pose in space (usually identity for USD scenes)
             spawn_origin: Position (x, y, z) where robot should spawn
 
@@ -94,7 +90,7 @@ class World:
             # Inference in warehouse
             warehouse = simulo.World.usd(
                 name="warehouse",
-                path="nucleus://Isaac/Environments/Simple_Warehouse/warehouse.usd",
+                path="/path/to/warehouse.usd",
                 spawn_origin=(0, 0, 0),
             )
             scene.add(warehouse, at="/World", per_environment=False)

{simulo_interfaces-0.20.2 → simulo_interfaces-0.22.0}/src/simulo/interfaces/ids.py

@@ -31,7 +31,7 @@ AssetVersionId = NewType("AssetVersionId", str)  # one immutable asset version (
 OutputId = NewType("OutputId", str)  # a job-produced output in the /outputs projection (Plan B)
 
 JobPublicId = NewType("JobPublicId", str)
-ModelPublicId = NewType("ModelPublicId", str)
+PolicyPublicId = NewType("PolicyPublicId", str)
 RecordingPublicId = NewType("RecordingPublicId", str)
 OutputPublicId = NewType("OutputPublicId", str)
 
@@ -43,9 +43,10 @@ _ASCII_LOWERCASE_TRANSLATION = str.maketrans(
 _JOB_STEM_PATTERN = r"[a-z]{3,10}-[a-z]{3,10}-[0-9a-hjkmnp-tv-z]{6}"
 _CANONICAL_CHILD_COUNTER_PATTERN = r"(?:(?!0000)[0-9]{4}|[1-9][0-9]{4,})"
 _JOB_PUBLIC_ID_RE = re.compile(rf"job_{_JOB_STEM_PATTERN}\Z")
-_MODEL_PUBLIC_ID_RE = re.compile(rf"mdl_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
 _RECORDING_PUBLIC_ID_RE = re.compile(rf"rec_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
 _OUTPUT_PUBLIC_ID_RE = re.compile(rf"out_{_JOB_STEM_PATTERN}-{_CANONICAL_CHILD_COUNTER_PATTERN}\Z")
+_POLICY_CHECKPOINT_REF_RE = re.compile(rf"policy_({_JOB_STEM_PATTERN}):(best|latest)\Z")
+_JOB_CHECKPOINT_REF_RE = re.compile(rf"job_({_JOB_STEM_PATTERN}):(best|latest)\Z")
 _MAX_JOB_PUBLIC_ID_LENGTH = 32
 _MAX_CHILD_PUBLIC_ID_LENGTH = 64
 
@@ -81,24 +82,6 @@ def parse_job_public_id(value: str) -> JobPublicId:
     )
 
 
-def parse_model_public_id(value: str) -> ModelPublicId:
-    """Return a canonical Model ID such as ``mdl_quiet-cedar-7k3m4q-0001``.
-
-    Only outer ASCII whitespace is trimmed and only ASCII ``A-Z`` is
-    lowercased. Matching is exact and non-ASCII input is rejected. Counters
-    use exactly four digits through ``9999`` and expand unpadded at ``10000``.
-    """
-
-    return ModelPublicId(
-        _parse_public_id(
-            value,
-            parser="parse_model_public_id",
-            pattern=_MODEL_PUBLIC_ID_RE,
-            max_length=_MAX_CHILD_PUBLIC_ID_LENGTH,
-        )
-    )
-
-
 def parse_recording_public_id(value: str) -> RecordingPublicId:
     """Return a Recording ID such as ``rec_quiet-cedar-7k3m4q-0001``.
 
@@ -133,3 +116,40 @@ def parse_output_public_id(value: str) -> OutputPublicId:
             max_length=_MAX_CHILD_PUBLIC_ID_LENGTH,
         )
     )
+
+
+class CheckpointRefIsJobError(ValueError):
+    """A checkpoint reference used a job ID where a policy ID is required."""
+
+    def __init__(self, stem: str, kind: str) -> None:
+        self.stem = stem
+        self.kind = kind
+        super().__init__(checkpoint_ref_is_job_hint(stem, kind))
+
+
+def checkpoint_ref_is_job_hint(stem: str, kind: str) -> str:
+    """Format Rule 10's actionable job-reference correction."""
+
+    return f"job_{stem} is a job; did you mean policy_{stem}:{kind}?"
+
+
+def policy_id_for_job(value: str) -> PolicyPublicId:
+    """Return the policy ID for one canonical public job ID."""
+
+    job_id = parse_job_public_id(value)
+    return PolicyPublicId(f"policy_{str(job_id).removeprefix('job_')}")
+
+
+def parse_checkpoint_ref(value: str) -> tuple[PolicyPublicId, str]:
+    """Parse a normalized ``policy_<stem>:best|latest`` checkpoint reference."""
+
+    normalized = _normalize_public_id(value, parser="parse_checkpoint_ref")
+    match = _POLICY_CHECKPOINT_REF_RE.fullmatch(normalized)
+    if match is not None:
+        stem, kind = match.groups()
+        return PolicyPublicId(f"policy_{stem}"), kind
+    job_match = _JOB_CHECKPOINT_REF_RE.fullmatch(normalized)
+    if job_match is not None:
+        stem, kind = job_match.groups()
+        raise CheckpointRefIsJobError(stem, kind)
+    raise ValueError("parse_checkpoint_ref() requires policy_<stem>:best or policy_<stem>:latest.")