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

lab_sync_driver_sdk/lab_host.py

@@ -0,0 +1,543 @@
+"""Host a ``lab-device-sdk`` Device over the stdio driver protocol.
+
+A ``lab-device-sdk`` driver is written to be called in-process. This adapter
+wraps such a Device instance and presents the SDK host's structural
+contract -- translating lab command/param metadata and wire type names -- so
+the unchanged ``lab_sync_driver_sdk.host`` serves it out-of-process, with no rewrite of
+the driver. Install the ``lab`` extra (``pip install "lab-sync-driver-sdk[lab]"``).
+
+This host serves exactly one device, so it has to be told which instance it is.
+A manifest declares that with the supervisor's ``{device_id}`` token rather than
+a hardcoded id -- that is what lets a site run several devices of one type (the
+supervisor appends ``--http-port <n>`` when the driver serves routes)::
+
+    python -m lab_sync_driver_sdk.lab_host --device my_pkg.my_device:MyDevice \
+        --device-id {device_id}
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import contextlib
+import functools
+import importlib
+import inspect
+import json
+import logging
+import os
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import cast
+
+from lab_sync_driver_protocol import CONFIGURATION_ENV
+
+from lab_sync_driver_sdk.decorators import TYPE_STRING
+from lab_sync_driver_sdk.decorators import CommandMeta
+from lab_sync_driver_sdk.decorators import Param
+from lab_sync_driver_sdk.decorators import TelemetryMeta
+from lab_sync_driver_sdk.decorators import get_telemetry_meta
+from lab_sync_driver_sdk.host import Hostable
+from lab_sync_driver_sdk.host import claim_stdout
+from lab_sync_driver_sdk.host import serve
+from lab_sync_driver_sdk.host import valid_duration
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+    from collections.abc import Awaitable
+    from collections.abc import Callable
+
+    from fastapi import APIRouter
+    from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+# lab-device-sdk emits these wire type names; the driver protocol expects the short forms.
+_LAB_TYPE_MAP = {
+    "integer": "int",
+    "floating_point": "float",
+    "boolean": "bool",
+    "string": "string",
+}
+
+
+def _wire_type(lab_type: str) -> str:
+    if not lab_type:
+        return TYPE_STRING
+    mapped = _LAB_TYPE_MAP.get(lab_type)
+    if mapped is None:
+        logger.warning("lab driver param type %r has no wire mapping; defaulting to string", lab_type)
+        return TYPE_STRING
+    return mapped
+
+
+_IS_COMMAND = "_is_command"
+
+
+def _params(raw: object) -> list[Param]:
+    return [
+        Param(
+            name=str(entry.get("name", "")),
+            description=str(entry.get("description", "")),
+            type=_wire_type(str(entry.get("type", ""))),
+            options=_options(entry.get("options")),
+            dynamic_options=bool(entry.get("dynamic_options", False)),
+            maps_to=str(entry["maps_to"]) if entry.get("maps_to") is not None else None,
+            default=entry.get("default"),
+            min_value=cast("float | None", entry["min_value"]) if entry.get("min_value") is not None else None,
+            max_value=cast("float | None", entry["max_value"]) if entry.get("max_value") is not None else None,
+            string_type=str(entry["string_type"]) if entry.get("string_type") is not None else None,
+            type_details=str(entry["type_details"]) if entry.get("type_details") is not None else None,
+            allow_empty=bool(entry.get("allow_empty", False)),
+            group=str(entry.get("group", "")),
+        )
+        for entry in cast("list[dict[str, object]]", raw or [])
+    ]
+
+
+def _options(raw: object) -> list[str] | None:
+    if not raw:
+        return None
+    return [str(option) for option in cast("list[object]", raw)]
+
+
+def _marshal(result: object, out_names: list[str]) -> dict[str, object]:
+    """Shape a lab command's raw return into the SDK's dict-output contract.
+
+    lab commands return scalars/strings/None or tuples; the SDK host expects a dict keyed by the declared output params and validates against
+    them.
+    """
+    if isinstance(result, dict):
+        return cast("dict[str, object]", result)
+    if not out_names:
+        return {}
+    if len(out_names) == 1:
+        return {out_names[0]: result}
+    if isinstance(result, (list, tuple)):
+        items: list[object] = list(cast("list[object]", result))
+        if len(items) == len(out_names):
+            return {name: items[i] for i, name in enumerate(out_names)}
+    return {out_names[0]: result}
+
+
+_SIM_DEFAULT: dict[str, object] = {"int": 0, "float": 0.0, "bool": False}
+_SIM_PROGRESS_STEPS = 4
+
+
+def _sim_default(param: Param) -> object:
+    return _SIM_DEFAULT.get(param.type, "")
+
+
+async def _sim_run(seconds: float, progress: object, outputs: list[Param]) -> dict[str, object]:
+    """Fake a command: pace out default_sim_sec (streaming progress), return typed defaults."""
+    reporter = cast("Callable[[float, str], Awaitable[None]] | None", progress if callable(progress) else None)
+    for i in range(_SIM_PROGRESS_STEPS):
+        await asyncio.sleep(seconds / _SIM_PROGRESS_STEPS if seconds > 0 else 0)
+        if reporter is not None:
+            await reporter((i + 1) / _SIM_PROGRESS_STEPS, "simulating")
+    return {p.name: _sim_default(p) for p in outputs}
+
+
+@dataclass(frozen=True)
+class _InputSpec:
+    declared: str  # the name on the wire (the describe entry's `name`)
+    kwarg: str  # the method's actual parameter (lab `maps_to`)
+    default: object
+    has_default: bool
+
+
+def _input_specs(raw: object) -> list[_InputSpec]:
+    specs: list[_InputSpec] = []
+    for entry in cast("list[dict[str, object]]", raw or []):
+        name = str(entry.get("name", ""))
+        maps_to = entry.get("maps_to")
+        specs.append(
+            _InputSpec(
+                declared=name,
+                kwarg=str(maps_to) if maps_to else name,
+                default=entry.get("default"),
+                has_default="default" in entry,
+            )
+        )
+    return specs
+
+
+def _resolve_inputs(inputs: list[_InputSpec], provided: dict[str, object]) -> list[tuple[_InputSpec, object]]:
+    """Each declared input's value for one call, its declared default when omitted.
+
+    The SDK host has already remapped declared names to `maps_to` by the
+    time a wrapper runs, while a direct caller passes declared names, so
+    either spelling is accepted (declared first).
+    """
+    values: list[tuple[_InputSpec, object]] = []
+    for spec in inputs:
+        if spec.declared in provided:
+            values.append((spec, provided[spec.declared]))
+        elif spec.kwarg in provided:
+            values.append((spec, provided[spec.kwarg]))
+        elif spec.has_default:
+            values.append((spec, spec.default))
+    return values
+
+
+async def _sim_seconds(
+    sim_time: Callable[[dict[str, object]], object], declared: dict[str, object], fallback: float
+) -> float:
+    """How long to pace a simulated call: the device's own estimate, else `fallback`."""
+    try:
+        answer = sim_time(declared)
+        if inspect.isawaitable(answer):
+            answer = await answer
+    except Exception:  # an estimate must never fail the simulated command
+        logger.exception("simulation time hook failed; using default_sim_sec")
+        return fallback
+    seconds = valid_duration(answer)
+    return fallback if seconds is None else seconds
+
+
+def _wrap_command(
+    method: Callable[..., Awaitable[object]],
+    inputs: list[_InputSpec],
+    outputs: list[Param],
+    is_simulated: Callable[[], bool],
+    sim_time: Callable[[dict[str, object]], object] | None = None,
+) -> Callable[..., Awaitable[dict[str, object]]]:
+    """Bridge the SDK's call convention to a lab command.
+
+    Remap declared input names to the method's kwargs (lab `maps_to`), apply
+    declared defaults, then marshal the raw return into the studio dict-output
+    contract. When simulated, skip the hardware call and return typed defaults
+    unless the command opts into `handles_simulation` -- pacing out the
+    device's `get_dynamic_simulation_time_sec` for these inputs when `sim_time`
+    is given, as lab-device-sdk's own host did, else `default_sim_sec`.
+    """
+    out_names = [p.name for p in outputs]
+    handles_sim = bool(getattr(method, "_cmd_handles_simulation", False))
+    sim_sec = float(getattr(method, "_cmd_default_sim_sec", 3.0))
+
+    @functools.wraps(method)
+    async def wrapper(**provided: object) -> dict[str, object]:
+        values = _resolve_inputs(inputs, provided)
+        if is_simulated() and not handles_sim:
+            # The hook is keyed by declared (display) name, as `estimate_time` asks it.
+            declared = {spec.declared: value for spec, value in values}
+            seconds = sim_sec if sim_time is None else await _sim_seconds(sim_time, declared, sim_sec)
+            return await _sim_run(seconds, provided.get("progress"), outputs)
+        kwargs: dict[str, object] = {spec.kwarg: value for spec, value in values}
+        if "progress" in provided:
+            kwargs["progress"] = provided["progress"]
+        return _marshal(await method(**kwargs), out_names)
+
+    return wrapper
+
+
+def _telemetry_specs(device: object) -> dict[str, tuple[str, TelemetryMeta]]:
+    """Build SDK telemetry specs from a lab Device's decorated methods.
+
+    The mirror of `_command_specs`, and it is what makes `@telemetry` usable
+    from a driver written against lab-device-sdk rather than lab_sync_driver_sdk. The
+    decorator is lab_sync_driver_sdk's either way; only the base class differs.
+    """
+    specs: dict[str, tuple[str, TelemetryMeta]] = {}
+    for attr in dir(device):
+        fn = getattr(device, 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
+
+
+def _command_specs(device: object) -> dict[str, tuple[str, CommandMeta]]:
+    """Build SDK command specs from a lab Device's decorated methods."""
+    specs: dict[str, tuple[str, CommandMeta]] = {}
+    for attr in dir(device):
+        fn = getattr(device, attr, None)
+        if fn is None or not getattr(fn, _IS_COMMAND, False):
+            continue
+        name = str(getattr(fn, "_cmd_name", "") or attr)
+        raw_sim_sec = getattr(fn, "_cmd_default_sim_sec", None)
+        meta = CommandMeta(
+            name=name,
+            description=str(getattr(fn, "_cmd_desc", "")),
+            inputs=_params(getattr(fn, "_params_in", None)),
+            outputs=_params(getattr(fn, "_params_out", None)),
+            category=str(getattr(fn, "_cmd_category", "") or ""),
+            operator_visible=bool(getattr(fn, "_cmd_operator_visible", True)),
+            default_sim_sec=float(cast("float", raw_sim_sec)) if raw_sim_sec is not None else None,
+            # lab-device-sdk 0.1.12 stamps `_cmd_operation_phase`; older releases and
+            # hand-rolled metadata used the bare name. Read both so neither is dropped.
+            operation_phase=str(getattr(fn, "_cmd_operation_phase", None) or getattr(fn, "operation_phase", "") or ""),
+            handles_simulation=bool(getattr(fn, "_cmd_handles_simulation", False)),
+            # `@command(..., exclusive=False)` marks a command that may run beside an
+            # exclusive one (a light toggled while motion commands run, say).
+            # Dropping the flag would have the supervisor serialise them behind every move.
+            exclusive=bool(getattr(fn, "_cmd_exclusive", True)),
+            concurrent=bool(getattr(fn, "_cmd_concurrent", False)),
+        )
+        specs[name] = (attr, meta)
+    return specs
+
+
+class LabDeviceAdapter:
+    """Wrap a lab-device-sdk Device so the SDK host can serve it.
+
+    Attribute access (command methods, lifecycle) delegates to the wrapped device.
+    """
+
+    def __init__(self, device: object, config: dict[str, object] | None = None) -> None:
+        super().__init__()
+        self._device = device
+        self._config = config or {}
+        self._is_simulated = False
+        cls = type(device)
+        self.device_type_id = str(getattr(cls, "device_type_id", ""))
+        self.manufacturer = str(getattr(cls, "manufacturer", ""))
+        self.model = str(getattr(cls, "model", ""))
+        self._specs = _command_specs(device)
+        # Bind a bridging wrapper for each command so the host's
+        # getattr(device, method)(**declared) maps to the lab method + dict output.
+        hook = getattr(device, "get_dynamic_simulation_time_sec", None)
+        for attr, meta in self._specs.values():
+            method = cast("Callable[..., Awaitable[object]]", getattr(device, attr))
+            inputs = _input_specs(getattr(getattr(device, attr), "_params_in", None))
+            sim_time = functools.partial(hook, meta.name) if callable(hook) else None
+            setattr(
+                self,
+                attr,
+                _wrap_command(method, inputs, meta.outputs, lambda: self._is_simulated, sim_time),
+            )
+
+    def command_specs(self) -> dict[str, tuple[str, CommandMeta]]:
+        return self._specs
+
+    def telemetry_specs(self) -> dict[str, tuple[str, TelemetryMeta]]:
+        """The demand-gated samplers the wrapped device declares, if any."""
+        return _telemetry_specs(self._device)
+
+    def settings_specs(self) -> list[dict[str, object]]:
+        """Wire descriptors for the device's settings (its @settings connect params)."""
+        connect = getattr(self._device, "connect", None)
+        raw = getattr(connect, "_params_in", None) if connect is not None else None
+        specs: list[dict[str, object]] = []
+        for entry in cast("list[dict[str, object]]", raw or []):
+            spec: dict[str, object] = {
+                "name": str(entry.get("name", "")),
+                "description": str(entry.get("description", "")),
+                "type": _wire_type(str(entry.get("type", ""))),
+                "dynamic_options": bool(entry.get("dynamic_options", False)),
+            }
+            options = _options(entry.get("options"))
+            if options is not None:
+                spec["options"] = options
+            if entry.get("maps_to") is not None:
+                spec["maps_to"] = str(entry["maps_to"])
+            if "default" in entry:
+                spec["default"] = entry["default"]
+            for key in ("min_value", "max_value", "string_type", "type_details", "allow_empty", "group"):
+                if entry.get(key) is not None:
+                    spec[key] = entry[key]
+            specs.append(spec)
+        return specs
+
+    def picture(self) -> str | None:
+        """Return the device image as base64, resolved from the driver's picture_url."""
+        # The instance's, not the class's: a driver with configurations picks its
+        # picture per variant in `__init__`.
+        url = str(getattr(self._device, "picture_url", "") or "")
+        if not url:
+            return None
+        module = importlib.import_module(type(self._device).__module__)
+        module_file = getattr(module, "__file__", None)
+        if module_file is None:
+            return None
+        path = (Path(module_file).parent / url).resolve()
+        if not path.is_file():
+            return None
+        return base64.b64encode(path.read_bytes()).decode("ascii")
+
+    async def connect(self, settings: dict[str, object] | None = None) -> None:
+        # The protocol's connect carries one settings dict; lab connect is an @settings method
+        # with explicit params. Bind them from configuration, then apply any
+        # per-instance settings the user saved (keyed by the declared name -> maps_to).
+        if self._is_simulated:
+            return
+        connect = getattr(self._device, "connect", None)
+        if connect is None:
+            return
+        params = inspect.signature(connect).parameters
+        raw = cast("list[dict[str, object]]", getattr(connect, "_params_in", None) or [])
+        kwarg_by_name = {str(e.get("name", "")): str(e.get("maps_to") or e.get("name", "")) for e in raw}
+
+        # Start from the values the driver declares on its own @settings params.
+        # A lab connect takes them as *required* positional arguments, so any the
+        # operator has not overridden must still be supplied -- otherwise a device
+        # whose settings were never edited cannot connect at all.
+        kwargs: dict[str, object] = {}
+        for entry in raw:
+            kwarg = kwarg_by_name.get(str(entry.get("name", "")), "")
+            if kwarg in params and entry.get("default") is not None:
+                kwargs[kwarg] = entry["default"]
+
+        kwargs.update({name: self._config[name] for name in params if name in self._config})
+        for declared, value in (settings or {}).items():
+            kwarg = kwarg_by_name.get(declared, declared)
+            if kwarg in params:
+                kwargs[kwarg] = value
+        await connect(**kwargs)
+
+    async def set_simulation(self, *, enabled: bool) -> None:
+        """Gate hardware at the adapter; also poke the wrapped device if it tracks sim itself."""
+        self._is_simulated = enabled
+        setter = getattr(self._device, "set_simulation_mode", None)
+        if callable(setter):
+            with contextlib.suppress(TypeError):
+                _ = setter(enabled=enabled)
+        else:
+            with contextlib.suppress(AttributeError):
+                setattr(self._device, "is_simulated", enabled)
+
+    def __getattr__(self, name: str) -> object:
+        """Delegate lifecycle methods to the wrapped device."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(object.__getattribute__(self, "_device"), name)
+
+
+def _load_device(target: str, device_id: str, configuration: str | None) -> object:
+    module_name, _, class_name = target.partition(":")
+    if not class_name:
+        msg = f"--device must be 'module:Class', got {target!r}"
+        raise SystemExit(msg)
+    module = importlib.import_module(module_name)
+    cls = getattr(module, class_name)
+    return cls(device_id, configuration)
+
+
+class _LocalHub:
+    """Hub for the driver's own routes to resolve through.
+
+    Out-of-process, the driver process hosts exactly one device, so every lookup returns it -- the same `device_hub.get_device(id)` contract an
+    in-process hub provides.
+    """
+
+    def __init__(self, device: object) -> None:
+        super().__init__()
+        self._device = device
+
+    def get_device(self, device_id: str) -> object:
+        del device_id  # single-device process: every lookup returns the hosted device
+        return self._device
+
+
+def _http_app(device: object, routes_target: str) -> FastAPI | None:
+    """Build the driver's FastAPI app from its `get_routers(hub, state)` factory.
+
+    Inject a local hub. Returns None if the driver declares no routes.
+    """
+    module_name, _, factory_name = routes_target.partition(":")
+    try:
+        routes_module = importlib.import_module(module_name)
+    except ModuleNotFoundError:
+        return None
+    get_routers = getattr(routes_module, factory_name or "get_routers", None)
+    if get_routers is None:
+        return None
+
+    from fastapi import FastAPI  # noqa: PLC0415
+
+    get_hooks = getattr(routes_module, "get_lifespan_hooks", None)
+    hooks = cast("dict[str, Callable[[], Awaitable[None]]]", get_hooks()) if get_hooks else {}
+    startup = hooks.get("startup")
+    # An in-process host runs a driver's `shutdown` hook when the driver is
+    # replaced or the host stops; here the process ends when the supervisor
+    # closes stdin, but a driver holding sockets or a session open to hardware
+    # still wants to say goodbye rather than be dropped.
+    shutdown = hooks.get("shutdown")
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+        if startup is not None:
+            await startup()
+        try:
+            yield
+        finally:
+            if shutdown is not None:
+                await shutdown()
+
+    app = FastAPI(lifespan=lifespan)
+    routers = cast("list[APIRouter]", get_routers(_LocalHub(device), {}))
+    for router in routers:
+        app.include_router(router)
+    return app
+
+
+async def _serve_all(
+    device: Hostable,
+    *,
+    http_app: FastAPI | None,
+    http_port: int,
+    host: str,
+    driver_version: str,
+) -> None:
+    # Claim fd 1 for the protocol before uvicorn starts so its access logs (which
+    # default to stdout) cannot corrupt frames; serve() then reuses that stream.
+    out = claim_stdout()
+    if http_app is None:
+        await serve(device, driver_version=driver_version, out=out)
+        return
+    import uvicorn  # noqa: PLC0415
+
+    config = uvicorn.Config(http_app, host=host, port=http_port, log_level="warning", log_config=None)
+    server = uvicorn.Server(config)
+
+    async def _run_stdio() -> None:
+        try:
+            await serve(device, driver_version=driver_version, out=out)
+        finally:
+            server.should_exit = True  # stdin EOF ends the protocol -> stop the HTTP server so the process exits
+
+    _ = await asyncio.gather(_run_stdio(), server.serve())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="lab_sync_driver_sdk.lab_host")
+    _ = parser.add_argument("--device", required=True, help="import path 'module:Class'")
+    _ = parser.add_argument("--device-id", required=True)
+    _ = parser.add_argument("--config", default=None, help="JSON: connect settings to bind")
+    _ = parser.add_argument(
+        "--configuration",
+        default=os.environ.get(CONFIGURATION_ENV) or None,
+        help=f"hardware variant to construct the device as (default: ${CONFIGURATION_ENV})",
+    )
+    _ = parser.add_argument("--http-port", type=int, default=None, help="serve driver routes here")
+    _ = parser.add_argument("--routes", default=None, help="routes factory 'module:get_routers' (default <pkg>.routes)")
+    _ = parser.add_argument("--host", default="127.0.0.1", help="bind host for the HTTP routes")
+    _ = parser.add_argument("--driver-version", default="0.0.0")
+    args = parser.parse_args()
+
+    config = cast("dict[str, object]", json.loads(args.config)) if args.config else {}
+    device = _load_device(args.device, args.device_id, args.configuration)
+    adapter = LabDeviceAdapter(device, config)
+
+    http_app = None
+    if args.http_port is not None:
+        top_pkg = args.device.split(":", 1)[0].split(".", 1)[0]
+        http_app = _http_app(device, args.routes or f"{top_pkg}.routes:get_routers")
+
+    asyncio.run(
+        _serve_all(
+            adapter,
+            http_app=http_app,
+            http_port=args.http_port or 0,
+            host=args.host,
+            driver_version=args.driver_version,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()