lekit-robot 0.1.0__py3-none-any.whl

lekit_robot/__init__.py

@@ -0,0 +1,44 @@
+"""Public local and remote Robot interfaces."""
+
+from .observation import CameraObservation, Observation, ObservationStatus, RobotObservation
+from .remote import (
+    ActionMode,
+    ActionOutcomeUnknownError,
+    ActionReceipt,
+    ActionRejectedError,
+    AmbiguousRobotNameError,
+    ControlBusyError,
+    InvalidTargetError,
+    RemoteRobot,
+    RobotClientError,
+    RobotDescriptor,
+    RobotDisconnectedError,
+    RobotIdentityConflictError,
+    RobotNotFoundError,
+    TransportUnavailableError,
+    UnsupportedCommandError,
+    connect,
+)
+
+__all__ = [
+    "ActionMode",
+    "ActionOutcomeUnknownError",
+    "ActionReceipt",
+    "ActionRejectedError",
+    "AmbiguousRobotNameError",
+    "CameraObservation",
+    "ControlBusyError",
+    "InvalidTargetError",
+    "Observation",
+    "ObservationStatus",
+    "RemoteRobot",
+    "RobotClientError",
+    "RobotDescriptor",
+    "RobotDisconnectedError",
+    "RobotIdentityConflictError",
+    "RobotNotFoundError",
+    "RobotObservation",
+    "TransportUnavailableError",
+    "UnsupportedCommandError",
+    "connect",
+]

lekit_robot/observation.py

@@ -0,0 +1,90 @@
+"""Public observation models shared by local and remote Robot interfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+from numpy.typing import NDArray
+
+ObservationStatus = Literal[
+    "connected",
+    "unavailable",
+    "opening",
+    "warming_up",
+    "reconfiguring",
+    "stale",
+    "failed",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RobotObservation:
+    """One best-effort sample from the active Robot generation."""
+
+    status: ObservationStatus
+    state: dict[str, object] | None
+    captured_at: datetime | None
+    error: str | None = None
+    generation: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class CameraObservation:
+    """One latest Camera sample, or an explicit unavailable state."""
+
+    status: ObservationStatus
+    image: NDArray | None
+    captured_at: datetime | None
+    fps: int = 0
+    error: str | None = None
+    camera_id: str | None = None
+    name: str | None = None
+    generation: int = 0
+    frame_sequence: int = 0
+    depth: NDArray | None = None
+
+    @property
+    def color(self) -> NDArray | None:
+        """Return the color image using the public stream-oriented name."""
+        return self.image
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    """A versioned Robot state and keyed set of independent Camera samples."""
+
+    observed_at: datetime
+    robot: RobotObservation
+    cameras: Mapping[str, CameraObservation]
+    node_instance_id: str = ""
+    config_revision: int = 0
+    robot_id: str = ""
+    robot_name: str = ""
+
+    def camera(
+        self,
+        identifier: str | None = None,
+        *,
+        name: str | None = None,
+    ) -> CameraObservation:
+        """Find one Camera by mapping key, stable ID, or current name."""
+        if (identifier is None) == (name is None):
+            raise TypeError("Provide exactly one camera identifier or name")
+        requested = identifier if identifier is not None else name
+        assert requested is not None
+        direct = self.cameras.get(requested)
+        if direct is not None:
+            return direct
+        matches = [
+            camera
+            for camera in self.cameras.values()
+            if camera.camera_id == requested or camera.name == requested
+        ]
+        if not matches:
+            raise KeyError(f"Camera {requested!r} is not present in this observation")
+        if len(matches) > 1:
+            raise KeyError(f"Camera name {requested!r} is ambiguous")
+        return matches[0]

lekit_robot/protocol.py

@@ -0,0 +1,254 @@
+"""Versioned wire contract shared by Robot transport Adapters.
+
+This Module deliberately has no Zenoh imports.  It owns names, keys, schemas,
+and JSON encoding so transport details cannot leak into Robot Runtime code.
+"""
+
+from __future__ import annotations
+
+import math
+import unicodedata
+from typing import Literal, Self
+from urllib.parse import quote
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+PROTOCOL_MAJOR = 1
+PROTOCOL_ROOT = "lekit/v1"
+
+
+class ProtocolModel(BaseModel):
+    """Strict base for all v1 JSON payloads."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class FieldManifest(ProtocolModel):
+    key: str
+    label: str
+    minimum: float
+    maximum: float
+    step: float
+    unit: str | None = None
+
+
+class CommandManifest(ProtocolModel):
+    fields: list[FieldManifest] = Field(default_factory=list)
+    modes: list[Literal["stream", "point", "linear"]] = Field(default_factory=list)
+
+
+class CameraManifest(ProtocolModel):
+    camera_id: str
+    name: str
+    generation: int = Field(ge=0)
+    status: str
+    streams: list[Literal["color", "depth"]] = Field(default_factory=list)
+
+
+class RobotManifest(ProtocolModel):
+    schema_name: Literal["lekit.robot.manifest.v1"] = "lekit.robot.manifest.v1"
+    protocol_major: Literal[1] = 1
+    robot_id: str
+    robot_name: str
+    node_instance_id: str
+    config_revision: int = Field(ge=0)
+    robot_generation: int = Field(ge=0)
+    robot_status: str
+    joint_target: CommandManifest | None = None
+    eef_target: CommandManifest | None = None
+    gripper_target: CommandManifest | None = None
+    cameras: list[CameraManifest] = Field(default_factory=list)
+
+
+class RobotSample(ProtocolModel):
+    status: str
+    state: dict[str, object] | None = None
+    captured_at: str | None = None
+    error: str | None = None
+    generation: int = Field(ge=0)
+
+
+class CameraSampleMetadata(ProtocolModel):
+    status: str
+    captured_at: str | None = None
+    fps: int = Field(default=0, ge=0)
+    error: str | None = None
+    camera_id: str
+    name: str
+    generation: int = Field(ge=0)
+    frame_sequence: int = Field(ge=0)
+    has_color: bool = False
+    has_depth: bool = False
+
+
+class ObservationMetadata(ProtocolModel):
+    schema_name: Literal["lekit.robot.observation.v1"] = "lekit.robot.observation.v1"
+    robot_id: str
+    robot_name: str
+    node_instance_id: str
+    config_revision: int = Field(ge=0)
+    observed_at: str
+    robot: RobotSample
+    cameras: dict[str, CameraSampleMetadata] = Field(default_factory=dict)
+
+
+class FrameMetadata(ProtocolModel):
+    schema_name: Literal["lekit.robot.frame.v1"] = "lekit.robot.frame.v1"
+    camera_id: str
+    name: str
+    stream: Literal["color", "depth"]
+    generation: int = Field(ge=0)
+    frame_sequence: int = Field(ge=0)
+    captured_at: str | None = None
+    pixel_format: str
+
+
+class LeaseRequest(ProtocolModel):
+    schema_name: Literal["lekit.robot.lease-request.v1"] = "lekit.robot.lease-request.v1"
+    operation: Literal["acquire", "renew", "release"]
+    controller_session_id: str
+    lease_id: str | None = None
+    fencing_token: int | None = Field(default=None, ge=1)
+
+
+class LeaseReceipt(ProtocolModel):
+    schema_name: Literal["lekit.robot.lease-receipt.v1"] = "lekit.robot.lease-receipt.v1"
+    accepted: bool
+    code: str
+    lease_id: str | None = None
+    fencing_token: int | None = Field(default=None, ge=1)
+    ttl_ms: int = Field(default=0, ge=0)
+    message: str | None = None
+
+
+class ActionRequest(ProtocolModel):
+    schema_name: Literal["lekit.robot.action-request.v1"] = "lekit.robot.action-request.v1"
+    request_id: str
+    controller_session_id: str
+    client_sequence: int = Field(ge=1)
+    lease_id: str
+    fencing_token: int = Field(ge=1)
+    robot_id: str
+    node_instance_id: str
+    expected_robot_generation: int = Field(ge=0)
+    sent_at_unix_ns: int = Field(gt=0)
+    max_age_ms: int = Field(default=1000, ge=1, le=60_000)
+    kind: Literal["joint_target", "eef_target", "gripper_target"]
+    mode: Literal["stream", "point", "linear"] | None = None
+    values: dict[str, float]
+
+    @model_validator(mode="after")
+    def values_are_finite(self) -> Self:
+        if not self.values or any(not math.isfinite(value) for value in self.values.values()):
+            raise ValueError("Action values must be non-empty finite numbers")
+        if self.kind == "eef_target" and self.mode is None:
+            raise ValueError("EEF targets require a mode")
+        if self.kind != "eef_target" and self.mode is not None:
+            raise ValueError("Joint and gripper targets do not accept a mode")
+        return self
+
+
+class ActionReceiptPayload(ProtocolModel):
+    schema_name: Literal["lekit.robot.action-receipt.v1"] = "lekit.robot.action-receipt.v1"
+    request_id: str
+    status: Literal["accepted", "duplicate", "rejected"]
+    code: str
+    robot_generation: int = Field(ge=0)
+    accepted_at_unix_ns: int | None = None
+    applied_values: dict[str, float] | None = None
+    message: str | None = None
+
+
+def normalize_robot_name(name: str) -> str:
+    """Normalize a display name for exact, case-insensitive discovery."""
+    normalized = unicodedata.normalize("NFKC", name).strip()
+    if not normalized:
+        raise ValueError("Robot name must not be empty")
+    if len(normalized.encode("utf-8")) > 64:
+        raise ValueError("Robot name must be at most 64 UTF-8 bytes")
+    return normalized.casefold()
+
+
+def key_chunk(value: str) -> str:
+    """Encode one opaque identifier as a single safe Zenoh key chunk."""
+    normalized = unicodedata.normalize("NFKC", value).strip()
+    if not normalized:
+        raise ValueError("Key value must not be empty")
+    return quote(normalized, safe="abcdefghijklmnopqrstuvwxyz0123456789_.-")
+
+
+def name_key(name: str) -> str:
+    return key_chunk(normalize_robot_name(name))
+
+
+def live_robot_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{PROTOCOL_ROOT}/live/robots/{key_chunk(robot_id)}/{key_chunk(node_instance_id)}"
+
+
+def live_name_key(robot_name: str, robot_id: str, node_instance_id: str) -> str:
+    return f"{PROTOCOL_ROOT}/live/names/{name_key(robot_name)}/{key_chunk(robot_id)}/{key_chunk(node_instance_id)}"
+
+
+def live_name_selector(robot_name: str) -> str:
+    return f"{PROTOCOL_ROOT}/live/names/{name_key(robot_name)}/*/*"
+
+
+def robot_root(robot_id: str, node_instance_id: str) -> str:
+    return f"{PROTOCOL_ROOT}/robots/{key_chunk(robot_id)}/{key_chunk(node_instance_id)}"
+
+
+def manifest_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/manifest"
+
+
+def observation_selector(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/observations/current/**"
+
+
+def observation_meta_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/observations/current/meta"
+
+
+def observation_frame_key(
+    robot_id: str,
+    node_instance_id: str,
+    camera_id: str,
+    stream: Literal["color", "depth"],
+) -> str:
+    return (
+        f"{robot_root(robot_id, node_instance_id)}/observations/current/"
+        f"cameras/{key_chunk(camera_id)}/{stream}"
+    )
+
+
+def state_stream_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/streams/state"
+
+
+def camera_stream_key(
+    robot_id: str,
+    node_instance_id: str,
+    camera_id: str,
+    stream: Literal["color", "depth"],
+) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/streams/cameras/{key_chunk(camera_id)}/{stream}"
+
+
+def camera_stream_selector(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/streams/cameras/**"
+
+
+def lease_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/control/lease"
+
+
+def command_key(robot_id: str, node_instance_id: str) -> str:
+    return f"{robot_root(robot_id, node_instance_id)}/commands"
+
+
+def encode_json(model: BaseModel) -> bytes:
+    return model.model_dump_json(by_alias=True).encode("utf-8")
+
+
+def decode_json(model_type: type[ProtocolModel], payload: bytes | str) -> ProtocolModel:
+    return model_type.model_validate_json(payload)