simulo-interfaces 0.21.0__tar.gz → 0.23.0__tar.gz

{simulo_interfaces-0.21.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.21.0
+Version: 0.23.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

{simulo_interfaces-0.21.0 → simulo_interfaces-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.21.0"
+version = "0.23.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.21.0 → simulo_interfaces-0.23.0}/src/simulo/interfaces/__init__.py

@@ -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,
@@ -50,12 +51,15 @@ from simulo.interfaces.ids import (
     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",

{simulo_interfaces-0.21.0 → simulo_interfaces-0.23.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.23.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.21.0 → simulo_interfaces-0.23.0}/src/simulo/interfaces/authoring/record.py

@@ -44,10 +44,13 @@ fingerprint that overrides the auto-collected one when present).
 
 from __future__ import annotations
 
+import math
 import os
+import sys
 from dataclasses import dataclass, field
+from numbers import Real
 from pathlib import Path
-from typing import Any, Dict, Literal, Mapping, Optional, Sequence, Tuple, Union
+from typing import Any, Dict, Literal, Mapping, Optional, Sequence, SupportsFloat, Tuple, Union
 
 # All include_* field names this config exposes. Centralizing avoids drift
 # between the dataclass declaration, _PROFILE_DEFAULTS, and resolve_includes.
@@ -194,7 +197,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
@@ -253,7 +256,14 @@ class RecordConfig:
     video_fallback: Literal["software", "error"] = "software"
     video_codec: Literal["h264", "hevc", "av1"] = "h264"
     video_bitrate: Optional[str] = "8M"
-    video_fps: Optional[int] = 30
+    # ``None`` leaves cadence to the frame producer. The encoder then uses its
+    # documented 30 fps default, but the recorder omits ``video_fps`` from
+    # /run/start because packet timestamps, not an encoder setting, describe
+    # that producer-owned cadence. Callers such as evaluation filming set the
+    # measured cadence explicitly.
+    # Values must also fit a finite IEEE-754 double because both supported
+    # encoders and the MCAP JSON record use that representation.
+    video_fps: Optional[SupportsFloat] = None
     video_gop: Optional[int] = 30
     video_storage: Literal["embedded", "sidecar"] = "embedded"
     # When True (default), the recorder writes a parallel
@@ -300,6 +310,24 @@ class RecordConfig:
             raise ValueError(f"RecordConfig.profile must be one of {VALID_PROFILES}; got {self.profile!r}")
         if self.record_every_n_steps < 1:
             raise ValueError(f"RecordConfig.record_every_n_steps must be >= 1; got {self.record_every_n_steps}")
+        try:
+            video_fps = None if self.video_fps is None else float(self.video_fps)
+        except (OverflowError, TypeError, ValueError):
+            video_fps = None
+        if self.video_fps is not None and (
+            isinstance(self.video_fps, bool)
+            or not isinstance(self.video_fps, Real)
+            or video_fps is None
+            or not math.isfinite(video_fps)
+            # 0.1 fps is a policy floor that keeps rates sensible; ffmpeg's
+            # rational conversion only rounds to zero far below it.
+            or video_fps < 0.1
+            or video_fps > sys.float_info.max
+        ):
+            raise ValueError(
+                "RecordConfig.video_fps must be a finite real number representable by the encoder and at least 0.1 "
+                f"when set; got {self.video_fps!r}"
+            )
         # env_indices: accept any sequence of ints, including a torch tensor —
         # but normalize to a tuple of ints for hashability + reproducibility.
         try:

{simulo_interfaces-0.21.0 → simulo_interfaces-0.23.0}/src/simulo/interfaces/authoring/robot.py

@@ -7,7 +7,7 @@ and reset paths all reach through a live engine handle), so its
 *implementation* cannot live in a zero-dependency package. What CAN live here
 is its declared public surface: this Protocol names exactly what authoring
 code may rely on when it holds a robot — construction-time configuration,
-joint/body queries, command targets, state reads, and reset.
+joint/body queries, command targets, default state, live state reads, and reset.
 
 The backend's concrete ``Robot`` class explicitly inherits this Protocol
 (nominal conformance). Enforcement is the standard four layers for a mirror —
@@ -23,15 +23,16 @@ The Protocol stays structural for any other implementer.
 
 ``state`` is DECLARED, as ``RobotStateProtocol`` — the grouped live-state
 contract. It is the supported, typed way to read a robot's simulation state
-(``robot.state.joint_positions``, ``robot.state.pose``, …): six read-only,
+(``robot.state.joint_positions``, ``robot.state.pose``, …): eight read-only,
 batched members whose names are plain English rather than engine vocabulary.
-The members are LIVE VIEWS — each read goes straight through to the
-simulation's own buffers, at the same cost as reaching through the
-``internals`` escape hatch, with no copy and no per-access container
-allocation — so reading them inside a training loop is free of hidden
-overhead. Unlike ``internals``, these six names ARE a compatibility promise:
-they keep working across engine upgrades, because the backend maps each one
-to whatever the engine calls it.
+Six members are zero-copy live views of the simulation's buffers. The two
+base-frame velocity members are different: the engine rotates the current
+world-frame velocities into the base frame on every read, returning a new
+tensor. That small computation and allocation are the cost of those two
+accesses, and writing into either result does not reach the simulation.
+Unlike ``internals``, all eight names ARE a compatibility promise: they keep
+working across engine upgrades, because the backend maps each one to whatever
+the engine calls it.
 
 Deliberate scoping notes, so they are not mistaken for drift (each is an
 entry in the backend conformance test's documented-omissions allowlist):
@@ -68,27 +69,31 @@ from simulo.interfaces.runtime.tensors import TensorLike
 
 @runtime_checkable
 class RobotStateProtocol(Protocol):
-    """The live robot-state contract — batched, read-only, zero-copy.
+    """The live robot-state contract — batched and read-only.
 
     Obtained from a robot as ``robot.state``; never constructed directly.
-    Each member is a live view of the simulation's own state buffers: reading
-    one returns the current values without copying, and the same access works
-    identically inside a training loop's hot path. All members carry the
-    environment batch as their leading dimension (the scene's ``num_envs``).
+    Six members (``pose``, the two world-frame velocities, and the three
+    ``joint_*`` members) are zero-copy live views of the simulation's own
+    buffers. ``linear_velocity_in_base_frame`` and
+    ``angular_velocity_in_base_frame`` are computed from the current base
+    orientation on every read. Each of those reads returns a new tensor,
+    costs a small computation, and cannot modify the simulation when written
+    into. All members carry the environment batch as their leading dimension
+    (the scene's ``num_envs``).
 
     **Read a member each time you need it — do not hold the returned tensor
-    across steps, and do not write into it.** The tensor IS the simulation's
-    own memory: the engine refreshes most of these buffers by rebinding them
-    to new tensors, so a tensor held across a step can silently serve stale
-    values, and writing into one writes into the simulation. The accessor
-    (``robot.state`` itself) may be held freely; the tensors its members
-    return should be re-read at each use.
+    across steps, and do not write into it.** The six live-view tensors share
+    simulation memory, and writing into one writes into the simulation. The
+    engine can also rebind those buffers, while the base-frame members are
+    recomputed, so a tensor held across a step can silently serve stale values.
+    The accessor (``robot.state`` itself) may be held freely; the tensors its
+    members return should be re-read at each use.
 
     Members raise ``RuntimeError`` until the simulation runtime has attached
     the robot — read them from ``on_start`` onward. The ``state`` accessor
     itself is always available and is the same object on every access.
 
-    These six names are a compatibility promise: they keep working across
+    These eight names are a compatibility promise: they keep working across
     engine upgrades. For anything not named here, the ``internals`` escape
     hatch remains available — explicitly unstable, at your own risk.
     """
@@ -111,6 +116,24 @@ class RobotStateProtocol(Protocol):
         ``[wx, wy, wz]``."""
         ...
 
+    @property
+    def linear_velocity_in_base_frame(self) -> TensorLike:
+        """Base linear velocity expressed in the base frame, shape
+        ``(num_envs, 3)`` in m/s with columns ``[vx, vy, vz]``. Available
+        from ``on_start`` onward. Computed from the current base orientation
+        on every read; each read returns a new tensor, costs a small
+        computation, and writing into it does not reach the simulation."""
+        ...
+
+    @property
+    def angular_velocity_in_base_frame(self) -> TensorLike:
+        """Base angular velocity expressed in the base frame, shape
+        ``(num_envs, 3)`` in rad/s with columns ``[wx, wy, wz]``. Available
+        from ``on_start`` onward. Computed from the current base orientation
+        on every read; each read returns a new tensor, costs a small
+        computation, and writing into it does not reach the simulation."""
+        ...
+
     @property
     def joint_positions(self) -> TensorLike:
         """Joint positions (rad or m), shape ``(num_envs, num_joints)``."""
@@ -146,7 +169,7 @@ class RobotProtocol(Protocol):
     """Model source (USD or URDF) defining the robot."""
 
     initial_pose: Pose
-    """Pose the robot spawns at, in the world frame (identity when not given)."""
+    """Pose the robot spawns at (identity when not given). For a robot copied into each environment, the position is measured from that environment's origin, and default_pose reports it with the origin added. For some catalog robots, such as the cartpole, the identity pose keeps the catalog model's own spawn height; any other pose replaces it. A robot added under a Transform spawns at the Transform's position."""
 
     collision_enabled: bool
     """Whether collision detection is enabled."""
@@ -203,12 +226,45 @@ class RobotProtocol(Protocol):
         """The grouped live robot state — the supported, typed state surface.
 
         Always available (the accessor is the same object on every access);
-        its members read straight through to the simulation's state buffers
-        and raise ``RuntimeError`` until the simulation runtime has attached
-        the robot — read them from ``on_start`` onward.
+        six members read straight through to the simulation's state buffers,
+        while the two base-frame velocity members are computed into new
+        tensors on every read. Members raise ``RuntimeError`` until the
+        simulation runtime has attached the robot — read them from
+        ``on_start`` onward.
         """
         ...
 
+    @property
+    def default_joint_positions(self) -> TensorLike:
+        """Joint positions that :meth:`reset` writes, shape
+        ``(num_envs, num_joints)`` in rad for hinge joints and m for slider
+        joints. Columns use the same order as ``state.joint_positions`` and
+        the indices returned by :meth:`find_joints`. Available from
+        ``on_start`` onward. Each read returns a new tensor, so writing into
+        it cannot change a later reset."""
+        ...
+
+    @property
+    def default_joint_velocities(self) -> TensorLike:
+        """Joint velocities that :meth:`reset` writes, shape
+        ``(num_envs, num_joints)`` in rad/s for hinge joints and m/s for
+        slider joints. Columns use the same order as
+        ``state.joint_positions`` and the indices returned by
+        :meth:`find_joints`. Available from ``on_start`` onward. Each read
+        returns a new tensor, so writing into it cannot change a later
+        reset."""
+        ...
+
+    @property
+    def default_pose(self) -> TensorLike:
+        """Base pose that :meth:`reset` writes in the world frame, shape
+        ``(num_envs, 7)`` with columns ``[x, y, z, qw, qx, qy, qz]``:
+        position in m followed by a w-first unit quaternion. Each
+        environment's origin is included. Available from ``on_start``
+        onward. Each read returns a new tensor, so writing into it cannot
+        change a later reset."""
+        ...
+
     @property
     def sensors(self) -> List[Any]:
         """Sensors attached to this robot via :meth:`add_sensor`."""

{simulo_interfaces-0.21.0 → simulo_interfaces-0.23.0}/src/simulo/interfaces/authoring/terrain.py

@@ -59,10 +59,8 @@ class SubTerrainConfig:
             - "hf_pyramid_slope": Height-field pyramid slope
             - "hf_pyramid_slope_inv": Inverted height-field pyramid slope
         proportion: Proportion of terrain grid to use this type (0.0-1.0).
-            Defaults to 1.0 — "use 100% of the grid for this single
-            sub-terrain". Every in-tree caller passes ``proportion=``
-            explicitly (Wave 0 audit verified), so the default-value
-            change from the pre-Wave-B local default of 0.2 is safe.
+            Defaults to 1.0, which uses the whole grid for this single
+            sub-terrain.
         params: Type-specific parameters (e.g., height, step_height, etc.)
 
     Example: