robot-dam 0.6.0__py3-none-any.whl

dam/__init__.py

@@ -0,0 +1,69 @@
+import tomllib
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+from pathlib import Path
+
+from dam import testing
+from dam.api import RunSummary, SafetyGuard, SafetyKinematicsResolver, build_runner, run, safe
+from dam.decorators import callback, fallback, guard
+from dam.guard.aggregator import aggregate_decisions
+from dam.guard.base import Guard
+from dam.guard.layer import GuardLayer
+from dam.runner.base import BaseRunner as Runner
+from dam.runner.base import RunnerStatus
+from dam.types.action import ActionProposal, ValidatedAction
+from dam.types.observation import Observation
+from dam.types.result import GuardDecision, GuardResult
+from dam.types.risk import CycleResult, RiskLevel
+
+
+def _resolve_version() -> str:
+    version_file = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    if version_file.exists():
+        with version_file.open("rb") as fh:
+            data = tomllib.load(fh)
+        version = data.get("project", {}).get("version")
+        if version:
+            return str(version)
+    try:
+        return _package_version("dam")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = [
+    "__version__",
+    "guard",
+    "callback",
+    "fallback",
+    "Guard",
+    "aggregate_decisions",
+    "GuardLayer",
+    "GuardResult",
+    "GuardDecision",
+    "Observation",
+    "ActionProposal",
+    "ValidatedAction",
+    "RiskLevel",
+    "CycleResult",
+    "testing",
+    "build_runner",
+    "run",
+    "safe",
+    "RunSummary",
+    "SafetyGuard",
+    "SafetyKinematicsResolver",
+    "SafetyProcessorStep",
+    "Runner",
+    "RunnerStatus",
+]
+
+
+def __getattr__(name: str):  # type: ignore[no-untyped-def]
+    if name == "SafetyProcessorStep":
+        from dam.processor import SafetyProcessorStep
+
+        return SafetyProcessorStep
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

dam/adapter/__init__.py

@@ -0,0 +1,11 @@
+from dam.adapter.dataset import DatasetReplayPolicy, DatasetSimSource
+from dam.adapter.lerobot import LeRobotAdapter, LeRobotPolicyAdapter
+from dam.adapter.transforms import ImageNamespaceSource
+
+__all__ = [
+    "DatasetReplayPolicy",
+    "DatasetSimSource",
+    "LeRobotAdapter",
+    "LeRobotPolicyAdapter",
+    "ImageNamespaceSource",
+]

dam/adapter/base.py

@@ -0,0 +1,182 @@
+"""Abstract base classes for all DAM adapters.
+
+Design principle: Guards NEVER import concrete adapters. They only declare parameter names
+in their check() signature. The framework resolves and injects the correct objects from the
+runtime pool at startup. This boundary is enforced at the import level.
+
+Adapter roles:
+  SensorAdapter   — external world  → Observation
+  PolicyAdapter   — Observation     → ActionProposal
+  ActionAdapter   — ValidatedAction → hardware
+  SimulatorAdapter — (used by L1 only, never by guards directly)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dam.types.action import ActionProposal, ValidatedAction
+    from dam.types.observation import Observation
+
+
+class SensorAdapter(ABC):
+    """Bridges a hardware / ROS2 / serial source to DAM Observation.
+
+    Implementations: LeRobotAdapter, ROS2SourceAdapter, SerialSourceAdapter …
+    Declared in Stackfile hardware.sources; instantiated by StackfileLoader, never by user code.
+    """
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Open connection to the sensor / topic."""
+        ...
+
+    @abstractmethod
+    def read(self) -> Observation:
+        """Read one sample and return a fully-typed Observation."""
+        ...
+
+    @abstractmethod
+    def is_healthy(self) -> bool:
+        """Return True if the sensor is reachable and data is fresh."""
+        ...
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close connection gracefully."""
+        ...
+
+    def supported_channels(self) -> set[str]:
+        """Return the set of observation channel names this adapter can provide.
+
+        Subclasses that support device-specific channels (e.g. servo current,
+        temperature) must override this.  The default returns an empty set,
+        meaning no extra channels are available.
+        """
+        return set()
+
+    def set_observation_channels(self, channels: list[str]) -> None:
+        """Activate the given observation channels for reading.
+
+        Called by the factory after validating against supported_channels().
+        Subclasses that support channels must override this.
+        """
+        raise NotImplementedError(f"{type(self).__name__} does not support observation channels")
+
+    @property
+    def camera_shapes(self) -> dict[str, tuple[int, int]]:
+        """Return ``{camera_name: (height, width)}`` for cameras this source provides.
+
+        Populated after ``verify()`` has read a real frame. Empty when the
+        adapter has no cameras or before verify. The runtime uses this to
+        warm up downstream PyTorch models at the actual capture resolution.
+        """
+        return {}
+
+
+class PolicyAdapter(ABC):
+    """Wraps any policy model behind a single predict() contract.
+
+    Implementations: LeRobotPolicyAdapter, RandomPolicyAdapter (testing) …
+    The adapter hides framework-specific APIs (torch tensor shapes, chunk semantics, etc.)
+    so that guards and the runtime never depend on the policy library.
+    """
+
+    @abstractmethod
+    def initialize(self, config: dict[str, Any]) -> None:
+        """Load weights and prepare model for inference."""
+        ...
+
+    @abstractmethod
+    def predict(self, obs: Observation) -> ActionProposal:
+        """Run a forward pass and return the next action proposal."""
+        ...
+
+    @abstractmethod
+    def get_policy_name(self) -> str:
+        """Return a human-readable identifier, e.g. 'lerobot_act_so101'."""
+        ...
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Reset any internal recurrent state (called on task start)."""
+        ...
+
+    def preflight(self, camera_shapes: dict[str, tuple[int, int]] | None = None) -> None:  # noqa: B027
+        """Eagerly warm up the policy at the real capture resolution.
+
+        ``camera_shapes`` maps camera name → ``(height, width)`` from the
+        source adapters' first verified frames. Implementations should build
+        a dummy Observation with those exact shapes and run one forward pass
+        so PyTorch can compile its per-shape kernels before the control loop
+        starts. Default is a no-op for policies that don't need warmup.
+        """
+        pass
+
+
+class ActionAdapter(ABC):
+    """Sends a ValidatedAction to the physical hardware or ROS2 topic.
+
+    Implementations: LeRobotAdapter, ROS2SinkAdapter …
+    Declared in Stackfile hardware.sinks; instantiated by StackfileLoader.
+    """
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Open connection to the actuator / topic."""
+        ...
+
+    @abstractmethod
+    def apply(self, action: ValidatedAction) -> None:
+        """Send the validated action to hardware. Must be non-blocking in hot path."""
+        ...
+
+    @abstractmethod
+    def emergency_stop(self) -> None:
+        """Immediately halt all motion. Must be callable from any thread."""
+        ...
+
+    @abstractmethod
+    def get_hardware_status(self) -> dict[str, Any]:
+        """Return a dict of diagnostic information (temperatures, torques, errors)."""
+        ...
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Stop actuator and close connection gracefully."""
+        ...
+
+
+class SimulatorAdapter(ABC):
+    """Rollout interface used exclusively by L1 (SimPreflightGuard).
+
+    Guards must NOT import this class directly — L1 receives the simulator object
+    via injection pool key 'simulator'. Other guards must not declare 'simulator'
+    in their check() signatures.
+
+    The adapter's job is to synchronise with real-world state, step forward one action,
+    and report whether the result is safe. If is_available() returns False, L1 skips
+    the sim check and returns PASS (graceful degradation — simulator is optional).
+    """
+
+    @abstractmethod
+    def reset(self, obs: Observation) -> None:
+        """Synchronise the simulator state with the current real-world observation."""
+        ...
+
+    @abstractmethod
+    def step(self, action: ActionProposal) -> Observation:
+        """Apply action in simulation and return the resulting observation."""
+        ...
+
+    @abstractmethod
+    def has_collision(self) -> bool:
+        """Return True if the most recent step produced a collision."""
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return False if the simulator process is unavailable; L1 will PASS gracefully."""
+        ...

dam/adapter/dataset/__init__.py

@@ -0,0 +1,3 @@
+from dam.adapter.dataset.source import DatasetReplayPolicy, DatasetSimSource
+
+__all__ = ["DatasetReplayPolicy", "DatasetSimSource"]

dam/adapter/dataset/source.py

@@ -0,0 +1,279 @@
+"""Dataset adapter source and policy for LeRobot dataset replay.
+
+Usage
+-----
+Used in simulation mode when a ``simulation.dataset_repo_id`` is set in the
+Stackfile, and by dataset-to-hardware replay templates. Replays observations
+(joint positions + camera images) from the dataset; ``DatasetReplayPolicy``
+can emit each recorded action through the normal guard/sink path.
+
+The source iterates through one episode in sequence; when it reaches the end
+it wraps around to the beginning.  This gives infinite continuous replay for
+demo and regression-testing purposes.
+
+Initialisation
+--------------
+Dataset download / decoding happens in ``__init__``.  This call blocks until
+the dataset is ready (typically a few seconds for cached data, longer on first
+download).  The control loop does NOT start until the factory returns the
+source, so blocking in ``__init__`` is acceptable and avoids partial-init race
+conditions.
+
+Image format
+------------
+LeRobot datasets store camera frames as CHW float32 tensors in [0, 1].
+This class converts them to HWC uint8 numpy arrays ([0, 255]) to match the
+format expected by ``Observation.images`` and the MCAP image encoder.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import numpy as np
+
+from dam.adapter.base import PolicyAdapter
+from dam.types.action import ActionProposal
+from dam.types.observation import Observation
+
+logger = logging.getLogger(__name__)
+
+
+class DatasetSimSource:
+    """Replay a LeRobot dataset episode as a live observation stream.
+
+    Parameters
+    ----------
+    repo_id:
+        HuggingFace repo ID for the dataset (e.g. ``MikeChenYZ/soarm-fmb-v2``).
+    episode:
+        Episode index to replay (default 0).
+    hz:
+        Control frequency — used only for velocity estimation via finite
+        difference when the dataset does not include velocity data.
+    """
+
+    def __init__(
+        self,
+        repo_id: str,
+        episode: int = 0,
+        hz: float = 10.0,
+        degrees_mode: bool = True,
+        *,
+        strict: bool = False,
+    ) -> None:
+        self._repo_id = repo_id
+        self._episode = episode
+        self._hz = hz
+        self._degrees_mode = degrees_mode
+        self._cursor: float = 0.0
+        self._current_frame: dict[str, Any] | None = None
+        self._strict = strict
+        self._n_joints = 6  # updated from first loaded frame
+
+        # Pre-loaded episode data: list of {"joint_positions", "images"?, "action"?}
+        self._frames: list[dict[str, Any]] = []
+        self._prev_pos: np.ndarray | None = None
+
+        logger.info("DatasetSimSource: loading %s episode %d …", repo_id, episode)
+        try:
+            self._frames, self._source_fps = self._load_episode(repo_id, episode)
+            if strict and (
+                not self._frames or any("action" not in frame for frame in self._frames)
+            ):
+                raise ValueError(
+                    "Dataset hardware replay requires a non-empty episode with an action per frame"
+                )
+            if self._frames:
+                self._n_joints = len(self._frames[0]["joint_positions"])
+            logger.info(
+                "DatasetSimSource: ready — %d frames, %d joints, source_fps: %.1f, cameras: %s",
+                len(self._frames),
+                self._n_joints,
+                self._source_fps,
+                sorted({k for f in self._frames[:1] for k in (f.get("images") or {})}),
+            )
+        except Exception:
+            if strict:
+                raise
+            logger.exception(
+                "DatasetSimSource: failed to load %s — falling back to random walk",
+                repo_id,
+            )
+            self._frames = []
+            self._source_fps = hz
+
+    # ── Public API ─────────────────────────────────────────────────────────
+
+    def connect(self) -> None:
+        """Reset playback state on fresh connection/task start."""
+        self._cursor = 0.0
+        self._current_frame = None
+        self._prev_pos = None
+        logger.info("DatasetSimSource: playback cursor reset")
+
+    def disconnect(self) -> None:
+        """No-op for simulation."""
+        pass
+
+    def read(self) -> Observation:
+        if not self._frames:
+            return self._random_obs()
+
+        # Step-driven: advance cursor by (source_fps / runtime_hz) frames per call.
+        # This keeps replay pace proportional to the control loop rate regardless
+        # of wall-clock jitter, GC pauses, or guard latency spikes.
+        index = int(self._cursor)
+        frame = self._frames[index % len(self._frames)]
+        self._current_frame = frame
+        self._cursor += self._source_fps / self._hz
+
+        joint_pos: np.ndarray = frame["joint_positions"]
+
+        if self._degrees_mode:
+            joint_pos = joint_pos * (np.pi / 180.0)
+
+        # Velocity: dt is the real time between control cycles (1/runtime_hz),
+        # which is the interval between successive commands sent to the robot.
+        if self._prev_pos is not None:
+            dt = 1.0 / self._hz
+            velocity = (joint_pos - self._prev_pos) / dt
+        else:
+            velocity = np.zeros_like(joint_pos)
+        self._prev_pos = joint_pos
+
+        return Observation(
+            timestamp=time.monotonic(),
+            joint_positions=joint_pos.copy(),
+            joint_velocities=velocity,
+            images=frame.get("images"),
+        )
+
+    def current_action(self) -> np.ndarray:
+        """Return the recorded action paired with the most recently read observation."""
+        if self._current_frame is None:
+            raise RuntimeError("DatasetReplayPolicy called before the dataset source was read")
+        action = self._current_frame.get("action")
+        if action is None:
+            raise RuntimeError(
+                "Dataset has no 'action' field; hardware replay requires recorded actions"
+            )
+        action_arr = np.asarray(action, dtype=float)
+        if self._degrees_mode:
+            action_arr = action_arr * (np.pi / 180.0)
+        return action_arr.copy()
+
+    # ── Dataset loading ────────────────────────────────────────────────────
+
+    def _load_episode(self, repo_id: str, episode: int) -> tuple[list[dict[str, Any]], float]:
+        """Download + decode one episode.  Returns (frames, fps)."""
+        try:
+            from lerobot.datasets.lerobot_dataset import LeRobotDataset
+        except ImportError as exc:
+            raise ImportError(
+                "lerobot is required for DatasetSimSource. Install it with: make setup-lerobot"
+            ) from exc
+
+        import torch
+        from torch.utils.data import DataLoader
+
+        ds = LeRobotDataset(repo_id, episodes=[episode])
+        frames: list[dict[str, Any]] = []
+
+        # num_workers=0: single-process iteration — prevents leaked semaphore
+        # warnings from torch multiprocessing workers at shutdown.
+        # pin_memory=False: avoids CUDA page-locked memory on CPU-only setups.
+        loader = DataLoader(ds, batch_size=1, num_workers=0, pin_memory=False)
+
+        for batch in loader:
+            # DataLoader wraps each value in a batch dimension — squeeze it back
+            item = {k: (v[0] if isinstance(v, torch.Tensor) else v) for k, v in batch.items()}
+            frame: dict[str, Any] = {}
+
+            # ── Joint positions ────────────────────────────────────────
+            state = item.get("observation.state")
+            if state is None:
+                # Some datasets use different key names
+                state = item.get("state") or item.get("joints")
+            if state is not None:
+                if isinstance(state, torch.Tensor):
+                    state = state.detach().cpu().numpy()
+                frame["joint_positions"] = np.asarray(state, dtype=float)
+            else:
+                frame["joint_positions"] = np.zeros(self._n_joints)
+
+            # ── Camera images ──────────────────────────────────────────
+            images: dict[str, np.ndarray] = {}
+            for key, val in item.items():
+                if not key.startswith("observation.images."):
+                    continue
+                cam = key.split(".", 2)[2]  # e.g. "top" or "wrist"
+                if isinstance(val, torch.Tensor):
+                    # CHW float32 [0,1] → HWC uint8 [0,255]
+                    t = val.detach().cpu()
+                    if t.ndim == 3 and t.shape[0] in (1, 3, 4):
+                        t = t.permute(1, 2, 0)
+                    arr: np.ndarray[tuple[int, ...], np.dtype[np.uint8]] = (
+                        (t.numpy() * 255).clip(0, 255).astype(np.uint8)
+                    )
+                else:
+                    arr = np.asarray(val, dtype=np.uint8)
+                if arr.ndim == 2:
+                    arr = arr[:, :, np.newaxis]
+                images[cam] = arr
+
+            if images:
+                frame["images"] = images
+
+            action = item.get("action")
+            if action is not None:
+                if isinstance(action, torch.Tensor):
+                    action = action.detach().cpu().numpy()
+                frame["action"] = np.asarray(action, dtype=float)
+
+            frames.append(frame)
+
+        # Explicitly delete the loader so Python can clean up its internal
+        # shared-memory / semaphore state before the resource_tracker runs.
+        del loader
+
+        return frames, float(getattr(ds, "fps", 30.0))
+
+    # ── Fallback ───────────────────────────────────────────────────────────
+
+    def _random_obs(self) -> Observation:
+        """Random-walk fallback when dataset loading fails."""
+        if not hasattr(self, "_rng"):
+            self._rng = np.random.default_rng(42)
+            self._rng_pos = self._rng.uniform(-0.3, 0.3, size=self._n_joints)
+        delta = self._rng.normal(0.0, 0.03, size=self._n_joints)
+        self._rng_pos = np.clip(self._rng_pos + delta, -1.9, 1.9)
+        return Observation(
+            timestamp=time.monotonic(),
+            joint_positions=self._rng_pos.copy(),
+        )
+
+
+class DatasetReplayPolicy(PolicyAdapter):
+    """Emit the action recorded alongside the source's current dataset frame."""
+
+    def __init__(self, source: DatasetSimSource) -> None:
+        self._source = source
+
+    def initialize(self, config: dict[str, Any]) -> None:
+        pass
+
+    def predict(self, obs: Observation) -> ActionProposal:
+        return ActionProposal(
+            target_joint_positions=self._source.current_action(),
+            timestamp=obs.timestamp,
+            policy_name="dataset_replay",
+        )
+
+    def get_policy_name(self) -> str:
+        return "dataset_replay"
+
+    def reset(self) -> None:
+        pass

dam/adapter/isaac/__init__.py

@@ -0,0 +1,21 @@
+"""Isaac Sim 6.0 adapter — bridges DAM safety pipeline with NVIDIA Isaac Sim.
+
+Usage (minimal):
+
+    from dam.adapter.isaac import IsaacSafetyFilter
+
+    filter = IsaacSafetyFilter("safety.yaml", task="manipulation")
+    # In your Isaac Sim step loop:
+    safe_action = filter(action_tensor, obs_tensor)
+
+Usage (full runner with MCAP logging):
+
+    import dam
+    runner = dam.build_runner("franka_isaac.yaml")
+    runner.connect()
+    runner.start(task="pick_place")
+"""
+
+from dam.adapter.isaac.filter import IsaacSafetyFilter
+
+__all__ = ["IsaacSafetyFilter"]