simulo 0.26.0__py3-none-any.whl

simulo/_client/facades.py

@@ -0,0 +1,581 @@
+"""Typing facades for the instantiated (and called) learning names on ``simulo.*``.
+
+**Never instantiate or call anything from this module at runtime.** These
+classes — and the one plain function below — exist so a type
+checker sees precise types for the *instantiated* learning names
+(``simulo.LearningEnv(...)``, ``simulo.Scene(...)``, ``simulo.Robot(...)``,
+``simulo.RLTrainer(...)``, ``simulo.RLPlayer(...)``) and the one *called*
+name (``simulo.run(...)``, the scenario execution loop). At runtime those
+names resolve through the thin client's internal mode-aware learning-name
+resolver — an inert stand-in at submit, the real heavy class/function on the
+worker — and this module is imported ONLY under ``if TYPE_CHECKING:`` in
+``simulo/__init__.py``.
+
+Why a facade class per name, rather than aliasing the ``simulo.interfaces``
+Protocol (measured, mypy 2.3.0):
+
+* aliasing the Protocol rejects instantiation ("Cannot instantiate protocol
+  class") — which is why these names aliased ``Any`` before Plan C Wave C4;
+* a bare subclass of the Protocol is ABSTRACT to mypy (every ``...``-bodied
+  Protocol member is implicitly abstract in an explicit subclass), so each
+  facade re-declares its contract's full surface — method/property bodies
+  ``raise NotImplementedError`` (they never run; an empty body would trip
+  mypy's ``[empty-body]`` check), data members as bare annotations;
+* the facade additionally declares ``__init__`` with the concrete class's
+  real constructor signature — the one member a Protocol cannot pin.
+
+Drift is not left to review. The backend suite's conformance engine
+(``sdk/tests/test_scene_protocol_conformance.py``) compares every facade
+against its contract (member-set equality + per-member signature comparison,
+parameter NAMES included — mypy is silent on a rename in these
+re-declarations) and every facade ``__init__``, method, property, and bare
+data-annotation member against the CONCRETE ``simulo.core`` class — including
+that a facade data member (``asset``, ``initial_pose``, …) actually EXISTS on
+the concrete class — so a member being renamed, added, or dropped on any of
+the three sides (contract, concrete class, facade) fails a named test by
+member name.
+
+**What is NOT pinned (a known, deliberate gap — Wave C4 fix round):** the
+engine compares parameter/attribute *shape* (name, kind, presence of a
+default) and, for data members, *existence* — never the declared TYPE
+annotation. A facade parameter or data member can carry a narrower or wider
+type than its concrete counterpart (e.g. ``Optional[Any]`` vs
+``Optional[ArticulationConfig]``) with every test above green; only
+``mypy --strict`` on user code that actually touches the divergent member
+would catch it, and only if that code exists. Five such divergences ship
+today, all deliberate widenings where the precise type isn't importable
+thin-side: ``Robot.articulation`` (``Any``), ``Robot.joint_config`` (element
+type ``Any``), ``Robot.asset`` (widened), ``Robot.actuator_gains`` (value
+type ``Any``), ``LearningEnv.viewstream`` (``Any`` vs ``ViewStreamOption``).
+
+The facades deliberately present the surface a user of the bare
+``simulo.<Name>`` may rely on: the contract members, plus the concrete
+class's documented extensions (``RLTrainer.close`` / ``export_policy``;
+``RLPlayer``'s ``record=`` playback, accessors, and exporters). Members the
+contracts deliberately omit (gymnasium plumbing on the env; engine seams)
+are omitted here too — see the interfaces module docstrings for the record.
+
+**``run`` is a plain function, not a class — a different shape for a
+different reason.** There is no ``RunProtocol`` to alias (``run`` is not a
+method any contract declares), so the "why not alias the Protocol" bullets
+above do not apply to it. Its problem is narrower: with no static override at
+all, ``simulo.run`` types as ``object`` (``__getattr__``'s declared return
+type) — which is not merely imprecise, it is **not callable**, so
+``simulo.run(MyScenario, ...)`` in a freshly scaffolded app is a hard mypy
+error a user cannot suppress with ``--ignore-missing-imports`` (that flag
+only silences a *missing import*; ``object`` not being callable is a real
+type error). A bare function with the real ``simulo.scenario.run`` signature
+and a ``NotImplementedError`` body — never called — fixes that the same way
+the classes above fix instantiation. Like ``Camera``, ``run`` is NOT
+registered in the backend suite's four-layer conformance engine (that engine
+pins classes: constructor + method/property members against a Protocol and a
+concrete class; ``run`` is a bare function with no Protocol to check member
+parity against). Its drift guard is a live, unmocked signature comparison
+against the REAL ``simulo.scenario.run`` in ``simulo-backend``'s
+``sdk/tests/test_scenario_run_execution_alias.py`` — stronger than the
+snapshot-only pin ``test_camera_facade.py`` uses, because ``simulo.scenario``
+(unlike ``simulo.core``) is a single-file module with no heavy top-level
+class graph to import.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
+
+from simulo._client.asset import Asset as RegistryAsset
+from simulo.interfaces.authoring import (
+    AssetSource,
+    CameraProtocol,
+    Pose,
+    PrimitiveShape,
+    PropProtocol,
+    PropStateProtocol,
+    RecordConfig,
+    RobotProtocol,
+    RobotStateProtocol,
+    SceneProtocol,
+)
+from simulo.interfaces.runtime import (
+    DebugOnAnomaly,
+    LearningEnvProtocol,
+    PlayerProtocol,
+    ScenarioProtocol,
+    TaskProtocol,
+    TrainerProtocol,
+)
+from simulo.interfaces.runtime.tensors import TensorLike
+
+__all__ = ["Camera", "LearningEnv", "Prop", "RLPlayer", "RLTrainer", "Robot", "run"]
+
+# There is deliberately NO ``Scene`` facade: measured across every shipped
+# user surface (demos, thin examples, templates), ``simulo.Scene`` appears
+# ONLY in annotation position (``def build(self, scene: simulo.Scene)``) —
+# never instantiated (the environment constructs the scene and hands it to
+# ``build``). So ``simulo.Scene`` aliases ``SceneProtocol`` itself, which is
+# also what keeps a user's ``build`` override Liskov-compatible with the
+# contract's ``scene: SceneProtocol`` parameter — a facade subtype there
+# would make every shipped ``build`` annotation an override error.
+
+
+class Camera(CameraProtocol):
+    """Typing facade for the ``simulo.Camera`` authoring surface.
+
+    ``CameraProtocol`` (which extends ``SensorProtocol``) declares the full
+    surface this facade needs, unlike the other sensor subclasses (see the
+    ``simulo/__init__.py`` TYPE_CHECKING block for why ``ContactSensor`` /
+    ``RayCaster`` / ``IMU`` / ``ForceTorqueSensor`` / ``FrameTransformer`` do
+    not get a facade — they conform only to the base ``SensorProtocol``, which
+    would be a lossy alias for their richer, type-specific readers).
+
+    **Known gap (documented, not a silent one):** unlike ``Robot`` /
+    ``LearningEnv`` / ``RLTrainer`` / ``RLPlayer`` above, this facade is NOT
+    registered in the backend suite's conformance engine
+    (``sdk/tests/test_scene_protocol_conformance.py`` pins those four by name,
+    not generically over ``facades.__all__``) — extending that engine to a
+    fifth facade is backend-suite work with its own gate, deliberately
+    deferred rather than bundled in here. Drift between this facade,
+    ``CameraProtocol``, and the concrete ``simulo.core.sensor.Camera`` is
+    caught only by the lighter thin-client-side structural check in
+    ``tests/test_camera_facade.py``, not the four-layer mirror machinery the
+    other facades get.
+    """
+
+    path: Optional[str]
+    update_period: float
+    enabled: bool
+    debug_vis: bool
+    width: int
+    height: int
+    data_types: List[str]
+    offset: Optional[Any]
+    spawn: Any
+
+    def __init__(
+        self,
+        path: Optional[str] = None,
+        width: int = 640,
+        height: int = 480,
+        data_types: Optional[List[str]] = None,
+        update_period: float = 0.0,
+        offset: Optional[Any] = None,
+        spawn: Optional[Any] = None,
+        enabled: bool = True,
+        debug_vis: bool = False,
+    ) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    @property
+    def name(self) -> Optional[str]:
+        raise NotImplementedError
+
+    def update(self, dt: float) -> None:
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        raise NotImplementedError
+
+    def read_rgb(self) -> TensorLike:
+        raise NotImplementedError
+
+    def read_depth(self) -> TensorLike:
+        raise NotImplementedError
+
+    def read_normals(self) -> TensorLike:
+        raise NotImplementedError
+
+    def read_semantic(self) -> TensorLike:
+        raise NotImplementedError
+
+
+class Prop(PropProtocol):
+    """Typing facade for the ``simulo.Prop`` authoring surface.
+
+    ``Prop`` is an *instantiated* mirror name (``simulo.Prop(shape)``), so it
+    follows the same rule as ``Robot`` / ``Camera``: a ``PropProtocol`` alias
+    would make mypy reject the call ("Cannot instantiate protocol class"), and
+    no alias at all would type it as ``object``. Unlike the ``Camera`` facade
+    above, this one IS registered in the backend suite's conformance engine,
+    so drift against both ``PropProtocol`` and the concrete
+    ``simulo.core.prop.Prop`` is caught by the same four-layer machinery
+    ``Robot`` gets.
+    """
+
+    shape: PrimitiveShape
+
+    def __init__(self, shape: PrimitiveShape) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    @property
+    def name(self) -> Optional[str]:
+        raise NotImplementedError
+
+    @property
+    def path(self) -> Optional[str]:
+        raise NotImplementedError
+
+    @property
+    def state(self) -> PropStateProtocol:
+        raise NotImplementedError
+
+    @property
+    def default_pose(self) -> TensorLike:
+        raise NotImplementedError
+
+    def set_pose(self, pose: TensorLike, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+    def set_velocity(self, velocity: TensorLike, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+    def reset(self, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+
+class Robot(RobotProtocol):
+    """Typing facade for the ``simulo.Robot`` authoring surface."""
+
+    asset: AssetSource
+    initial_pose: Pose
+    collision_enabled: bool
+    visual_only: bool
+    mass_scale: float
+    scale: Tuple[float, float, float]
+    articulation: Any
+    joint_config: Optional[List[Any]]
+    disable_gravity: bool
+    actuator_gains: Optional[Dict[str, Any]]
+
+    def __init__(
+        self,
+        # The authoring model-source spec (``AssetSource.usd(...)`` /
+        # ``.urdf(...)``) or the platform registry handle
+        # (``simulo.Asset.from_registry(...)``) — both are shipped calling
+        # conventions; the runtime resolves the registry handle to a model
+        # source on the worker.
+        asset: Union[AssetSource, RegistryAsset],
+        initial_pose: Optional[Pose] = None,
+        collision_enabled: bool = True,
+        visual_only: bool = False,
+        mass_scale: float = 1.0,
+        scale: Tuple[float, float, float] = (1.0, 1.0, 1.0),
+        articulation: Optional[Any] = None,
+        joint_config: Optional[List[Any]] = None,
+        disable_gravity: bool = False,
+        actuator_gains: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    @property
+    def name(self) -> Optional[str]:
+        raise NotImplementedError
+
+    @property
+    def path(self) -> Optional[str]:
+        raise NotImplementedError
+
+    @property
+    def internals(self) -> Any:
+        raise NotImplementedError
+
+    @property
+    def state(self) -> RobotStateProtocol:
+        raise NotImplementedError
+
+    @property
+    def sensors(self) -> List[Any]:
+        raise NotImplementedError
+
+    @property
+    def actuators(self) -> List[Any]:
+        raise NotImplementedError
+
+    @property
+    def num_joints(self) -> int:
+        raise NotImplementedError
+
+    @property
+    def is_fixed_base(self) -> bool:
+        raise NotImplementedError
+
+    def add_sensor(self, sensor: Any, attach_to: str) -> "Robot":
+        raise NotImplementedError
+
+    def add_actuator(self, actuator: Any, attach_to: str) -> "Robot":
+        raise NotImplementedError
+
+    def get_joint_names(self) -> List[str]:
+        raise NotImplementedError
+
+    def find_joints(self, name_pattern: str) -> List[int]:
+        raise NotImplementedError
+
+    def find_bodies(self, name_pattern: str) -> List[int]:
+        raise NotImplementedError
+
+    def get_jacobians(self, body_indices: Optional[List[int]] = None) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_mass_matrix(self, joint_ids: Optional[List[int]] = None) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_gravity_compensation(self, joint_ids: Optional[List[int]] = None) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_body_velocity_in_base_frame(self, body_name: str) -> Optional[Tuple[TensorLike, TensorLike]]:
+        raise NotImplementedError
+
+    def get_body_pose_in_base_frame(self, body_name: str) -> Optional[Any]:
+        raise NotImplementedError
+
+    def set_joint_state(
+        self,
+        positions: TensorLike,
+        velocities: Optional[TensorLike] = None,
+        env_ids: Optional[TensorLike] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def set_joint_position_target(
+        self,
+        positions: TensorLike,
+        joint_ids: Optional[TensorLike] = None,
+        env_ids: Optional[TensorLike] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def set_joint_velocity_target(
+        self,
+        velocities: TensorLike,
+        joint_ids: Optional[TensorLike] = None,
+        env_ids: Optional[TensorLike] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def set_joint_effort_target(
+        self,
+        efforts: TensorLike,
+        joint_ids: Optional[TensorLike] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def set_root_pose(self, pose: TensorLike, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+    def set_root_velocity(self, velocity: TensorLike, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+    def get_body_pose(self, body_name: str) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_body_velocity(self, body_name: str) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_joint_state(self) -> Tuple[Optional[TensorLike], Optional[TensorLike]]:
+        raise NotImplementedError
+
+    def get_root_pose(self) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def get_root_velocity(self) -> Optional[TensorLike]:
+        raise NotImplementedError
+
+    def reset(self, env_ids: Optional[TensorLike] = None) -> None:
+        raise NotImplementedError
+
+    def reset_to_default(self) -> None:
+        raise NotImplementedError
+
+    def update(self, dt: float) -> None:
+        raise NotImplementedError
+
+
+class LearningEnv(LearningEnvProtocol):
+    """Typing facade for the ``simulo.LearningEnv`` runtime surface."""
+
+    num_envs: int
+    task: TaskProtocol
+
+    def __init__(
+        self,
+        task: TaskProtocol,
+        num_envs: int = 1,
+        device: str = "cuda",
+        dt: float = 1.0 / 120.0,
+        physics_steps_per_action: int = 2,
+        env_spacing: float = 4.0,
+        headless: bool = True,
+        seed: int = 0,
+        render_mode: Optional[str] = None,
+        scene_usd: Optional[str] = None,
+        viewstream: Any = None,
+        enable_cameras: bool = False,
+    ) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    @property
+    def device(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def dt(self) -> float:
+        raise NotImplementedError
+
+    @property
+    def physics_dt(self) -> float:
+        raise NotImplementedError
+
+    @property
+    def physics_steps_per_action(self) -> int:
+        raise NotImplementedError
+
+    @property
+    def max_episode_length(self) -> int:
+        raise NotImplementedError
+
+    @property
+    def scene(self) -> SceneProtocol:
+        raise NotImplementedError
+
+    def reset(
+        self, seed: Optional[int] = None, options: Optional[Dict[str, Any]] = None
+    ) -> Tuple[TensorLike, Dict[str, Any]]:
+        raise NotImplementedError
+
+    def step(self, actions: TensorLike) -> Tuple[TensorLike, TensorLike, TensorLike, TensorLike, Dict[str, Any]]:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+
+class RLTrainer(TrainerProtocol):
+    """Typing facade for the ``simulo.RLTrainer`` runtime surface.
+
+    Declares the Trainer contract plus the concrete class's documented
+    extensions: the checkpointing keywords on ``train`` (a compatible
+    extension of the contract signature), ``close``, and the
+    ``export_policy`` capability (the separate narrow exporter contract).
+    """
+
+    def __init__(
+        self,
+        env: LearningEnv,
+        algorithm: str = "PPO",
+        device: str = "cuda",
+        seed: int = 42,
+        log_dir: Optional[str] = None,
+        ml_framework: str = "torch",
+        agent_cfg: Optional[Dict[str, Any]] = None,
+        debug_on_anomaly: Optional[DebugOnAnomaly] = None,
+    ) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    def train(
+        self,
+        max_iterations: int = 1000,
+        *,
+        checkpoint_dir: Optional[str] = None,
+        checkpoint_every: Optional[int] = None,
+        keep_last: Optional[int] = None,
+        resume: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def evaluate(self, checkpoint: Optional[str] = None, num_episodes: int = 10) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def save(self, path: str) -> None:
+        raise NotImplementedError
+
+    def load(self, path: str) -> None:
+        raise NotImplementedError
+
+    def export_policy(self, path: str) -> str:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+
+class RLPlayer(PlayerProtocol):
+    """Typing facade for the ``simulo.RLPlayer`` runtime surface.
+
+    Declares the Player contract plus the concrete class's documented
+    extensions: ``play``'s MCAP ``record=`` keyword (a compatible extension
+    of the contract signature), the ``policy`` / ``agent`` / ``recorder``
+    accessors, and the ONNX/JIT exporters.
+    """
+
+    def __init__(
+        self,
+        env: LearningEnv,
+        checkpoint: str,
+        device: str = "cuda",
+        ml_framework: str = "torch",
+    ) -> None:
+        raise NotImplementedError("typing facade — never instantiate; the runtime object comes from the simulo surface")
+
+    def play(
+        self,
+        num_episodes: Optional[int] = None,
+        num_steps: Optional[int] = None,
+        real_time: bool = False,
+        video_path: Optional[str] = None,
+        video_length: int = 200,
+        deterministic: bool = True,
+        record: Union[None, str, Path, RecordConfig] = None,
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def load(self, path: str) -> None:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+    @property
+    def policy(self) -> Optional[Any]:
+        raise NotImplementedError
+
+    @property
+    def agent(self) -> Optional[Any]:
+        raise NotImplementedError
+
+    @property
+    def recorder(self) -> Optional[Any]:
+        raise NotImplementedError
+
+    def export_onnx(self, path: str) -> None:
+        raise NotImplementedError
+
+    def export_jit(self, path: str) -> None:
+        raise NotImplementedError
+
+
+def run(
+    scenario_class: Type[ScenarioProtocol],
+    device: str = "cuda",
+    dt: float = 0.01,
+    headless: bool = False,
+    seed: int = 0,
+    max_steps: Optional[int] = None,
+    num_envs: int = 1,
+    env_spacing: float = 2.0,
+    enable_cameras: bool = True,
+    viewstream: Any = None,
+) -> None:
+    """Typing facade for the ``simulo.run`` scenario execution loop.
+
+    A plain FUNCTION facade, not a class one — the module docstring's
+    dedicated paragraph on ``run`` explains why this shape exists (``object``
+    is not callable) and where drift against the real
+    ``simulo.scenario.run`` is caught (a live signature comparison in
+    ``simulo-backend``, not this snapshot).
+
+    ``viewstream: Any`` is the same deliberate widening as
+    ``LearningEnv.viewstream`` above and for the identical reason: the real
+    parameter type, ``simulo.streaming.config.ViewStreamOption``, is not
+    importable thin-side (``simulo.streaming`` ships with ``simulo-backend``).
+    """
+    raise NotImplementedError("typing facade — never call; the runtime function comes from the simulo surface")