inspect-robots-isaacsim 0.1.0__tar.gz

inspect_robots_isaacsim-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

inspect_robots_isaacsim-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: inspect-robots-isaacsim
+Version: 0.1.0
+Summary: IsaacSim / Isaac Lab embodiment adapter for Inspect Robots — run Inspect Robots evals against an Isaac Lab simulation.
+Project-URL: Homepage, https://github.com/robocurve/inspect-robots/tree/main/plugins/inspect-robots-isaacsim
+Project-URL: Repository, https://github.com/robocurve/inspect-robots
+Author: Inspect Robots contributors
+License-Expression: MIT
+Keywords: evaluation,inspect_robots,isaac-lab,isaac-sim,robotics,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.2
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# inspect-robots-isaacsim
+
+An [Isaac Lab](https://isaac-sim.github.io/IsaacLab/) (Isaac Sim) **embodiment**
+plugin for [Inspect Robots](https://github.com/robocurve/inspect-robots) — the "Inspect AI
+for robotics".
+
+Inspect Robots factors a robotics eval into two swappable inputs: a `Policy` (the VLA
+"brain") and an `Embodiment` (the "body + world"). This package supplies the
+second one, backed by a real Isaac Lab physics simulation, so you can run any
+compatible VLA against your Isaac Sim setup.
+
+The default profile is a **7-DoF Franka Panda under joint-position control** with
+a binary gripper (action dimension `= num_arm_joints + 1 = 8`).
+
+## Install
+
+This package installs and registers on any machine, but `reset()`/`step()` need
+a working **Isaac Lab** environment (NVIDIA Omniverse + GPU) — Isaac Sim is not a
+PyPI dependency and is imported lazily.
+
+```bash
+# inside the conda/venv that already has isaaclab + isaacsim available
+pip install inspect-robots inspect-robots-isaacsim
+```
+
+## Use it
+
+The embodiment is discovered through the `inspect_robots.embodiments` entry point, so
+it appears in the CLI without any import:
+
+```bash
+inspect-robots list embodiments          # -> includes "isaacsim"
+
+inspect-robots run \
+  --task my-benchmark \
+  --policy my-vla \
+  --embodiment isaacsim \
+  -E task_id=Isaac-Lift-Cube-Franka-v0 \
+  -E headless=true
+```
+
+Or programmatically:
+
+```python
+from inspect_robots import eval
+
+logs = eval("my-benchmark", "my-vla", "isaacsim")
+print(logs[0].results.metrics)
+```
+
+Constructing directly (e.g. for a non-Franka arm or extra cameras):
+
+```python
+from inspect_robots_isaacsim import IsaacSimEmbodiment
+
+emb = IsaacSimEmbodiment(
+    task_id="Isaac-Open-Drawer-Franka-v0",
+    num_arm_joints=7,
+    cameras=[("base_rgb", 224, 224), ("wrist_rgb", 224, 224)],
+    control_hz=30.0,
+    headless=True,
+)
+```
+
+## Compatibility
+
+Inspect Robots fail-fast-checks the `(policy, embodiment)` pair before any rollout. To
+run against this embodiment your policy must emit **8-D `joint_pos` actions**
+(`control_mode="joint_pos"`, `gripper="binary"`) and require only observation
+keys this task provides. The mock `cubepick` policies (2-D `eef_delta_pos`) are
+intentionally **incompatible** — bring a Franka-trained VLA.
+
+### Mapping your task
+
+Isaac Lab tasks vary in their observation-dict layout and success signal. The
+constructor exposes hooks so you don't edit the adapter:
+
+| Argument | Purpose |
+|---|---|
+| `obs_group` | top-level obs-dict group to read (default `"policy"`) |
+| `image_keys` / `state_keys` | map Inspect Robots keys → your task's raw dict keys |
+| `success_info_key` | where the task reports success in `info` (default `"success"`) |
+| `num_arm_joints` | arm DoF; action dim is this `+ 1` for the gripper |
+
+## Memory & GPU hygiene
+
+Long unattended evals should not creep in RAM or VRAM. This adapter is built to
+hold nothing per step, but a few usage rules keep a full run leak-free:
+
+- **Free the simulator when done.** `eval()` closes what it resolves: an
+  embodiment looked up by **registry name** (e.g. `embodiment="isaacsim"`) is
+  closed when the run finishes. An embodiment object *you* construct is yours
+  to close — an open `SimulationApp` holds GPU memory until the process exits,
+  so use it as a context manager (or `close()` in a `finally`):
+
+  ```python
+  with IsaacSimEmbodiment() as emb:
+      eval("my-bench", "my-vla", emb)
+  # GPU + sim torn down here
+  ```
+
+  `close()` is idempotent and safe to call before launch or twice.
+
+- **One simulator per process.** Isaac Sim is a hard process singleton; if you
+  construct several embodiments the adapter reuses the one live `SimulationApp`
+  rather than launching (and leaking) a second.
+
+- **Stream frames to disk for long episodes.** Inspect Robots keeps each step's
+  observation — including camera frames — in the per-trial record. Pass
+  `store_frames=True` to `eval()` so frames go to disk side-cars instead of RAM.
+  (Per-trial records are released after each scene is scored, so there is no
+  cross-trial accumulation regardless.)
+
+- **Skip rendering you don't need.** If your scorer is state/oracle based, build
+  the embodiment with `cameras=()` to avoid allocating images at all.
+
+The adapter never stores tensors on `self`, and copies observations off Isaac's
+reused buffers (`.astype`), so a step loop holds no growing references — a
+`tracemalloc` regression test asserts flat RAM over thousands of steps.
+
+## Develop / test
+
+The test suite runs **without Isaac** (it checks spaces, semantics, protocol
+conformance, compatibility, and registry wiring):
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT.

inspect_robots_isaacsim-0.1.0/README.md

@@ -0,0 +1,133 @@
+# inspect-robots-isaacsim
+
+An [Isaac Lab](https://isaac-sim.github.io/IsaacLab/) (Isaac Sim) **embodiment**
+plugin for [Inspect Robots](https://github.com/robocurve/inspect-robots) — the "Inspect AI
+for robotics".
+
+Inspect Robots factors a robotics eval into two swappable inputs: a `Policy` (the VLA
+"brain") and an `Embodiment` (the "body + world"). This package supplies the
+second one, backed by a real Isaac Lab physics simulation, so you can run any
+compatible VLA against your Isaac Sim setup.
+
+The default profile is a **7-DoF Franka Panda under joint-position control** with
+a binary gripper (action dimension `= num_arm_joints + 1 = 8`).
+
+## Install
+
+This package installs and registers on any machine, but `reset()`/`step()` need
+a working **Isaac Lab** environment (NVIDIA Omniverse + GPU) — Isaac Sim is not a
+PyPI dependency and is imported lazily.
+
+```bash
+# inside the conda/venv that already has isaaclab + isaacsim available
+pip install inspect-robots inspect-robots-isaacsim
+```
+
+## Use it
+
+The embodiment is discovered through the `inspect_robots.embodiments` entry point, so
+it appears in the CLI without any import:
+
+```bash
+inspect-robots list embodiments          # -> includes "isaacsim"
+
+inspect-robots run \
+  --task my-benchmark \
+  --policy my-vla \
+  --embodiment isaacsim \
+  -E task_id=Isaac-Lift-Cube-Franka-v0 \
+  -E headless=true
+```
+
+Or programmatically:
+
+```python
+from inspect_robots import eval
+
+logs = eval("my-benchmark", "my-vla", "isaacsim")
+print(logs[0].results.metrics)
+```
+
+Constructing directly (e.g. for a non-Franka arm or extra cameras):
+
+```python
+from inspect_robots_isaacsim import IsaacSimEmbodiment
+
+emb = IsaacSimEmbodiment(
+    task_id="Isaac-Open-Drawer-Franka-v0",
+    num_arm_joints=7,
+    cameras=[("base_rgb", 224, 224), ("wrist_rgb", 224, 224)],
+    control_hz=30.0,
+    headless=True,
+)
+```
+
+## Compatibility
+
+Inspect Robots fail-fast-checks the `(policy, embodiment)` pair before any rollout. To
+run against this embodiment your policy must emit **8-D `joint_pos` actions**
+(`control_mode="joint_pos"`, `gripper="binary"`) and require only observation
+keys this task provides. The mock `cubepick` policies (2-D `eef_delta_pos`) are
+intentionally **incompatible** — bring a Franka-trained VLA.
+
+### Mapping your task
+
+Isaac Lab tasks vary in their observation-dict layout and success signal. The
+constructor exposes hooks so you don't edit the adapter:
+
+| Argument | Purpose |
+|---|---|
+| `obs_group` | top-level obs-dict group to read (default `"policy"`) |
+| `image_keys` / `state_keys` | map Inspect Robots keys → your task's raw dict keys |
+| `success_info_key` | where the task reports success in `info` (default `"success"`) |
+| `num_arm_joints` | arm DoF; action dim is this `+ 1` for the gripper |
+
+## Memory & GPU hygiene
+
+Long unattended evals should not creep in RAM or VRAM. This adapter is built to
+hold nothing per step, but a few usage rules keep a full run leak-free:
+
+- **Free the simulator when done.** `eval()` closes what it resolves: an
+  embodiment looked up by **registry name** (e.g. `embodiment="isaacsim"`) is
+  closed when the run finishes. An embodiment object *you* construct is yours
+  to close — an open `SimulationApp` holds GPU memory until the process exits,
+  so use it as a context manager (or `close()` in a `finally`):
+
+  ```python
+  with IsaacSimEmbodiment() as emb:
+      eval("my-bench", "my-vla", emb)
+  # GPU + sim torn down here
+  ```
+
+  `close()` is idempotent and safe to call before launch or twice.
+
+- **One simulator per process.** Isaac Sim is a hard process singleton; if you
+  construct several embodiments the adapter reuses the one live `SimulationApp`
+  rather than launching (and leaking) a second.
+
+- **Stream frames to disk for long episodes.** Inspect Robots keeps each step's
+  observation — including camera frames — in the per-trial record. Pass
+  `store_frames=True` to `eval()` so frames go to disk side-cars instead of RAM.
+  (Per-trial records are released after each scene is scored, so there is no
+  cross-trial accumulation regardless.)
+
+- **Skip rendering you don't need.** If your scorer is state/oracle based, build
+  the embodiment with `cameras=()` to avoid allocating images at all.
+
+The adapter never stores tensors on `self`, and copies observations off Isaac's
+reused buffers (`.astype`), so a step loop holds no growing references — a
+`tracemalloc` regression test asserts flat RAM over thousands of steps.
+
+## Develop / test
+
+The test suite runs **without Isaac** (it checks spaces, semantics, protocol
+conformance, compatibility, and registry wiring):
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT.

inspect_robots_isaacsim-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "inspect-robots-isaacsim"
+version = "0.1.0"
+description = "IsaacSim / Isaac Lab embodiment adapter for Inspect Robots — run Inspect Robots evals against an Isaac Lab simulation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Inspect Robots contributors" }]
+keywords = ["robotics", "isaac-sim", "isaac-lab", "inspect_robots", "vla", "evaluation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# NOTE: `isaacsim` / `isaaclab` are intentionally NOT declared here. Isaac Sim and
+# Isaac Lab are not installable from PyPI as ordinary wheels — they are provided by
+# the user's NVIDIA Omniverse / Isaac Lab environment (and need a GPU). This adapter
+# imports them lazily so the package installs, registers, and is discoverable
+# (`inspect-robots list embodiments`) on any machine; only `reset()`/`step()` require Isaac.
+dependencies = ["inspect-robots>=0.2", "numpy>=1.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "mypy>=1.11", "ruff>=0.6"]
+
+# Entry-point discovery: an installed inspect-robots-isaacsim appears in `inspect-robots list`
+# without being imported first. The registry calls this factory by the name `isaacsim`.
+[project.entry-points."inspect_robots.embodiments"]
+isaacsim = "inspect_robots_isaacsim:isaacsim_embodiment"
+
+[project.urls]
+Homepage = "https://github.com/robocurve/inspect-robots/tree/main/plugins/inspect-robots-isaacsim"
+Repository = "https://github.com/robocurve/inspect-robots"
+
+# In the Inspect Robots monorepo this resolves the `inspect_robots` dependency to the in-repo
+# core package instead of PyPI. Harmless in a standalone checkout (uv ignores a
+# workspace source when there is no workspace root).
+[tool.uv.sources]
+inspect-robots = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inspect_robots_isaacsim"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/inspect_robots_isaacsim", "tests", "README.md"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true
+
+# Isaac Sim / Isaac Lab / torch are not installed in lint/test environments and
+# ship no stubs; they are imported lazily inside methods. Don't fail strict on them.
+[[tool.mypy.overrides]]
+module = ["isaaclab.*", "isaaclab_tasks.*", "gymnasium.*", "torch.*"]
+ignore_missing_imports = true

inspect_robots_isaacsim-0.1.0/src/inspect_robots_isaacsim/__init__.py

@@ -0,0 +1,36 @@
+"""inspect-robots-isaacsim — an Isaac Lab (Isaac Sim) embodiment for Inspect Robots.
+
+Install this alongside a working Isaac Lab environment and the ``isaacsim``
+embodiment becomes available to Inspect Robots::
+
+    inspect-robots list embodiments        # -> includes "isaacsim"
+    inspect-robots run --task my-task --policy my-vla --embodiment isaacsim \
+        -E task_id=Isaac-Lift-Cube-Franka-v0
+
+or programmatically::
+
+    from inspect_robots import eval
+    eval("my-task", "my-vla", "isaacsim")
+
+The embodiment is discovered via the ``inspect_robots.embodiments`` entry point, so it
+shows up without being imported first.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from inspect_robots_isaacsim.embodiment import IsaacSimEmbodiment
+
+__all__ = ["IsaacSimEmbodiment", "isaacsim_embodiment"]
+
+__version__ = "0.1.0"
+
+
+def isaacsim_embodiment(**kwargs: Any) -> IsaacSimEmbodiment:
+    """Factory the Inspect Robots registry calls (entry point ``isaacsim``).
+
+    Accepts the same keyword arguments as :class:`IsaacSimEmbodiment`; the CLI
+    forwards ``-E key=value`` pairs here.
+    """
+    return IsaacSimEmbodiment(**kwargs)

inspect_robots_isaacsim-0.1.0/src/inspect_robots_isaacsim/embodiment.py

@@ -0,0 +1,327 @@
+"""An ``Embodiment`` adapter that wraps an Isaac Lab (Isaac Sim) environment.
+
+This is the "body + world" half of a Inspect Robots eval, backed by a real physics
+simulation. It conforms to :class:`inspect_robots.Embodiment` (the runtime-checkable
+protocol), so once installed it can be paired with any compatible
+:class:`inspect_robots.Policy` and run through ``inspect_robots.eval``.
+
+Design mirrors Inspect Robots's own ``RerunSink``: the heavy, GPU-bound, non-PyPI
+dependencies (``isaacsim`` / ``isaaclab`` / ``torch``) are imported **lazily,
+inside methods**. Constructing the adapter and reading ``.info`` therefore work
+on any machine (so ``inspect-robots list embodiments`` and the fail-fast compatibility
+check run without Isaac); only :meth:`reset` / :meth:`step` actually launch the
+simulator.
+
+Default profile: a 7-DoF **Franka Panda** under **joint-position** control with a
+binary gripper (action dim ``= num_arm_joints + 1``). Everything is configurable
+so any Isaac Lab manipulation task can be wrapped.
+
+Version note: Isaac Lab's gym wrapper returns a dict observation grouped by
+``"policy"`` and batched over ``num_envs``. The obs/action *group keys* and the
+``success`` signal differ across tasks; the constructor exposes ``obs_group``,
+``image_keys``, ``state_keys`` and ``success_info_key`` so you can map your task
+without editing this file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from inspect_robots import (
+    ActionSemantics,
+    Box,
+    CameraSpec,
+    EmbodimentInfo,
+    ObservationSpace,
+    Observation,
+    Scene,
+    StateField,
+    StateSpec,
+    StepResult,
+)
+from inspect_robots.spaces import CANONICAL_STATE_UNITS
+
+if TYPE_CHECKING:
+    from inspect_robots import Action
+
+# Isaac Lab simulators expose a privileged success oracle, are resettable and
+# seedable, and can render — but they are NOT self-paced (they step as fast as the
+# GPU allows; Inspect Robots owns wall-clock pacing).
+_DEFAULT_CAPABILITIES = frozenset({"seedable", "resettable", "privileged_success", "renderable"})
+
+# Isaac Sim allows exactly ONE SimulationApp per process. Track it module-side so a
+# second embodiment instance reuses the live app instead of launching a duplicate
+# (which crashes) or leaking one. Cleared by close().
+_ACTIVE_APP: Any | None = None
+
+
+def _missing_isaac(exc: ImportError) -> RuntimeError:
+    return RuntimeError(
+        "Isaac Sim / Isaac Lab is not importable in this environment "
+        f"({exc}). The inspect-robots-isaacsim adapter needs a working Isaac Lab "
+        "install (NVIDIA Omniverse + GPU). Constructing the embodiment and "
+        "reading .info work without it, but reset()/step() require it. "
+        "See: https://isaac-sim.github.io/IsaacLab/"
+    )
+
+
+def _default_state_fields(num_arm_joints: int) -> tuple[StateField, ...]:
+    """Canonical proprioception for a Franka-like arm (keys/units from Inspect Robots)."""
+
+    def unit(key: str) -> str:
+        return CANONICAL_STATE_UNITS.get(key, "")
+
+    return (
+        StateField("joint_pos", (num_arm_joints,), unit("joint_pos")),
+        StateField("joint_vel", (num_arm_joints,), unit("joint_vel")),
+        StateField("eef_pos", (3,), unit("eef_pos")),
+        StateField("eef_quat", (4,), unit("eef_quat")),
+        StateField("gripper", (1,), unit("gripper")),
+    )
+
+
+class IsaacSimEmbodiment:
+    """Wrap an Isaac Lab gym task as a Inspect Robots :class:`~inspect_robots.Embodiment`.
+
+    Parameters
+    ----------
+    task_id:
+        The Isaac Lab / gymnasium task id, e.g. ``"Isaac-Lift-Cube-Franka-v0"``.
+    num_arm_joints:
+        Number of actuated arm joints (Franka Panda = 7). The action is
+        ``num_arm_joints`` joint targets plus one binary gripper command, so the
+        action dimension is ``num_arm_joints + 1``.
+    cameras:
+        Camera streams the task renders, as ``(name, height, width[, channels])``
+        tuples. Match the names your policy requires (Inspect Robots remaps if needed).
+    headless / device:
+        Forwarded to Isaac's ``AppLauncher`` / env. ``headless=True`` is required
+        on machines without a display (the usual eval box).
+    obs_group / image_keys / state_keys / success_info_key:
+        How to read the task's observation dict and success flag (see module docs).
+    name / supported_setups / supported_target_kinds:
+        Surfaced on ``EmbodimentInfo`` for logging and R7 scene-realizability
+        checks. Empty ``supported_*`` means "unconstrained".
+    """
+
+    def __init__(
+        self,
+        task_id: str = "Isaac-Lift-Cube-Franka-v0",
+        *,
+        num_arm_joints: int = 7,
+        cameras: Sequence[tuple[str, int, int] | tuple[str, int, int, int]] = (
+            ("base_rgb", 224, 224, 3),
+        ),
+        control_hz: float = 30.0,
+        headless: bool = True,
+        device: str = "cuda:0",
+        obs_group: str = "policy",
+        image_keys: Mapping[str, str] | None = None,
+        state_keys: Mapping[str, str] | None = None,
+        success_info_key: str = "success",
+        name: str = "isaacsim",
+        supported_setups: Sequence[str] = (),
+        supported_target_kinds: Sequence[str] = (),
+    ) -> None:
+        if num_arm_joints < 1:
+            raise ValueError("num_arm_joints must be >= 1")
+
+        self.task_id = task_id
+        self.num_arm_joints = num_arm_joints
+        self.headless = headless
+        self.device = device
+        self.obs_group = obs_group
+        # Map Inspect Robots obs keys -> the task's raw dict keys. Identity by default.
+        self.image_keys = dict(image_keys or {})
+        self.state_keys = dict(state_keys or {})
+        self.success_info_key = success_info_key
+
+        camera_specs = tuple(CameraSpec(c[0], c[1], c[2], *(c[3:] or (3,))) for c in cameras)
+        action_dim = num_arm_joints + 1  # arm joint targets + 1 binary gripper
+
+        self.info = EmbodimentInfo(
+            name=name,
+            action_space=Box(
+                shape=(action_dim,),
+                semantics=ActionSemantics(
+                    control_mode="joint_pos",
+                    rotation_repr="none",
+                    gripper="binary",
+                    frame="base",
+                ),
+            ),
+            observation_space=ObservationSpace(
+                cameras=camera_specs,
+                state=StateSpec(fields=_default_state_fields(num_arm_joints)),
+            ),
+            control_hz=control_hz,
+            is_simulated=True,
+            capabilities=_DEFAULT_CAPABILITIES,
+            supported_setups=frozenset(supported_setups),
+            supported_target_kinds=frozenset(supported_target_kinds),
+        )
+
+        # Lazily-initialised Isaac handles (None until first reset()).
+        self._app: Any | None = None
+        self._env: Any | None = None
+        self._torch: Any | None = None
+
+    # ------------------------------------------------------------------ #
+    # Lazy Isaac bring-up (app launch and env creation are separable so the
+    # simulator boot can be validated independently of any task registry)
+    # ------------------------------------------------------------------ #
+    def _ensure_app(self) -> Any:
+        """Launch the Isaac Sim ``SimulationApp`` on first use and return it.
+
+        If another instance already launched the app this process, reuse it —
+        Isaac Sim is a hard process singleton, so launching twice would crash.
+        """
+        global _ACTIVE_APP
+        if self._app is not None:
+            return self._app
+        try:
+            import torch
+        except ImportError as exc:  # pragma: no cover - exercised only without Isaac
+            raise _missing_isaac(exc) from exc
+        self._torch = torch
+
+        if _ACTIVE_APP is not None:
+            self._app = _ACTIVE_APP
+            return self._app
+
+        try:
+            from isaaclab.app import AppLauncher
+        except ImportError as exc:  # pragma: no cover - exercised only without Isaac
+            raise _missing_isaac(exc) from exc
+        self._app = AppLauncher(headless=self.headless, device=self.device).app
+        _ACTIVE_APP = self._app
+        return self._app
+
+    def _ensure_env(self) -> Any:
+        """Build the gym env on first use (boots the app if needed)."""
+        if self._env is not None:
+            return self._env
+        self._ensure_app()
+        # Importing the tasks registers the gym ids; must happen AFTER the app boots.
+        import gymnasium as gym
+        import isaaclab_tasks  # noqa: F401  (registers Isaac-* gym ids)
+
+        self._env = gym.make(self.task_id, num_envs=1, render_mode="rgb_array")
+        return self._env
+
+    # ------------------------------------------------------------------ #
+    # Embodiment protocol
+    # ------------------------------------------------------------------ #
+    def reset(self, scene: Scene, *, seed: int | None = None) -> Observation:
+        env = self._ensure_env()
+        obs, _info = env.reset(seed=seed)
+        return self._to_observation(obs, scene.instruction)
+
+    def step(self, action: Action) -> StepResult:
+        env = self._ensure_env()
+        torch = self._torch
+        assert torch is not None  # set alongside _env
+        tensor = torch.as_tensor(
+            np.asarray(action.data, dtype=np.float32), device=self.device
+        ).reshape(1, -1)
+        obs, reward, terminated, truncated, info = env.step(tensor)
+
+        success = self._read_success(info, terminated)
+        term = bool(_scalar(terminated))
+        return StepResult(
+            observation=self._to_observation(obs, None),
+            reward=float(_scalar(reward)),
+            terminated=term,
+            termination_reason="success" if (term and success) else None,
+            truncated=bool(_scalar(truncated)),
+            info={"success": success},
+        )
+
+    def close(self) -> None:
+        """Release the gym env and Isaac Sim app (and the GPU memory they hold).
+
+        Idempotent: safe to call before launch or twice. ``eval()`` closes what
+        it resolves — an embodiment looked up by registry name is closed when
+        the run finishes, but an embodiment object you construct is yours to
+        close. Use it as a context manager (or call ``close()`` in a
+        ``finally``) to guarantee the simulator is torn down and GPU memory is
+        freed when a run ends.
+        """
+        global _ACTIVE_APP
+        if self._env is not None:
+            self._env.close()
+            self._env = None
+        if self._app is not None:
+            self._app.close()
+            if _ACTIVE_APP is self._app:
+                _ACTIVE_APP = None
+            self._app = None
+        self._torch = None
+
+    def __enter__(self) -> IsaacSimEmbodiment:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------ #
+    # Translation: Isaac Lab dict/tensors <-> Inspect Robots types
+    # ------------------------------------------------------------------ #
+    def _to_observation(self, raw: Any, instruction: str | None) -> Observation:
+        group = raw[self.obs_group] if isinstance(raw, Mapping) and self.obs_group in raw else raw
+        images: dict[str, np.ndarray] = {}
+        state: dict[str, np.ndarray] = {}
+
+        for cam in self.info.observation_space.cameras:
+            key = self.image_keys.get(cam.name, cam.name)
+            if isinstance(group, Mapping) and key in group:
+                images[cam.name] = _to_image(group[key])
+
+        if self.info.observation_space.state is not None:
+            for field in self.info.observation_space.state.fields:
+                key = self.state_keys.get(field.key, field.key)
+                if isinstance(group, Mapping) and key in group:
+                    state[field.key] = _to_float_array(group[key])
+
+        return Observation(images=images, state=state, instruction=instruction)
+
+    def _read_success(self, info: Any, terminated: Any) -> bool:
+        if isinstance(info, Mapping) and self.success_info_key in info:
+            return bool(_scalar(info[self.success_info_key]))
+        # Fall back to "terminated implies success" when the task exposes no oracle.
+        return bool(_scalar(terminated))
+
+
+# --------------------------------------------------------------------------- #
+# Tensor/array helpers (kept torch-free at import time; operate duck-typed)
+# --------------------------------------------------------------------------- #
+def _np(value: Any) -> np.ndarray:
+    """Best-effort conversion of a (possibly GPU torch) value to a NumPy array."""
+    if hasattr(value, "detach"):  # torch.Tensor
+        value = value.detach().cpu().numpy()
+    return np.asarray(value)
+
+
+def _scalar(value: Any) -> float:
+    arr = _np(value).reshape(-1)
+    return float(arr[0]) if arr.size else 0.0
+
+
+def _to_float_array(value: Any) -> np.ndarray:
+    arr = _np(value).astype(np.float64)
+    # Drop the leading num_envs axis (we run num_envs=1).
+    return arr[0] if arr.ndim >= 1 and arr.shape[0] == 1 else arr
+
+
+def _to_image(value: Any) -> np.ndarray:
+    arr = _np(value)
+    if arr.ndim >= 1 and arr.shape[0] == 1:  # drop num_envs axis
+        arr = arr[0]
+    if arr.ndim == 3 and arr.shape[0] in (1, 3, 4) and arr.shape[-1] not in (1, 3, 4):
+        arr = np.transpose(arr, (1, 2, 0))  # CHW -> HWC
+    if np.issubdtype(arr.dtype, np.floating):
+        arr = np.clip(arr * 255.0 if arr.max() <= 1.0 else arr, 0, 255)
+    return arr.astype(np.uint8)

inspect_robots_isaacsim-0.1.0/tests/test_isaacsim_embodiment.py

@@ -0,0 +1,246 @@
+"""Tests for the Isaac Lab embodiment adapter.
+
+These run on any machine — Isaac Sim is NOT required. They verify the parts that
+matter before a simulator ever boots: the declared spaces/semantics, protocol
+conformance, registry resolution, Inspect Robots compatibility checking, and that
+calling reset() without Isaac fails with a clear, actionable error.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pytest
+
+from inspect_robots import (
+    ActionSemantics,
+    Box,
+    Embodiment,
+    ObservationSpace,
+    PolicyConfig,
+    PolicyInfo,
+    Scene,
+)
+from inspect_robots.compat import check_compatibility
+from inspect_robots.errors import CompatibilityError
+from inspect_robots.types import ActionChunk, Observation
+
+from inspect_robots_isaacsim import IsaacSimEmbodiment, isaacsim_embodiment
+
+_FRANKA_SEM = ActionSemantics(
+    control_mode="joint_pos", rotation_repr="none", gripper="binary", frame="base"
+)
+
+
+class _FrankaPolicy:
+    """A minimal policy whose spaces match the default Franka profile (dim 8)."""
+
+    def __init__(self) -> None:
+        self.info = PolicyInfo(
+            name="franka-stub",
+            action_space=Box(shape=(8,), semantics=_FRANKA_SEM),
+            observation_space=ObservationSpace(state_keys=frozenset({"joint_pos"})),
+        )
+        self.config = PolicyConfig(action_horizon=1)
+
+    def reset(self, scene: Scene) -> None: ...
+
+    def act(self, observation: Observation) -> ActionChunk:  # pragma: no cover - unused
+        from inspect_robots import Action
+
+        return ActionChunk(actions=[Action(data=np.zeros(8))])
+
+
+def test_info_describes_franka_joint_pos() -> None:
+    emb = IsaacSimEmbodiment()
+    assert emb.info.name == "isaacsim"
+    assert emb.info.is_simulated is True
+    # 7 arm joints + 1 binary gripper command.
+    assert emb.info.action_space.dim == 8
+    sem = emb.info.action_space.semantics
+    assert sem is not None
+    assert sem.control_mode == "joint_pos"
+    assert sem.gripper == "binary"
+    assert "privileged_success" in emb.info.capabilities
+    assert "self_paced" not in emb.info.capabilities  # sim is framework-paced
+
+
+def test_action_dim_tracks_arm_joints() -> None:
+    assert IsaacSimEmbodiment(num_arm_joints=6).info.action_space.dim == 7
+
+
+def test_rejects_bad_joint_count() -> None:
+    with pytest.raises(ValueError):
+        IsaacSimEmbodiment(num_arm_joints=0)
+
+
+def test_observation_space_has_state_and_cameras() -> None:
+    emb = IsaacSimEmbodiment()
+    obs_space = emb.info.observation_space
+    assert "base_rgb" in obs_space.camera_names
+    assert {"joint_pos", "joint_vel", "eef_pos", "eef_quat", "gripper"} <= obs_space.state_keys
+
+
+def test_satisfies_embodiment_protocol() -> None:
+    assert isinstance(IsaacSimEmbodiment(), Embodiment)
+
+
+def test_factory_and_kwargs() -> None:
+    emb = isaacsim_embodiment(task_id="Isaac-Open-Drawer-Franka-v0", control_hz=20.0)
+    assert isinstance(emb, IsaacSimEmbodiment)
+    assert emb.task_id == "Isaac-Open-Drawer-Franka-v0"
+    assert emb.info.control_hz == 20.0
+
+
+def test_compatible_with_matching_franka_policy() -> None:
+    report = check_compatibility(_FrankaPolicy(), IsaacSimEmbodiment())
+    assert report.ok, report.errors
+
+
+def test_incompatible_with_2d_policy_fails_fast() -> None:
+    class _2DPolicy(_FrankaPolicy):
+        def __init__(self) -> None:
+            self.info = PolicyInfo(
+                name="cube2d",
+                action_space=Box(
+                    shape=(2,),
+                    semantics=ActionSemantics(control_mode="eef_delta_pos", frame="world"),
+                ),
+            )
+            self.config = PolicyConfig()
+
+    report = check_compatibility(_2DPolicy(), IsaacSimEmbodiment())
+    assert not report.ok
+    codes = {i.code for i in report.errors}
+    assert "action_dim" in codes
+    with pytest.raises(CompatibilityError):
+        report.raise_for_errors()
+
+
+def test_reset_without_isaac_raises_clear_error() -> None:
+    emb = IsaacSimEmbodiment()
+    with pytest.raises(RuntimeError, match="Isaac Sim / Isaac Lab is not importable"):
+        emb.reset(Scene(id="s0", instruction="lift the cube"))
+
+
+def test_close_is_safe_before_launch_and_idempotent() -> None:
+    emb = IsaacSimEmbodiment()
+    emb.close()  # no env/app yet -> no-op, must not raise
+    emb.close()  # second call must also be safe
+
+
+def test_context_manager_calls_close() -> None:
+    closed = {"n": 0}
+
+    class _Emb(IsaacSimEmbodiment):
+        def close(self) -> None:
+            closed["n"] += 1
+
+    with _Emb() as emb:
+        assert isinstance(emb, IsaacSimEmbodiment)
+    assert closed["n"] == 1
+
+
+# --------------------------------------------------------------------------- #
+# Memory-safety: drive reset()/step() many times against a fake Isaac env and
+# assert the adapter accumulates no state and leaks no RAM. Runs without Isaac.
+# --------------------------------------------------------------------------- #
+class _FakeIsaacEnv:
+    """A stand-in for the Isaac Lab gym env: dict obs batched over num_envs=1."""
+
+    def __init__(self, action_dim: int) -> None:
+        self.action_dim = action_dim
+        self.reset_calls = 0
+        self.step_calls = 0
+
+    def _obs(self) -> dict[str, dict[str, np.ndarray]]:
+        # Fresh arrays each call, exactly like Isaac handing back buffer reads.
+        return {
+            "policy": {
+                "base_rgb": np.zeros((1, 224, 224, 3), dtype=np.uint8),
+                "joint_pos": np.zeros((1, 7), dtype=np.float32),
+                "joint_vel": np.zeros((1, 7), dtype=np.float32),
+                "eef_pos": np.zeros((1, 3), dtype=np.float32),
+                "eef_quat": np.zeros((1, 4), dtype=np.float32),
+                "gripper": np.zeros((1, 1), dtype=np.float32),
+            }
+        }
+
+    def reset(self, seed: int | None = None) -> tuple[Any, dict[str, Any]]:
+        self.reset_calls += 1
+        return self._obs(), {}
+
+    def step(self, action: Any) -> tuple[Any, Any, Any, Any, dict[str, Any]]:
+        self.step_calls += 1
+        return (
+            self._obs(),
+            np.array([0.0]),
+            np.array([False]),
+            np.array([False]),
+            {"success": False},
+        )
+
+    def close(self) -> None: ...
+
+
+class _FakeTorch:
+    @staticmethod
+    def as_tensor(value: Any, device: str | None = None) -> np.ndarray:
+        return np.asarray(value)
+
+
+def _inject_fake(emb: IsaacSimEmbodiment) -> _FakeIsaacEnv:
+    fake = _FakeIsaacEnv(emb.info.action_space.dim)
+    emb._env = fake
+    emb._torch = _FakeTorch()
+    return fake
+
+
+def test_step_translation_against_fake_env() -> None:
+    from inspect_robots import Action
+
+    emb = IsaacSimEmbodiment()
+    _inject_fake(emb)
+    emb.reset(Scene(id="s", instruction="lift"))
+    result = emb.step(Action(data=np.zeros(8)))
+    assert set(result.observation.images) == {"base_rgb"}
+    assert result.observation.images["base_rgb"].dtype == np.uint8
+    assert {"joint_pos", "eef_pos", "gripper"} <= set(result.observation.state)
+    assert result.terminated is False
+    assert result.info["success"] is False
+
+
+def test_no_ram_leak_over_many_steps() -> None:
+    """RAM must stay flat over thousands of steps (caller drops each result)."""
+    import gc
+    import tracemalloc
+
+    from inspect_robots import Action
+
+    emb = IsaacSimEmbodiment()
+    fake = _inject_fake(emb)
+    act = Action(data=np.zeros(8, dtype=np.float32))
+
+    # Warm up so one-time allocations (interned strings, caches) settle.
+    emb.reset(Scene(id="s", instruction="lift"))
+    for _ in range(200):
+        emb.step(act)
+
+    gc.collect()
+    tracemalloc.start()
+    before = tracemalloc.take_snapshot()
+    for _ in range(3000):
+        emb.step(act)  # result intentionally dropped each iteration
+    gc.collect()
+    after = tracemalloc.take_snapshot()
+    tracemalloc.stop()
+
+    grew = sum(s.size_diff for s in after.compare_to(before, "filename") if s.size_diff > 0)
+    # 3000 steps each allocating a 150KB image would be ~450MB if retained; a
+    # leak-free loop holds nothing, so allow only a small slack for allocator noise.
+    assert grew < 5_000_000, f"RAM grew {grew} bytes over 3000 steps; suspect a leak"
+    # The adapter itself must hold no per-step accumulation.
+    assert fake.step_calls == 3200
+    for value in vars(emb).values():
+        assert not isinstance(value, (list, dict)) or len(value) <= 1