loop-sdk 0.1.0__py3-none-any.whl

loop_sdk/gen/v1/source_ingest_pb2_grpc.py

@@ -0,0 +1,288 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from ..v1 import source_ingest_pb2 as v1_dot_source__ingest__pb2
+
+GRPC_GENERATED_VERSION = '1.81.1'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in v1/source_ingest_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class SourceIngestServiceStub:
+    """SourceIngestService is the foundation-owned gRPC contract for remote source
+    clients (sensor/helper processes). It replaces the legacy
+    recorder.tactile.v1.TactileIngestService and generalizes it from tactile-only
+    to every remote source kind via per-kind descriptors. Cameras use this
+    contract for discovery/control; camera media frames are pulled over RTSP/RTP.
+
+    Connect       - control plane: bidirectional stream. The client drives the
+    stream with ClientEvent; the server answers with
+    RecorderCommand. command_id correlates a command with the
+    event(s) the client emits in response.
+    StreamSamples - data plane: client-streaming. The client pushes SampleBatch
+    messages; the server acknowledges once with
+    StreamSamplesResponse.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Connect = channel.stream_stream(
+                '/loop.foundation.source.v1.SourceIngestService/Connect',
+                request_serializer=v1_dot_source__ingest__pb2.ClientEvent.SerializeToString,
+                response_deserializer=v1_dot_source__ingest__pb2.RecorderCommand.FromString,
+                _registered_method=True)
+        self.StreamSamples = channel.stream_unary(
+                '/loop.foundation.source.v1.SourceIngestService/StreamSamples',
+                request_serializer=v1_dot_source__ingest__pb2.SampleBatch.SerializeToString,
+                response_deserializer=v1_dot_source__ingest__pb2.StreamSamplesResponse.FromString,
+                _registered_method=True)
+
+
+class SourceIngestServiceServicer:
+    """SourceIngestService is the foundation-owned gRPC contract for remote source
+    clients (sensor/helper processes). It replaces the legacy
+    recorder.tactile.v1.TactileIngestService and generalizes it from tactile-only
+    to every remote source kind via per-kind descriptors. Cameras use this
+    contract for discovery/control; camera media frames are pulled over RTSP/RTP.
+
+    Connect       - control plane: bidirectional stream. The client drives the
+    stream with ClientEvent; the server answers with
+    RecorderCommand. command_id correlates a command with the
+    event(s) the client emits in response.
+    StreamSamples - data plane: client-streaming. The client pushes SampleBatch
+    messages; the server acknowledges once with
+    StreamSamplesResponse.
+    """
+
+    def Connect(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamSamples(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_SourceIngestServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Connect': grpc.stream_stream_rpc_method_handler(
+                    servicer.Connect,
+                    request_deserializer=v1_dot_source__ingest__pb2.ClientEvent.FromString,
+                    response_serializer=v1_dot_source__ingest__pb2.RecorderCommand.SerializeToString,
+            ),
+            'StreamSamples': grpc.stream_unary_rpc_method_handler(
+                    servicer.StreamSamples,
+                    request_deserializer=v1_dot_source__ingest__pb2.SampleBatch.FromString,
+                    response_serializer=v1_dot_source__ingest__pb2.StreamSamplesResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'loop.foundation.source.v1.SourceIngestService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('loop.foundation.source.v1.SourceIngestService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class SourceIngestService:
+    """SourceIngestService is the foundation-owned gRPC contract for remote source
+    clients (sensor/helper processes). It replaces the legacy
+    recorder.tactile.v1.TactileIngestService and generalizes it from tactile-only
+    to every remote source kind via per-kind descriptors. Cameras use this
+    contract for discovery/control; camera media frames are pulled over RTSP/RTP.
+
+    Connect       - control plane: bidirectional stream. The client drives the
+    stream with ClientEvent; the server answers with
+    RecorderCommand. command_id correlates a command with the
+    event(s) the client emits in response.
+    StreamSamples - data plane: client-streaming. The client pushes SampleBatch
+    messages; the server acknowledges once with
+    StreamSamplesResponse.
+    """
+
+    @staticmethod
+    def Connect(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/loop.foundation.source.v1.SourceIngestService/Connect',
+            v1_dot_source__ingest__pb2.ClientEvent.SerializeToString,
+            v1_dot_source__ingest__pb2.RecorderCommand.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamSamples(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_unary(
+            request_iterator,
+            target,
+            '/loop.foundation.source.v1.SourceIngestService/StreamSamples',
+            v1_dot_source__ingest__pb2.SampleBatch.SerializeToString,
+            v1_dot_source__ingest__pb2.StreamSamplesResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+
+class SourceReadServiceStub:
+    """---------------------------------------------------------------------------
+    Read plane — external consumers subscribe to a source's sample stream.
+
+    The mirror of ingest: ingest (SourceIngestService) is client->server (the
+    server is a sink); read is server->client (the server is a source). The
+    bus-side primitive already exists in-process as SourceSession.subscribe with
+    per-subscriber fan-out; this service is its network front for external clients
+    (e.g. a customer robot receiving actions an in-Loop control loop produces, or
+    a client pulling inference outputs published as a source).
+    ---------------------------------------------------------------------------
+
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Subscribe = channel.unary_stream(
+                '/loop.foundation.source.v1.SourceReadService/Subscribe',
+                request_serializer=v1_dot_source__ingest__pb2.SubscribeRequest.SerializeToString,
+                response_deserializer=v1_dot_source__ingest__pb2.SubscribeEvent.FromString,
+                _registered_method=True)
+
+
+class SourceReadServiceServicer:
+    """---------------------------------------------------------------------------
+    Read plane — external consumers subscribe to a source's sample stream.
+
+    The mirror of ingest: ingest (SourceIngestService) is client->server (the
+    server is a sink); read is server->client (the server is a source). The
+    bus-side primitive already exists in-process as SourceSession.subscribe with
+    per-subscriber fan-out; this service is its network front for external clients
+    (e.g. a customer robot receiving actions an in-Loop control loop produces, or
+    a client pulling inference outputs published as a source).
+    ---------------------------------------------------------------------------
+
+    """
+
+    def Subscribe(self, request, context):
+        """Subscribe streams one already-open source's samples to an external client.
+        Data plane is per source_id (matching SampleBatch/subscribe). The source
+        must be open (a producer streaming it); an unopened/failed source is
+        reported via SubscribeEvent.state = STREAM_STATE_FAILED, not a hard error.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_SourceReadServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Subscribe': grpc.unary_stream_rpc_method_handler(
+                    servicer.Subscribe,
+                    request_deserializer=v1_dot_source__ingest__pb2.SubscribeRequest.FromString,
+                    response_serializer=v1_dot_source__ingest__pb2.SubscribeEvent.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'loop.foundation.source.v1.SourceReadService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('loop.foundation.source.v1.SourceReadService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class SourceReadService:
+    """---------------------------------------------------------------------------
+    Read plane — external consumers subscribe to a source's sample stream.
+
+    The mirror of ingest: ingest (SourceIngestService) is client->server (the
+    server is a sink); read is server->client (the server is a source). The
+    bus-side primitive already exists in-process as SourceSession.subscribe with
+    per-subscriber fan-out; this service is its network front for external clients
+    (e.g. a customer robot receiving actions an in-Loop control loop produces, or
+    a client pulling inference outputs published as a source).
+    ---------------------------------------------------------------------------
+
+    """
+
+    @staticmethod
+    def Subscribe(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/loop.foundation.source.v1.SourceReadService/Subscribe',
+            v1_dot_source__ingest__pb2.SubscribeRequest.SerializeToString,
+            v1_dot_source__ingest__pb2.SubscribeEvent.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

loop_sdk/source/client.py

@@ -0,0 +1,123 @@
+"""Public facade: the one-object surface a Source Bus producer uses.
+
+``SourceProducer.connect()`` is the composition root for the library — it wires the
+gRPC source client and the session, then opens the connection. The customer's
+hot loop only calls ``send_*`` (non-blocking).
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from loop_sdk.source.domain.config import OnSelectRobotConfig
+from loop_sdk.source.domain.frame import (
+    MarkerFrame,
+    RobotFrame,
+    RobotStateValue,
+    TactileChannelValue,
+    TactileFrame,
+)
+from loop_sdk.source.domain.schema import SourceSchema
+from loop_sdk.source.domain.stats import SendStats
+from loop_sdk.source.outbound.grpc_source_client import GrpcSourceClient
+from loop_sdk.source.service.producer_session import ProducerSession
+from loop_sdk.source.setup.config import SourceConfig
+
+
+class SourceProducer:
+    """A connected Source Bus producer for one declared schema."""
+
+    def __init__(self, session: ProducerSession) -> None:
+        self._session = session
+
+    @classmethod
+    def connect(
+        cls,
+        loop_addr: str,
+        schema: SourceSchema,
+        config: SourceConfig | None = None,
+        client_id: str | None = None,
+        on_select: OnSelectRobotConfig | None = None,
+    ) -> SourceProducer:
+        """Open a connection to the Loop Source Bus and begin answering its commands.
+
+        ``loop_addr`` is the Source Bus's ``host:port``. ``schema`` declares the
+        sources the SDK will stream. Recording start/stop is operator-driven; the
+        SDK starts streaming when the Source Bus opens a session.
+
+        ``on_select`` is the robot config apply callback. When a robot source
+        advertises ``available_options``, the Source Bus selects one config and
+        sends it on Open; ``on_select(source_id, requested)`` reconfigures the
+        device and returns the config it actually applied (``None`` = applied as
+        requested; raising fails the source). Omit it when no robot source
+        negotiates a config.
+        """
+        settings = config or SourceConfig()
+        client = GrpcSourceClient(
+            loop_addr=loop_addr,
+            client_id=client_id or uuid.uuid4().hex,
+            version=settings.client_version,
+            reconnect_backoff_seconds=settings.reconnect_backoff_seconds,
+            reconnect_backoff_max_seconds=settings.reconnect_backoff_max_seconds,
+            on_select=on_select,
+        )
+        session = ProducerSession(schema, client)
+        session.start()
+        return cls(session)
+
+    def send_robot(
+        self,
+        source_id: str,
+        timestamp_us: int,
+        sequence: int,
+        state: dict[str, RobotStateValue],
+    ) -> None:
+        """Send one robot-state sample as named channel readings. Non-blocking.
+
+        ``state`` maps the source's declared channel keys to heterogeneous
+        readings (scalar/vector/int/bool/string). Omit a key (or map it to
+        ``None``) for "no reading this sample"."""
+        self._session.send(RobotFrame(source_id=source_id, timestamp_us=timestamp_us, sequence=sequence, state=state))
+
+    def send_tactile(
+        self,
+        source_id: str,
+        timestamp_us: int,
+        sequence: int,
+        channels: tuple[TactileChannelValue, ...],
+    ) -> None:
+        """Send one tactile sample. Non-blocking."""
+        self._session.send(
+            TactileFrame(source_id=source_id, timestamp_us=timestamp_us, sequence=sequence, channels=channels)
+        )
+
+    def send_marker(self, source_id: str, timestamp_us: int, sequence: int, label: str, category: str = "") -> None:
+        """Send one sparse marker sample. Non-blocking."""
+        self._session.send(
+            MarkerFrame(
+                source_id=source_id,
+                timestamp_us=timestamp_us,
+                sequence=sequence,
+                label=label,
+                category=category,
+            )
+        )
+
+    def report_source_error(self, source_id: str, code: str, message: str = "") -> None:
+        """Report a per-source fault. The Source Bus maps it to ``SourceEvent(FAILED)``
+        so the recorder fails that source fast. Best-effort, non-blocking."""
+        self._session.report_error(source_id, code, message)
+
+    def stats(self) -> SendStats:
+        """Return a snapshot of delivery and connection statistics."""
+        return self._session.stats()
+
+    def close(self) -> None:
+        """Stop sending and tear the connection down."""
+        self._session.close()
+
+    def __enter__(self) -> SourceProducer:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

loop_sdk/source/consumer.py

@@ -0,0 +1,54 @@
+"""Public facade: the one-object surface a Source Bus consumer uses.
+
+The mirror of ``SourceProducer``. ``SourceConsumer.connect()`` wires the gRPC
+read client and opens the channel; ``subscribe()`` returns a blocking iterator of
+decoded domain frames for one already-open source. The customer's loop only
+iterates::
+
+    with SourceConsumer.connect(loop_addr) as consumer:
+        for frame in consumer.subscribe("franka"):
+            act(frame)  # e.g. a RobotFrame: frame.state["joint_0"]
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from loop_sdk.source.domain.frame import FrameSample
+from loop_sdk.source.outbound.grpc_source_reader import GrpcSourceReader
+from loop_sdk.source.port.source_reader import SourceReader
+
+
+class SourceConsumer:
+    """A connected Source Bus consumer that reads sources back off the bus."""
+
+    def __init__(self, reader: SourceReader) -> None:
+        self._reader = reader
+
+    @classmethod
+    def connect(cls, loop_addr: str) -> SourceConsumer:
+        """Open a connection to the Loop Source Bus read plane.
+
+        ``loop_addr`` is the Source Bus's ``host:port``.
+        """
+        return cls(GrpcSourceReader(loop_addr=loop_addr))
+
+    def subscribe(self, source_id: str, session_id: str = "") -> Iterator[FrameSample]:
+        """Stream one already-open source's samples as decoded domain frames.
+
+        Iteration ends when the source stops cleanly and raises
+        ``SubscriptionFailedError`` if the bus reports the source faulted (most
+        commonly: the source is not open). ``session_id`` optionally scopes the
+        subscription, mirroring ``Open``.
+        """
+        return self._reader.subscribe(source_id, session_id)
+
+    def close(self) -> None:
+        """Cancel any in-flight subscription and tear the connection down."""
+        self._reader.close()
+
+    def __enter__(self) -> SourceConsumer:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

loop_sdk/source/domain/config.py

@@ -0,0 +1,61 @@
+"""Robot config negotiation models (mirrors the foundation contract).
+
+A robot source advertises per-axis candidate lists (``RobotConfigOptions``) at
+Describe time; the Source Bus selects one value per axis into a ``RobotConfig``
+and sends it on Open; the SDK applies it (via the ``on_select`` callback) and
+reports the config it actually applied back on the control plane.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class RobotConfig(BaseModel):
+    """One negotiated robot configuration: the selection the server opens with,
+    and the config the client confirms it actually applied.
+
+    ``control_hz`` and ``action_space`` are the required runtime-negotiated axes;
+    the rest are optional identity / compatibility-gate fields."""
+
+    model_config = ConfigDict(frozen=True)
+
+    control_hz: int
+    action_space: str
+    gripper_type: str = ""
+    finger_type: str = ""
+    robot_type: str = ""
+    robot_firmware_version: str = ""
+    teleoperation_version: str = ""
+
+
+class RobotConfigOptions(BaseModel):
+    """Per-axis candidate lists a robot source advertises at Describe time. Each
+    axis is independent; the server selects one value per axis into a
+    ``RobotConfig``. Empty lists everywhere means "no negotiation" (the device
+    opens with its default config)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    control_hz: tuple[int, ...] = ()
+    action_space: tuple[str, ...] = ()
+    gripper_type: tuple[str, ...] = ()
+    finger_type: tuple[str, ...] = ()
+    robot_type: tuple[str, ...] = ()
+    robot_firmware_version: tuple[str, ...] = ()
+    teleoperation_version: tuple[str, ...] = ()
+
+
+# Apply callback: the Source Bus selected ``requested`` for ``source_id``; the
+# client reconfigures the device and returns the config it ACTUALLY applied
+# (may differ, e.g. requested 100 Hz but the device runs at 90). Returning
+# ``None`` means "applied exactly as requested". Raising signals the source
+# cannot open with that config (reported as a per-source FAILED state).
+#
+# IMPORTANT: this runs synchronously on the SDK control thread (the one that
+# processes Open/Close/Shutdown). Keep it fast and non-blocking — a slow or
+# hanging callback stalls the whole control plane (including a clean ``close()``).
+# Do the heavy device reconfiguration off this thread if it can block.
+OnSelectRobotConfig = Callable[[str, RobotConfig], RobotConfig | None]

loop_sdk/source/domain/frame.py

@@ -0,0 +1,108 @@
+"""Frame samples: the transport-free representation of one ``send()``.
+
+A ``FrameSample`` is one timestamped sample for one source. The outbound adapter
+maps it to a ``pb2.SampleBatch`` of one ``Sample`` at the gRPC boundary; the
+domain never references protobuf.
+
+``timestamp_us`` and ``sequence`` map to ``Sample.timestamp_us`` (int64
+microseconds) and ``Sample.sequence`` (uint64) on the wire — see
+``docs/spec_discrepancies.md`` item 9(c).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from loop_sdk.source.domain.source_kind import SourceKind
+
+# One named robot signal: the heterogeneous state-value domain (float, vector,
+# int, bool, string), mirroring a RobotEnv observation value. ``None`` means the
+# reading is absent for this sample — the key is omitted from the wire, not sent
+# as an empty value. ``bool`` precedes ``int`` because ``bool`` is an ``int``
+# subclass and must be encoded as a distinct arm.
+RobotStateValue = bool | int | float | str | list[float] | None
+
+
+class RobotFrame(BaseModel):
+    """One robot-state sample: a dict of named channel readings.
+
+    Keys are the source's verbatim channel keys; values are heterogeneous
+    (scalar/vector/int/bool/string). A key absent from ``state`` (or mapped to
+    ``None``) means "no reading this sample" and is omitted on the wire."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    timestamp_us: int
+    sequence: int
+    state: dict[str, RobotStateValue]
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.ROBOT
+
+
+class TactileChannelValue(BaseModel):
+    """One channel's reading within a tactile sample."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    raw: bytes = b""
+    values_i16: tuple[int, ...] = ()
+
+
+class TactileFrame(BaseModel):
+    """One tactile sample carrying per-channel readings."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    timestamp_us: int
+    sequence: int
+    channels: tuple[TactileChannelValue, ...]
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.TACTILE
+
+
+class MarkerFrame(BaseModel):
+    """One sparse marker sample."""
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    timestamp_us: int
+    sequence: int
+    label: str
+    category: str = ""
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.MARKER
+
+
+class PolicyActionFrame(BaseModel):
+    """One policy-action sample read back from a deploy-owned action source.
+
+    ``actions`` is the list of action vectors emitted for one input sample-set tick;
+    the input-sample-set fields trace which observation produced it (``None`` when
+    the producer did not set them). Read-plane only — the SDK does not produce these.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source_id: str
+    timestamp_us: int
+    sequence: int
+    actions: tuple[tuple[float, ...], ...]
+    input_sample_set_source_id: str | None = None
+    input_sample_set_sequence: int | None = None
+
+    @property
+    def kind(self) -> SourceKind:
+        return SourceKind.POLICY_ACTION
+
+
+FrameSample = RobotFrame | TactileFrame | MarkerFrame | PolicyActionFrame