react-manip 0.1.0__py3-none-any.whl

react_manip/robots/adapters.py

@@ -0,0 +1,135 @@
+"""Built-in and custom robot embodiment adapters."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .base import ModelBackedAdapter, RobotSpec
+
+
+class RobosuiteRobotAdapter:
+    """Metadata adapter for a robot already supported by robosuite."""
+
+    def __init__(self, robot_name: str):
+        self.robot_name = robot_name
+        bimanual = robot_name in {"Baxter", "GR1ArmsOnly"}
+        self.spec = RobotSpec(
+            robot_id=robot_name.lower(),
+            arm_names=("left", "right") if bimanual else ("right",),
+            gripper_type="robosuite",
+            metadata={"robosuite_name": robot_name},
+        )
+
+    def validate_assets(self) -> None:
+        # The robosuite installation performs the authoritative asset check.
+        return None
+
+    def make(self, **kwargs: Any) -> str:
+        del kwargs
+        return self.robot_name
+
+    def load_mujoco_model(self) -> Any:
+        raise NotImplementedError("robosuite robots are loaded through suite.make")
+
+
+class PiperXAdapter(ModelBackedAdapter):
+    """PiperX single-arm adapter.
+
+    ``spec`` is configurable because Piper/PiperX hardware revisions and
+    grippers may differ.  No default joint list is guessed here; the adapter
+    must be constructed with the exact MJCF and calibrated metadata.
+    """
+
+    def __init__(
+        self,
+        model_path: str | None = None,
+        *,
+        arm_dof: int | None = None,
+        action_dim: int | None = None,
+        eef_site: str = "piperx_gripper_site",
+        gripper_type: str = "parallel",
+        metadata: Mapping[str, Any] | None = None,
+    ):
+        super().__init__(
+            RobotSpec(
+                robot_id="piperx",
+                arm_names=("right",),
+                arm_dof=() if arm_dof is None else (int(arm_dof),),
+                gripper_type=gripper_type,
+                action_dim=action_dim,
+                eef_sites=(eef_site,),
+                model_path=model_path,
+                capabilities=frozenset({"single_arm", "parallel_gripper", "custom_mjcf"}),
+                metadata=dict(metadata or {}),
+            )
+        )
+
+
+class AlohaAdapter(ModelBackedAdapter):
+    """Adapter for a split, fixed-base bimanual ALOHA embodiment.
+
+    The two arm model paths may point to one combined MJCF or two independent
+    arm MJCF files.  A later loader can choose the representation without
+    changing task or policy APIs.
+    """
+
+    def __init__(
+        self,
+        model_path: str | None = None,
+        *,
+        left_model_path: str | None = None,
+        right_model_path: str | None = None,
+        arm_dof: int | None = None,
+        gripper_type: str = "parallel",
+        eef_sites: tuple[str, str] = ("aloha_left_gripper_site", "aloha_right_gripper_site"),
+        metadata: Mapping[str, Any] | None = None,
+    ):
+        paths = {"left_model_path": left_model_path, "right_model_path": right_model_path}
+        super().__init__(
+            RobotSpec(
+                robot_id="aloha",
+                arm_names=("left", "right"),
+                arm_dof=() if arm_dof is None else (int(arm_dof), int(arm_dof)),
+                gripper_type=gripper_type,
+                eef_sites=eef_sites,
+                model_path=model_path,
+                capabilities=frozenset({"bimanual", "parallel_gripper", "custom_mjcf"}),
+                metadata={**paths, **dict(metadata or {})},
+            )
+        )
+
+    def validate_assets(self) -> None:
+        if self.model_path is not None:
+            return super().validate_assets()
+        missing = []
+        for key in ("left_model_path", "right_model_path"):
+            value = self.spec.metadata.get(key)
+            if not value:
+                missing.append(key)
+            else:
+                from pathlib import Path
+
+                if not Path(str(value)).expanduser().is_file():
+                    raise FileNotFoundError(f"robot model does not exist: {value}")
+        if missing:
+            raise FileNotFoundError(
+                "aloha requires model_path or both left_model_path/right_model_path; missing "
+                + ", ".join(missing)
+            )
+
+    def load_mujoco_model(self) -> Any:
+        """Load one combined model or both split arm models.
+
+        A split return value is a mapping so a higher-level bimanual scene
+        builder can place and namespace the two arms explicitly.
+        """
+
+        if self.model_path is not None:
+            return super().load_mujoco_model()
+        self.validate_assets()
+        import mujoco
+
+        return {
+            "left": mujoco.MjModel.from_xml_path(str(self.spec.metadata["left_model_path"])),
+            "right": mujoco.MjModel.from_xml_path(str(self.spec.metadata["right_model_path"])),
+        }

react_manip/robots/agilex_adapter.py

@@ -0,0 +1,35 @@
+"""Metadata facade for the generated official PiPER-X and custom dual assemblies."""
+from .base import RobotSpec
+
+
+class AgileXAdapter:
+    def __init__(self, robot_id):
+        if robot_id not in ("piperx", "dual_piperx", "mobile_dual_piperx", "legacy_piperx", "aloha", "aloha_mobile"):
+            raise ValueError(robot_id)
+        arms = ("right", "left") if robot_id not in ("piperx", "legacy_piperx") else ("right",)
+        self.spec = RobotSpec(
+            robot_id=robot_id, arm_names=arms, arm_dof=(6,)*len(arms),
+            gripper_type="parallel", action_dim=7*len(arms), control_modes=("osc_pose",),
+            eef_sites=tuple(f"gripper0_{arm}_grip_site" for arm in arms),
+            capabilities=frozenset({"custom_mjcf", "parallel_gripper", "bimanual" if len(arms)==2 else "single_arm"}),
+            metadata={"manufacturer": "AgileX", "arm_model": "legacy follower" if robot_id in ("legacy_piperx", "aloha", "aloha_mobile") else "PiPER-X", "asset_version": "legacy-agilex-family.v1" if robot_id in ("legacy_piperx", "aloha", "aloha_mobile") else "piperx-family.v1", "assembly": "custom" if len(arms) == 2 else "single", "mobile_base": robot_id in ("mobile_dual_piperx", "aloha_mobile"), "base_command_dim": 2 if robot_id in ("mobile_dual_piperx", "aloha_mobile") else 0, "calibrated": False,
+                      "action_layout": "right_pose,left_pose,right_gripper,left_gripper" if len(arms)==2 else "right_pose,right_gripper"},
+        )
+
+    def validate_assets(self):
+        from .agilex_robosuite import validate_bundle
+        if self.spec.robot_id in ("legacy_piperx", "aloha", "aloha_mobile"):
+            from .legacy_agilex_robosuite import validate_bundle
+        validate_bundle()
+
+    def make(self, **kwargs):
+        from .agilex_robosuite import resolve_robot
+        return resolve_robot(self.spec.robot_id)
+
+    def load_mujoco_model(self):
+        from robosuite.models.robots import create_robot
+        from robosuite.models.grippers import gripper_factory
+        robot = create_robot(self.make())
+        for arm in robot.arms:
+            robot.add_gripper(gripper_factory(robot.default_gripper[arm], idn=f"0_{arm}"), robot.eef_name[arm])
+        return robot.get_model()

react_manip/robots/agilex_description.py

@@ -0,0 +1,74 @@
+"""Legacy extractor for the archived mobile_aloha_sim follower model.
+
+This prepares URDF input; it does not implement a runnable task or convert DAE
+meshes. Source: agilexrobotics/mobile_aloha_sim, aloha_new.urdf.
+"""
+from copy import deepcopy
+import xml.etree.ElementTree as ET
+
+
+def extract_followers(source: ET.Element, embodiment: str) -> ET.Element:
+    """Keep front follower subtrees, excluding leaders, chassis and cameras.
+
+    Single PiPER is rooted at its base origin. Dual-arm mounting transforms are
+    preserved relative to the upstream body_Link frame (not the world frame).
+    This legacy model is not the official PiPER-X asset.
+    """
+    if embodiment in ("piperx", "dual_piperx", "mobile_dual_piperx"):
+        raise ValueError("PiPER-X requires scripts/build_agilex_assets.py and official agx_arm_urdf assets")
+    selections = {"piper": ("fr",), "agilex_aloha": ("fl", "fr")}
+    if embodiment not in selections:
+        raise ValueError("embodiment must be piper or agilex_aloha")
+    links = {link.attrib["name"]: link for link in source.findall("link")}
+    joints = source.findall("joint")
+    output = ET.Element("robot", name=embodiment + "_followers")
+    ET.SubElement(output, "link", name="world")
+    for material in source.findall("material"):
+        output.append(deepcopy(material))
+    for prefix in selections[embodiment]:
+        base = prefix + "_base_link"
+        if base not in links:
+            raise ValueError(f"missing follower base: {base}")
+        selected = {base}
+        chosen = []
+        pending = list(joints)
+        while True:
+            additions = [j for j in pending if j.find("parent").get("link") in selected]
+            if not additions:
+                break
+            for joint in additions:
+                child = joint.find("child").get("link")
+                if child in selected or child not in links:
+                    raise ValueError(f"invalid follower tree at {child}")
+                selected.add(child)
+                chosen.append(joint)
+                pending.remove(joint)
+        revolute = [j for j in chosen if j.get("type") == "revolute"]
+        fingers = [j for j in chosen if j.get("type") == "prismatic"]
+        if len(revolute) != 6 or len(fingers) != 2:
+            raise ValueError(f"{prefix}: expected six arm and two finger joints")
+        for joint in revolute + fingers:
+            limit = joint.find("limit")
+            if limit is None or not {"lower", "upper", "effort", "velocity"} <= set(limit.keys()):
+                raise ValueError(f"missing limits: {joint.get('name')}")
+            child = links[joint.find("child").get("link")]
+            if child.find("inertial") is None or child.find("collision") is None:
+                raise ValueError(f"missing dynamics/collision: {child.get('name')}")
+        mounts = [j for j in joints if j.find("child").get("link") == base]
+        if len(mounts) != 1 or mounts[0].get("type") != "fixed":
+            raise ValueError(f"expected fixed mount for {base}")
+        mount = deepcopy(mounts[0])
+        if mount.find("parent").get("link") != "body_Link":
+            raise ValueError("unexpected mounting frame; inspect upstream model")
+        mount.find("parent").set("link", "world")
+        if embodiment == "piper":
+            origin = mount.find("origin")
+            if origin is None:
+                origin = ET.SubElement(mount, "origin")
+            origin.set("xyz", "0 0 0")
+            origin.set("rpy", "0 0 0")
+        for name in sorted(selected):
+            output.append(deepcopy(links[name]))
+        output.append(mount)
+        output.extend(deepcopy(chosen))
+    return output

react_manip/robots/agilex_robosuite.py

@@ -0,0 +1,246 @@
+"""Lazy robosuite integration of pinned official AgileX follower models."""
+from pathlib import Path
+import os
+import numpy as np
+
+
+def asset_dir():
+    override = os.environ.get("AGILEX_ASSET_DIR")
+    if override:
+        return Path(override)
+    root = Path(__file__).resolve().parents[2]
+    if (root / "pyproject.toml").is_file() and (root / "scripts/build_agilex_assets.py").is_file():
+        return root / "assets/robots/agilex"
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "react-manip/robots/agilex"
+
+
+def validate_bundle():
+    """Reject stale or modified generated bundles, including old grasp aids."""
+    import hashlib
+    import json
+    import xml.etree.ElementTree as ET
+    directory = asset_dir()
+    manifest = directory / "provenance.json"
+    if not manifest.exists():
+        raise FileNotFoundError("Run react-manip-assets prepare to build PiPER-X assets")
+    data = json.loads(manifest.read_text())
+    if data.get("schema") != "piperx-family.v1":
+        raise ValueError("Legacy AgileX assets: rebuild with scripts/build_agilex_assets.py")
+    lock = Path(__file__).resolve().parents[2] / "scripts/piperx_assets.lock.json"
+    if data.get("source_lock_sha256") != hashlib.sha256(lock.read_bytes()).hexdigest():
+        raise ValueError("PiPER-X source lock changed; rebuild the asset bundle")
+    for name in ("piperx.xml", "dual_piperx.xml", "mobile_dual_piperx.xml", "gripper.xml"):
+        if name not in data.get("generated_sha256", {}):
+            raise ValueError(f"Incomplete PiPER-X manifest: {name}")
+    for name, expected in data["generated_sha256"].items():
+        path = directory / name
+        if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != expected:
+            raise ValueError(f"Stale or modified PiPER-X asset {path}; rebuild the bundle")
+    gripper = ET.parse(directory / "gripper.xml")
+    for geom in gripper.iter("geom"):
+        if geom.get("name", "").endswith(("_pad", "_flat_pad")):
+            raise ValueError("Unexpected legacy grasp-helper geometry")
+        if "_collision" in geom.get("name", "") and (geom.get("contype", "1") == "0" or geom.get("conaffinity", "1") == "0"):
+            raise ValueError("Disabled physical gripper surface")
+
+
+def controller_config(arms=("right",)):
+    return {"type": "BASIC", "body_parts": {arm: {
+        "type": "OSC_POSE", "input_max": 1, "input_min": -1,
+        "output_max": [0.015]*3 + [0.08]*3, "output_min": [-0.015]*3 + [-0.08]*3,
+        "kp": 60, "damping_ratio": 1.5, "impedance_mode": "fixed",
+        "input_type": "delta", "input_ref_frame": "world", "uncouple_pos_ori": True,
+        "goal_update_mode": "achieved", "interpolation": None,
+        "gripper": {"type": "GRIP"},
+    } for arm in arms}}
+
+
+def register_agilex():
+    """Register classes without importing robosuite during registry discovery."""
+    validate_bundle()
+    from robosuite.models.robots.robot_model import REGISTERED_ROBOTS
+    if "PiperX" in REGISTERED_ROBOTS:
+        return
+    from robosuite.models.robots.manipulators.manipulator_model import ManipulatorModel
+    from robosuite.models.grippers.gripper_model import GripperModel
+    from robosuite.models.grippers import GRIPPER_MAPPING
+    from robosuite.robots import ROBOT_CLASS_MAPPING, FixedBaseRobot
+
+    class PiperXGripper(GripperModel):
+        def __init__(self, idn=0):
+            super().__init__(str(asset_dir() / "gripper.xml"), idn=idn)
+            # Simulation tuning, independent of the checksum-locked geometry.
+            # The generated 1 N s/m damping lets a full-stroke position command
+            # overshoot the slide stops and interlock the opposing finger meshes.
+            # Dampen the physical joints, without clipping positions or removing
+            # contact surfaces. Tasks can still apply their validated settings.
+            for joint in self.worldbody.iter("joint"):
+                if joint.get("type") == "slide":
+                    joint.set("damping", "8")
+
+        @property
+        def dof(self):
+            return 1
+
+        @property
+        def init_qpos(self):
+            return np.array([0.04, -0.04])
+
+        def format_action(self, action):
+            # +1 closes both opposing slides; -1 opens.  The keyboard demo
+            # sends a persistent toggle state, so map that state directly to
+            # the normalized gripper target instead of accumulating only a
+            # small increment on every simulation step.  The downstream
+            # position actuators still provide the physical smoothing.
+            self.current_action = np.clip(np.asarray(action, dtype=float), -1, 1)
+            return np.array([-self.current_action[0], self.current_action[0]])
+
+        @property
+        def _important_geoms(self):
+            # Every convex part participates in robosuite contact detection.
+            import json
+            names = json.loads((asset_dir() / "provenance.json").read_text())["gripper_collision_names"]
+            return {"left_finger": names["finger7"], "right_finger": names["finger8"],
+                    "left_fingerpad": names["finger7"], "right_fingerpad": names["finger8"]}
+
+
+    class PiperX(ManipulatorModel):
+        arms = ["right"]
+        asset_name = "piperx.xml"
+        fixed_stand = dict(height=.80, half_depth=.09, half_width=.10)
+
+        def __init__(self, idn=0):
+            super().__init__(str(asset_dir() / self.asset_name), idn=idn)
+            if self.fixed_stand is not None:
+                from .mounts import install_fixed_stand
+                install_fixed_stand(self, **self.fixed_stand)
+
+        def add_gripper(self, gripper, arm_name=None):
+            super().add_gripper(gripper, arm_name)
+            # Install cameras on the embodiment before any task merges XML.
+            # Covers tasks that use robosuite's own ManipulationTask as well.
+            from ..cameras import ensure_robot_cameras
+            ensure_robot_cameras(self)
+            self.cameras = self.get_element_names(self.worldbody, 'camera')
+
+        @property
+        def default_base(self):
+            return "NullMount"
+
+        @property
+        def default_gripper(self):
+            return {arm: "PiperXGripper" for arm in self.arms}
+
+        @property
+        def default_controller_config(self):
+            return {arm: "osc_pose" for arm in self.arms}
+
+        @property
+        def init_qpos(self):
+            # Official PiPER-X joint frames differ from the old extracted arm.
+            # Start with the fingers pointing toward the tabletop, within the
+            # official limits and with margin to the wrist limit.
+            return np.tile([0, 1.2, -1.1, 1.2, 0, 0], len(self.arms))
+
+        @property
+        def base_xpos_offset(self):
+            return {"empty": (-0.45, 0, 0), "bins": (-0.45, 0, 0),
+                    "table": lambda length: (-0.1-length/2, 0, 0)}
+
+        @property
+        def top_offset(self):
+            return np.array([0, 0, 0.7])
+
+        @property
+        def _horizontal_radius(self):
+            return 0.7
+
+        @property
+        def arm_type(self):
+            return "single" if len(self.arms) == 1 else "bimanual"
+
+        @property
+        def _eef_name(self):
+            return {arm: arm + "_hand" for arm in self.arms}
+
+    class DualPiperX(PiperX):
+        arms = ["right", "left"]
+        asset_name = "dual_piperx.xml"
+        # Imported dual-arm bases are at x=.23875, y=+/- .30.
+        # Support their mounting plane, not the empty asset origin.
+        fixed_stand = dict(height=.65, half_depth=.09, half_width=.375, center_xy=(.23875, 0.))
+
+    class MobileDualPiperX(DualPiperX):
+        asset_name = "mobile_dual_piperx.xml"
+        fixed_stand = None
+
+        # FixedBaseRobot is used only for the two arm controllers. The XML
+        # still contains the physical free root and ten wheel/caster joints;
+        # they must not enter robosuite's scalar arm-qpos reset/indexing.
+        @property
+        def joints(self):
+            return [name for name in super().joints if "mobile_" not in name]
+
+        @property
+        def actuators(self):
+            return [name for name in super().actuators if "mobile_" not in name]
+
+    GRIPPER_MAPPING["PiperXGripper"] = PiperXGripper
+    for cls in (PiperX, DualPiperX, MobileDualPiperX):
+        ROBOT_CLASS_MAPPING[cls.__name__] = FixedBaseRobot
+
+
+def resolve_robot(robot_id):
+    if robot_id in ('legacy_piperx', 'aloha', 'aloha_mobile'):
+        from .legacy_agilex_robosuite import resolve_robot as resolve_legacy
+        return resolve_legacy(robot_id)
+    if robot_id not in ("piperx", "dual_piperx", "mobile_dual_piperx"):
+        raise ValueError(f"not an AgileX robot: {robot_id}")
+    register_agilex()
+    if robot_id == "mobile_dual_piperx":
+        import xml.etree.ElementTree as ET
+        if ET.parse(asset_dir() / "mobile_dual_piperx.xml").find(".//freejoint[@name='mobile_free']") is None:
+            raise ValueError("Stale planar ALOHA assets: run python scripts/build_agilex_assets.py")
+    return "PiperX" if robot_id == "piperx" else ("MobileDualPiperX" if robot_id == "mobile_dual_piperx" else "DualPiperX")
+
+
+def validate_compiled_grippers(env):
+    """Task composition may tune materials, but cannot replace contact shapes."""
+    import json
+    raw = getattr(env, 'env', env)
+    robots = getattr(raw, 'robots', ())
+    if not any(getattr(robot, 'name', '') in ('PiperX','DualPiperX','MobileDualPiperX','AgileXPiper','AgileXAloha','AgileXMobileAloha') for robot in robots):
+        return
+    model = raw.sim.model
+    for robot in robots:
+        if getattr(robot, 'name', '') not in ('PiperX','DualPiperX','MobileDualPiperX','AgileXPiper','AgileXAloha','AgileXMobileAloha'):
+            continue
+        legacy = getattr(robot, 'name', '').startswith('AgileX')
+        directory = asset_dir()
+        if legacy:
+            from .legacy_agilex_robosuite import asset_dir as legacy_asset_dir
+            directory = legacy_asset_dir()
+        manifest = json.loads((directory / 'provenance.json').read_text())
+        for gripper in robot.gripper.values():
+            if type(gripper).__name__ != ('AgileXPiperGripper' if legacy else 'PiperXGripper'):
+                raise ValueError('PiPER-X must use the central PiperXGripper asset')
+            prefix = gripper.naming_prefix
+            expected = {prefix + name for parts in manifest['gripper_collision_names'].values() for name in parts}
+            finger_bodies = {model.body_name2id(prefix + name) for name in ('finger7', 'finger8')}
+            for geom_id in range(model.ngeom):
+                if model.geom_bodyid[geom_id] in finger_bodies and (model.geom_contype[geom_id] or model.geom_conaffinity[geom_id]):
+                    if model.geom_id2name(geom_id) not in expected:
+                        raise ValueError('Task added an unapproved PiPER-X finger collision shape')
+            for parts in manifest['gripper_collision_names'].values():
+                for name in parts:
+                    c = model.geom_name2id(prefix + name)
+                    v = model.geom_name2id(prefix + name.replace('_collision','_visual'))
+                    if (model.geom_type[c] != model.geom_type[v]
+                        or not np.allclose(model.geom_size[c], model.geom_size[v], atol=1e-10)
+                        or model.geom_dataid[c] != model.geom_dataid[v]
+                        or not np.allclose(model.geom_pos[c],model.geom_pos[v],atol=1e-10)
+                        or not np.allclose(model.geom_quat[c],model.geom_quat[v],atol=1e-10)
+                        or not model.geom_contype[c] or not model.geom_conaffinity[c]
+                        or model.geom_contype[v] or model.geom_conaffinity[v]
+                        or model.geom_margin[c] != 0):
+                        raise ValueError(f'Task changed PiPER-X contact surface: {prefix + name}')

react_manip/robots/arm_actions.py

@@ -0,0 +1,17 @@
+"""Build multi-arm actions using controller-advertised slices, not 7D chunks."""
+import numpy as np
+
+
+def arm_action(action_dim, layout, active_arm, pose, grippers):
+    action = np.zeros(action_dim, dtype=np.float32)
+    start, end = layout[active_arm]
+    if end - start != 6:
+        raise ValueError("keyboard pose control requires six Cartesian inputs per arm")
+    action[start:end] = np.clip(np.asarray(pose), -1, 1)
+    for arm, value in grippers.items():
+        start, end = layout[arm + "_gripper"]
+        if end - start != 1:
+            raise ValueError("keyboard gripper control requires one input per gripper")
+        action[start:end] = np.clip(value, -1, 1)
+    return action
+

react_manip/robots/base.py

@@ -0,0 +1,119 @@
+"""Embodiment-neutral robot metadata and adapter contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Protocol
+
+
+@dataclass(frozen=True)
+class RobotSpec:
+    robot_id: str
+    arm_names: tuple[str, ...] = ("right",)
+    arm_dof: tuple[int, ...] = ()
+    gripper_type: str | None = None
+    control_modes: tuple[str, ...] = ("joint_position",)
+    action_dim: int | None = None
+    eef_sites: tuple[str, ...] = ()
+    model_path: str | None = None
+    capabilities: frozenset[str] = field(default_factory=frozenset)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.robot_id or any(ch.isspace() for ch in self.robot_id):
+            raise ValueError("robot_id must be a non-empty, whitespace-free string")
+        if not self.arm_names and 'task_level_proxy' not in self.capabilities:
+            raise ValueError("arm_names must contain at least one arm")
+        if self.arm_dof and len(self.arm_dof) != len(self.arm_names):
+            raise ValueError("arm_dof must have one entry per arm")
+        if self.action_dim is not None and self.action_dim < 1:
+            raise ValueError("action_dim must be positive")
+
+    @property
+    def required_arms(self) -> int:
+        return len(self.arm_names)
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "RobotSpec":
+        arm_names = value.get("arm_names", ("right",))
+        if isinstance(arm_names, str):
+            arm_names = (arm_names,)
+        control_modes = value.get("control_modes", ("joint_position",))
+        if isinstance(control_modes, str):
+            control_modes = (control_modes,)
+        eef_sites = value.get("eef_sites", ())
+        if isinstance(eef_sites, str):
+            eef_sites = (eef_sites,)
+        arm_dof = value.get("arm_dof", ())
+        if isinstance(arm_dof, int):
+            arm_dof = (arm_dof,)
+        return cls(
+            robot_id=str(value["robot_id"]),
+            arm_names=tuple(arm_names),
+            arm_dof=tuple(int(v) for v in arm_dof),
+            gripper_type=value.get("gripper_type"),
+            control_modes=tuple(control_modes),
+            action_dim=None if value.get("action_dim") is None else int(value["action_dim"]),
+            eef_sites=tuple(eef_sites),
+            model_path=value.get("model_path"),
+            capabilities=frozenset(value.get("capabilities", ())),
+            metadata=dict(value.get("metadata", {})),
+        )
+
+
+class RobotAdapter(Protocol):
+    """Protocol implemented by a robot embodiment integration."""
+
+    spec: RobotSpec
+
+    def validate_assets(self) -> None:
+        ...
+
+    def make(self, **kwargs: Any) -> Any:
+        ...
+
+    def load_mujoco_model(self) -> Any:
+        ...
+
+
+class ModelBackedAdapter:
+    """Common asset validation for custom MJCF-backed robots."""
+
+    spec: RobotSpec
+
+    def __init__(self, spec: RobotSpec):
+        self.spec = spec
+
+    @property
+    def model_path(self) -> Path | None:
+        return Path(self.spec.model_path).expanduser() if self.spec.model_path else None
+
+    def validate_assets(self) -> None:
+        path = self.model_path
+        if path is None:
+            raise FileNotFoundError(
+                f"{self.spec.robot_id} has no model_path; provide an MJCF asset before simulation"
+            )
+        if not path.is_file():
+            raise FileNotFoundError(f"robot model does not exist: {path}")
+
+    def load_mujoco_model(self) -> Any:
+        """Load the configured MJCF for lightweight asset/control smoke tests."""
+
+        self.validate_assets()
+        import mujoco  # imported only when a simulator is actually requested
+
+        return mujoco.MjModel.from_xml_path(str(self.model_path))
+
+    def make(self, **kwargs: Any) -> Any:
+        """Return integration-specific robot object.
+
+        Subclasses should implement this once the exact robosuite/MuJoCo
+        model is available.  Keeping the method explicit prevents a missing
+        asset from silently falling back to Panda.
+        """
+
+        del kwargs
+        self.validate_assets()
+        raise NotImplementedError(f"{self.spec.robot_id} model loader is not configured")

react_manip/robots/catalog.py

@@ -0,0 +1,18 @@
+"""Built-in ID snapshots plus live registry-based normalization.
+
+Use registered_robot_ids() for extension-aware enumeration. Task compatibility
+is separate from registration and may still narrow the available combinations.
+"""
+
+ALL_ROBOT_IDS = ("panda", "sawyer", "piperx", "dual_piperx", "mobile_dual_piperx", "legacy_piperx", "aloha", "aloha_mobile")
+SINGLE_ARM_ROBOT_IDS = ("panda", "sawyer", "piperx", "legacy_piperx")
+
+
+def normalize_robot_id(robot_id: str) -> str:
+    from .resolution import registered_robot_ids
+    value = str(robot_id).strip().lower()
+    if value not in registered_robot_ids():
+        raise ValueError(
+            f"unknown robot {robot_id!r}; supported IDs: {', '.join(registered_robot_ids())}"
+        )
+    return value