roboscope-kit 0.8.0b1__py3-none-any.whl

roboscope_kit/__init__.py

@@ -0,0 +1,67 @@
+# Copyright 2026 RoboScope Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""RoboScope SDK for adapting custom inference code to official simulation."""
+
+from roboscope_kit.benchmark_specs import (
+    ActionSpec,
+    BenchmarkName,
+    BenchmarkSpec,
+    FeatureKind,
+    FeatureSpec,
+    benchmark_names,
+    get_benchmark_spec,
+)
+from roboscope_kit.client import PolicyClient, PolicyRemoteError
+from roboscope_kit.policy import (
+    ActionChunk,
+    EpisodeContext,
+    Observation,
+    Policy,
+    PolicyCapabilities,
+    PolicyExecutionContract,
+    SessionContext,
+    negotiate_policy_action_contract,
+    validate_action_chunk,
+    validate_observation,
+    validate_policy_capabilities,
+)
+from roboscope_kit.policy_config import (
+    POLICY_CONFIG_PATH,
+    POLICY_CONFIG_SCHEMA_VERSION,
+    PolicyConfigError,
+    PolicyRuntimeConfig,
+    load_policy_runtime_config,
+)
+from roboscope_kit.server import PolicyServer, PolicyState, run
+
+__all__ = [
+    "ActionChunk",
+    "ActionSpec",
+    "BenchmarkName",
+    "BenchmarkSpec",
+    "EpisodeContext",
+    "FeatureKind",
+    "FeatureSpec",
+    "Observation",
+    "Policy",
+    "POLICY_CONFIG_PATH",
+    "POLICY_CONFIG_SCHEMA_VERSION",
+    "PolicyConfigError",
+    "PolicyRuntimeConfig",
+    "PolicyCapabilities",
+    "PolicyExecutionContract",
+    "PolicyClient",
+    "PolicyRemoteError",
+    "PolicyServer",
+    "PolicyState",
+    "SessionContext",
+    "benchmark_names",
+    "get_benchmark_spec",
+    "load_policy_runtime_config",
+    "negotiate_policy_action_contract",
+    "run",
+    "validate_action_chunk",
+    "validate_observation",
+    "validate_policy_capabilities",
+]

roboscope_kit/benchmark_specs.py

@@ -0,0 +1,268 @@
+# Copyright 2026 RoboScope Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Built-in benchmark contracts exposed to user policy implementations."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+
+from roboscope_kit.contracts import ActionSpec, BenchmarkSpec, FeatureKind, FeatureSpec
+
+
+class BenchmarkName(str, Enum):  # noqa: UP042 -- benchmark images include Python 3.10
+    LIBERO = "libero"
+    LIBERO_PLUS = "libero_plus"
+    ROBOCASA = "robocasa"
+    ROBOTWIN = "robotwin"
+    CALVIN = "calvin"
+    METAWORLD = "metaworld"
+
+
+class BenchmarkDefinition(ABC):
+    """Internal provider for one platform-owned benchmark specification."""
+
+    name: BenchmarkName
+    protocol_version: str
+    supported_action_representations: tuple[str, ...]
+    default_action_representation: str
+
+    @abstractmethod
+    def features(self, suite: str) -> tuple[FeatureSpec, ...]: ...
+
+    @abstractmethod
+    def action(self, suite: str) -> ActionSpec: ...
+
+    def spec(self, suite: str) -> BenchmarkSpec:
+        if not suite:
+            raise ValueError("benchmark suite cannot be empty")
+        return BenchmarkSpec(
+            name=self.name.value,
+            suite=suite,
+            protocol_version=self.protocol_version,
+            features=self.features(suite),
+            action=self.action(suite),
+            supported_action_representations=self.supported_action_representations,
+            default_action_representation=self.default_action_representation,
+        )
+
+
+def _feature(
+    name: str,
+    kind: FeatureKind,
+    description: str,
+    *,
+    required: bool = True,
+    shape: tuple[int | None, ...] | None = None,
+) -> FeatureSpec:
+    dtype = {
+        FeatureKind.IMAGE: "uint8",
+        FeatureKind.STATE: "float32",
+        FeatureKind.LANGUAGE: "string",
+    }[kind]
+    return FeatureSpec(
+        name=name,
+        kind=kind,
+        description=description,
+        required=required,
+        dtype=dtype,
+        shape=shape,
+    )
+
+
+class LiberoBenchmarkDefinition(BenchmarkDefinition):
+    name = BenchmarkName.LIBERO
+    protocol_version = "libero-v1"
+    supported_action_representations = ("libero.delta-eef-v1",)
+    default_action_representation = "libero.delta-eef-v1"
+
+    def features(self, _suite: str) -> tuple[FeatureSpec, ...]:
+        return (
+            _feature(
+                "images.primary",
+                FeatureKind.IMAGE,
+                "Agent-view RGB image.",
+                shape=(256, 256, 3),
+            ),
+            _feature(
+                "images.wrist",
+                FeatureKind.IMAGE,
+                "Robot wrist RGB image.",
+                shape=(256, 256, 3),
+            ),
+            _feature(
+                "state.proprioception",
+                FeatureKind.STATE,
+                "EEF position/quaternion, gripper position, and seven joint positions.",
+                shape=(16,),
+            ),
+            _feature("language.instruction", FeatureKind.LANGUAGE, "Task instruction."),
+        )
+
+    def action(self, _suite: str) -> ActionSpec:
+        return ActionSpec("action.robot", "LIBERO 6-DoF end-effector delta and gripper command.", 7)
+
+
+class LiberoPlusBenchmarkDefinition(LiberoBenchmarkDefinition):
+    name = BenchmarkName.LIBERO_PLUS
+    protocol_version = "libero-plus-v1"
+
+
+class RoboCasaBenchmarkDefinition(BenchmarkDefinition):
+    name = BenchmarkName.ROBOCASA
+    protocol_version = "robocasa-v1"
+    supported_action_representations = ("robocasa.gr1-joint-v1",)
+    default_action_representation = "robocasa.gr1-joint-v1"
+
+    def features(self, _suite: str) -> tuple[FeatureSpec, ...]:
+        return (
+            _feature("images.primary", FeatureKind.IMAGE, "Primary workspace RGB image."),
+            _feature("images.wrist", FeatureKind.IMAGE, "Robot wrist RGB image.", required=False),
+            _feature("state.proprioception", FeatureKind.STATE, "RoboCasa embodiment state vector."),
+            _feature("language.instruction", FeatureKind.LANGUAGE, "Task instruction."),
+        )
+
+    def action(self, _suite: str) -> ActionSpec:
+        return ActionSpec("action.robot", "RoboCasa GR1 arms, hands, and waist action vector.", 29)
+
+
+class RoboTwinBenchmarkDefinition(BenchmarkDefinition):
+    name = BenchmarkName.ROBOTWIN
+    protocol_version = "robotwin2-v1"
+    supported_action_representations = (
+        "robotwin.qpos-v1",
+        "robotwin.ee-compact-quat-v1",
+    )
+    default_action_representation = "robotwin.qpos-v1"
+
+    def features(self, _suite: str) -> tuple[FeatureSpec, ...]:
+        return (
+            _feature("images.head", FeatureKind.IMAGE, "Head-camera RGB image."),
+            _feature("images.left_wrist", FeatureKind.IMAGE, "Left wrist RGB image."),
+            _feature("images.right_wrist", FeatureKind.IMAGE, "Right wrist RGB image."),
+            _feature("state.joints", FeatureKind.STATE, "Dual-arm joint and gripper state."),
+            _feature("language.instruction", FeatureKind.LANGUAGE, "Task instruction."),
+        )
+
+    def action(self, _suite: str) -> ActionSpec:
+        return ActionSpec("action.robot", "Absolute dual-arm joint and gripper target.", 14)
+
+
+class CalvinBenchmarkDefinition(BenchmarkDefinition):
+    name = BenchmarkName.CALVIN
+    protocol_version = "calvin-v1"
+    supported_action_representations = (
+        "calvin.relative-v1",
+        "calvin.absolute-compact-quat-v1",
+    )
+    default_action_representation = "calvin.relative-v1"
+
+    def features(self, _suite: str) -> tuple[FeatureSpec, ...]:
+        return (
+            _feature("images.static", FeatureKind.IMAGE, "Static scene RGB image."),
+            _feature("images.gripper", FeatureKind.IMAGE, "Gripper RGB image."),
+            _feature("state.proprioception", FeatureKind.STATE, "CALVIN robot state vector."),
+            _feature("language.instruction", FeatureKind.LANGUAGE, "Task instruction."),
+        )
+
+    def action(self, _suite: str) -> ActionSpec:
+        return ActionSpec("action.robot", "CALVIN relative end-effector and gripper action.", 7)
+
+
+METAWORLD_DEFAULT_CAMERA = {
+    "feature": "images.primary",
+    "camera_name": "corner2",
+    "render_width": 480,
+    "render_height": 480,
+    "camera_position": None,
+    "rotation_deg": 180,
+    "center_crop_ratio": 1.0,
+    "output_width": 480,
+    "output_height": 480,
+}
+
+
+class MetaworldBenchmarkDefinition(BenchmarkDefinition):
+    name = BenchmarkName.METAWORLD
+    protocol_version = "metaworld-v1"
+    supported_action_representations = ("metaworld.delta-eef-v1",)
+    default_action_representation = "metaworld.delta-eef-v1"
+
+    def features(self, _suite: str, cameras: tuple[dict, ...] | None = None) -> tuple[FeatureSpec, ...]:
+        resolved = (METAWORLD_DEFAULT_CAMERA,) if cameras is None else cameras
+        features = [str(camera["feature"]) for camera in resolved]
+        if not features or len(set(features)) != len(features):
+            raise ValueError("metaworld camera features must be unique and non-empty")
+        image_features = tuple(
+            _feature(
+                feature,
+                FeatureKind.IMAGE,
+                f"MetaWorld RGB image from camera {camera['camera_name']!r}.",
+                shape=(int(camera["output_height"]), int(camera["output_width"]), 3),
+            )
+            for feature, camera in zip(features, resolved, strict=True)
+        )
+        return (
+            *image_features,
+            _feature(
+                "state.proprioception",
+                FeatureKind.STATE,
+                "End-effector xyz position and normalized gripper aperture (raw observation[:4]).",
+                shape=(4,),
+            ),
+            _feature("language.instruction", FeatureKind.LANGUAGE, "Official MetaWorld task instruction."),
+        )
+
+    def action(self, _suite: str) -> ActionSpec:
+        return ActionSpec(
+            "action.robot",
+            "MetaWorld delta end-effector position (dx, dy, dz) and gripper command in [-1, 1].",
+            4,
+        )
+
+    def spec(self, suite: str, cameras: tuple[dict, ...] | None = None) -> BenchmarkSpec:
+        if not suite:
+            raise ValueError("benchmark suite cannot be empty")
+        return BenchmarkSpec(
+            name=self.name.value,
+            suite=suite,
+            protocol_version=self.protocol_version,
+            features=self.features(suite, cameras),
+            action=self.action(suite),
+            supported_action_representations=self.supported_action_representations,
+            default_action_representation=self.default_action_representation,
+        )
+
+
+_DEFINITIONS: dict[BenchmarkName, BenchmarkDefinition] = {
+    definition.name: definition
+    for definition in (
+        LiberoBenchmarkDefinition(),
+        LiberoPlusBenchmarkDefinition(),
+        RoboCasaBenchmarkDefinition(),
+        RoboTwinBenchmarkDefinition(),
+        CalvinBenchmarkDefinition(),
+        MetaworldBenchmarkDefinition(),
+    )
+}
+
+
+def get_benchmark_spec(name: str | BenchmarkName, suite: str) -> BenchmarkSpec:
+    benchmark = BenchmarkName(name)
+    return _DEFINITIONS[benchmark].spec(suite)
+
+
+def benchmark_names() -> tuple[str, ...]:
+    return tuple(benchmark.value for benchmark in _DEFINITIONS)
+
+
+__all__ = [
+    "ActionSpec",
+    "BenchmarkName",
+    "BenchmarkSpec",
+    "FeatureKind",
+    "FeatureSpec",
+    "benchmark_names",
+    "get_benchmark_spec",
+]

roboscope_kit/client.py

@@ -0,0 +1,133 @@
+# Copyright 2026 RoboScope Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Client used by the simulation runtime to call a custom policy process."""
+
+from __future__ import annotations
+
+import socket
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from roboscope_kit.policy import (
+    ActionChunk,
+    EpisodeContext,
+    Observation,
+    PolicyCapabilities,
+    SessionContext,
+)
+from roboscope_kit.protocol import (
+    PROTOCOL_VERSION,
+    ProtocolError,
+    receive_message,
+    send_message,
+    validate_version,
+)
+
+
+class PolicyRemoteError(RuntimeError):
+    def __init__(self, error: dict[str, Any]) -> None:
+        self.operation = str(error.get("operation") or "unknown")
+        self.error_type = str(error.get("type") or "RemoteError")
+        self.remote_message = str(error.get("message") or "")
+        self.remote_traceback = str(error.get("traceback") or "")
+        self.state = str(error.get("state") or "")
+        super().__init__(f"policy {self.operation} failed ({self.error_type}): {self.remote_message}")
+
+
+class PolicyClient:
+    def __init__(self, socket_path: str | Path, timeout_s: float = 30.0) -> None:
+        self.socket_path = str(socket_path)
+        self.timeout_s = timeout_s
+        self._connection: socket.socket | None = None
+
+    def connect(self) -> None:
+        if self._connection is not None:
+            return
+        connection = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        connection.settimeout(self.timeout_s)
+        connection.connect(self.socket_path)
+        self._connection = connection
+
+    def wait_until_ready(self, timeout_s: float) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout_s
+        last_error: OSError | None = None
+        while time.monotonic() < deadline:
+            try:
+                self.connect()
+                return self.health()
+            except OSError as exc:
+                last_error = exc
+                self.close()
+                time.sleep(0.05)
+        raise TimeoutError(
+            f"policy socket {self.socket_path} was not ready within {timeout_s}s"
+        ) from last_error
+
+    def health(self) -> dict[str, Any]:
+        return self._request("health", {})
+
+    def load(self, context: SessionContext) -> PolicyCapabilities:
+        result = self._request("load", {"context": context.to_dict()})
+        return PolicyCapabilities.from_dict(result["capabilities"])
+
+    def reset(self, context: EpisodeContext) -> dict[str, Any]:
+        return self._request("reset", {"context": context.to_dict()})
+
+    def act(self, observation: Observation) -> ActionChunk:
+        result = self._request("act", {"observation": observation.to_dict()})
+        return ActionChunk.from_dict(result["action_chunk"])
+
+    def act_batch(self, observations: tuple[Observation, ...]) -> tuple[ActionChunk, ...]:
+        result = self._request(
+            "act_batch",
+            {"observations": [observation.to_dict() for observation in observations]},
+        )
+        return tuple(ActionChunk.from_dict(item) for item in result["action_chunks"])
+
+    def end_episode(self, episode_id: str) -> dict[str, Any]:
+        if not episode_id:
+            raise ValueError("episode_id cannot be empty")
+        return self._request("end_episode", {"episode_id": episode_id})
+
+    def unload(self) -> dict[str, Any]:
+        return self._request("unload", {})
+
+    def close(self) -> None:
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def __enter__(self) -> PolicyClient:
+        self.connect()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(self, operation: str, payload: dict[str, Any]) -> Any:
+        if self._connection is None:
+            self.connect()
+        if self._connection is None:
+            raise RuntimeError("policy connection is unavailable")
+        request_id = str(uuid.uuid4())
+        send_message(
+            self._connection,
+            {
+                "version": PROTOCOL_VERSION,
+                "request_id": request_id,
+                "operation": operation,
+                "payload": payload,
+            },
+        )
+        response = receive_message(self._connection)
+        if response is None:
+            raise ProtocolError("policy server closed the connection without a response")
+        validate_version(response)
+        if response.get("request_id") != request_id:
+            raise ProtocolError("response request_id does not match request")
+        if not response.get("ok"):
+            raise PolicyRemoteError(response.get("error") or {})
+        return response.get("result")

roboscope_kit/contracts.py

@@ -0,0 +1,176 @@
+# Copyright 2026 RoboScope Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Benchmark-neutral data contracts shared by Policy clients and servers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class FeatureKind(str, Enum):  # noqa: UP042 -- benchmark images include Python 3.10
+    IMAGE = "image"
+    STATE = "state"
+    LANGUAGE = "language"
+
+
+@dataclass(frozen=True)
+class FeatureSpec:
+    name: str
+    kind: FeatureKind
+    required: bool = True
+    description: str = ""
+    dtype: str | None = None
+    shape: tuple[int | None, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("feature name cannot be empty")
+        if self.dtype == "":
+            raise ValueError("feature dtype cannot be empty")
+        if self.shape is not None and any(
+            dimension is not None and dimension < 1 for dimension in self.shape
+        ):
+            raise ValueError("feature dimensions must be positive or dynamic")
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> FeatureSpec:
+        return cls(
+            name=str(value["name"]),
+            kind=FeatureKind(value["kind"]),
+            required=bool(value.get("required", True)),
+            description=str(value.get("description", "")),
+            dtype=str(value["dtype"]) if value.get("dtype") is not None else None,
+            shape=(
+                tuple(int(dimension) if dimension is not None else None for dimension in value["shape"])
+                if value.get("shape") is not None
+                else None
+            ),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "kind": self.kind.value,
+            "required": self.required,
+            "description": self.description,
+            "dtype": self.dtype,
+            "shape": list(self.shape) if self.shape is not None else None,
+        }
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    name: str
+    description: str
+    dimension: int | None = None
+    dtype: str = "float32"
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("action name cannot be empty")
+        if not self.dtype:
+            raise ValueError("action dtype cannot be empty")
+        if self.dimension is not None and self.dimension < 1:
+            raise ValueError("action dimension must be positive")
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> ActionSpec:
+        dimension = value.get("dimension")
+        return cls(
+            name=str(value["name"]),
+            description=str(value["description"]),
+            dimension=int(dimension) if dimension is not None else None,
+            dtype=str(value.get("dtype", "float32")),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "dimension": self.dimension,
+            "dtype": self.dtype,
+        }
+
+
+@dataclass(frozen=True)
+class BenchmarkSpec:
+    name: str
+    suite: str
+    protocol_version: str
+    features: tuple[FeatureSpec, ...]
+    action: ActionSpec
+    supported_action_representations: tuple[str, ...] = ()
+    default_action_representation: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("benchmark name cannot be empty")
+        if not self.suite:
+            raise ValueError("benchmark suite cannot be empty")
+        if not self.protocol_version:
+            raise ValueError("benchmark protocol version cannot be empty")
+        if not self.features:
+            raise ValueError("benchmark features cannot be empty")
+        names = [feature.name for feature in self.features]
+        if len(names) != len(set(names)):
+            raise ValueError("benchmark feature names must be unique")
+        if not self.supported_action_representations:
+            raise ValueError("benchmark action representations cannot be empty")
+        if len(self.supported_action_representations) != len(
+            set(self.supported_action_representations)
+        ):
+            raise ValueError("benchmark action representations must be unique")
+        if self.default_action_representation not in self.supported_action_representations:
+            raise ValueError("benchmark default action representation must be supported")
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> BenchmarkSpec:
+        representations = tuple(
+            str(item) for item in value.get("supported_action_representations", ())
+        )
+        default_representation = str(value.get("default_action_representation", ""))
+        if not representations:
+            default_representation = _legacy_action_representation(str(value["name"]))
+            representations = (default_representation,)
+        return cls(
+            name=str(value["name"]),
+            suite=str(value["suite"]),
+            protocol_version=str(value["protocol_version"]),
+            features=tuple(FeatureSpec.from_dict(item) for item in value["features"]),
+            action=ActionSpec.from_dict(value["action"]),
+            supported_action_representations=representations,
+            default_action_representation=default_representation,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "suite": self.suite,
+            "protocol_version": self.protocol_version,
+            "features": [feature.to_dict() for feature in self.features],
+            "action": self.action.to_dict(),
+            "supported_action_representations": list(self.supported_action_representations),
+            "default_action_representation": self.default_action_representation,
+        }
+
+
+def _legacy_action_representation(benchmark: str) -> str:
+    defaults = {
+        "libero": "libero.delta-eef-v1",
+        "libero_plus": "libero.delta-eef-v1",
+        "robocasa": "robocasa.gr1-joint-v1",
+        "robotwin": "robotwin.qpos-v1",
+        "calvin": "calvin.relative-v1",
+    }
+    try:
+        return defaults[benchmark]
+    except KeyError as exc:
+        raise ValueError(
+            f"legacy benchmark payload {benchmark!r} has no action representation default"
+        ) from exc
+
+
+__all__ = ["ActionSpec", "BenchmarkSpec", "FeatureKind", "FeatureSpec"]