loop-sdk 0.1.1__tar.gz → 0.1.2__tar.gz

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-sdk
-Version: 0.1.1
+Version: 0.1.2
 Summary: Customer-side gRPC client SDK for the Loop Source Bus.
 Requires-Python: >=3.10
 Requires-Dist: grpcio>=1.81.1

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/src/loop_sdk/source/domain/schema.py

@@ -99,7 +99,12 @@ class RobotStreamSchema(BaseModel):
 
     source_id: str
     name: str = ""
-    channels: tuple[ChannelSpec, ...] = Field(min_length=1)
+    # A robot sample is self-describing (its ``state`` keys define the columns the
+    # recorder writes), so the declared channel layout is OPTIONAL metadata. Leave
+    # it empty to announce the source for discovery/config-negotiation and let the
+    # streamed samples define the channels; declare it to attach per-channel
+    # metadata (role/unit/...) and have the SDK validate sends against it.
+    channels: tuple[ChannelSpec, ...] = ()
     # 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.

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/src/loop_sdk/source/robot_step_sender.py

@@ -225,22 +225,26 @@ class RobotStepSender:
 
     def declare(
         self,
-        channels: ChannelLayout,
+        channels: ChannelLayout = (),
         *,
         name: str | None = None,
         options: RobotConfigOptions | None = None,
     ) -> bool:
-        """**Optional — the first ``send()`` does this for you** from its own keys.
-        Call ``declare`` explicitly only to fix the layout and open the source
-        *before* the first send — i.e. so the Source Bus negotiates the config (your
-        ``apply_config`` fires at Open) before you start streaming, rather than on the
-        first tick.
-
-        ``channels`` is the authoritative, COMPLETE set of channel keys this source
-        will ever carry — channel keys, full ``ChannelSpec``s, or a representative
-        step dict (its flattened keys become the layout). The layout is fixed here:
-        later ``send()`` calls may omit a key (→ "no reading") but may not introduce
-        new keys. Idempotent once the source is open.
+        """Open the source so the Source Bus can discover and negotiate it (→ "ready"),
+        before any data flows. Idempotent once the source is open.
+
+        ``channels`` is OPTIONAL — a robot sample is self-describing, so the recorder
+        takes its columns from the streamed samples, not from this layout:
+
+          * **Omit it (options-only)** to announce the source for discovery / config
+            negotiation now and let the FIRST ``send`` capture the channel layout from
+            its keys. Use this to reach "ready" at startup without knowing the full
+            channel set yet.
+          * **Pass it** (keys / ``ChannelSpec``s / a representative step dict) to fix
+            the layout up front and have the SDK validate sends against it (and attach
+            per-channel metadata).
+
+        Either way ``options`` + ``apply_config`` negotiation happens at Open.
         """
         if not self.connected:
             self.connect()
@@ -252,10 +256,7 @@ class RobotStepSender:
             self.name = name
 
         specs = self._resolve_specs(channels)
-        if not specs:
-            logger.warning("RobotStepSender: empty channel layout; not opening source %s", self.source_id)
-            return False
-        self._order = [spec.key for spec in specs]
+        self._order = [spec.key for spec in specs] if specs else None
         schema = SourceSchema(
             robot=(
                 RobotStreamSchema(
@@ -274,7 +275,10 @@ class RobotStepSender:
             on_select=self._on_select,
         )
         logger.info(
-            "RobotStepSender: source %s open on %s (%d channels)", self.source_id, self.loop_addr, len(self._order)
+            "RobotStepSender: source %s open on %s (%s)",
+            self.source_id,
+            self.loop_addr,
+            f"{len(specs)} channels" if specs else "options-only; layout from first send",
         )
         return True
 
@@ -312,7 +316,11 @@ class RobotStepSender:
         try:
             if self._producer is None and not self.declare(flat):
                 return False
-            assert self._order is not None and self._producer is not None
+            if self._order is None:
+                # Source was declared options-only — the first frame fixes the layout
+                # (and thus the recorder's columns), so make this first frame complete.
+                self._order = list(flat)
+            assert self._producer is not None
             self._warn_unknown_keys(flat)
             state = {key: _normalize_value(flat.get(key)) for key in self._order}
             seq = self._seq if sequence is None else sequence

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/src/loop_sdk/source/service/producer_session.py

@@ -67,6 +67,10 @@ class ProducerSession:
 
     def _validate_robot(self, frame: RobotFrame) -> None:
         declared = self._schema.robot_channel_keys(frame.source_id)
+        if not declared:
+            # Options-only / self-describing source: no declared layout to enforce —
+            # the recorder writes whatever keys each sample carries.
+            return
         unknown = frame.state.keys() - declared
         if unknown:
             raise SchemaMismatchError(

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/tests/unit/source/domain/test_schema.py

@@ -31,9 +31,13 @@ def test_robot_stream_channel_keys_match_declared_channels() -> None:
     assert stream.kind is SourceKind.ROBOT
 
 
-def test_robot_stream_requires_at_least_one_joint() -> None:
-    with pytest.raises(ValidationError):
-        RobotStreamSchema(source_id="arm/state", channels=())
+def test_robot_stream_allows_empty_channels() -> None:
+    # A robot sample is self-describing, so the channel layout is optional metadata:
+    # an empty layout announces the source (discovery / config negotiation) and lets
+    # the streamed samples define the columns.
+    stream = RobotStreamSchema(source_id="arm/state", channels=())
+    assert stream.channel_keys == frozenset()
+    assert stream.kind is SourceKind.ROBOT
 
 
 def test_schema_rejects_empty() -> None:

{loop_sdk-0.1.1 → loop_sdk-0.1.2}/tests/unit/source/test_robot_step_sender.py

@@ -105,6 +105,28 @@ def test_first_send_auto_declares_from_step() -> None:
     assert {c.key for c in schema.robot[0].channels} == {"x", "y"}
 
 
+def test_options_only_declare_reaches_ready_then_first_send_fixes_layout() -> None:
+    # declare() with NO channels announces the source (discovery/negotiation -> ready)
+    # with an empty layout; the first send fixes the channels from its keys.
+    opts = RobotConfigOptions(control_hz=(20,), action_space=("target_cartesian_delta",))
+    sender, harness = _sender(options=opts)
+    sender.connect()
+    assert sender.declare() is True  # options-only, no channels
+    robot = harness.connect_calls[0]["schema"].robot[0]
+    assert robot.channels == ()  # announced with an empty layout
+    assert robot.available_options.control_hz == (20,)  # options still negotiated
+    assert sender._order is None  # layout not fixed yet
+    assert harness.producer.sent == []  # declaring sends no sample
+
+    sender.send(1, {"a": 1.0, "b": 2.0})  # first frame fixes the layout
+    _sid, _ts, _seq, state = harness.producer.sent[0]
+    assert set(state) == {"a", "b"} and sender._order == ["a", "b"]
+
+    sender.send(2, {"a": 3.0, "c": 9.0})  # stable key set: c dropped, b -> no reading
+    _sid, _ts, _seq, state2 = harness.producer.sent[1]
+    assert set(state2) == {"a", "b"} and state2["b"] is None
+
+
 def test_nested_step_is_flattened_on_send_not_dropped() -> None:
     sender, harness = _sender()
     sender.connect()