lab-sync-driver-protocol 0.3.0__py3-none-any.whl

lab_sync_driver_protocol/__init__.py

@@ -0,0 +1,27 @@
+"""Shared wire contract for the driver protocol.
+
+Hand-written newline-delimited JSON framing -- no codegen. Importable by the
+supervisor AND by out-of-process drivers, so a driver speaks the protocol without
+importing anything of the supervisor's. Transport is the child process's
+stdin/stdout; see `wire` for the frame schema.
+"""
+
+from lab_sync_driver_protocol.environment import CONFIGURATION_ENV
+from lab_sync_driver_protocol.environment import DATA_DIR_ENV
+from lab_sync_driver_protocol.wire import PROTOCOL_VERSION
+from lab_sync_driver_protocol.wire import STREAM_LIMIT
+from lab_sync_driver_protocol.wire import decode
+from lab_sync_driver_protocol.wire import encode
+from lab_sync_driver_protocol.wire import read_frame
+from lab_sync_driver_protocol.wire import write_frame
+
+__all__ = [
+    "CONFIGURATION_ENV",
+    "DATA_DIR_ENV",
+    "PROTOCOL_VERSION",
+    "STREAM_LIMIT",
+    "decode",
+    "encode",
+    "read_frame",
+    "write_frame",
+]

lab_sync_driver_protocol/environment.py

@@ -0,0 +1,17 @@
+"""Per-instance values the supervisor hands a driver process through its environment.
+
+The launch command is a driver *type's* (shared by every instance), and stdin is the protocol channel, so anything the supervisor knows about
+one *instance* before the process starts rides the environment. Both are set on every spawn; a driver that does not read them is unaffected.
+"""
+
+#: The hardware variant this device was added as -- one of the names the driver
+#: lists as its ``configurations`` in ``describe`` -- or unset for a driver that
+#: declares none, or a device added before the driver declared any (the driver's
+#: first configuration is then the one it runs as).
+CONFIGURATION_ENV = "STUDIO_DEVICE_CONFIGURATION"
+
+#: This instance's own writable directory (also the process's working
+#: directory). The supervisor searches it when serving a relative ``model_path`` or
+#: ``top_view_image_path``, so a driver that generates a file per instance --
+#: a 3D model assembled for the configuration it runs as -- writes it here.
+DATA_DIR_ENV = "STUDIO_DEVICE_DATA_DIR"

lab_sync_driver_protocol/wire.py

@@ -0,0 +1,65 @@
+"""Newline-delimited JSON framing for the driver protocol.
+
+One JSON object per line over the child process's stdin/stdout; stdout carries
+protocol frames only, stderr is the driver's log channel. The frame schema is
+transport-shaped -- a request `id` plus a `type` discriminator -- so unary
+replies and the Execute progress stream share one duplex pipe, and a driver may
+later push un-correlated frames (telemetry) without a pending request.
+
+Request   (supervisor -> driver): {"id": <int>, "method": <str>, "params": {...}}
+Reply     (driver -> supervisor): {"id": <int>, "type": "reply",  "result": {...}}
+Execute stream:                   {"id", "type": "progress", "fraction", "message"}
+                           ... -> {"id", "type": "result",   "output_json"}
+                              or  {"id", "type": "error",    "code", "message"}
+Telemetry (driver -> supervisor): {"type": "telemetry", "channel": <str>, "payload": {...}}
+
+Telemetry is the un-correlated case this framing was shaped for: the frame
+carries no `id` because nothing requested that particular reading, and a reader
+must route on `type` before looking for one. It is **demand-gated rather than
+free-running** -- a driver samples nothing until the supervisor says to:
+
+    supervisor -> driver: {"id", "method": "set_telemetry_demand",
+                     "params": {"channels": [<str>, ...]}}
+    driver -> supervisor: {"id", "type": "reply", "result": {"channels": [...]}}
+
+`channels` is the complete set that should be running, not a delta, so a lost
+or reordered frame cannot leave a sampler stuck on. A driver that declares no
+telemetry channels never sees the method, and one that receives a channel it
+does not know ignores it rather than erroring -- both keep a supervisor and a driver
+at different versions working together.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+from typing import cast
+
+if TYPE_CHECKING:
+    import asyncio
+
+PROTOCOL_VERSION = "v0"
+
+# Bump asyncio's 64 KiB line cap: a single Execute params/output frame may be
+# larger than the default StreamReader limit, and readline() would raise.
+STREAM_LIMIT = 2**24
+
+
+def encode(frame: dict[str, object]) -> bytes:
+    return (json.dumps(frame) + "\n").encode("utf-8")
+
+
+def decode(line: bytes) -> dict[str, object]:
+    return cast("dict[str, object]", json.loads(line))
+
+
+async def read_frame(reader: asyncio.StreamReader) -> dict[str, object] | None:
+    line = await reader.readline()
+    if not line:
+        return None
+    return decode(line)
+
+
+async def write_frame(writer: asyncio.StreamWriter, frame: dict[str, object]) -> None:
+    writer.write(encode(frame))
+    await writer.drain()

lab_sync_driver_protocol-0.3.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: lab-sync-driver-protocol
+Version: 0.3.0
+Summary: Versioned stdio wire contract between the device engine and out-of-process device drivers
+Author: Lab Sync
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lab-sync-driver-protocol
+
+The versioned wire contract between device drivers and the supervisor that
+launches them. A driver runs as a child process and the two talk
+newline-delimited JSON over the child's stdin and stdout: stdout is the
+protocol channel and nothing else may write to it, stderr is the driver's log
+channel. The package is importable by both sides and depends on nothing, so a
+driver speaks the protocol without importing anything of the supervisor's.
+
+Most driver authors want [`lab-sync-driver-sdk`](https://pypi.org/project/lab-sync-driver-sdk/),
+which implements the driver side of this protocol from a decorated Python
+class. Depend on `lab-sync-driver-protocol` directly only to implement the protocol
+yourself, in Python or as a reference for another language.
+
+```bash
+pip install lab-sync-driver-protocol
+```
+
+## Frames
+
+One JSON object per line. Every request carries an `id`, and every frame a
+driver sends in answer carries the same `id` and a `type`:
+
+```text
+Request   (supervisor -> driver): {"id": <int>, "method": <str>, "params": {...}}
+Reply     (driver -> supervisor): {"id": <int>, "type": "reply", "result": {...}}
+Execute stream:                   {"id", "type": "progress", "fraction", "message"}
+                           ... -> {"id", "type": "result", "output_json"}
+                              or  {"id", "type": "error", "code", "message"}
+Telemetry (driver -> supervisor): {"type": "telemetry", "channel": <str>, "payload": {...}}
+```
+
+`lab_sync_driver_protocol.wire` holds the framing (`encode`, `decode`, `read_frame`,
+`write_frame`), the protocol version (`PROTOCOL_VERSION`, currently `v0`) and
+`STREAM_LIMIT`, the line length a reader should accept.
+
+## Methods
+
+The request vocabulary is `handshake`, `describe`, `connect`,
+`set_simulation`, `ping`, `execute` (streaming progress/result/error frames),
+`abort`, `describe_options`, `estimate_time` and `set_telemetry_demand`.
+
+`describe_options` is optional and additive (the protocol version stays `v0`):
+request `{"command": name, "parameters": {…}}`, reply
+`{"options": {param_name: [choice, …]}}` — the runtime choices for the
+command's `dynamic_options` parameters, best-effort per parameter. A driver
+predating it answers with the standard `unknown_method` error frame, which a
+supervisor reads as "no dynamic options" rather than a fault.
+
+Telemetry is demand-gated: a driver samples nothing until the supervisor sends
+`set_telemetry_demand` with the complete set of channels that should be
+running. See the `lab_sync_driver_protocol.wire` module docstring.
+
+## Environment
+
+The supervisor passes per-instance values in the driver process's environment,
+since the launch command is shared by every instance of a driver type:
+
+- `STUDIO_DEVICE_CONFIGURATION` (`CONFIGURATION_ENV`): the hardware variant
+  the device was added as, one of the `configurations` the driver describes.
+- `STUDIO_DEVICE_DATA_DIR` (`DATA_DIR_ENV`): the instance's own writable
+  directory, which is also the process's working directory.
+
+## License
+
+MIT

lab_sync_driver_protocol-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+lab_sync_driver_protocol/__init__.py,sha256=d9uHwgBQP1w0qVjcT2OJakxBr26-nZ0SQThqsPg7xbU,951
+lab_sync_driver_protocol/environment.py,sha256=VfDHBV7lI-1cS4nKf8oSdaRDLTairYxqqMfopMuXsAI,1068
+lab_sync_driver_protocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lab_sync_driver_protocol/wire.py,sha256=ovU-pRCx3JWwwYLf11VN8nrF7ajAvsTa2zSKtMNBISw,2692
+lab_sync_driver_protocol-0.3.0.dist-info/licenses/LICENSE,sha256=jm-ZYaMIQMfZVTbmqsfK44orj0ZnKzzsKwwJwq21xOI,1065
+lab_sync_driver_protocol-0.3.0.dist-info/METADATA,sha256=9rgBg9I57nkvtDKa-6vT9TuUYh-D5JPGZ4vI127EqX8,3675
+lab_sync_driver_protocol-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+lab_sync_driver_protocol-0.3.0.dist-info/top_level.txt,sha256=8T2VVh7A2hbLgohJ50HpgInb31l3ZHK6fOL0_UzHook,25
+lab_sync_driver_protocol-0.3.0.dist-info/RECORD,,

lab_sync_driver_protocol-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lab_sync_driver_protocol-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lab Sync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lab_sync_driver_protocol-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lab_sync_driver_protocol