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

lab_sync_driver_sdk/__init__.py

@@ -0,0 +1,43 @@
+"""lab-sync-driver-sdk: the driver-authoring SDK.
+
+A driver subclasses `Device`, decorates async methods with `@command` and the
+in/out decorators, and runs `serve(device)` (over stdio). It depends only on
+the shared wire contract (`lab_sync_driver_protocol`), never on the supervisor that
+launches the driver.
+"""
+
+from lab_sync_driver_sdk.decorators import OutputValidationError
+from lab_sync_driver_sdk.decorators import bool_in
+from lab_sync_driver_sdk.decorators import bool_out
+from lab_sync_driver_sdk.decorators import command
+from lab_sync_driver_sdk.decorators import float_in
+from lab_sync_driver_sdk.decorators import float_out
+from lab_sync_driver_sdk.decorators import int_in
+from lab_sync_driver_sdk.decorators import int_out
+from lab_sync_driver_sdk.decorators import settings
+from lab_sync_driver_sdk.decorators import string_in
+from lab_sync_driver_sdk.decorators import string_out
+from lab_sync_driver_sdk.decorators import telemetry
+from lab_sync_driver_sdk.device import Device
+from lab_sync_driver_sdk.device import DeviceCategory
+from lab_sync_driver_sdk.device import NestOffset
+from lab_sync_driver_sdk.host import serve
+
+__all__ = [
+    "Device",
+    "DeviceCategory",
+    "NestOffset",
+    "OutputValidationError",
+    "bool_in",
+    "bool_out",
+    "command",
+    "float_in",
+    "float_out",
+    "int_in",
+    "int_out",
+    "serve",
+    "settings",
+    "string_in",
+    "string_out",
+    "telemetry",
+]

lab_sync_driver_sdk/decorators.py

@@ -0,0 +1,349 @@
+"""Driver authoring decorators.
+
+A driver author annotates async methods on a `Device` subclass:
+
+    @command("Echo", "Echo the message")
+    @string_in("message", "text to echo")
+    @string_out("message", "echoed text")
+    async def echo(self, message: str = "") -> dict[str, object]:
+        return {"message": message}
+
+Decorators accumulate a CommandMeta on the function; the host runtime
+(`lab_sync_driver_sdk.host`) builds the Describe message from it and validates outputs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Protocol
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+# Wire type names (match the protocol ParamDescriptor.type and the SDK surface).
+TYPE_STRING = "string"
+TYPE_INT = "int"
+TYPE_FLOAT = "float"
+TYPE_BOOL = "bool"
+
+
+@dataclass
+class Param:
+    name: str
+    description: str
+    type: str
+    options: list[str] | None = None  # constrained-to-options choices, when the param is an enum
+    dynamic_options: bool = False  # options are computed by the driver at runtime (see describe-options)
+    maps_to: str | None = None
+    default: object = None
+    min_value: float | None = None
+    max_value: float | None = None
+    string_type: str | None = None
+    type_details: str | None = None
+    allow_empty: bool = False
+    group: str = ""
+
+
+@dataclass
+class CommandMeta:
+    name: str = ""
+    description: str = ""
+    inputs: list[Param] = field(default_factory=list[Param])
+    outputs: list[Param] = field(default_factory=list[Param])
+    exclusive: bool = True
+    concurrent: bool = False
+    category: str = ""  # display grouping in operator UIs; "" lands in the default group
+    operator_visible: bool = True  # hidden commands stay callable but are not listed for operators
+    default_sim_sec: float | None = None  # nominal duration, the UI's progress-bar estimate
+    # Workflow phase hint: setup/processing/teardown/maintenance/emergency, or
+    # storage_present/storage_receive/storage_store/storage_position/storage_inventory.
+    # "" is unset. See `command` for what each phase tells a scheduler.
+    operation_phase: str = ""
+    # The command simulates itself, so the host must not stand in for it by pacing
+    # out `default_sim_sec` and returning typed defaults.
+    handles_simulation: bool = False
+
+
+@dataclass
+class TelemetryMeta:
+    """Declaration of a sampler that runs only while somebody is watching.
+
+    A telemetry channel is the opposite of a command in every way that matters:
+    nobody asks for an individual reading, the frames are un-correlated (they
+    carry no request id), and a frame nobody wants should never be produced at
+    all. That last part is the reason this exists rather than a driver simply
+    publishing on a timer -- sampling usually costs a round trip on the same
+    link the device's real work goes over, so the supervisor tells the driver when to
+    start and stop, and the default is stopped.
+    """
+
+    channel: str = ""
+    hz: float = 5.0
+    description: str = ""
+
+
+_ATTR = "__studio_command__"
+_SETTINGS_ATTR = "__studio_settings__"
+_TELEMETRY_ATTR = "__studio_telemetry__"
+
+
+def _meta(fn: object) -> CommandMeta:
+    meta = getattr(fn, _ATTR, None)
+    if not isinstance(meta, CommandMeta):
+        meta = CommandMeta()
+        setattr(fn, _ATTR, meta)
+    return meta
+
+
+def get_command_meta(fn: object) -> CommandMeta | None:
+    meta = getattr(fn, _ATTR, None)
+    return meta if isinstance(meta, CommandMeta) else None
+
+
+def command(  # noqa: PLR0913 - the decorator surface is the API; each field is a distinct declaration
+    name: str,
+    description: str = "",
+    *,
+    exclusive: bool = True,
+    concurrent: bool = False,
+    category: str = "",
+    operator_visible: bool = True,
+    default_sim_sec: float | None = None,
+    operation_phase: str = "",
+    handles_simulation: bool = False,
+) -> Callable[[F], F]:
+    """Declare a command.
+
+    `exclusive` means it needs the device to itself: the supervisor admits it only when no other
+    exclusive command is in flight there, so hardware expecting one command at a time is not
+    driven twice at once. Clear it for a command that guards no physical resource.
+
+    `concurrent` allows several invocations of this same command at once, which a stateless
+    service device needs when every running sequence routes its steps through one instance.
+
+    `operation_phase` is a workflow phase hint — setup/processing/teardown/maintenance/emergency,
+    plus the storage phases for a storage device that acts on a plate's way in or out itself.
+    Leave it unset unless it is true: a scheduler treats every `processing` command as a step a
+    plate can be sent to, so marking a command that does not process a plate offers a
+    misleading step. A scheduler does not offer the storage phases as steps; it runs them
+    itself when a plate leaves or enters storage, each at a fixed point around the robot's pick
+    or place:
+
+    - `storage_present` fetches a plate onto the device's *own* nest, **before** the robot
+      picks it on a get.
+    - `storage_receive` gets the device ready to take a plate, **before** the robot places it
+      on a put — a stacker raising its stack so a plate set into its ring lands on top. Put
+      side only: it never runs before a get.
+    - `storage_store` files a plate away off the device's nest, **after** the robot placed it
+      on a put.
+    - `storage_position` moves the storage to the robot (a carousel turning a hotel round),
+      first on **both** sides.
+    - `storage_inventory` reports which barcode is in each location the supervisor asks about.
+
+    A put therefore runs `storage_position` -> `storage_receive` -> the robot ->
+    `storage_store`, skipping whichever the device does not declare. Pick by *when* the device
+    has to act: a command that must run before the robot lets go of the plate is
+    `storage_receive`, never `storage_store`.
+
+    `handles_simulation` says the command does its own simulation. Leave it clear and the host
+    stands in for a simulated device by pacing out `default_sim_sec` and returning typed
+    defaults; set it and the command body runs even in simulation.
+    """
+
+    def deco(fn: F) -> F:
+        meta = _meta(fn)
+        meta.name = name
+        meta.description = description
+        meta.exclusive = exclusive
+        meta.concurrent = concurrent
+        meta.category = category
+        meta.operator_visible = operator_visible
+        meta.default_sim_sec = default_sim_sec
+        meta.operation_phase = operation_phase
+        meta.handles_simulation = handles_simulation
+        return fn
+
+    return deco
+
+
+def get_telemetry_meta(fn: object) -> TelemetryMeta | None:
+    """The telemetry declaration on a method, or None if it has none."""
+    meta = getattr(fn, _TELEMETRY_ATTR, None)
+    return meta if isinstance(meta, TelemetryMeta) else None
+
+
+def telemetry(channel: str, *, hz: float = 5.0, description: str = "") -> Callable[[F], F]:
+    """Declare a demand-gated sampler.
+
+    The decorated method takes no arguments and returns a JSON-serializable
+    mapping -- one reading. The host calls it about `hz` times a second, but
+    **only while the supervisor says someone is watching**, and never before then: a
+    driver that is connected but unobserved samples nothing.
+
+    That gating is the whole point. Reading a robot's joint angles means a round
+    trip on the serial link its motion commands share, so doing it for a page
+    nobody has open would steal bandwidth from the hardware. The supervisor
+    switches a channel on only while something downstream is subscribed to it,
+    so the thing that switches the sampler on is the thing that wants the data.
+
+    `hz` is a ceiling and a target, not a guarantee: a sampler that takes longer
+    than its period simply runs less often, and one that raises is logged and
+    retried on the next tick rather than tearing the channel down. Neither a
+    slow device nor a flaky read should end the stream.
+
+        @telemetry("articulation", hz=10)
+        async def sample_joints(self) -> dict[str, object]:
+            return {"joints": dict(zip(JOINT_IDS, await self.read_joints()))}
+
+    Args:
+        channel: Channel name, unique on the device. The supervisor publishes
+            its readings under this name.
+        hz: How often to sample while demand is on.
+        description: What the channel carries, for humans reading a describe.
+    """
+
+    def deco(fn: F) -> F:
+        setattr(fn, _TELEMETRY_ATTR, TelemetryMeta(channel=channel, hz=hz, description=description))
+        return fn
+
+    return deco
+
+
+def settings() -> Callable[[F], F]:
+    """Declare the device's connection settings on a method (conventionally `connect`).
+
+    The input decorators stacked under this one describe the settings form the operator fills in; the host reports them in describe and passes
+    the saved values dict into `connect(settings)`. Decorate `connect` itself with one parameter per setting (named by `maps_to`, else the
+    display name) and the host binds and coerces them instead -- see `lab_sync_driver_sdk.settings_binding`. A settings method is not a command.
+    """
+
+    def deco(fn: F) -> F:
+        setattr(fn, _SETTINGS_ATTR, True)
+        return fn
+
+    return deco
+
+
+def is_settings_method(fn: object) -> bool:
+    return bool(getattr(fn, _SETTINGS_ATTR, False))
+
+
+class _InputFactory(Protocol):
+    def __call__(  # noqa: PLR0913 - mirrors the input-decorator surface
+        self,
+        name: str,
+        description: str = "",
+        *,
+        default: object = None,
+        maps_to: str | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        options: list[str] | None = None,
+        dynamic_options: bool = False,
+        string_type: str | None = None,
+        type_details: str | None = None,
+        allow_empty: bool = False,
+        group: str = "",
+    ) -> Callable[[F], F]: ...
+
+
+def _input(type_name: str) -> _InputFactory:
+    # insert(0) so that, since decorators apply bottom-up, source order is kept.
+    def make(  # noqa: PLR0913 - the decorator surface is the API; each field is a distinct declaration
+        name: str,
+        description: str = "",
+        *,
+        default: object = None,
+        maps_to: str | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        options: list[str] | None = None,
+        dynamic_options: bool = False,
+        string_type: str | None = None,
+        type_details: str | None = None,
+        allow_empty: bool = False,
+        group: str = "",
+    ) -> Callable[[F], F]:
+        def deco(fn: F) -> F:
+            _meta(fn).inputs.insert(
+                0,
+                Param(
+                    name,
+                    description,
+                    type_name,
+                    options=options,
+                    dynamic_options=dynamic_options,
+                    maps_to=maps_to,
+                    default=default,
+                    min_value=min_value,
+                    max_value=max_value,
+                    string_type=string_type,
+                    type_details=type_details,
+                    allow_empty=allow_empty,
+                    group=group,
+                ),
+            )
+            return fn
+
+        return deco
+
+    return make
+
+
+def _output(type_name: str) -> Callable[[str, str], Callable[[F], F]]:
+    def make(name: str, description: str = "") -> Callable[[F], F]:
+        def deco(fn: F) -> F:
+            _meta(fn).outputs.insert(0, Param(name, description, type_name))
+            return fn
+
+        return deco
+
+    return make
+
+
+string_in = _input(TYPE_STRING)
+int_in = _input(TYPE_INT)
+float_in = _input(TYPE_FLOAT)
+bool_in = _input(TYPE_BOOL)
+
+string_out = _output(TYPE_STRING)
+int_out = _output(TYPE_INT)
+float_out = _output(TYPE_FLOAT)
+bool_out = _output(TYPE_BOOL)
+
+
+def param_dict(param: Param) -> dict[str, object]:
+    """Serialize a Param to its wire descriptor (describe inputs / settings entries)."""
+    descriptor: dict[str, object] = {"name": param.name, "description": param.description, "type": param.type}
+    optional: dict[str, object | None] = {
+        "options": param.options,
+        "maps_to": param.maps_to,
+        "default": param.default,
+        "min_value": param.min_value,
+        "max_value": param.max_value,
+        "string_type": param.string_type,
+        "type_details": param.type_details,
+    }
+    descriptor.update({key: value for key, value in optional.items() if value is not None})
+    if param.dynamic_options:
+        descriptor["dynamic_options"] = True
+    if param.allow_empty:
+        descriptor["allow_empty"] = True
+    if param.group:
+        descriptor["group"] = param.group
+    return descriptor
+
+
+class OutputValidationError(Exception):
+    """A command returned fields not declared with an output decorator."""
+
+
+def validate_outputs(meta: CommandMeta, result: dict[str, object]) -> None:
+    """Raise `OutputValidationError` if the result has a field no output decorator declared."""
+    declared = {p.name for p in meta.outputs}
+    extra = set(result) - declared
+    if extra:
+        msg = f"command '{meta.name}' returned undeclared output fields: {sorted(extra)}"
+        raise OutputValidationError(msg)

lab_sync_driver_sdk/device.py

@@ -0,0 +1,234 @@
+"""The Device base class a driver subclasses."""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from collections.abc import Sequence
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+from typing import ClassVar
+
+from lab_sync_driver_protocol import CONFIGURATION_ENV
+
+from lab_sync_driver_sdk.decorators import CommandMeta
+from lab_sync_driver_sdk.decorators import TelemetryMeta
+from lab_sync_driver_sdk.decorators import get_command_meta
+from lab_sync_driver_sdk.decorators import get_telemetry_meta
+from lab_sync_driver_sdk.decorators import is_settings_method
+from lab_sync_driver_sdk.decorators import param_dict
+from lab_sync_driver_sdk.settings_binding import described_settings
+
+# How a driver may write one nest's offset in `Device.default_nests`: an
+# (x, y, z) sequence, an {"x": .., "y": .., "z": ..} mapping, or None when the
+# position is not known yet. `lab_sync_driver_sdk.host` normalizes all three onto the
+# wire, so a driver author picks whichever reads best.
+type NestOffset = Sequence[float] | Mapping[str, float] | None
+
+
+class DeviceCategory(StrEnum):
+    """What a device is for.
+
+    A scheduler reads it to find the plate handler that loads and unloads every
+    other device — hence `PLATE_HANDLING` rather than a generic "robot".
+
+    The value is carried as a plain string end to end and never validated
+    against this enum, so an out-of-tree driver declaring something else keeps
+    working; it simply matches nothing that looks a category up.
+    """
+
+    SEALING_PEELING = "sealing_peeling"
+    CAPPING_DECAPPING = "capping_decapping"
+    LABELING = "labeling"
+    PCR = "pcr"
+    LIQUID_HANDLING = "liquid_handling"
+    BARCODE_READING = "barcode_reading"
+    LABEL_PRINTING = "label_printing"
+    PLATE_HANDLING = "plate_handling"
+    MOBILE_ROBOT = "mobile_robot"
+    TRANSPORT = "transport"
+    STORAGE = "storage"
+    SHAKING = "shaking"
+    DETECTION = "detection"
+    SENSOR = "sensor"
+    ACTUATOR = "actuator"
+    MISC = "misc"
+
+
+class Device:
+    device_type_id: str = ""
+    manufacturer: str = ""
+    model: str = ""
+    category: str = DeviceCategory.MISC
+    is_simulated: bool = False
+    # Plain-language summary of what this device does. Describes only when set.
+    description: str = ""
+    # How the driver reaches its hardware (serial, tcp, sila, ...). Describes only when set.
+    integration_mode: str = ""
+    # Physical envelope in millimetres — right-handed, +Z up — for the 3D layout
+    # view. Leave any axis None and the view falls back to a default cube.
+    width_mm: float | None = None
+    depth_mm: float | None = None
+    height_mm: float | None = None
+    # GLB model for the 3D layout view, resolved relative to the directory of the
+    # module defining the driver subclass (an absolute path is also accepted).
+    # Describes only when set; the view falls back to a box when there is none.
+    model_path: str = ""
+    # Top-down image of the device for the layout views, resolved like `model_path`
+    # (relative to the driver's own directory; an absolute path is also accepted).
+    # Describes only when set; without one the supervisor serves a placeholder
+    # rectangle proportional to `width_mm` x `depth_mm`.
+    top_view_image_path: str = ""
+    # The labware positions this device holds, keyed by nest name. The value is
+    # the nest's offset from the device's own location in millimetres —
+    # right-handed, +Z up, the same frame as `width_mm`/`depth_mm`/`height_mm` —
+    # written as a `(x, y, z)` sequence or an `{"x": .., "y": .., "z": ..}` dict,
+    # or None for a nest whose position nobody has measured yet.
+    #
+    # Describes only when non-empty. The supervisor records each entry the
+    # first time the device is added, and an operator may reposition it after
+    # that — so this is the *default* layout a driver ships, not a live read of
+    # where the nests are now.
+    # ClassVar because a driver declares its nests on the class, the way it
+    # declares its envelope; that also lets a subclass annotate its own literal
+    # as a ClassVar, which the mutable-class-attribute lint requires of a dict.
+    default_nests: ClassVar[Mapping[str, NestOffset] | None] = None
+    # Hardware variants this one driver serves -- a robot with or without an
+    # optional rail, an instrument with a different deck -- when they change how
+    # the driver behaves without being a different device type. The first entry is
+    # the default. Describes only when non-empty; the operator then picks one when
+    # adding the device and the supervisor hands it back as `configuration`.
+    configurations: ClassVar[Sequence[str]] = ()
+
+    @property
+    def configuration(self) -> str | None:
+        """The variant this instance was added as: one of `configurations`, or None when the driver declares none.
+
+        The supervisor passes it in the process environment; unset (a device added
+        before the driver declared any) or unknown reads as the first.
+        """
+        if not self.configurations:
+            return None
+        chosen = os.environ.get(CONFIGURATION_ENV, "")
+        return chosen if chosen in self.configurations else self.configurations[0]
+
+    def agent_context(self) -> str:
+        """Return the long-form brief automated consumers read, or "" when there is none.
+
+        The default reads `agent_context.md` from the directory of the module that
+        defines the driver subclass, so each driver ships its own; the base class
+        has none and answers "".
+        """
+        module = sys.modules.get(type(self).__module__)
+        source = getattr(module, "__file__", None)
+        if source is None:
+            return ""
+        context_file = Path(source).parent / "agent_context.md"
+        return context_file.read_text(encoding="utf-8") if context_file.is_file() else ""
+
+    async def connect(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401 - gradual, so any override shape fits
+        """Open the device session.
+
+        Override as needed, in one of three shapes: no parameters;
+        `connect(self, settings)`, which receives the saved settings dict keyed by
+        display name; or `@settings()` on `connect` itself with one parameter per
+        setting, which the host binds and coerces (`lab_sync_driver_sdk.settings_binding`).
+        """
+        _ = (args, kwargs)
+
+    async def disconnect(self) -> None:
+        """Close the device session.
+
+        Override as needed.
+        """
+
+    async def set_simulation(self, *, enabled: bool) -> None:
+        """Toggle simulation mode live.
+
+        Override to open/close a sim backend.
+        """
+        self.is_simulated = enabled
+
+    def get_dynamic_parameter_options(
+        self,
+        command_name: str,
+        parameter_name: str,
+        parameters: dict[str, object] | None = None,
+    ) -> list[str]:
+        """Compute runtime choices for a `dynamic_options=True` string parameter.
+
+        `parameters` carries the current values of all of the command's inputs, so
+        one parameter's options can depend on another. Keep it cheap (called on
+        every operator keystroke, debounced) and best-effort: a raised exception
+        yields `[]` for that parameter rather than failing the request.
+        """
+        _ = (command_name, parameter_name, parameters)
+        return []
+
+    def get_dynamic_simulation_time_sec(self, command_name: str, parameters: dict[str, object]) -> float | None:
+        """Estimate how long one call of a command will take, from its inputs.
+
+        The supervisor asks before it runs a command (and from its estimated-time
+        route) and records the answer as the call's `estimated_duration_sec`, the
+        UI's progress-bar estimate. Override it when the duration depends on the
+        inputs or on the device's state -- a spin's time and speed, a move's
+        distance -- rather than being one number per command. `parameters` is
+        keyed by the inputs' declared (display) names, as an operator form holds
+        them. The default answers the command's `default_sim_sec`, or None when
+        it declares none; a raised exception falls back to that default too.
+
+        The name and signature match lab-device-sdk's, so a driver ported from it
+        keeps its override.
+        """
+        _ = parameters
+        spec = type(self).command_specs().get(command_name)
+        return spec[1].default_sim_sec if spec is not None else None
+
+    @classmethod
+    def command_specs(cls) -> dict[str, tuple[str, CommandMeta]]:
+        """Map command name -> (method attribute name, metadata)."""
+        specs: dict[str, tuple[str, CommandMeta]] = {}
+        for attr in dir(cls):
+            fn = getattr(cls, attr, None)
+            meta = get_command_meta(fn) if fn is not None else None
+            if meta is None:
+                continue
+            if not meta.name:
+                if is_settings_method(fn):
+                    continue  # a @settings method declares inputs but is not a command
+                if meta.inputs or meta.outputs:
+                    msg = f"{cls.__name__}.{attr} declares command params but is missing @command"
+                    raise ValueError(msg)
+                continue
+            specs[meta.name] = (attr, meta)
+        return specs
+
+    @classmethod
+    def telemetry_specs(cls) -> dict[str, tuple[str, TelemetryMeta]]:
+        """Map telemetry channel -> (method attribute name, metadata).
+
+        Empty for every driver that declares no `@telemetry` sampler, which is
+        all of them until one opts in -- and an empty mapping is omitted from
+        `describe` entirely, so such a driver describes exactly as it did
+        before telemetry existed.
+        """
+        specs: dict[str, tuple[str, TelemetryMeta]] = {}
+        for attr in dir(cls):
+            fn = getattr(cls, attr, None)
+            meta = get_telemetry_meta(fn) if fn is not None else None
+            if meta is None or not meta.channel:
+                continue
+            specs[meta.channel] = (attr, meta)
+        return specs
+
+    @classmethod
+    def settings_specs(cls) -> list[dict[str, object]]:
+        """Serialized settings descriptors from the `@settings`-decorated method, if any."""
+        for attr in dir(cls):
+            fn = getattr(cls, attr, None)
+            if fn is None or not is_settings_method(fn):
+                continue
+            return [param_dict(p) for p in described_settings(fn)]
+        return []