loop-sdk 0.1.0__py3-none-any.whl

loop_sdk/source/domain/schema.py

@@ -0,0 +1,193 @@
+"""Source schema: the sources the SDK declares to the Source Bus.
+
+The Source Bus drives discovery: it sends ``Describe`` and the SDK answers from
+this schema (see ``docs/spec_discrepancies.md`` item 10). The schema is declared
+once at connect time and replayed on every ``Describe``, so it must be answerable
+synchronously without probing devices.
+
+Each stream maps 1:1 to a Source Bus source: a ``source_id``, a kind, and the
+kind's scan-time layout. A robot stream's ``channels`` declare the keys every
+``RobotPayload.state`` sample may carry (each sample is a dict keyed by channel
+key; a key may be omitted for "no reading this sample").
+"""
+
+from __future__ import annotations
+
+import warnings
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from loop_sdk.source.domain.config import RobotConfigOptions
+from loop_sdk.source.domain.source_kind import SourceKind
+
+
+class ChannelRole(str, Enum):
+    """Data-kind of a channel, by its role in THIS source's purpose (closed set).
+
+    Purpose-relative, not robot-boundary: ``CORE`` is the essential payload the
+    source exists to carry (the action on an action source, the measured state on a
+    state source); ``AUX`` is supplementary provenance/metadata carried alongside
+    (values used to derive the action, source labels, diagnostics, mode/task
+    context). "Actually executed vs candidate" is distinguished by *which* source it
+    is (state source = ground truth, action source = command), not by this role.
+    Maps to ``pb2.ChannelRole``. A value outside this set is rejected at declaration
+    time (pydantic raises on construction)."""
+
+    CORE = "core"  # the essential signal this source exists to carry
+    AUX = "aux"  # supplementary provenance/metadata carried alongside
+
+
+class RotationType(str, Enum):
+    """Orientation encoding for a rotation channel (closed set).
+
+    Maps to ``pb2.RobotRotationType``. Omit (``None``) for a non-rotation channel —
+    a scalar angle uses ``unit='rad'``, not a rotation type."""
+
+    QUATERNION = "quaternion"
+    EULER = "euler"
+    ROTATION_6D = "rotation_6d"
+
+
+# Recommended physical units. Units are unbounded (mm, N, kPa, …), so this is NOT
+# enforced: an unrecognized unit warns rather than rejects (see ``ChannelSpec``).
+RECOMMENDED_UNITS = frozenset({
+    "rad", "rad/s", "rad/s²", "m", "m/s", "m/s²", "normalized", "normalized/s",
+    "N", "N·m", "quat", "rot6d", "ms", "bool", "enum", "g",
+})
+
+
+class ChannelSpec(BaseModel):
+    """One ordered dimension of a robot-state vector.
+
+    ``key`` is the client's verbatim channel name, preserved losslessly. ``role``
+    and ``rot_type`` are closed enums (invalid values raise on construction);
+    ``unit`` is semi-open (a non-recommended value warns, not raises)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    label: str = ""
+    role: ChannelRole | None = None
+    unit: str = ""
+    rot_type: RotationType | None = None
+    group: str = ""
+    range: tuple[float, float] | None = None
+
+    @field_validator("unit")
+    @classmethod
+    def _warn_unrecommended_unit(cls, value: str) -> str:
+        if value and value not in RECOMMENDED_UNITS:
+            warnings.warn(
+                f"unit {value!r} is not in the recommended set {sorted(RECOMMENDED_UNITS)}; "
+                "it is accepted as-is",
+                stacklevel=2,
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _check_range(self) -> ChannelSpec:
+        if self.range is not None and self.range[0] > self.range[1]:
+            raise ValueError(f"range min {self.range[0]} exceeds max {self.range[1]} for channel {self.key!r}")
+        return self
+
+
+class RobotStreamSchema(BaseModel):
+    """A robot-state source: a named channel layout, one heterogeneous state dict per sample."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    name: str = ""
+    channels: tuple[ChannelSpec, ...] = Field(min_length=1)
+    # Per-axis config candidates the source can open with. Empty (the default)
+    # means no negotiation: the Source Bus opens it with the device default and
+    # no ``on_select`` callback fires.
+    available_options: RobotConfigOptions = RobotConfigOptions()
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.ROBOT
+
+    @property
+    def channel_keys(self) -> frozenset[str]:
+        """The declared channel keys a sample's ``state`` may carry."""
+        return frozenset(channel.key for channel in self.channels)
+
+
+class TactileChannelSpec(BaseModel):
+    """One tactile channel descriptor."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    label: str = ""
+    sample_format: str = ""
+    sample_count: int = 0
+
+
+class TactileStreamSchema(BaseModel):
+    """A tactile source carrying its channel layout."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    name: str = ""
+    channels: tuple[TactileChannelSpec, ...] = Field(min_length=1)
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.TACTILE
+
+
+class MarkerStreamSchema(BaseModel):
+    """A marker source. Markers are sparse, event-like data-plane samples and carry no layout."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    name: str = ""
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.MARKER
+
+
+class SourceSchema(BaseModel):
+    """The full set of sources the SDK declares to the Source Bus."""
+
+    model_config = ConfigDict(frozen=True)
+
+    robot: tuple[RobotStreamSchema, ...] = ()
+    tactile: tuple[TactileStreamSchema, ...] = ()
+    marker: tuple[MarkerStreamSchema, ...] = ()
+
+    @model_validator(mode="after")
+    def _check_non_empty_and_unique(self) -> SourceSchema:
+        streams = (*self.robot, *self.tactile, *self.marker)
+        if not streams:
+            raise ValueError("SourceSchema must declare at least one source")
+        ids = [stream.source_id for stream in streams]
+        if len(ids) != len(set(ids)):
+            raise ValueError("source_id values must be unique across all streams")
+        return self
+
+    def kind_of(self, source_id: str) -> SourceKind:
+        """Return the kind of a declared source, raising ``KeyError`` if unknown."""
+        for stream in self.robot:
+            if stream.source_id == source_id:
+                return SourceKind.ROBOT
+        for stream in self.tactile:
+            if stream.source_id == source_id:
+                return SourceKind.TACTILE
+        for stream in self.marker:
+            if stream.source_id == source_id:
+                return SourceKind.MARKER
+        raise KeyError(source_id)
+
+    def robot_channel_keys(self, source_id: str) -> frozenset[str]:
+        """Return the declared channel keys for a robot source."""
+        for stream in self.robot:
+            if stream.source_id == source_id:
+                return stream.channel_keys
+        raise KeyError(source_id)

loop_sdk/source/domain/source_exception.py

@@ -0,0 +1,48 @@
+"""Source SDK domain exceptions.
+
+Business-rule violations the SDK surfaces to the customer. The outbound adapter
+translates transport-level failures (``grpc.RpcError`` and the like) into these
+before they propagate, per the project exception rules.
+"""
+
+from __future__ import annotations
+
+
+class SourceError(Exception):
+    """Base class for all Source SDK errors."""
+
+
+class SchemaMismatchError(SourceError):
+    """A frame does not match the declared schema for its source."""
+
+    def __init__(self, source_id: str, detail: str) -> None:
+        super().__init__(f"frame for source {source_id!r} does not match schema: {detail}")
+        self.source_id = source_id
+        self.detail = detail
+
+
+class UnknownSourceError(SourceError):
+    """A frame names a source that was not declared in the schema."""
+
+    def __init__(self, source_id: str) -> None:
+        super().__init__(f"source {source_id!r} was not declared in the source schema")
+        self.source_id = source_id
+
+
+class NotConnectedError(SourceError):
+    """An operation requires an active connection that does not exist."""
+
+
+class SubscriptionFailedError(SourceError):
+    """A subscription ended in failure.
+
+    The Source Bus reports a per-source fault (``STREAM_STATE_FAILED``) on the
+    read stream — most commonly because the source is not open (no producer
+    streaming it), or because the underlying source terminated abnormally.
+    """
+
+    def __init__(self, source_id: str, detail: str = "") -> None:
+        suffix = f": {detail}" if detail else ""
+        super().__init__(f"subscription to source {source_id!r} failed{suffix}")
+        self.source_id = source_id
+        self.detail = detail

loop_sdk/source/domain/source_kind.py

@@ -0,0 +1,18 @@
+"""Source-kind discriminator for the Source Bus SDK.
+
+Mirrors the kinds the Source Bus gRPC contract carries (camera is excluded from
+the contract and therefore from this SDK).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SourceKind(str, Enum):
+    """The source kinds the SDK can declare and stream."""
+
+    TACTILE = "tactile"
+    ROBOT = "robot"
+    MARKER = "marker"
+    POLICY_ACTION = "policy_action"  # read-plane only: actions consumed back from the bus

loop_sdk/source/domain/stats.py

@@ -0,0 +1,22 @@
+"""Send/connection statistics surfaced to the customer."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SendStats(BaseModel):
+    """Counters for the SDK send pipeline and connection liveness.
+
+    ``Loop`` cannot reach into the customer process, so these are the SDK's own
+    view of how delivery is going (see ``docs/spec_discrepancies.md`` item 12).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    enqueued: int = 0
+    sent: int = 0
+    failed: int = 0
+    dropped: int = 0
+    reconnects: int = 0
+    connected: bool = False

loop_sdk/source/outbound/frame_queue.py

@@ -0,0 +1,85 @@
+"""Latest-only frame queue for the send pipeline.
+
+``send()`` runs on the customer's real-time control thread, so enqueue must never
+block. The queue holds only the most recent frame: a new frame replaces an
+unsent one, and the replaced frame is counted as dropped (see
+``docs/spec_discrepancies.md`` item 15). This keeps the stream at the freshest
+state under backpressure rather than falling behind. A sentinel ``None`` unblocks
+the sender thread on shutdown.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+
+from loop_sdk.source.domain.frame import FrameSample
+
+
+class FrameQueue:
+    """A thread-safe queue that keeps only the latest frame (drops the previous one)."""
+
+    def __init__(self) -> None:
+        self._items: deque[FrameSample] = deque(maxlen=1)
+        self._lock = threading.Lock()
+        self._not_empty = threading.Condition(self._lock)
+        self._closed = False
+        self._woken = False
+        self._dropped = 0
+
+    def put(self, frame: FrameSample) -> None:
+        """Enqueue a frame without blocking, replacing an unsent one (counted as dropped)."""
+        with self._not_empty:
+            if self._closed:
+                return
+            if self._items:
+                self._dropped += 1
+            self._items.append(frame)  # maxlen=1 evicts the previous frame
+            self._not_empty.notify()
+
+    def get(self) -> FrameSample | None:
+        """Block until a frame is available; return ``None`` once closed or woken.
+
+        A pending wake takes priority over queued items so the consumer (a
+        per-session sender) retires promptly on session end. Queued frames are
+        left in place for the next session — the queue survives reconnects.
+        """
+        with self._not_empty:
+            while not self._items and not self._closed and not self._woken:
+                self._not_empty.wait()
+            if self._woken:
+                self._woken = False
+                return None
+            if self._closed and not self._items:
+                return None
+            return self._items.popleft()
+
+    def wake(self) -> None:
+        """Unblock a waiting ``get()`` once so it returns ``None`` without closing the queue.
+
+        Used to retire a per-session sender thread while keeping the queue open
+        across reconnects.
+        """
+        with self._not_empty:
+            self._woken = True
+            self._not_empty.notify_all()
+
+    def reset_wake(self) -> None:
+        """Clear a pending wake at the start of a new session.
+
+        Guards against a wake set at the end of one session leaking into the
+        next and prematurely retiring its sender.
+        """
+        with self._not_empty:
+            self._woken = False
+
+    def close(self) -> None:
+        """Mark the queue closed and wake any waiting consumer."""
+        with self._not_empty:
+            self._closed = True
+            self._not_empty.notify_all()
+
+    @property
+    def dropped(self) -> int:
+        with self._lock:
+            return self._dropped