simulo-interfaces 0.7.0__tar.gz → 0.10.0__tar.gz

{simulo_interfaces-0.7.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.7.0
+Version: 0.10.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.7.0 → simulo_interfaces-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.7.0"
+version = "0.10.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.7.0 → simulo_interfaces-0.10.0}/src/simulo/interfaces/__init__.py

@@ -1,6 +1,6 @@
 """Simulo Interfaces — implementation-free contract layer for the Simulo platform.
 
-Torch-free, zero-runtime-dependency (Rule #11). Importable on a laptop with no
+Torch-free, zero-runtime-dependency. Importable on a laptop with no
 torch / numpy / gymnasium / Isaac / AWS / HTTP / DB installed. Two parts:
 
 * **Part A — ``simulo.interfaces.runtime``**: tensor-library-agnostic structural

simulo_interfaces-0.10.0/src/simulo/interfaces/authoring/__init__.py

@@ -0,0 +1,189 @@
+"""Part C — the typed authoring surface.
+
+The **relocation and mirror destination** for the Simulo authoring value types.
+Each type here has exactly ONE definition — this one — shared by both
+distributions: the thin client authors these values at submit (torch-free,
+e.g. ``simulo.Pose(xyz=(1, 2, 3))``) and the backend executes them on the
+worker. There is no other copy and no re-export shim anywhere ("nuke as you
+go", per the owner's 2026-07-26 directive recorded in the plan): the former
+backend ``core`` modules for these types are deleted, so ``isinstance`` keeps
+working because only this definition exists.
+
+Relocated so far — Wave C1: ``pose`` (``Pose``), ``materials`` (``Material``,
+``SurfaceMaterial``), ``physics`` (``Physics``, ``Collision``, ``RigidPhysics``,
+``DeformableMaterial``, ``DeformablePhysics``), ``asset`` (``Asset``,
+``USDAsset``, ``URDFAsset`` — the model-source specs, distinct from the thin
+client's registry-handle ``simulo.Asset``), and ``light`` (``Light``,
+``LightConfig``, ``DistantLight``, ``DomeLight``). Wave C2: ``terrain``
+(``Terrain``, ``TerrainConfig``, ``GroundPlane``, ``SubTerrainConfig``,
+``RoughTerrain``), ``primitives`` (``PrimitiveShape``, ``Cone``,
+``Cuboid``, ``Sphere``, ``Cylinder``, ``Transform``), ``entity`` (``Entity``,
+``AssetEntity``), and ``visual`` (``Visual``, ``VisualMarkerBase``,
+``AxesMarker``, ``SphereMarker``, ``ArrowMarker``, ``PointMarker``).
+Wave C4: ``record`` (``RecordConfig`` — the MCAP recording configuration;
+stdlib-only, so it classifies RELOCATE, and the backend recorder imports it
+from here), and ``world`` (``World``, ``USDWorld``): ``Terrain`` is the
+ground you *generate* (``plane``, ``rough``); ``World.usd(...)`` returns
+``USDWorld``, a prebuilt place you *bring*.
+
+Mirrored so far — Wave C2: ``scene`` (``SceneProtocol``, ``SceneGroupProtocol``
+— the first MIRROR; the concrete ``Scene``/``SceneGroup`` stay in the backend
+package and explicitly inherit these Protocols). Wave C3: ``robot``
+(``RobotProtocol``, plus ``RobotStateProtocol`` — the grouped live-state
+contract behind ``robot.state``), ``sensor`` (``SensorProtocol``,
+``CameraProtocol``), and ``actuator`` (``ActuatorProtocol``) — same
+mechanism; the concrete classes
+stay in the backend package and explicitly inherit their Protocols, and the
+other concrete sensor/actuator subclasses conform through their bases. Later
+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.
+
+Two relocation mechanisms select which types land here and how (see the derived
+plan for the full worked example and rejected alternatives):
+
+* **RELOCATE** — the class definition MOVES here; the old ``core/<module>.py``
+  is deleted and every call site rewritten in the same PR (no re-export shims).
+  Reserved for types with zero import-time *or* call-time dependency on
+  anything that cannot live in a zero-dependency package.
+* **MIRROR** — a ``typing.Protocol`` (named ``*Protocol``, matching the
+  ``runtime`` contracts) with real signatures and ``...`` bodies lands here,
+  describing the class's PUBLIC surface only; the backend's ``core/`` class
+  explicitly INHERITS it (nominal conformance, the same pattern
+  ``simulo-protocol`` already blesses for the ``runtime`` Protocols). Reserved
+  for everything else — anything with a real or call-time dependency on torch,
+  numpy, gymnasium, skrl, isaaclab, or another MIRROR-classified ``core``
+  module. Divergence is gated in three measured layers, because no single one
+  suffices: mypy fails signature-*shape* drift (arity, kinds,
+  default-presence, types) at the ``core/`` definition site but is SILENT on
+  parameter renames and on a property degrading to a plain attribute — those
+  need the backend suite's signature-conformance test (per-member bidirectional
+  — it compares the live contract against the live implementation — plus a
+  member-SET equality check over the implementation's statically-derivable
+  public surface: class-body names across its MRO and ``__init__``-bound
+  instance attributes, with a pinned documented-omissions allowlist; an extra
+  public member is legal subtyping no per-member loop can see, and attributes
+  bound outside ``__init__`` stay statically invisible even to the set check)
+  — and
+  constructor signatures need a separate ``__call__``-Protocol pin in the
+  backend's static conformance checks (type checkers exempt ``__init__`` from
+  override checks).
+
+The checked-in authoring-surface inventory table classifies every name
+currently referenced by the example trees (RELOCATE or MIRROR, source module,
+and cross-references for cryptic engine-style names) — that table, not this
+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 Asset, URDFAsset, USDAsset
+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
+from simulo.interfaces.authoring.physics import (
+    Collision,
+    DeformableMaterial,
+    DeformablePhysics,
+    Physics,
+    RigidPhysics,
+)
+from simulo.interfaces.authoring.pose import Pose
+from simulo.interfaces.authoring.primitives import (
+    Cone,
+    Cuboid,
+    Cylinder,
+    PrimitiveShape,
+    Sphere,
+    Transform,
+)
+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.terrain import (
+    GroundPlane,
+    RoughTerrain,
+    SubTerrainConfig,
+    Terrain,
+    TerrainConfig,
+)
+from simulo.interfaces.authoring.visual import (
+    ArrowMarker,
+    AxesMarker,
+    PointMarker,
+    SphereMarker,
+    Visual,
+    VisualMarkerBase,
+)
+from simulo.interfaces.authoring.world import USDWorld, World
+
+__all__ = [
+    # pose
+    "Pose",
+    # materials
+    "Material",
+    "SurfaceMaterial",
+    # physics
+    "Collision",
+    "RigidPhysics",
+    "DeformableMaterial",
+    "DeformablePhysics",
+    "Physics",
+    # asset (model-source specs)
+    "Asset",
+    "USDAsset",
+    "URDFAsset",
+    # light
+    "LightConfig",
+    "DistantLight",
+    "DomeLight",
+    "Light",
+    # terrain (ground you generate)
+    "TerrainConfig",
+    "GroundPlane",
+    "SubTerrainConfig",
+    "RoughTerrain",
+    "Terrain",
+    # world (a prebuilt place you bring — split from terrain in Wave C4)
+    "USDWorld",
+    "World",
+    # primitives
+    "PrimitiveShape",
+    "Cone",
+    "Cuboid",
+    "Sphere",
+    "Cylinder",
+    "Transform",
+    # entity
+    "Entity",
+    "AssetEntity",
+    # record (RELOCATED Wave C4 — the MCAP recording config; its helper
+    # functions stay importable from ``simulo.interfaces.authoring.record``)
+    "RecordConfig",
+    # visual
+    "VisualMarkerBase",
+    "AxesMarker",
+    "SphereMarker",
+    "ArrowMarker",
+    "PointMarker",
+    "Visual",
+    # 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)
+    "RobotProtocol",
+    "RobotStateProtocol",
+    "SensorProtocol",
+    "CameraProtocol",
+    "ActuatorProtocol",
+]

simulo_interfaces-0.10.0/src/simulo/interfaces/authoring/actuator.py

@@ -0,0 +1,53 @@
+"""``ActuatorProtocol`` — the declared actuator authoring contract.
+
+A MIRROR, not a relocation (same mechanism as the Scene, Robot, and Sensor
+contracts in this package): the concrete ``Actuator`` implementation stays in
+the backend package — its command path writes into a live simulation engine
+handle — so what lives here is the declared public surface only.
+
+The backend's concrete ``Actuator`` base class explicitly inherits this
+Protocol (nominal conformance); concrete actuator types (e.g. the surface
+gripper) inherit it through the base and keep their richer surfaces as
+implementation-defined extensions.
+
+Enforcement is the standard four layers for a mirror (see the Robot contract
+module's docstring). ``get_state`` faithfully mirrors today's untyped return:
+a named supported subset for actuator state is a later, separate contract
+decision, deliberately not designed here.
+"""
+
+from typing import Any, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ActuatorProtocol(Protocol):
+    """The actuator authoring contract — an action interface for robots.
+
+    An actuator is configured at authoring time, attached to a scene path,
+    and driven with commands during simulation. Concrete actuator types
+    define their own command and state shapes.
+    """
+
+    path: Optional[str]
+    """Scene path where the actuator is attached (may be set via the scene)."""
+
+    enabled: bool
+    """Whether the actuator is active."""
+
+    @property
+    def name(self) -> Optional[str]:
+        """Actuator name — set by the scene when the actuator is added."""
+        ...
+
+    def set_command(self, command: Any) -> None:
+        """Set an actuator-specific command. Commands are buffered and
+        flushed automatically before the next physics step."""
+        ...
+
+    def get_state(self) -> Any:
+        """Current actuator-specific state."""
+        ...
+
+    def reset(self) -> None:
+        """Reset the actuator to its default state."""
+        ...

simulo_interfaces-0.10.0/src/simulo/interfaces/authoring/asset.py

@@ -0,0 +1,92 @@
+"""Model-source asset specs — USD/URDF sources a scene loads.
+
+Owns the canonical ``Asset`` / ``USDAsset`` / ``URDFAsset`` model-source
+dataclasses. Distinct from the thin client's user-facing ``simulo.Asset``
+registry handle (a catalog ref like ``robot/so-arm-100:v3``): these classes
+name a USD/URDF *file source* to load into a scene, and the backend consumes
+them when it builds the simulation.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+
+@dataclass
+class Asset:
+    """Base asset class."""
+
+    if TYPE_CHECKING:
+        # ``Asset.usd`` / ``Asset.urdf`` are attached dynamically below (they
+        # return the ``USDAsset`` / ``URDFAsset`` subclasses, which are defined
+        # after this class). These declarations never execute; they exist so a
+        # type checker sees the convenience aliases with their precise
+        # signatures instead of rejecting ``Asset.usd(...)`` as an unknown
+        # attribute.
+        @classmethod
+        def usd(cls, path: str) -> "USDAsset": ...
+
+        @classmethod
+        def urdf(cls, path: str) -> "URDFAsset": ...
+
+
+@dataclass
+class USDAsset(Asset):
+    """USD file asset.
+
+    Attributes:
+        path: Path to USD file (supports file://, nucleus:// schemes). The
+            legacy simulo:// path alias is REMOVED — 'simulo/...' is a catalog
+            ref ([publisher/]kind/name[:vN], 'simulo' = the global-catalog
+            publisher), resolved through
+            simulo.Asset.from_registry("robot/<name>:v1"), never a runtime
+            path scheme. A simulo:// path raises a clear migration error at
+            resolution time.
+    """
+
+    path: str
+
+    @classmethod
+    def usd(cls, path: str) -> "USDAsset":
+        """Create a USD asset.
+
+        Args:
+            path: Path to USD file
+
+        Returns:
+            USDAsset instance
+        """
+        return cls(path=path)
+
+
+@dataclass
+class URDFAsset(Asset):
+    """URDF file asset.
+
+    Attributes:
+        path: Path to URDF file
+    """
+
+    path: str
+
+    @classmethod
+    def urdf(cls, path: str) -> "URDFAsset":
+        """Create a URDF asset.
+
+        Args:
+            path: Path to URDF file
+
+        Returns:
+            URDFAsset instance
+        """
+        return cls(path=path)
+
+
+# Alias for convenience — callers reach for `Asset.usd(...)` / `Asset.urdf(...)`.
+# Attached dynamically; the TYPE_CHECKING declarations on Asset above are what
+# let a type checker see them.
+Asset.usd = USDAsset.usd  # type: ignore[method-assign]
+Asset.urdf = URDFAsset.urdf  # type: ignore[method-assign]
+
+# Explicit public surface — keeps the TYPE_CHECKING import (needed for the
+# static-only `usd`/`urdf` declarations above) off the star-import namespace.
+__all__ = ["Asset", "USDAsset", "URDFAsset"]

simulo_interfaces-0.10.0/src/simulo/interfaces/authoring/entity.py

@@ -0,0 +1,180 @@
+"""Entity abstraction for objects in the scene."""
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+from simulo.interfaces.authoring.asset import Asset
+from simulo.interfaces.authoring.materials import Material
+from simulo.interfaces.authoring.physics import DeformablePhysics, RigidPhysics
+from simulo.interfaces.authoring.pose import Pose
+from simulo.interfaces.authoring.primitives import Cone, Cuboid, Cylinder, Sphere
+
+
+@dataclass
+class Entity:
+    """An Entity is any object that can exist within a Scene.
+
+    Entities represent presence. They exist in space, have identity,
+    and may have physical state.
+    """
+
+    name: str
+    pose: Pose = field(default_factory=Pose.identity)
+    material: Optional[Material] = None
+    physics: Optional[RigidPhysics | DeformablePhysics] = None
+
+    class primitive:
+        """Factory for primitive entities."""
+
+        @staticmethod
+        def cone(
+            name: str,
+            radius: float = 0.5,
+            height: float = 1.0,
+            pose: Optional[Pose] = None,
+            material: Optional[Material] = None,
+            physics: Optional[RigidPhysics | DeformablePhysics] = None,
+        ) -> Cone:
+            """Create a cone entity.
+
+            Args:
+                name: Entity name
+                radius: Cone base radius
+                height: Cone height
+                pose: Pose in space
+                material: Visual material
+                physics: Physics properties
+
+            Returns:
+                Cone entity
+            """
+            return Cone(
+                name=name,
+                radius=radius,
+                height=height,
+                pose=pose or Pose.identity(),
+                material=material,
+                physics=physics,
+            )
+
+        @staticmethod
+        def cuboid(
+            name: str,
+            size: Tuple[float, float, float] = (1.0, 1.0, 1.0),
+            pose: Optional[Pose] = None,
+            material: Optional[Material] = None,
+            physics: Optional[RigidPhysics | DeformablePhysics] = None,
+        ) -> Cuboid:
+            """Create a cuboid entity.
+
+            Args:
+                name: Entity name
+                size: Box size as (width, depth, height)
+                pose: Pose in space
+                material: Visual material
+                physics: Physics properties
+
+            Returns:
+                Cuboid entity
+            """
+            return Cuboid(
+                name=name,
+                size=size,
+                pose=pose or Pose.identity(),
+                material=material,
+                physics=physics,
+            )
+
+        @staticmethod
+        def sphere(
+            name: str,
+            radius: float = 0.5,
+            pose: Optional[Pose] = None,
+            material: Optional[Material] = None,
+            physics: Optional[RigidPhysics | DeformablePhysics] = None,
+        ) -> Sphere:
+            """Create a sphere entity.
+
+            Args:
+                name: Entity name
+                radius: Sphere radius
+                pose: Pose in space
+                material: Visual material
+                physics: Physics properties
+
+            Returns:
+                Sphere entity
+            """
+            return Sphere(
+                name=name,
+                radius=radius,
+                pose=pose or Pose.identity(),
+                material=material,
+                physics=physics,
+            )
+
+        @staticmethod
+        def cylinder(
+            name: str,
+            radius: float = 0.5,
+            height: float = 1.0,
+            pose: Optional[Pose] = None,
+            material: Optional[Material] = None,
+            physics: Optional[RigidPhysics | DeformablePhysics] = None,
+        ) -> Cylinder:
+            """Create a cylinder entity.
+
+            Args:
+                name: Entity name
+                radius: Cylinder radius
+                height: Cylinder height
+                pose: Pose in space
+                material: Visual material
+                physics: Physics properties
+
+            Returns:
+                Cylinder entity
+            """
+            return Cylinder(
+                name=name,
+                radius=radius,
+                height=height,
+                pose=pose or Pose.identity(),
+                material=material,
+                physics=physics,
+            )
+
+    @staticmethod
+    def from_asset(
+        name: str,
+        asset: Asset,
+        pose: Optional[Pose] = None,
+    ) -> "AssetEntity":
+        """Create an entity from a USD or URDF asset.
+
+        Args:
+            name: Entity name
+            asset: Asset specification
+            pose: Pose in space
+
+        Returns:
+            AssetEntity instance
+        """
+        return AssetEntity(
+            name=name,
+            asset=asset,
+            pose=pose or Pose.identity(),
+        )
+
+
+@dataclass
+class AssetEntity(Entity):
+    """Entity loaded from an external asset file.
+
+    Attributes:
+        asset: Asset specification (USD, URDF, etc.). Required at construction;
+            ``None`` is not a valid default but is kept here to preserve the
+            existing dataclass field ordering. Callers always supply this.
+    """
+
+    asset: Optional[Asset] = None

simulo_interfaces-0.10.0/src/simulo/interfaces/authoring/light.py

@@ -0,0 +1,87 @@
+"""Light source definitions."""
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple
+
+from simulo.interfaces.authoring.pose import Pose
+
+
+@dataclass
+class LightConfig:
+    """Base light configuration."""
+
+    name: str
+    intensity: float = 1000.0
+    color: Tuple[float, float, float] = (1.0, 1.0, 1.0)
+    pose: Pose = field(default_factory=Pose.identity)
+
+
+@dataclass
+class DistantLight(LightConfig):
+    """Distant (directional) light source.
+
+    Similar to sunlight - parallel rays from infinity.
+    """
+
+    pass
+
+
+@dataclass
+class DomeLight(LightConfig):
+    """Dome light for ambient illumination."""
+
+    pass
+
+
+class Light:
+    """Light factory."""
+
+    @staticmethod
+    def distant(
+        name: str = "distantLight",
+        intensity: float = 1000.0,
+        color: Tuple[float, float, float] = (1.0, 1.0, 1.0),
+        pose: Optional[Pose] = None,
+    ) -> DistantLight:
+        """Create a distant light.
+
+        Args:
+            name: Light name
+            intensity: Light intensity
+            color: RGB color
+            pose: Pose in space
+
+        Returns:
+            DistantLight instance
+        """
+        return DistantLight(
+            name=name,
+            intensity=intensity,
+            color=color,
+            pose=pose or Pose.identity(),
+        )
+
+    @staticmethod
+    def dome(
+        name: str = "domeLight",
+        intensity: float = 1000.0,
+        color: Tuple[float, float, float] = (1.0, 1.0, 1.0),
+    ) -> DomeLight:
+        """Create a dome light.
+
+        Args:
+            name: Light name
+            intensity: Light intensity
+            color: RGB color
+
+        Returns:
+            DomeLight instance
+        """
+        return DomeLight(
+            name=name,
+            intensity=intensity,
+            color=color,
+        )
+
+
+__all__ = ["LightConfig", "DistantLight", "DomeLight", "Light"]