simulo-interfaces 0.11.0__tar.gz → 0.12.0__tar.gz

{simulo_interfaces-0.11.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.11.0
+Version: 0.12.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.11.0"
+version = "0.12.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -26,8 +26,11 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-# black/isort/ruff/mypy pinned EXACT, not >=: see simulo-backend/pyproject.toml's
-# `dev` extra for the full rationale (2026-08-01 ruff 0.15.21->0.16.1 CI incident).
+# black/isort/ruff/mypy pinned EXACT, not >=: these are rule-set tools whose
+# defaults change between releases, so an unbounded lower bound lets CI silently
+# resolve a newer release than a developer's environment has — "clean locally" and
+# "hundreds of errors in CI" both true of one commit (2026-08-01: ruff 0.15.21 ->
+# 0.16.1 flagged 1088 findings from new default rules, zero of them real).
 # Keep in lockstep with `.github/workflows/simulo-interfaces-ci.yml`'s
 # `ruff`/`black`/`isort`/`mypy` steps, which resolve their versions from THIS extra
 # (`pip install -e ".[dev]"`).

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/src/simulo/interfaces/authoring/__init__.py

@@ -106,10 +106,11 @@ from simulo.interfaces.authoring.primitives import (
     Sphere,
     Transform,
 )
+from simulo.interfaces.authoring.prop import PropProtocol, PropStateProtocol
 from simulo.interfaces.authoring.record import RecordConfig
 from simulo.interfaces.authoring.robot import RobotProtocol, RobotStateProtocol
 from simulo.interfaces.authoring.scene import SceneGroupProtocol, SceneProtocol
-from simulo.interfaces.authoring.sensor import CameraProtocol, SensorProtocol
+from simulo.interfaces.authoring.sensor import CameraProtocol
 from simulo.interfaces.authoring.terrain import (
     GroundPlane,
     RoughTerrain,
@@ -180,11 +181,12 @@ __all__ = [
     # scene (MIRROR — the concrete classes live in the backend package)
     "SceneProtocol",
     "SceneGroupProtocol",
-    # robot / sensor / actuator (MIRROR — the concrete classes live in the
-    # backend package and explicitly inherit these Protocols)
+    # robot / prop / sensor / actuator (MIRROR — the concrete classes live in
+    # the backend package and explicitly inherit these Protocols)
     "RobotProtocol",
     "RobotStateProtocol",
-    "SensorProtocol",
+    "PropProtocol",
+    "PropStateProtocol",
     "CameraProtocol",
     "ActuatorProtocol",
 ]

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/src/simulo/interfaces/authoring/pose.py

@@ -17,8 +17,8 @@ class Pose:
         xyz: Position as (x, y, z)
         quat_wxyz: Orientation as quaternion (w, x, y, z)
 
-    Example:
-        ```python
+    Example::
+
         # Using named arguments
         pose = Pose(position=[0.5, 0.3, 0.7], orientation=[1, 0, 0, 0])
 
@@ -27,7 +27,6 @@ class Pose:
 
         # Position only (identity rotation)
         pose = Pose.from_xyz(0.5, 0.3, 0.7)
-        ```
     """
 
     xyz: Tuple[float, float, float] = (0.0, 0.0, 0.0)

simulo_interfaces-0.12.0/src/simulo/interfaces/authoring/prop.py

@@ -0,0 +1,210 @@
+"""``PropProtocol`` — the declared contract for a movable scene prop.
+
+A MIRROR, not a relocation (the same mechanism as the Robot and Scene
+contracts in this package): the concrete ``Prop`` implementation stays in the
+backend package, because reading and writing a prop's pose reaches through a
+live engine handle and cannot exist in a zero-dependency package. What CAN
+live here is the declared public surface — what a prop is constructed from,
+how its live state is read, and how its pose is written.
+
+Why this contract exists at all
+-------------------------------
+
+A scene holds two kinds of movable thing: robots, which the simulation drives
+through joints, and *props* — the block on the table, the crate to push, the
+ball to catch. Robots have carried a full pose surface since the beginning
+(``robot.state.pose``, ``set_root_pose``, ``reset``). Props carried none: a
+shape handed to ``scene.add(...)`` is pure authoring data, so the only way to
+reach the spawned body's pose was the engine-private scene index.
+
+That gap is what kept manipulation demos *scripted*. An episodic task must
+re-randomise its object at the start of every episode and read the object's
+height back to score the lift — both of which are prop pose access. This
+contract closes it.
+
+``PrimitiveShape``, not every entity
+------------------------------------
+
+A prop is built from a :class:`~simulo.interfaces.authoring.primitives.PrimitiveShape`
+carrying **rigid** physics. That restriction is the honest one rather than a
+convenience: a pose that can be read and written is the simulation's own
+rigid-body state, and only a rigid body has one. A visual-only shape (no
+physics) and a deformable one have no rigid-body pose to write, so the
+implementation refuses them at construction, naming the prop — rather than
+accepting them and silently doing nothing at reset time, which would surface
+much later as "my object never moves".
+
+A shape that only needs to be *visible* does not need a prop at all: hand it
+straight to ``scene.add(shape, at=...)`` exactly as before. ``Prop`` is
+strictly the opt-in for "I also need to read or write where this thing is".
+
+Tensors, not ``Pose``
+---------------------
+
+Every batched member here is ``TensorLike`` with the environment count as its
+leading dimension, and the write methods take the same. ``Pose`` remains the
+*authoring* type — where the prop spawns, written once as
+``Cuboid(pose=Pose.from_xyz(...))``. It is deliberately NOT the runtime type:
+a ``Pose`` is one pose, and the entire purpose of this surface is giving each
+of thousands of environments a *different* pose on the same call. See
+``PropProtocol.set_pose`` for the full reasoning.
+
+Enforcement is the standard four layers for a mirror — the type checker alone
+is NOT sufficient (measured on the Scene mirror): mypy catches signature
+*shape* divergence at the backend definition site but is silent on parameter
+renames and on a property degrading to a plain attribute. Those are caught by
+the signature-conformance test in the backend package's suite (per-member,
+both directions, plus member-set equality with a pinned omissions allowlist),
+and the constructor is pinned separately by a ``__call__``-Protocol in the
+backend's static conformance checks (type checkers exempt ``__init__`` from
+override checks). The Protocol stays structural for any other implementer.
+"""
+
+from typing import Optional, Protocol, runtime_checkable
+
+from simulo.interfaces.authoring.primitives import PrimitiveShape
+from simulo.interfaces.runtime.tensors import TensorLike
+
+
+@runtime_checkable
+class PropStateProtocol(Protocol):
+    """The live prop-state contract — batched, read-only, zero-copy.
+
+    Obtained from a prop as ``prop.state``; never constructed directly. The
+    three members are exactly the rigid-body half of
+    :class:`~simulo.interfaces.authoring.robot.RobotStateProtocol` and carry
+    the same names for the same quantities — a prop has no joints, so the
+    three joint members simply do not appear. Code that reads
+    ``robot.state.pose`` reads ``prop.state.pose`` identically.
+
+    Each member is a live view of the simulation's own state buffers: reading
+    one returns the current values without copying, at the same cost inside a
+    training loop's hot path as anywhere else. 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 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
+    (``prop.state`` itself) may be held freely.
+
+    Members raise ``RuntimeError`` until the simulation runtime has attached
+    the prop — read them from ``on_start`` onward. The ``state`` accessor
+    itself is always available and is the same object on every access.
+    """
+
+    @property
+    def pose(self) -> TensorLike:
+        """Pose in the world frame, shape ``(num_envs, 7)``:
+        ``[x, y, z, qw, qx, qy, qz]`` (position + w-first quaternion)."""
+        ...
+
+    @property
+    def linear_velocity(self) -> TensorLike:
+        """Linear velocity in the world frame, shape ``(num_envs, 3)``:
+        ``[vx, vy, vz]``."""
+        ...
+
+    @property
+    def angular_velocity(self) -> TensorLike:
+        """Angular velocity in the world frame, shape ``(num_envs, 3)``:
+        ``[wx, wy, wz]``."""
+        ...
+
+
+@runtime_checkable
+class PropProtocol(Protocol):
+    """The prop authoring contract — a rigid body whose pose you can read and write.
+
+    This is the surface authoring code may rely on when it creates a prop,
+    adds it to a scene, and moves it: the shape it was built from, its
+    identity in the scene, its live state, its spawn pose, and the pose /
+    velocity writes an episodic reset needs.
+    """
+
+    # -- Construction-time configuration ----------------------------------
+
+    shape: PrimitiveShape
+    """The primitive shape this prop spawns, carrying its size, material, and
+    rigid physics. The shape's own ``pose`` is where the prop spawns."""
+
+    # -- Identity and attachment ------------------------------------------
+
+    @property
+    def name(self) -> Optional[str]:
+        """Prop name — taken from the shape, or set by the scene when added."""
+        ...
+
+    @property
+    def path(self) -> Optional[str]:
+        """Scene path — set by the scene when the prop is added."""
+        ...
+
+    @property
+    def state(self) -> PropStateProtocol:
+        """The grouped live prop 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 prop — read them from ``on_start`` onward.
+        """
+        ...
+
+    @property
+    def default_pose(self) -> TensorLike:
+        """The prop's spawn pose in the **world** frame, ``(num_envs, 7)``.
+
+        The pose the prop was authored at, already offset by each
+        environment's own origin — so it is directly comparable with
+        ``state.pose`` and directly usable as the base for a randomised
+        reset. Index it with the environments being reset
+        (``prop.default_pose[env_ids]``), perturb, and write it back with
+        :meth:`set_pose`.
+
+        Raises ``RuntimeError`` until the simulation runtime has attached the
+        prop.
+        """
+        ...
+
+    # -- Pose writes ------------------------------------------------------
+
+    def set_pose(self, pose: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Write the prop's pose directly (teleport, not control), world frame.
+
+        Args:
+            pose: ``(num_envs, 7)`` — or ``(len(env_ids), 7)`` when ``env_ids``
+                is given — as ``[x, y, z, qw, qx, qy, qz]``.
+            env_ids: Environment indices to write; ``None`` writes every
+                environment. Passing the subset being reset is what makes a
+                partial episodic reset possible: the environments that did not
+                finish keep the pose they had.
+        """
+        ...
+
+    def set_velocity(self, velocity: TensorLike, env_ids: Optional[TensorLike] = ...) -> None:
+        """Write the prop's velocity directly (teleport, not control), world frame.
+
+        Args:
+            velocity: ``(num_envs, 6)`` — or ``(len(env_ids), 6)`` when
+                ``env_ids`` is given — as ``[vx, vy, vz, wx, wy, wz]``.
+            env_ids: Environment indices to write; ``None`` writes every
+                environment.
+
+        A reset that moves a prop should zero its velocity too, or the body
+        arrives at its new pose still carrying the momentum it had at the end
+        of the previous episode.
+        """
+        ...
+
+    # -- Lifecycle --------------------------------------------------------
+
+    def reset(self, env_ids: Optional[TensorLike] = ...) -> None:
+        """Return the prop to its spawn pose with zero velocity.
+
+        Args:
+            env_ids: Environment indices to reset; ``None`` resets every
+                environment.
+        """
+        ...

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/src/simulo/interfaces/platform/__init__.py

@@ -7,7 +7,6 @@ implementation-free — concrete behaviour lives in the future
 ``simulo`` client and the ``simulo-backend`` SDK.
 """
 
-from simulo.interfaces.platform.app import AppProtocol, JobFunctionProtocol, Mount
 from simulo.interfaces.platform.artifacts import (
     DECLARED_OUTPUT_MISSING_CODE,
     JOB_ARTIFACT_DOWNLOAD_ROUTE_TEMPLATE,
@@ -97,7 +96,7 @@ from simulo.interfaces.platform.asset_catalog import (
 from simulo.interfaces.platform.callbacks import JobCallbackProtocol
 from simulo.interfaces.platform.debug import DebugSessionProtocol, ReplaySessionProtocol, VisualizationSessionProtocol
 from simulo.interfaces.platform.domain import Checkpoint, Job, Package, Project, Resource, Tag, TrainedModel
-from simulo.interfaces.platform.enums import ArtifactKind, JobStatus, ResourceKind, ResumePolicy
+from simulo.interfaces.platform.enums import ArtifactKind
 from simulo.interfaces.platform.manifest import (
     FINDING_CLASSIFICATIONS,
     MAX_PREFLIGHT_BODY_BYTES,
@@ -124,7 +123,6 @@ from simulo.interfaces.platform.runs import (
     LOG_CHUNK_MAX_BYTES,
     LOG_TAIL_MAX_BYTES,
     TERMINAL_JOB_STATUSES,
-    JobRecord,
 )
 from simulo.interfaces.platform.runtime import RuntimeProtocol
 from simulo.interfaces.platform.submit import (
@@ -158,8 +156,6 @@ from simulo.interfaces.platform.submit import (
     WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE,
     WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE,
     WORKER_LEASE_HEADER,
-    ModelRecord,
-    RecordingRecord,
     canonical_pypi_name,
     is_platform_pinned,
 )
@@ -167,9 +163,6 @@ from simulo.interfaces.platform.volume import VolumeProtocol
 
 __all__ = [
     # enums
-    "JobStatus",
-    "ResumePolicy",
-    "ResourceKind",
     "ArtifactKind",
     # domain dataclasses
     "Tag",
@@ -210,7 +203,6 @@ __all__ = [
     "OUTPUT_FLAG_ANOMALY",
     "DECLARED_OUTPUT_MISSING_CODE",
     # job-run contract (run record schema + jobs HTTP API shape)
-    "JobRecord",
     "TERMINAL_JOB_STATUSES",
     "JOBS_API_DEFAULT_PORT",
     "JOBS_ROUTE",
@@ -249,8 +241,6 @@ __all__ = [
     "MAX_COMPLETE_MESSAGE_CHARS",
     "MAX_COMPLETE_REASON_CODE_CHARS",
     "MODEL_KINDS",
-    "ModelRecord",
-    "RecordingRecord",
     "RESERVED_RUNTIME_ENV_KEYS",
     "RESERVED_RUNTIME_ENV_PREFIXES",
     "PLATFORM_PINNED_PACKAGES",
@@ -337,9 +327,6 @@ __all__ = [
     "AssetProtocol",
     "VolumeProtocol",
     "JobCallbackProtocol",
-    "JobFunctionProtocol",
-    "AppProtocol",
-    "Mount",
     "DebugSessionProtocol",
     "ReplaySessionProtocol",
     "VisualizationSessionProtocol",

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/src/simulo/interfaces/runtime/__init__.py

@@ -28,14 +28,13 @@ from simulo.interfaces.runtime.policy import PolicyProtocol
 from simulo.interfaces.runtime.scenario import ScenarioProtocol
 from simulo.interfaces.runtime.task import TaskProtocol
 from simulo.interfaces.runtime.tensors import TensorLike
-from simulo.interfaces.runtime.trainer import PolicyExporterProtocol, TrainerProtocol
+from simulo.interfaces.runtime.trainer import TrainerProtocol
 
 __all__ = [
     "TensorLike",
     "TaskProtocol",
     "PolicyProtocol",
     "TrainerProtocol",
-    "PolicyExporterProtocol",
     "PlayerProtocol",
     "LearningEnvProtocol",
     "ScenarioProtocol",

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0/src/simulo_interfaces.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.11.0
+Version: 0.12.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.11.0 → simulo_interfaces-0.12.0}/src/simulo_interfaces.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/simulo/interfaces/authoring/materials.py
 src/simulo/interfaces/authoring/physics.py
 src/simulo/interfaces/authoring/pose.py
 src/simulo/interfaces/authoring/primitives.py
+src/simulo/interfaces/authoring/prop.py
 src/simulo/interfaces/authoring/record.py
 src/simulo/interfaces/authoring/robot.py
 src/simulo/interfaces/authoring/scene.py