simulo 0.26.0__py3-none-any.whl

simulo/_client/learning.py

@@ -0,0 +1,393 @@
+"""Mode-aware lazy resolution of the learning / authoring surface.
+
+The thin client exposes the training & simulation authoring names — ``Task``,
+``Scene``, ``Robot``, ``LearningEnv``, ``RLTrainer``, components, … — as clean
+top-level ``simulo.*`` attributes via a PEP 562 ``__getattr__`` in
+``simulo/__init__.py`` that delegates here. The point is to let a user author a
+normal training program with clean names that **submits locally without the heavy
+runtime installed** and is **executed unchanged** by the backend runner.
+
+What a name resolves to depends on the thin client's current submit/execution mode:
+
+* **discovery** (*submit*, the default) — return a lean, torch-free **stand-in** so
+  the user app imports without ``torch`` / ``simulo.core``:
+
+  - *Subclassable* names (``Task``, ``Scenario``, ``Policy``, ``Player``,
+    ``Trainer`` and the
+    three component bases) resolve to a concrete class derived from the matching
+    ``simulo.interfaces.runtime`` ``@runtime_checkable`` Protocol, so
+    ``class CartpoleTask(simulo.Task)`` is definable at module level AND
+    ``isinstance(CartpoleTask(), TaskProtocol)`` holds — the task is nominally
+    contract-typed without importing any heavy runtime.
+  - *Value / config + in-body-only* names (``Scene``, ``Robot``, ``LearningEnv``,
+    ``RLTrainer``, …) resolve to an inert :class:`Stub`, so
+    ``simulo.Scene(...)`` / ``simulo.LearningEnv(...)`` are harmless if touched
+    while a class or job body is *read* (never executed) at submit. The engine
+    authoring vocabulary — ``Camera`` and its sibling sensors, ``Simulation``,
+    the controllers, the actuators, and the ``*Set`` component containers —
+    rides the exact same Stub mechanism: their real definitions live in
+    ``simulo.core`` (torch-adjacent modules), so they cannot be eager imports
+    the way the RELOCATED authoring value types below are.
+  - *Relocated authoring value types* (``Pose``, ``Material``, ``Physics``,
+    ``Light`` since Plan C Wave C1; ``Terrain``, ``Entity``, ``Visual`` since
+    Wave C2; ``RecordConfig`` and ``World`` since Wave C4 — dependency-free,
+    single-definition classes living in
+    ``simulo.interfaces.authoring``) resolve to the **real
+    class in BOTH modes**: they need no heavy runtime, so submit-time authoring
+    gets real construction and precise static typing instead of an inert stub
+    (``RecordConfig`` even validates its fields at construction, so a bad
+    profile now fails at submit instead of on the worker), and
+    ``isinstance`` agrees everywhere because only one definition exists.
+    ``World`` names the authoring concept of a prebuilt place you *bring*
+    (``World.usd(...)``); ``Terrain`` keeps the ground you *generate*
+    (``plane``/``rough``). ``World`` is unrelated to the backend's sim
+    clock, ``core.simulation.Simulation`` — a different class entirely.
+
+* **execution** (*run*, set only by the ``simulo-backend`` runner on a worker that
+  has the heavy runtime) — lazily import the real defining module and return the
+  real class. Most names live on the ``simulo.core`` aggregate; a few resolve from
+  a per-name source module recorded in :data:`_EXECUTION_ALIAS` (``Scenario`` from
+  ``simulo.scenario``, the component bases from their ``simulo.core.<module>``,
+  the relocated value types from ``simulo.interfaces.authoring``).
+
+Importing the heavy runtime happens **only** in execution mode, and only on first
+access (then cached). At submit ``simulo.core`` / ``simulo.recording`` are never
+imported.
+
+Two non-learning names ride the same mechanism:
+
+* ``simulo.save_output`` — the execution-time output registration helper.
+  Its execution-mode target is the torch-free implementation in the thin
+  client's internal outputs module — thin client code, but its call
+  reaches the ``simulo-backend`` registry (``simulo.outputs``), so at
+  discovery it resolves to an inert :class:`Stub` exactly like the
+  value/config names.
+* ``simulo.run`` — the scenario execution loop (``simulo.scenario.run`` on
+  the worker). Called from a job body exactly like ``save_output``
+  (in-body-only, so a discovery-mode touch is harmless and never executes),
+  it resolves at discovery to an inert :class:`Stub` and at execution to the
+  real function via :data:`_EXECUTION_ALIAS`. Before this name existed, the
+  scaffold and shipped examples spelled it ``from simulo.scenario import
+  run`` — a second import into a module the torch-free client cannot even
+  see, breaking the one-import rule.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from simulo._client.mode import EXECUTION, current_mode
+from simulo._client.stub import Stub
+from simulo.interfaces.authoring import Entity, Light, Material, Physics, Pose, RecordConfig, Terrain, Visual, World
+from simulo.interfaces.runtime import (
+    ObservationComponentProtocol,
+    PlayerProtocol,
+    PolicyProtocol,
+    RewardComponentProtocol,
+    ScenarioProtocol,
+    TaskProtocol,
+    TerminationConditionProtocol,
+    TrainerProtocol,
+)
+
+#: Every name exposed lazily and mode-aware on ``simulo`` (the PEP 562
+#: surface). Mostly the learning/authoring names; ``save_output`` and
+#: ``run`` are the two non-learning members — execution-time platform helpers
+#: that need exactly the same resolution (discovery → inert Stub, execution →
+#: the real implementation), so they ride the same mechanism rather than a
+#: parallel one.
+LEARNING_NAMES: frozenset[str] = frozenset(
+    {
+        # subclassable bases
+        "Task",
+        "Scenario",
+        "Policy",
+        "Player",
+        "Trainer",
+        "ObservationComponent",
+        "RewardComponent",
+        "TerminationCondition",
+        # value / config + in-body-only
+        "Scene",
+        "Robot",
+        "LearningEnv",
+        "RLTrainer",
+        "RLPlayer",
+        "RecordConfig",
+        "Pose",
+        "Terrain",
+        "World",
+        "Light",
+        "Entity",
+        "Material",
+        "Physics",
+        "Visual",
+        # engine authoring vocabulary (one-import rule, second half) — value/config classes
+        # and one runtime-context class whose real definition lives in
+        # ``simulo.core`` (torch-adjacent), so they are Stubs in discovery,
+        # never RELOCATED real classes like the authoring types above.
+        "Camera",
+        "CameraSpawnConfig",
+        "SensorOffset",
+        "ContactSensor",
+        "RayCaster",
+        "RayPattern",
+        "IMU",
+        "ForceTorqueSensor",
+        "FrameTransformer",
+        "FrameTransformerTarget",
+        "Simulation",
+        "ObservationSet",
+        "RewardSet",
+        "TerminationSet",
+        "DifferentialIKController",
+        "OperationalSpaceController",
+        "SurfaceGripperActuator",
+        "ParallelGripperActuator",
+        "GripperState",
+        "GripperCommand",
+        "ActuatorGainsConfig",
+        "Prop",
+        # execution-time output registration (Plan B PR-B8) — in-body-only
+        "save_output",
+        # scenario execution loop — in-body-only, real definition in
+        # simulo.scenario (simulo-backend distribution)
+        "run",
+    }
+)
+
+# --- Discovery-mode subclassable bases --------------------------------------
+#
+# A concrete (non-protocol) subclass of a ``@runtime_checkable`` Protocol is both
+# instantiable AND structurally an instance of that Protocol on Python 3.11 and
+# 3.12. Deriving the user-facing base from the Protocol gives ``class
+# X(simulo.Task)`` nominal contract typing while keeping submit torch-free — the
+# stand-in is the Protocol, never ``simulo.core.Task``.
+
+
+class _Task(TaskProtocol):
+    """Discovery stand-in for :class:`simulo.core.task.Task`."""
+
+
+class _Scenario(ScenarioProtocol):
+    """Discovery stand-in for :class:`simulo.scenario.Scenario`."""
+
+
+class _Policy(PolicyProtocol):
+    """Discovery stand-in for :class:`simulo.core.policy.Policy`."""
+
+
+class _Player(PlayerProtocol):
+    """Discovery stand-in for :class:`simulo.core.player.Player`."""
+
+
+class _Trainer(TrainerProtocol):
+    """Discovery stand-in for :class:`simulo.core.trainer.Trainer`.
+
+    Joined the subclassable table in Plan C Wave C4: ``Trainer`` is the
+    user-extensible training-orchestration base (``RLTrainer`` is the
+    instantiated concrete name), so ``class MyTrainer(simulo.Trainer)`` must
+    be definable at module level at submit — a bare :class:`Stub` (its
+    pre-C4 stand-in) is not subclassable at all.
+    """
+
+
+class _ObservationComponent(ObservationComponentProtocol):
+    """Discovery stand-in for ``simulo.core.observations.ObservationComponent``."""
+
+
+class _RewardComponent(RewardComponentProtocol):
+    """Discovery stand-in for ``simulo.core.rewards.RewardComponent``."""
+
+
+class _TerminationCondition(TerminationConditionProtocol):
+    """Discovery stand-in for ``simulo.core.terminations.TerminationCondition``."""
+
+
+class _RobotDiscoveryStandIn:
+    """Discovery-mode ``simulo.Robot`` stand-in that ALSO enforces kind
+    safety — the submit-reachable half of the two-layer split: a module-level/entrypoint ``Robot(asset=<world
+    handle>)`` fails HERE, at construction, because that code path runs during
+    discovery; a task-BODY construction is structurally unreachable at
+    discovery (job bodies never execute at submit) and is instead caught by
+    the execution-mode guard in ``core/robot.py``. Otherwise inert — returns a
+    plain :class:`Stub`, exactly like the bare ``Stub("simulo.Robot")`` this
+    replaces.
+    """
+
+    def __call__(self, *args: object, **kwargs: object) -> Stub:
+        asset = kwargs.get("asset", args[0] if args else None)
+        require_kind = getattr(asset, "require_kind", None)
+        if callable(require_kind):
+            require_kind("robot")
+        return Stub("simulo.Robot()")
+
+    def __getattr__(self, item: str) -> Stub:
+        if item.startswith("__") and item.endswith("__"):
+            raise AttributeError(item)
+        return Stub(f"simulo.Robot.{item}")
+
+
+# Discovery-mode resolution table. Subclassable names map to their Protocol-derived
+# base (a stable singleton class — stable identity for ``isinstance`` / ``issubclass``);
+# value/config names map to an inert :class:`Stub` (``Robot`` maps to the
+# kind-checking stand-in above instead of a bare Stub — see its docstring).
+# RELOCATED authoring value types (``Pose``/``Material``/``Physics``/``Light``
+# from Wave C1; ``Terrain``/``Entity``/``Visual`` from Wave C2;
+# ``RecordConfig``/``World`` from Wave C4)
+# map to their REAL, dependency-free class — the same object execution mode
+# resolves, so submit-time authoring constructs real values (see the module
+# docstring).
+_DISCOVERY_STANDINS: dict[str, object] = {
+    "Task": _Task,
+    "Scenario": _Scenario,
+    "Policy": _Policy,
+    "Player": _Player,
+    "Trainer": _Trainer,
+    "ObservationComponent": _ObservationComponent,
+    "RewardComponent": _RewardComponent,
+    "TerminationCondition": _TerminationCondition,
+    "Scene": Stub("simulo.Scene"),
+    "Robot": _RobotDiscoveryStandIn(),
+    "LearningEnv": Stub("simulo.LearningEnv"),
+    "RLTrainer": Stub("simulo.RLTrainer"),
+    "RLPlayer": Stub("simulo.RLPlayer"),
+    "RecordConfig": RecordConfig,
+    "Pose": Pose,
+    "Terrain": Terrain,
+    "World": World,
+    "Light": Light,
+    "Entity": Entity,
+    "Material": Material,
+    "Physics": Physics,
+    "Visual": Visual,
+    # Engine authoring vocabulary (one-import rule, second half): plain inert Stubs, same
+    # posture as Scene/LearningEnv/RLTrainer/RLPlayer above — none of these
+    # are subclassed, all are constructed and then only touched (attached to
+    # a scene/robot, read for config), which a Stub tolerates harmlessly.
+    "Camera": Stub("simulo.Camera"),
+    "CameraSpawnConfig": Stub("simulo.CameraSpawnConfig"),
+    "SensorOffset": Stub("simulo.SensorOffset"),
+    "ContactSensor": Stub("simulo.ContactSensor"),
+    "RayCaster": Stub("simulo.RayCaster"),
+    "RayPattern": Stub("simulo.RayPattern"),
+    "IMU": Stub("simulo.IMU"),
+    "ForceTorqueSensor": Stub("simulo.ForceTorqueSensor"),
+    "FrameTransformer": Stub("simulo.FrameTransformer"),
+    "FrameTransformerTarget": Stub("simulo.FrameTransformerTarget"),
+    "Simulation": Stub("simulo.Simulation"),
+    "ObservationSet": Stub("simulo.ObservationSet"),
+    "RewardSet": Stub("simulo.RewardSet"),
+    "TerminationSet": Stub("simulo.TerminationSet"),
+    "DifferentialIKController": Stub("simulo.DifferentialIKController"),
+    "OperationalSpaceController": Stub("simulo.OperationalSpaceController"),
+    "SurfaceGripperActuator": Stub("simulo.SurfaceGripperActuator"),
+    "ParallelGripperActuator": Stub("simulo.ParallelGripperActuator"),
+    "GripperState": Stub("simulo.GripperState"),
+    "GripperCommand": Stub("simulo.GripperCommand"),
+    "ActuatorGainsConfig": Stub("simulo.ActuatorGainsConfig"),
+    "Prop": Stub("simulo.Prop"),
+    # ``simulo.save_output`` is in-body-only: job bodies never execute at
+    # submit, so a discovery-mode call (necessarily module-level) is inert and
+    # registers nothing — the same posture as touching ``simulo.Scene(...)``.
+    "save_output": Stub("simulo.save_output"),
+    # ``simulo.run`` (the scenario execution loop) is in-body-only too: a
+    # scenario job's ``@app.job`` body calls ``simulo.run(MyScenario, ...)``
+    # and job bodies never execute at submit, so the discovery-mode call is
+    # inert — same posture as ``save_output`` above.
+    "run": Stub("simulo.run"),
+}
+
+# Execution-mode resolution targets: thin-client name -> (source module, attribute).
+# Most learning names are re-exported from the ``simulo.core`` package aggregate,
+# so they default to ``("simulo.core", name)``. Names whose defining module is NOT
+# the ``simulo.core`` aggregate carry an explicit per-name source module here: the
+# component bases and ``Scenario`` live in their own modules, and ``RecordConfig``
+# belongs to the recording subpackage (``simulo.recording``) — it is deliberately
+# not re-exported from ``simulo.core``.
+_EXECUTION_ALIAS: dict[str, tuple[str, str]] = {
+    "Scenario": ("simulo.scenario", "Scenario"),
+    # ``run`` is the scenario execution loop that takes a ``Scenario``
+    # subclass and drives its lifecycle — it lives alongside ``Scenario``
+    # itself in ``simulo.scenario`` (the simulo-backend distribution), not on
+    # the ``simulo.core`` aggregate.
+    "run": ("simulo.scenario", "run"),
+    "ObservationComponent": ("simulo.core.observations", "ObservationComponent"),
+    "RewardComponent": ("simulo.core.rewards", "RewardComponent"),
+    "TerminationCondition": ("simulo.core.terminations", "TerminationCondition"),
+    # RELOCATED authoring value types (Plan C — Waves C1, C2, then C4's
+    # ``RecordConfig`` — formerly resolved from the recording subpackage —
+    # and C4's ``World``, the spatial-vocabulary split): the
+    # single definition lives in ``simulo.interfaces.authoring`` —
+    # ``simulo.core`` deliberately does NOT re-export it ("nuke as you go", no
+    # shims), so the default ``getattr(simulo.core, name)`` resolution would
+    # fail on the worker.
+    "RecordConfig": ("simulo.interfaces.authoring", "RecordConfig"),
+    "Pose": ("simulo.interfaces.authoring", "Pose"),
+    "Material": ("simulo.interfaces.authoring", "Material"),
+    "Physics": ("simulo.interfaces.authoring", "Physics"),
+    "Light": ("simulo.interfaces.authoring", "Light"),
+    "Terrain": ("simulo.interfaces.authoring", "Terrain"),
+    "World": ("simulo.interfaces.authoring", "World"),
+    "Entity": ("simulo.interfaces.authoring", "Entity"),
+    "Visual": ("simulo.interfaces.authoring", "Visual"),
+    # Engine authoring vocabulary (one-import rule, second half): unlike the RELOCATED
+    # authoring types above, these stay defined in ``simulo.core`` — but
+    # ``simulo.core.__init__`` only re-exports a curated subset onto the
+    # aggregate (measured: ``Simulation``, ``SurfaceGripperActuator``,
+    # ``ParallelGripperActuator``, ``GripperState``, ``GripperCommand``,
+    # ``Prop`` and ``DifferentialIKController`` ARE on the aggregate, so they
+    # fall through to the default ``("simulo.core", name)`` resolution
+    # below and need no entry here). Everything else here is bound only on
+    # its OWN submodule, never on the aggregate, so the default resolution
+    # would raise ``AttributeError`` on the worker without an explicit alias.
+    "Camera": ("simulo.core.sensor", "Camera"),
+    "CameraSpawnConfig": ("simulo.core.sensor", "CameraSpawnConfig"),
+    "SensorOffset": ("simulo.core.sensor", "SensorOffset"),
+    "ContactSensor": ("simulo.core.sensor", "ContactSensor"),
+    "RayCaster": ("simulo.core.sensor", "RayCaster"),
+    "RayPattern": ("simulo.core.sensor", "RayPattern"),
+    "IMU": ("simulo.core.sensor", "IMU"),
+    "ForceTorqueSensor": ("simulo.core.sensor", "ForceTorqueSensor"),
+    "FrameTransformer": ("simulo.core.sensor", "FrameTransformer"),
+    "FrameTransformerTarget": ("simulo.core.sensor", "FrameTransformerTarget"),
+    "ObservationSet": ("simulo.core.observations", "ObservationSet"),
+    "RewardSet": ("simulo.core.rewards", "RewardSet"),
+    "TerminationSet": ("simulo.core.terminations", "TerminationSet"),
+    "OperationalSpaceController": ("simulo.core.controller", "OperationalSpaceController"),
+    "ActuatorGainsConfig": ("simulo.core.robot", "ActuatorGainsConfig"),
+    # The real ``save_output`` lives in the thin client itself (it is
+    # torch-free); only its CALL reaches the ``simulo.outputs`` registry that
+    # ships with ``simulo-backend`` — see ``_client/outputs.py``.
+    "save_output": ("simulo._client.outputs", "save_output"),
+}
+
+# Cache resolved execution-mode classes for stable identity across repeated access.
+_EXECUTION_CACHE: dict[str, object] = {}
+
+
+def _resolve_execution(name: str) -> object:
+    """Lazily import the name's real defining module and return the real class."""
+    module_name, attribute = _EXECUTION_ALIAS.get(name, ("simulo.core", name))
+    module = importlib.import_module(module_name)
+    return getattr(module, attribute)
+
+
+def resolve(name: str) -> object:
+    """Resolve a learning name under the current mode.
+
+    Execution → the real class from its defining module (``simulo.core`` by
+    default, or the per-name source in :data:`_EXECUTION_ALIAS`; imported lazily,
+    then cached). Discovery → the lean torch-free stand-in (a stable singleton) —
+    which for the RELOCATED authoring value types is the real class itself.
+    Raises ``AttributeError`` for any name outside :data:`LEARNING_NAMES`.
+    """
+    if name not in LEARNING_NAMES:
+        raise AttributeError(name)
+    if current_mode() == EXECUTION:
+        cached = _EXECUTION_CACHE.get(name)
+        if cached is None:
+            cached = _resolve_execution(name)
+            _EXECUTION_CACHE[name] = cached
+        return cached
+    return _DISCOVERY_STANDINS[name]