inspect-robots-so101 0.3.0__py3-none-any.whl

inspect_robots_so101/CLAUDE.md

@@ -0,0 +1,36 @@
+# `inspect_robots_so101` package — module map
+
+Two Inspect Robots components + the glue to make them an honest, testable, safe pair.
+The package is `mypy --strict` clean, ships `py.typed`, and is 100%-covered.
+
+## Modules
+
+| Module | Responsibility |
+|--------|----------------|
+| `packing.py` | **Pure** 6-D SO-ARM packing — the single source of truth for the motor order (`shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper`) and how the flat vector maps to LeRobot's `"<motor>.pos"` dicts. `to_action_dict`/`from_obs_dict`/`validate_dim`, `STATE_KEY`, `STATE_SPEC`, `MOTORS`. No optional deps. |
+| `config.py` | `SOArmConfig` / `LeRobotPolicyConfig` (frozen, `from_kwargs` for CLI scalars) + shared `action_box()` / `observation_space()` / `ACTION_SEMANTICS` so both components declare an **identical** contract. |
+| `operator.py` | `OperatorIO` (injectable stdin/stdout) for readiness + success prompts; `default_poll_end` (real TTY poll, `# pragma: no cover`). |
+| `policy.py` | `LeRobotPolicy` — wraps a LeRobot checkpoint. `act()` builds the RAW robot payload (`"<motor>.pos"` floats, frames keyed by camera name, `task`), runs the injectable `predict_fn`, truncates to `chunk_size`, returns an `ActionChunk`. Real in-process inference is `_default_predict` (lazy torch + lerobot; obs prep via lerobot's own `raw_observation_to_observation`) — NOT pragma'd: it is covered by `sys.modules`-fake tests, and its real import paths are validated by the `lerobot-seam` CI job. |
+| `embodiment.py` | `SOArmEmbodiment` — LeRobot SO follower driver. Clamp backstop, optional delta→abs, `SELF_PACED` pacing, operator-keypress success, context manager (`with emb:` guarantees `close()`; `close()` clears the handle even if disconnect raises). The driver's `get_observation` yields motor positions **and** cameras. Hardware seam (`_default_driver_factory`) is injected/pragma'd; it connects with `calibrate=False` and fails fast via the tested `_check_calibrated` (never lerobot's blocking interactive calibration). |
+| `preflight.py` | `build` / `run_preflight` + the `inspect-robots-so101-preflight` CLI: run the compat check, print, exit non-zero on errors. |
+| `__init__.py` | Public API fenced by `__all__` (guarded by `tests/test_api_snapshot.py`). |
+
+## Key invariants
+
+- **Contract symmetry:** policy and embodiment build their `action_space` /
+  `observation_space` from the *same* `config.py` helpers. If you change the dim,
+  semantics, camera names, or state key, change them there once — not in two
+  places — or compat breaks.
+- **Construction is inert:** `__init__` touches no hardware/model/stdin (only
+  `.info`). The driver connects, and the model loads, lazily on first use. This is
+  what lets the registry (`factories[name]()`) and preflight construct components
+  freely — and keeps `import inspect_robots_so101` free of torch.
+- **Coverage discipline:** the only uncoverable code is hardware/TTY I/O,
+  isolated in `# pragma: no cover` seams (`_default_driver_factory`,
+  `default_poll_end`, the `_require_driver` pre-reset guard, `__main__`).
+  `_default_predict` is NOT pragma'd — it is exercised with `sys.modules` fakes
+  (see `tests/test_policy.py`), and the `lerobot-seam` CI job imports the real
+  lerobot symbols it relies on. Prefer that pattern (fake the modules, assert the
+  wiring, guard the imports in CI) over new pragmas.
+- **Safety lives in `step()`**, not in an optional Approver — see the root
+  `CLAUDE.md`.

inspect_robots_so101/__init__.py

@@ -0,0 +1,38 @@
+"""inspect-robots-so101 — Inspect Robots adapters for LeRobot SO-ARM followers + LeRobot policies.
+
+Registers two Inspect Robots components via entry points:
+
+* embodiment ``so_arm`` — :class:`~inspect_robots_so101.embodiment.SOArmEmbodiment`
+* policy ``lerobot`` — :class:`~inspect_robots_so101.policy.LeRobotPolicy`
+
+so ``inspect-robots run --task cubepick-reach --policy lerobot --embodiment so_arm``
+works once both packages are installed. Use
+:func:`~inspect_robots_so101.preflight.run_preflight` (or the ``inspect-robots-so101-preflight``
+CLI) to verify compatibility before any motion.
+"""
+
+from __future__ import annotations
+
+from inspect_robots_so101.config import LeRobotPolicyConfig, SOArmConfig
+from inspect_robots_so101.embodiment import SOArmEmbodiment
+from inspect_robots_so101.operator import OperatorIO
+from inspect_robots_so101.packing import MOTORS, STATE_KEY, TOTAL_DIM, from_obs_dict, to_action_dict
+from inspect_robots_so101.policy import LeRobotPolicy
+from inspect_robots_so101.preflight import build, run_preflight
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "MOTORS",
+    "STATE_KEY",
+    "TOTAL_DIM",
+    "LeRobotPolicy",
+    "LeRobotPolicyConfig",
+    "OperatorIO",
+    "SOArmConfig",
+    "SOArmEmbodiment",
+    "build",
+    "from_obs_dict",
+    "run_preflight",
+    "to_action_dict",
+]

inspect_robots_so101/config.py

@@ -0,0 +1,180 @@
+"""Configuration for the SO-ARM embodiment and the LeRobot policy client.
+
+Both configs are frozen dataclasses with defaults that match a stock LeRobot SO
+follower (SO-100 / SO-101) and a SmolVLA checkpoint, so zero-arg construction
+"just works" for `.info` / preflight. Each exposes :meth:`from_kwargs` so the
+adapters accept flat scalar keyword arguments — this is what lets
+``inspect-robots run -P pretrained_path=... -E port=...`` configure them, since the
+Inspect Robots CLI only forwards scalar ``key=value`` pairs.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import numpy as np
+import numpy.typing as npt
+from inspect_robots.spaces import (
+    ActionSemantics,
+    Box,
+    CameraSpec,
+    ObservationSpace,
+)
+
+from inspect_robots_so101.packing import NUM_JOINTS, STATE_KEY, STATE_SPEC, TOTAL_DIM
+
+_T = TypeVar("_T", bound="_FromKwargs")
+
+# Conservative default action limits: the five revolute joints in [-180, 180]
+# degrees, the gripper in [0, 100]. These are SAFETY limits — override with your
+# real, calibrated SO-ARM joint limits before trusting them on hardware.
+_DEFAULT_LOW: tuple[float, ...] = (-180.0,) * NUM_JOINTS + (0.0,)
+_DEFAULT_HIGH: tuple[float, ...] = (180.0,) * NUM_JOINTS + (100.0,)
+
+DEFAULT_CAMERAS: tuple[str, ...] = ("front",)
+
+# The SO follower variants lerobot ships. At lerobot v0.5.x both names alias the
+# SAME driver + config classes (SO100Follower = SO101Follower = SOFollower), so
+# `robot_type` is a documented, validated label — it does not change runtime
+# behavior. It exists so configs stay self-describing and so a future lerobot
+# that splits the classes has an obvious wiring point.
+VALID_ROBOT_TYPES: tuple[str, ...] = ("so101_follower", "so100_follower")
+
+
+class _FromKwargs:
+    """Mixin: build a frozen dataclass from flat scalar kwargs (CLI-friendly)."""
+
+    @classmethod
+    def from_kwargs(cls: type[_T], **flat: Any) -> _T:
+        names = {f.name for f in dataclasses.fields(cls)}  # type: ignore[arg-type]
+        unknown = set(flat) - names
+        if unknown:
+            raise TypeError(f"{cls.__name__} got unexpected config keys: {sorted(unknown)}")
+        return cls(**flat)
+
+
+@dataclass(frozen=True)
+class SOArmConfig(_FromKwargs):
+    """Static configuration for a single SO-ARM follower embodiment."""
+
+    port: str = "/dev/ttyACM0"
+    robot_type: str = "so101_follower"  # or "so100_follower" (see VALID_ROBOT_TYPES)
+    # The lerobot robot id: selects the calibration file
+    # (<calibration_dir>/<robot_id>.json, written by `lerobot-calibrate`). Without
+    # it lerobot would look for "None.json" — set it to the id you calibrated with.
+    robot_id: str | None = None
+    # Where lerobot stores calibration files. None -> lerobot's default
+    # (~/.cache/huggingface/lerobot/calibration/robots/<robot_type>/).
+    calibration_dir: str | None = None
+    cameras: tuple[str, ...] = DEFAULT_CAMERAS
+    control_hz: float = 30.0
+    cam_height: int = 480
+    cam_width: int = 640
+    joint_low: tuple[float, ...] = _DEFAULT_LOW
+    joint_high: tuple[float, ...] = _DEFAULT_HIGH
+    home_pose: tuple[float, ...] | None = None
+    joints_are_delta: bool = False
+    use_degrees: bool = True
+    max_relative_target: float | None = None
+    disable_torque_on_disconnect: bool = True
+    # LeRobot CameraConfig objects keyed by camera name, used only by the default
+    # (hardware) driver factory. Opaque to this package; not CLI-settable. Their
+    # keys should match ``cameras``. ``None`` means "build the robot with no
+    # cameras" — fine for preflight, but a real run needs camera streams.
+    camera_configs: Any = None
+
+    def __post_init__(self) -> None:
+        for name in ("joint_low", "joint_high"):
+            if len(getattr(self, name)) != TOTAL_DIM:
+                raise ValueError(f"{name} must have {TOTAL_DIM} entries")
+        if self.home_pose is not None and len(self.home_pose) != TOTAL_DIM:
+            raise ValueError(f"home_pose must have {TOTAL_DIM} entries")
+        if self.robot_type not in VALID_ROBOT_TYPES:
+            raise ValueError(
+                f"robot_type must be one of {VALID_ROBOT_TYPES}, got {self.robot_type!r}"
+            )
+        if not self.use_degrees:
+            # Supporting normalized (+/-100) joints means deriving STATE_SPEC units
+            # and the clamp bounds from the config throughout packing/policy/
+            # embodiment; not implemented yet. Tracked as an issue.
+            raise ValueError(
+                "use_degrees=False is not supported: this package's state spec and "
+                "default joint limits assume degrees (lerobot's SO follower default). "
+                "Leave use_degrees=True, or file/upvote the issue for normalized units."
+            )
+        if self.home_pose is not None and self.max_relative_target is None:
+            # Homing sends ONE absolute command; without lerobot's
+            # max_relative_target slew limit the arm would slam to home at full
+            # speed from wherever it is. Interpolated homing is tracked as an issue.
+            raise ValueError(
+                "home_pose without max_relative_target would command a full-speed "
+                "jump to the home pose; set SOArmConfig.max_relative_target (degrees "
+                "per step) to slew-limit it, or unset home_pose"
+            )
+
+    @property
+    def low(self) -> npt.NDArray[np.float64]:
+        return np.asarray(self.joint_low, dtype=np.float64)
+
+    @property
+    def high(self) -> npt.NDArray[np.float64]:
+        return np.asarray(self.joint_high, dtype=np.float64)
+
+
+@dataclass(frozen=True)
+class LeRobotPolicyConfig(_FromKwargs):
+    """Static configuration for a LeRobot policy loaded from a checkpoint."""
+
+    pretrained_path: str = "lerobot/smolvla_base"
+    policy_type: str = "smolvla"  # act, smolvla, pi0, pi05, diffusion, ...
+    device: str = "cuda"
+    cameras: tuple[str, ...] = DEFAULT_CAMERAS
+    state_key: str = STATE_KEY
+    # Max actions consumed per inference: ``act()`` truncates the model's chunk to
+    # its first ``chunk_size`` actions (mirrors the async policy server's
+    # ``actions_per_chunk``) and advertises it as ``PolicyConfig.action_horizon``.
+    # Distinct from the framework-side ``DefaultController.replan_interval``, which
+    # caps how many actions of an already-returned chunk get executed per replan.
+    chunk_size: int = 50
+    cam_height: int = 480
+    cam_width: int = 640
+
+    def __post_init__(self) -> None:
+        if self.chunk_size < 1:
+            raise ValueError(f"chunk_size must be >= 1, got {self.chunk_size}")
+
+
+# The action *semantics* both the policy and the embodiment declare. Compatibility
+# checking compares control_mode + rotation_repr (errors) and gripper + frame
+# (warnings); declaring this single constant on both sides guarantees a clean check.
+ACTION_SEMANTICS = ActionSemantics(
+    control_mode="joint_pos",
+    rotation_repr="none",
+    gripper="continuous",
+    frame="base",
+)
+
+
+def camera_specs(height: int, width: int, names: tuple[str, ...]) -> tuple[CameraSpec, ...]:
+    """Build CameraSpecs for the given names at one resolution (single source of truth)."""
+    return tuple(CameraSpec(name=n, height=height, width=width, channels=3) for n in names)
+
+
+def action_box(
+    low: npt.NDArray[np.float64] | None = None,
+    high: npt.NDArray[np.float64] | None = None,
+) -> Box:
+    """The shared 6-D joint-position action space. ``low``/``high`` are optional
+    safety limits (the embodiment supplies them; the policy leaves them unset)."""
+    return Box(shape=(TOTAL_DIM,), low=low, high=high, semantics=ACTION_SEMANTICS)
+
+
+def observation_space(height: int, width: int, names: tuple[str, ...]) -> ObservationSpace:
+    """The shared observation space: the configured cameras + packed 6-D ``joint_pos``."""
+    return ObservationSpace(
+        cameras=camera_specs(height, width, names),
+        state_keys=frozenset({STATE_KEY}),
+        state=STATE_SPEC,
+    )

inspect_robots_so101/embodiment.py

@@ -0,0 +1,236 @@
+"""``SOArmEmbodiment`` — Inspect Robots embodiment for a LeRobot SO-ARM follower.
+
+Wraps the LeRobot SO follower driver (SO-100 / SO-101). Designed for real-robot
+reality:
+
+* **Safety backstop** — every command is clamped to the configured joint limits
+  inside :meth:`step`, *independently* of any Inspect Robots ``Approver`` (so unclamped
+  model outputs can never reach the motors). This is layered on top of LeRobot's
+  own ``max_relative_target`` slew limit, which the driver applies.
+* **Operator-in-the-loop success** — there is no privileged oracle; when the
+  operator signals end-of-episode the embodiment returns
+  ``StepResult(terminated=True, termination_reason="success"|"failure")``, which is
+  the only path that reaches the scorer.
+* **Self-paced** — declares ``SELF_PACED`` and sleeps to the control rate inside
+  :meth:`step` (the framework does not pace for us).
+* **No interactive calibration** — the default driver connects with
+  ``calibrate=False`` and fails fast (:func:`_check_calibrated`) when the arm
+  isn't calibrated for ``SOArmConfig.robot_id``, instead of dropping into
+  lerobot's blocking, arm-moving calibration prompt mid-:meth:`reset`.
+
+The driver is injected (``driver_factory``) and so are the clock / sleep / operator
+seams, so the whole embodiment runs in tests with no serial port, no motors, no
+cameras, and no stdin. The real driver — a connected ``lerobot`` SO follower whose
+``get_observation`` already returns both motor positions *and* camera frames — is
+built in a pragma'd default that only executes on hardware.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Protocol, cast, runtime_checkable
+
+import numpy as np
+import numpy.typing as npt
+from inspect_robots.embodiment import SELF_PACED, EmbodimentInfo
+from inspect_robots.scene import Scene
+from inspect_robots.types import Action, Observation, StepResult
+
+from inspect_robots_so101 import packing
+from inspect_robots_so101.config import SOArmConfig, action_box, observation_space
+from inspect_robots_so101.operator import OperatorIO, default_poll_end
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+ImageMap = Mapping[str, npt.NDArray[np.uint8]]
+Vec = npt.NDArray[np.float64]
+
+
+@runtime_checkable
+class SOArmDriver(Protocol):
+    """The minimal LeRobot-robot surface the embodiment needs.
+
+    Satisfied directly by ``lerobot.robots.so_follower.SOFollower`` (and any other
+    LeRobot ``Robot``): observations are dicts of ``"<motor>.pos"`` floats plus
+    camera frames keyed by camera name; actions are dicts of ``"<motor>.pos"``.
+    """
+
+    def get_observation(self) -> Mapping[str, Any]: ...
+
+    def send_action(self, action: Mapping[str, float]) -> Mapping[str, Any]: ...
+
+    def disconnect(self) -> None: ...
+
+
+DriverFactory = Callable[[SOArmConfig], SOArmDriver]
+
+
+def _check_calibrated(robot: Any, cfg: SOArmConfig) -> None:
+    """Refuse to run with an uncalibrated arm, loudly and before any motion.
+
+    ``connect(calibrate=False)`` does **not** raise on missing/mismatched
+    calibration — without this guard the failure would surface mid-``reset()`` as
+    an opaque error at the first normalized read/write. This also catches a
+    calibration file that exists but no longer matches the motors' EEPROM.
+    """
+    if not robot.is_calibrated:
+        raise RuntimeError(
+            f"SO-ARM follower (robot_id={cfg.robot_id!r}) is not calibrated: no calibration "
+            f"matching the motors at {getattr(robot, 'calibration_fpath', '<unknown>')}. "
+            f"Calibrate first with `lerobot-calibrate --robot.type={cfg.robot_type} "
+            f"--robot.port={cfg.port} --robot.id=<your-id>`, then set "
+            "SOArmConfig.robot_id (and calibration_dir if you used a custom one) to match."
+        )
+
+
+def _default_driver_factory(cfg: SOArmConfig) -> SOArmDriver:  # pragma: no cover - real hardware
+    from pathlib import Path
+
+    from lerobot.robots.so_follower import SOFollower
+    from lerobot.robots.so_follower.config_so_follower import SOFollowerRobotConfig
+
+    robot = SOFollower(
+        SOFollowerRobotConfig(
+            id=cfg.robot_id,
+            calibration_dir=Path(cfg.calibration_dir) if cfg.calibration_dir else None,
+            port=cfg.port,
+            cameras=dict(cfg.camera_configs or {}),
+            max_relative_target=cfg.max_relative_target,
+            use_degrees=cfg.use_degrees,
+            disable_torque_on_disconnect=cfg.disable_torque_on_disconnect,
+        )
+    )
+    # NEVER auto-calibrate: lerobot's default connect(calibrate=True) drops into a
+    # BLOCKING interactive calibration that moves the arm — mid-reset(), unprompted.
+    robot.connect(calibrate=False)
+    _check_calibrated(robot, cfg)
+    return cast(SOArmDriver, robot)
+
+
+class SOArmEmbodiment:
+    """Inspect Robots embodiment for a single SO-ARM follower (joint-position control)."""
+
+    def __init__(
+        self,
+        config: SOArmConfig | None = None,
+        *,
+        driver_factory: DriverFactory | None = None,
+        operator: OperatorIO | None = None,
+        poll_end: Callable[[], bool] | None = None,
+        sleep_fn: Callable[[float], None] | None = None,
+        clock: Callable[[], float] | None = None,
+        **flat: Any,
+    ) -> None:
+        self._cfg = config if config is not None else SOArmConfig.from_kwargs(**flat)
+        self._driver_factory: DriverFactory = driver_factory or _default_driver_factory
+        self._operator = operator if operator is not None else OperatorIO()
+        self._poll_end: Callable[[], bool] = poll_end or default_poll_end
+        self._sleep: Callable[[float], None] = sleep_fn or time.sleep
+        self._clock: Callable[[], float] = clock or time.perf_counter
+
+        self._driver: SOArmDriver | None = None
+        self._instruction: str | None = None
+        self._t_last = 0.0
+        self.num_steps = 0
+
+        self.info = EmbodimentInfo(
+            name="so_arm",
+            action_space=action_box(low=self._cfg.low, high=self._cfg.high),
+            observation_space=observation_space(
+                self._cfg.cam_height, self._cfg.cam_width, self._cfg.cameras
+            ),
+            control_hz=self._cfg.control_hz,
+            is_simulated=False,
+            capabilities=frozenset({SELF_PACED}),
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def reset(self, scene: Scene, *, seed: int | None = None) -> Observation:
+        """Connect (if needed), drive to home, and block on operator readiness."""
+        if self._driver is None:
+            self._driver = self._driver_factory(self._cfg)
+        if self._cfg.home_pose is not None:
+            self._send(np.asarray(self._cfg.home_pose, dtype=np.float64))
+        self._operator.wait_ready()
+        self._instruction = scene.instruction
+        self.num_steps = 0
+        self._t_last = self._clock()
+        return self._observe(scene.instruction)
+
+    def step(self, action: Action) -> StepResult:
+        """Clamp + command one action, pace to the control rate, then maybe end."""
+        driver = self._require_driver()
+        self.num_steps += 1
+        cmd = packing.validate_dim(action.data)
+        if self._cfg.joints_are_delta:
+            cmd = packing.from_obs_dict(driver.get_observation()) + cmd
+        self._send(cmd)
+        self._pace()
+
+        obs = self._observe(self._instruction)
+        if self._poll_end():
+            success = self._operator.confirm_success()
+            return StepResult(
+                observation=obs,
+                terminated=True,
+                termination_reason="success" if success else "failure",
+                info={"operator_confirmed": success},
+            )
+        return StepResult(observation=obs, terminated=False)
+
+    def close(self) -> None:
+        """Disconnect and release the driver (no-op if never connected).
+
+        The handle is cleared even if ``disconnect()`` raises, so a failed
+        shutdown can't leave a half-dead driver behind (``close()`` stays
+        idempotent either way).
+        """
+        if self._driver is not None:
+            try:
+                self._driver.disconnect()
+            finally:
+                self._driver = None
+
+    def __enter__(self) -> SOArmEmbodiment:
+        """Support ``with SOArmEmbodiment(...) as emb:`` for guaranteed shutdown."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # -- internals ---------------------------------------------------------
+
+    def _require_driver(self) -> SOArmDriver:
+        if self._driver is None:  # pragma: no cover - reset() always connects first
+            raise RuntimeError("step() called before reset()")
+        return self._driver
+
+    def _send(self, cmd: Vec) -> None:
+        """Clamp to joint limits (safety backstop) and command the motors."""
+        clamped = np.clip(cmd, self._cfg.low, self._cfg.high)
+        self._require_driver().send_action(packing.to_action_dict(clamped))
+
+    def _pace(self) -> None:
+        hz = self._cfg.control_hz
+        if hz and hz > 0:
+            elapsed = self._clock() - self._t_last
+            self._sleep(max(0.0, 1.0 / hz - elapsed))
+        self._t_last = self._clock()
+
+    def _observe(self, instruction: str | None) -> Observation:
+        raw = self._require_driver().get_observation()
+        state = packing.from_obs_dict(raw)
+        images = {cam: np.asarray(raw[cam], dtype=np.uint8) for cam in self._cfg.cameras}
+        return Observation(
+            images=images,
+            state={packing.STATE_KEY: state},
+            instruction=instruction,
+        )

inspect_robots_so101/operator.py

@@ -0,0 +1,51 @@
+"""Operator-in-the-loop confirmation for real hardware runs.
+
+A real tabletop has no privileged success oracle, so the human operator decides.
+All stdin/stdout goes through injectable ``input_fn`` / ``output_fn`` so tests
+drive these paths without a real terminal. The one genuinely TTY-bound piece —
+the non-blocking "operator pressed end" poll — is isolated in
+:func:`default_poll_end`, which is excluded from coverage.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+# Affirmative answers (case-insensitive) for the end-of-episode success prompt.
+_AFFIRMATIVE = frozenset({"y", "yes", "1", "true", "success", "pass"})
+
+
+@dataclass
+class OperatorIO:
+    """Console I/O for operator prompts, with injectable functions for testing."""
+
+    input_fn: Callable[[str], str] = input
+    output_fn: Callable[[str], None] = print
+
+    def wait_ready(self, prompt: str = "Position the scene, then press Enter to start...") -> None:
+        """Block until the operator confirms the scene is set up."""
+        self.input_fn(prompt)
+
+    def confirm_success(self, prompt: str = "Did the robot succeed? [y/N]: ") -> bool:
+        """Return the operator's success verdict (affirmative answers → True)."""
+        answer = self.input_fn(prompt)
+        return answer.strip().lower() in _AFFIRMATIVE
+
+
+def default_poll_end() -> bool:  # pragma: no cover - requires a real TTY
+    """Real non-blocking check for an operator "end episode" keypress.
+
+    Platform/TTY-specific; replaced by a scripted callable in tests. The default
+    returns ``False`` so an unattended run simply runs to ``max_steps``.
+    """
+    import select
+    import sys
+
+    if not sys.stdin.isatty():
+        return False
+    ready, _, _ = select.select([sys.stdin], [], [], 0)
+    if not ready:
+        return False
+    sys.stdin.readline()
+    return True

inspect_robots_so101/packing.py

@@ -0,0 +1,86 @@
+"""Canonical 6-D joint packing for an SO-ARM follower (SO-100 / SO-101).
+
+A LeRobot SO follower is a single 6-motor arm. LeRobot names the motors and keys
+its observations / actions by ``"<motor>.pos"``; Inspect Robots, like the rest of this
+package, works in a flat **6-D** vector. This module is the *one* place that
+defines how those 6 numbers map to the named motors, so the policy (a LeRobot
+model) and the embodiment (the LeRobot driver) can never disagree.
+
+Convention (6-D): ``[shoulder_pan, shoulder_lift, elbow_flex, wrist_flex,
+wrist_roll, gripper]`` — the five revolute joints in order, gripper last. This is
+exactly the motor order of :class:`lerobot.robots.so_follower.SOFollower`.
+
+This module is pure NumPy with no optional/hardware dependencies (no torch, no
+``lerobot``), so it imports and tests anywhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from inspect_robots.spaces import StateField, StateSpec
+
+# The SO follower motor names, in LeRobot's canonical order (see
+# lerobot/robots/so_follower/so_follower.py). The five arm joints then the gripper.
+MOTORS: tuple[str, ...] = (
+    "shoulder_pan",
+    "shoulder_lift",
+    "elbow_flex",
+    "wrist_flex",
+    "wrist_roll",
+    "gripper",
+)
+NUM_JOINTS = 5  # revolute joints
+GRIPPER_DOF = 1  # one gripper
+TOTAL_DIM = NUM_JOINTS + GRIPPER_DOF  # 6-D
+GRIPPER_IDX = TOTAL_DIM - 1  # index 5
+
+# LeRobot keys motor positions as "<motor>.pos" in observations and actions.
+POS_SUFFIX = ".pos"
+
+# The canonical proprioception key. Joints are degrees (the SO follower default,
+# ``use_degrees=True``) and the trailing gripper is a 0..100 position; we model the
+# vector as a single field so ``StateSpec.keys == {"joint_pos"}`` stays consistent
+# with the ``state_keys`` both components declare for compatibility.
+STATE_KEY = "joint_pos"
+STATE_SPEC = StateSpec(
+    fields=(StateField(key=STATE_KEY, shape=(TOTAL_DIM,), unit="deg+normalized"),)
+)
+
+Vec = npt.NDArray[np.float64]
+
+
+def motor_keys() -> tuple[str, ...]:
+    """The LeRobot ``"<motor>.pos"`` keys, in canonical order."""
+    return tuple(f"{m}{POS_SUFFIX}" for m in MOTORS)
+
+
+def validate_dim(vec: npt.ArrayLike, n: int = TOTAL_DIM) -> Vec:
+    """Return ``vec`` as a 1-D float array, raising ``ValueError`` if not length ``n``."""
+    arr = np.asarray(vec, dtype=np.float64).reshape(-1)
+    if arr.shape[0] != n:
+        raise ValueError(
+            f"expected a {n}-D vector, got shape {np.shape(vec)} ({arr.shape[0]} elems)"
+        )
+    return arr
+
+
+def to_action_dict(vec: npt.ArrayLike) -> dict[str, float]:
+    """Turn a flat 6-D vector into LeRobot's ``{"<motor>.pos": value}`` action dict."""
+    arr = validate_dim(vec)
+    return {f"{m}{POS_SUFFIX}": float(arr[i]) for i, m in enumerate(MOTORS)}
+
+
+def from_obs_dict(obs: Mapping[str, Any]) -> Vec:
+    """Extract the flat 6-D joint vector from a LeRobot observation/action dict.
+
+    Reads ``"<motor>.pos"`` for each motor in canonical order. Raises ``KeyError``
+    if any motor position is missing (a misconfigured driver).
+    """
+    try:
+        return np.asarray([float(obs[f"{m}{POS_SUFFIX}"]) for m in MOTORS], dtype=np.float64)
+    except KeyError as exc:
+        raise KeyError(f"observation missing motor position {exc} (need {motor_keys()})") from exc

inspect_robots_so101/policy.py

@@ -0,0 +1,224 @@
+"""``LeRobotPolicy`` — a Inspect Robots policy backed by a LeRobot checkpoint.
+
+LeRobot policies (ACT, SmolVLA, π0, diffusion, …) are ordinary ``nn.Module``\\ s
+loaded from the Hugging Face Hub and run **in process** on the GPU. Unlike the
+YAM/MolmoAct2 stack (where the model owns its own HTTP server), LeRobot models are
+a library you import — so the heavy, GPU-bound dependencies (``torch`` +
+``lerobot`` + the checkpoint) live behind a single injectable seam: a
+``predict_fn`` that maps a **raw robot-style observation dict** (``"<motor>.pos"``
+floats, camera frames keyed by camera name, and ``"task"``) to an action chunk.
+
+The default ``predict_fn`` (``_default_predict``) lazily builds the policy and its
+pre/post-processors from a pretrained path and prepares each observation with
+lerobot's own ``raw_observation_to_observation`` helper — the same path
+``lerobot.async_inference.policy_server`` uses — so torch conversion, HWC→CHW,
+0..1 scaling, resizing, and batching stay lerobot's job, not ours. Tests exercise
+this wiring with ``sys.modules`` fakes (no torch, no lerobot, no network), and the
+``lerobot-seam`` CI job re-imports the real symbols on Python 3.12 to catch
+upstream drift. ``import inspect_robots_so101`` never imports torch.
+
+The action chunk this policy returns is already in the robot's **native motor
+units** (degrees for the joints, 0..100 for the gripper): LeRobot's postprocessor
+unnormalizes for us, so the embodiment commands the values verbatim (after its
+safety clamp). There is therefore no gripper renormalization here.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from inspect_robots.policy import PolicyConfig, PolicyInfo
+from inspect_robots.scene import Scene
+from inspect_robots.types import Action, ActionChunk, Observation
+
+from inspect_robots_so101 import packing
+from inspect_robots_so101.config import LeRobotPolicyConfig, action_box, observation_space
+
+# A RAW robot-style observation dict -> an (N, action_dim) action-chunk array.
+# Keys: "<motor>.pos" floats (packing.motor_keys()), camera frames keyed by the
+# camera name, and "task" (the instruction) — exactly what a lerobot Robot's
+# get_observation() returns, plus the task string. The default predict_fn feeds
+# this to lerobot's raw_observation_to_observation, which packs it into
+# "observation.state" / "observation.images.<cam>" tensors itself.
+LeRobotObs = Mapping[str, Any]
+PredictFn = Callable[[LeRobotObs], npt.NDArray[np.floating[Any]]]
+
+# LeRobot key conventions (see lerobot/utils/constants.py). Hardcoded so this
+# module needs no lerobot import.
+OBS_STR = "observation"
+OBS_IMAGE_PREFIX = "observation.images."
+TASK_KEY = "task"
+
+
+def _import_hw_to_dataset_features() -> Callable[..., dict[str, Any]]:
+    """Import lerobot's ``hw_to_dataset_features`` across supported versions.
+
+    lerobot moved it from ``lerobot.datasets.utils`` (v0.5.0) to
+    ``lerobot.datasets.feature_utils`` (v0.5.1); the ``lerobot-seam`` CI job
+    guards this against further drift.
+    """
+    try:
+        from lerobot.datasets.feature_utils import hw_to_dataset_features
+    except ImportError:  # lerobot == 0.5.0
+        from lerobot.datasets.utils import hw_to_dataset_features
+    return hw_to_dataset_features  # type: ignore[no-any-return]
+
+
+def _hw_observation_features(cfg: LeRobotPolicyConfig) -> dict[str, Any]:
+    """Reconstruct the SO follower's ``observation_features`` mapping.
+
+    The policy never holds a lerobot ``Robot`` object (the embodiment owns the
+    driver), so we synthesize the same mapping the driver would report —
+    ``"<motor>.pos" -> float`` for each motor in canonical order plus
+    ``"<camera>" -> (height, width, 3)`` for each configured camera — for
+    ``hw_to_dataset_features`` to turn into lerobot dataset features.
+    """
+    features: dict[str, Any] = dict.fromkeys(packing.motor_keys(), float)
+    for cam in cfg.cameras:
+        features[cam] = (cfg.cam_height, cfg.cam_width, 3)
+    return features
+
+
+def _default_predict(cfg: LeRobotPolicyConfig) -> PredictFn:
+    """Build an in-process LeRobot inference closure from a pretrained checkpoint.
+
+    Mirrors ``lerobot.async_inference.policy_server``: load the policy class from
+    the factory, build the matching pre/post-processor pipelines, then per call
+    ``raw_observation_to_observation`` → preprocess → ``predict_action_chunk`` →
+    postprocess back to native motor units.
+    """
+    import torch
+    from lerobot.async_inference.helpers import raw_observation_to_observation
+    from lerobot.policies.factory import get_policy_class, make_pre_post_processors
+
+    hw_to_dataset_features = _import_hw_to_dataset_features()
+
+    policy = get_policy_class(cfg.policy_type).from_pretrained(cfg.pretrained_path)
+    policy.to(cfg.device)
+    policy.eval()  # torch nn.Module inference mode (not Python's eval builtin)
+    preprocessor, postprocessor = make_pre_post_processors(
+        policy.config,
+        pretrained_path=cfg.pretrained_path,
+        preprocessor_overrides={"device_processor": {"device": cfg.device}},
+        postprocessor_overrides={"device_processor": {"device": cfg.device}},
+    )
+
+    # The dataset-feature spec raw_observation_to_observation uses to pack raw
+    # "<motor>.pos" keys into "observation.state" and camera frames into
+    # "observation.images.<cam>" (use_video=False: these are live frames).
+    lerobot_features = hw_to_dataset_features(
+        _hw_observation_features(cfg), OBS_STR, use_video=False
+    )
+    policy_image_features = dict(policy.config.image_features)
+    missing = [
+        cam for cam in cfg.cameras if f"{OBS_IMAGE_PREFIX}{cam}" not in policy_image_features
+    ]
+    if missing:
+        raise ValueError(
+            f"checkpoint {cfg.pretrained_path!r} was trained with image features "
+            f"{sorted(policy_image_features)} which do not cover configured camera(s) "
+            f"{missing} (expected {[OBS_IMAGE_PREFIX + cam for cam in missing]}); "
+            "set LeRobotPolicyConfig.cameras to the camera names the checkpoint expects"
+        )
+
+    def _predict(obs: LeRobotObs) -> npt.NDArray[np.floating[Any]]:
+        observation = raw_observation_to_observation(
+            dict(obs), lerobot_features, policy_image_features
+        )
+        batch = preprocessor(observation)
+        with torch.no_grad():
+            chunk = policy.predict_action_chunk(batch)
+        if chunk.ndim == 2:
+            chunk = chunk.unsqueeze(0)
+        out = torch.stack(
+            [postprocessor(chunk[:, i, :]) for i in range(chunk.shape[1])], dim=1
+        ).squeeze(0)
+        return out.detach().cpu().numpy()  # type: ignore[no-any-return]
+
+    return _predict
+
+
+class LeRobotPolicy:
+    """Inspect Robots policy wrapping a LeRobot checkpoint for the SO-ARM action space."""
+
+    def __init__(
+        self,
+        config: LeRobotPolicyConfig | None = None,
+        *,
+        predict_fn: PredictFn | None = None,
+        **flat: Any,
+    ) -> None:
+        self._cfg = config if config is not None else LeRobotPolicyConfig.from_kwargs(**flat)
+        self._predict_fn = predict_fn
+        self._instruction: str | None = None
+        self.num_inferences = 0
+        self.info = PolicyInfo(
+            name="lerobot",
+            action_space=action_box(),  # semantics only; the embodiment owns limits
+            observation_space=observation_space(
+                self._cfg.cam_height, self._cfg.cam_width, self._cfg.cameras
+            ),
+            # Intentionally None: advertising a rate would trip a (harmless) compat
+            # control_rate warning. The embodiment paces the rollout.
+            control_hz=None,
+        )
+        self.config = PolicyConfig(action_horizon=self._cfg.chunk_size)
+
+    def _predict(self) -> PredictFn:
+        """Lazily build the real inference closure on first use."""
+        if self._predict_fn is None:
+            self._predict_fn = _default_predict(self._cfg)
+        return self._predict_fn
+
+    def reset(self, scene: Scene) -> None:
+        """Stash the scene's instruction (fed to the VLA verbatim)."""
+        self._instruction = scene.instruction
+        self.num_inferences = 0
+
+    def act(self, observation: Observation) -> ActionChunk:
+        """Build the raw robot-style observation, run inference, return the chunk.
+
+        The chunk is truncated to the first ``chunk_size`` actions (see
+        ``LeRobotPolicyConfig.chunk_size``).
+        """
+        cfg = self._cfg
+        try:
+            images = {cam: observation.images[cam] for cam in cfg.cameras}
+        except KeyError as exc:
+            raise ValueError(f"observation missing camera {exc} for lerobot policy") from exc
+        if cfg.state_key not in observation.state:
+            raise ValueError(f"observation missing state key {cfg.state_key!r}")
+        state = packing.validate_dim(observation.state[cfg.state_key])
+
+        # The raw robot format lerobot's raw_observation_to_observation expects:
+        # "<motor>.pos" floats, camera frames keyed by camera name, and "task".
+        lerobot_obs: dict[str, Any] = {
+            **packing.to_action_dict(state),
+            TASK_KEY: self._instruction or "",
+            **images,
+        }
+
+        t0 = time.perf_counter()
+        raw = self._predict()(lerobot_obs)
+        elapsed = time.perf_counter() - t0
+
+        actions = np.asarray(raw, dtype=np.float64)
+        if actions.ndim != 2 or actions.shape[1] != packing.TOTAL_DIM:
+            raise ValueError(
+                f"policy returned actions of shape {actions.shape}; "
+                f"expected (N, {packing.TOTAL_DIM})"
+            )
+        if actions.shape[0] == 0:
+            raise ValueError("policy returned an empty action chunk")
+        actions = actions[: cfg.chunk_size]
+
+        self.num_inferences += 1
+        return ActionChunk(
+            actions=[Action(data=row.copy()) for row in actions],
+            control_hz=None,
+            inference_latency_s=elapsed,
+        )

inspect_robots_so101/preflight.py

@@ -0,0 +1,95 @@
+"""Preflight: prove an SO-ARM + LeRobot pairing is compatible *before any motion*.
+
+``inspect-robots-so101-preflight`` constructs the policy and embodiment (no serial
+connection, no model load — only their declared ``.info``), runs Inspect Robots's
+compatibility check, prints the report, and exits non-zero on any error. Pass
+``--task cubepick-reach`` (or any registered task) to also verify every scene is
+realizable.
+
+This is the "is it safe to move?" one-liner: a green preflight means dims, control
+mode, cameras, and state keys all line up. (Absolute-vs-delta joint behavior is
+*not* checkable here — see the README; use ``--dry-run`` plus a single jog to
+confirm on hardware.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Callable
+
+from inspect_robots.compat import CompatibilityReport, check_compatibility
+from inspect_robots.registry import resolve
+from inspect_robots.task import Task
+
+from inspect_robots_so101.config import LeRobotPolicyConfig, SOArmConfig
+from inspect_robots_so101.embodiment import SOArmEmbodiment
+from inspect_robots_so101.policy import LeRobotPolicy
+
+CheckFn = Callable[..., CompatibilityReport]
+
+
+def build(
+    soarm_cfg: SOArmConfig | None = None,
+    policy_cfg: LeRobotPolicyConfig | None = None,
+) -> tuple[LeRobotPolicy, SOArmEmbodiment]:
+    """Construct the (policy, embodiment) pair without connecting to anything."""
+    return LeRobotPolicy(policy_cfg), SOArmEmbodiment(soarm_cfg)
+
+
+def run_preflight(
+    task_name: str | None = None,
+    *,
+    policy: LeRobotPolicy | None = None,
+    embodiment: SOArmEmbodiment | None = None,
+    check: CheckFn = check_compatibility,
+) -> CompatibilityReport:
+    """Return the compatibility report for the SO-ARM + LeRobot pairing."""
+    pol = policy if policy is not None else LeRobotPolicy()
+    emb = embodiment if embodiment is not None else SOArmEmbodiment()
+    task: Task | None = resolve("task", task_name) if task_name else None
+    return check(pol, emb, task)
+
+
+def _format_human(report: CompatibilityReport, *, dry_run: bool) -> str:
+    lines = []
+    if report.ok:
+        lines.append("OK: policy and embodiment are compatible.")
+    else:
+        lines.append("INCOMPATIBLE:")
+    for issue in report.errors:
+        lines.append(f"  ERROR   [{issue.code}] {issue.message}")
+    for issue in report.warnings:
+        lines.append(f"  WARNING [{issue.code}] {issue.message}")
+    if dry_run:
+        lines.append("(dry-run) No motion will be commanded.")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None, *, run: CheckFn | None = None) -> int:
+    """CLI entry point. Returns a process exit code (non-zero on compat errors)."""
+    parser = argparse.ArgumentParser(prog="inspect-robots-so101-preflight")
+    parser.add_argument(
+        "--task", default=None, help="optional task name to check scene realizability"
+    )
+    parser.add_argument("--json", action="store_true", help="emit the report as JSON")
+    parser.add_argument("--dry-run", action="store_true", help="affirm no motion will be commanded")
+    args = parser.parse_args(argv)
+
+    run_fn: Callable[..., CompatibilityReport] = run if run is not None else run_preflight
+    report = run_fn(args.task)
+
+    if args.json:
+        payload = {
+            "ok": report.ok,
+            "errors": [{"code": i.code, "message": i.message} for i in report.errors],
+            "warnings": [{"code": i.code, "message": i.message} for i in report.warnings],
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        print(_format_human(report, dry_run=args.dry_run))
+    return 1 if report.errors else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

inspect_robots_so101-0.3.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: inspect-robots-so101
+Version: 0.3.0
+Summary: Inspect Robots adapters for LeRobot SO-ARM followers (SO-100/SO-101) driven by LeRobot policies.
+Project-URL: Homepage, https://github.com/robocurve/inspect-robots-so101
+Project-URL: Framework, https://github.com/robocurve/inspect-robots
+Project-URL: LeRobot, https://github.com/huggingface/lerobot
+Author: RoboCurve
+License-Expression: MIT
+License-File: LICENSE
+Keywords: inspect-robots,lerobot,robotics,so-arm,so100,so101,vla
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: inspect-robots>=0.3
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: numpy<2.5; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: lerobot
+Requires-Dist: lerobot[feetech]<0.6,>=0.5; (python_version >= '3.12') and extra == 'lerobot'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🦾 inspect-robots-so101
+
+**Run [Inspect Robots](https://github.com/robocurve/inspect-robots) evals on real
+[SO-ARM](https://github.com/TheRobotStudio/SO-ARM100) followers (SO-100 / SO-101)
+driven by [LeRobot](https://github.com/huggingface/lerobot) policies.**
+
+[![CI](https://github.com/robocurve/inspect-robots-so101/actions/workflows/ci.yml/badge.svg)](https://github.com/robocurve/inspect-robots-so101/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/robocurve/inspect-robots-so101/actions/workflows/ci.yml)
+[![Built on Inspect Robots](https://img.shields.io/badge/built%20on-Inspect%20Robots-indigo)](https://github.com/robocurve/inspect-robots)
+
+</div>
+
+Inspect Robots has **two** swappable inputs: a `Policy` (the VLA brain) and an
+`Embodiment` (the robot body + world). This package provides both for the
+SO-ARM + LeRobot stack, so any embodiment-agnostic Inspect Robots task runs on a real
+arm:
+
+- **`lerobot` policy** — wraps a LeRobot checkpoint (ACT, SmolVLA, π0, diffusion…)
+  and runs it **in process** on the GPU, returning an action chunk per inference.
+- **`so_arm` embodiment** — the LeRobot SO follower driver (Feetech bus), with a
+  hard safety clamp, operator-in-the-loop success, and self-paced control.
+
+Both declare the **same 6-D joint-position contract** (`shoulder_pan`,
+`shoulder_lift`, `elbow_flex`, `wrist_flex`, `wrist_roll`, `gripper`; the cameras
+you configure; packed `joint_pos` state), so Inspect Robots's compatibility check passes
+with **zero errors and zero warnings** — verifiable before any motion.
+
+```bash
+inspect-robots run --task cubepick-reach --policy lerobot --embodiment so_arm
+```
+
+> This is the SO-ARM/LeRobot sibling of
+> [inspect-robots-yam](https://github.com/robocurve/inspect-robots-yam) (bimanual I2RT YAM +
+> MolmoAct2). Same Inspect Robots contract, different body and brain.
+
+## Install (on the robot/GPU machine)
+
+```bash
+# Inspect Robots isn't on PyPI yet; uv resolves it from git. The `lerobot` extra pulls
+# torch + lerobot + the Feetech motor bus the SO follower uses.
+uv pip install "inspect-robots-so101[lerobot] @ git+https://github.com/robocurve/inspect-robots-so101"
+```
+
+- `lerobot` → `lerobot[feetech]` (torch, the policy, and the SO-ARM driver).
+- **The `lerobot` extra needs Python ≥ 3.12** (lerobot ≥ 0.5's floor). On
+  3.10/3.11 the extra silently resolves to *nothing*: the core package still
+  imports, but no torch/lerobot is installed and hardware runs will fail.
+
+Then pick a checkpoint. Any LeRobot policy trained on your SO-ARM works — e.g. the
+public `lerobot/smolvla_base`, or your own ACT/π0 checkpoint on the Hub or a path.
+
+## Preflight — *prove compatibility before any motion*
+
+```bash
+inspect-robots-so101-preflight                          # dims/semantics/cameras/state
+inspect-robots-so101-preflight --task cubepick-reach    # + scene realizability
+inspect-robots-so101-preflight --dry-run                # affirm no motion
+```
+
+A green preflight means action dim (6), control mode (`joint_pos`), cameras, and
+state keys all line up. **It does not prove the joint values are interpreted the
+same way** — see *Safety* below.
+
+## Calibrate first (once, with lerobot)
+
+The embodiment **never** runs lerobot's interactive calibration — connecting with
+an uncalibrated arm would otherwise drop into a *blocking* prompt that moves the
+arm mid-eval. Calibrate once with lerobot's own tool, then tell the config which
+identity you used:
+
+```bash
+lerobot-calibrate --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower
+```
+
+`SOArmConfig(robot_id="my_follower")` selects that calibration file
+(`<calibration_dir>/<robot_id>.json`; leave `calibration_dir=None` for lerobot's
+default location). If the arm isn't calibrated — or the file no longer matches
+the motors — `reset()` fails fast with an actionable error instead of prompting.
+
+## Run on hardware
+
+You must point the embodiment at your serial port, calibration id, and camera
+config, and the policy at a checkpoint:
+
+```python
+from inspect_robots import eval
+from inspect_robots.approver import ClampApprover
+from inspect_robots_so101 import LeRobotPolicy, SOArmEmbodiment, SOArmConfig, LeRobotPolicyConfig
+from lerobot.cameras.opencv import OpenCVCameraConfig  # your camera backend
+
+emb = SOArmEmbodiment(SOArmConfig(
+    port="/dev/ttyACM0",
+    robot_type="so101_follower",
+    robot_id="my_follower",    # the id you ran `lerobot-calibrate` with
+    max_relative_target=10.0,  # lerobot's slew limit (deg/step); required for home_pose
+    cameras=("front",),
+    camera_configs={"front": OpenCVCameraConfig(index_or_path=0, width=640, height=480, fps=30)},
+))
+pol = LeRobotPolicy(LeRobotPolicyConfig(
+    pretrained_path="lerobot/smolvla_base", policy_type="smolvla", device="cuda",
+))
+
+with emb:  # guarantees disconnect (and torque-off) even if the eval raises
+    (log,) = eval("cubepick-reach", pol, emb,
+                  approver=ClampApprover(emb.info.action_space))  # defense in depth
+print(log.status, log.results.metrics)
+```
+
+(Equivalently, wrap the `eval(...)` in `try: ... finally: emb.close()`.)
+
+At each episode end the embodiment asks the operator (y/N); a `yes` records
+`termination_reason="success"`, which the task's `success_at_end` scorer reads.
+Unattended runs simply run to `max_steps` and score as failures.
+
+## Safety
+
+- **Hard clamp backstop.** Every command is clipped to `SOArmConfig.joint_low/high`
+  *inside* `step()`, independent of any Inspect Robots `Approver` and on top of LeRobot's
+  own `max_relative_target` slew limit — unclamped model outputs can never reach
+  the motors. **Set these to your real, calibrated SO-ARM joint limits** (the
+  defaults are conservative placeholders: joints ±180°, gripper 0–100).
+- **Use `ClampApprover`** on hardware for a second layer.
+- **Native units, no renormalization.** LeRobot's postprocessor unnormalizes the
+  policy output to the robot's native motor units (degrees for joints, 0–100 for
+  the gripper), so the embodiment commands them verbatim after the clamp. Train
+  and run the policy in the *same* units. `use_degrees=False` (lerobot's
+  normalized ±100 mode) is **rejected** — the state spec and default limits here
+  assume degrees. Also note the units are *degrees* while Inspect Robots's canonical
+  `joint_pos` convention is radians: the compat check compares state **keys**
+  only, so pairing either component with a third-party counterpart will *not*
+  flag a unit mismatch — verify units yourself when mixing stacks.
+- **Homing is slew-limited or refused.** `home_pose` sends a single absolute
+  command, so the config requires `max_relative_target` (LeRobot's per-step slew
+  limit) whenever `home_pose` is set — otherwise the arm would slam to home at
+  full speed from wherever it happens to be.
+- **Absolute vs. delta joints — verify first.** Actions are treated as **absolute**
+  joint targets by default. If your checkpoint emits deltas, set
+  `SOArmConfig(joints_are_delta=True)` (the embodiment converts to absolute
+  internally so the declared `joint_pos` stays honest). The compat check *cannot*
+  tell these apart — confirm with `--dry-run` and a single slow jog before a task.
+
+## Configuration
+
+`SOArmConfig`: `port`, `robot_type`, `robot_id`, `calibration_dir`, `cameras`,
+`camera_configs`, `control_hz`, `cam_height/width`, `joint_low/high`,
+`home_pose` (requires `max_relative_target`), `joints_are_delta`, `use_degrees`
+(must stay `True`), `max_relative_target`, `disable_torque_on_disconnect`.
+`robot_type` is validated (`so101_follower` / `so100_follower`) but is a label:
+at lerobot v0.5.x both names alias the same driver class, so it changes no
+runtime behavior.
+`LeRobotPolicyConfig`: `pretrained_path`, `policy_type`, `device`, `cameras`,
+`state_key`, `chunk_size`, `cam_height/width`.
+
+Scalar knobs are settable from the CLI:
+`inspect-robots run -P pretrained_path=lerobot/smolvla_base -E port=/dev/ttyACM0 ...`.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"     # inspect-robots from a git tag
+uv run pre-commit install
+uv run pytest --cov                        # 100% coverage required
+uv run ruff check . && uv run mypy
+```
+
+The whole suite runs with **no hardware, no GPU, no torch, no lerobot, and no
+stdin** — the SO-ARM driver, the policy inference, the clock, and operator I/O are
+all injected. The real model seam (`_default_predict`) is covered via
+`sys.modules` fakes, and a dedicated `lerobot-seam` CI job (py3.12) imports the
+real lerobot symbols it uses; only direct hardware/TTY I/O keeps
+`# pragma: no cover`.
+
+## License
+
+[MIT](LICENSE)

inspect_robots_so101-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+inspect_robots_so101/CLAUDE.md,sha256=HYIsb-FdBSSp7mvyjPhBc7fUs7H-rsMxIzO2dv268lM,3490
+inspect_robots_so101/__init__.py,sha256=FN4mkP5UDb_DWeyjhW-r-26v8-ZFgtoo5_OSnUeH--I,1316
+inspect_robots_so101/config.py,sha256=lZbPnXDtJ8Z2wohTk25xgALwygajVsFtijVXp17ynCc,8029
+inspect_robots_so101/embodiment.py,sha256=tvUSivIfqRAm4I5VXKjiOkqLrCmQEOkDaMmkL2xccg4,9821
+inspect_robots_so101/operator.py,sha256=yUix11a3-VFZTg3vOsYxoM-nxsnk0S_yfufPzVQbRuI,1890
+inspect_robots_so101/packing.py,sha256=acL7bd_8LNZSW79YOblxNRo9rTqflD39u3F5q6aKlcY,3358
+inspect_robots_so101/policy.py,sha256=C1JqHZVwCV76MvQe8z8EN_NRyDlnBbDPUYlLYWgKt9Y,10085
+inspect_robots_so101/preflight.py,sha256=iWu5XPL8eJ32_huWcnqVf476m8274Ft65aueuXvywLo,3730
+inspect_robots_so101/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+inspect_robots_so101-0.3.0.dist-info/METADATA,sha256=daDDnCgAvcitlQx73RStWlgNrUyqUOlZsWt-xGF3YFA,10097
+inspect_robots_so101-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+inspect_robots_so101-0.3.0.dist-info/entry_points.txt,sha256=t7Zi78FShR_reiRZ1Nwu4c5mlAu67o8iyrk2nwTBx2g,253
+inspect_robots_so101-0.3.0.dist-info/licenses/LICENSE,sha256=Dv_L__TNAedADjrqdg67n216Joum0pHNDiY5XgiWREQ,1066
+inspect_robots_so101-0.3.0.dist-info/RECORD,,

inspect_robots_so101-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

inspect_robots_so101-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+inspect-robots-so101-preflight = inspect_robots_so101.preflight:main
+
+[inspect_robots.embodiments]
+so_arm = inspect_robots_so101.embodiment:SOArmEmbodiment
+
+[inspect_robots.policies]
+lerobot = inspect_robots_so101.policy:LeRobotPolicy

inspect_robots_so101-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoboCurve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.