qnbot-sdk-core 0.2.4__py3-none-any.whl

qnbot_sdk/core/__init__.py

@@ -0,0 +1,201 @@
+"""Core contracts and runtime for QnBot SDK."""
+
+from qnbot_sdk.core.buffer import BufferRecord, TimeSeriesBuffer
+from qnbot_sdk.core.calibration import CalibrationRecord, CalibrationStore
+from qnbot_sdk.core.config import (
+    AlgorithmConfig,
+    AlgorithmConfigInput,
+    AlgorithmGroup,
+    CalibrationConfig,
+    CalibrationInteractionKind,
+    ConnectionKind,
+    ConnectionSpec,
+    DebugConfig,
+    DeviceKind,
+    DeviceSpec,
+    ExternalConnection,
+    QnBotConfig,
+    SerialConnection,
+    Side,
+    Source,
+    SourceKind,
+    Target,
+    TargetKind,
+)
+from qnbot_sdk.core.device import Device
+from qnbot_sdk.core.driver import (
+    DeviceCommandWriter,
+    DeviceDriver,
+    SerialDiscoveryHook,
+    SerialEndpoint,
+    SerialFactory,
+    serial_connection_label,
+)
+from qnbot_sdk.core.keys import DataKeys
+from qnbot_sdk.core.models import (
+    ArmJointCommand,
+    DeviceStatus,
+    DiagnosticEvent,
+    DiagnosticLevel,
+    DiagnosticSample,
+    GloveHapticsCommand,
+    HandJointCommand,
+    HapticsCommand,
+    SafetyState,
+    Telemetry,
+    TelemetryMeta,
+)
+from qnbot_sdk.core.registry import (
+    BuilderContext,
+    DeviceFactory,
+    DriverFactory,
+    DriverFactoryKey,
+    ModuleRegistry,
+    QnBotModule,
+)
+from qnbot_sdk.core.retargeting import (
+    AlgorithmKind,
+    AlgorithmInfo,
+    AlgorithmMap,
+    Algorithm,
+    CalibrationAlgorithmEntry,
+    CalibrationMode,
+    CalibrationRequirement,
+    CalibrationResult,
+    CalibrationStage,
+    CalibrationStageSample,
+    Calibrator,
+    Retargeter,
+    RetargeterRegistry,
+    SourcePattern,
+    TargetPattern,
+    RetargetingAlgorithmEntry,
+    RetargetingBinding,
+    RetargetingBindingResolver,
+    RetargetingContext,
+    RetargetingPipeline,
+    RetargetingPlan,
+    RetargetingPlanResult,
+    RetargetingPreparation,
+    RetargetingResult,
+    ResolvedRetargetingBinding,
+    load_python_algorithm,
+    load_wheel_algorithm,
+    normalize_algorithm_manifest,
+    prepare_retargeting,
+)
+from qnbot_sdk.core.sdk import QnBotSDK
+from qnbot_sdk.core.system import (
+    CommandGate,
+    CalibrationController,
+    CalibrationInteraction,
+    ControlGate,
+    DeviceCommandController,
+    DiagnosticsEmitter,
+    HapticsController,
+    InputManager,
+    MissingRequiredCalibration,
+    OutputManager,
+    RecordingController,
+    RobotSystem,
+    RuntimeLoop,
+    SafetyController,
+    SystemBuilder,
+    WorkflowFacade,
+)
+
+__all__ = [
+    "ArmJointCommand",
+    "AlgorithmInfo",
+    "AlgorithmKind",
+    "AlgorithmMap",
+    "Algorithm",
+    "AlgorithmConfig",
+    "AlgorithmConfigInput",
+    "AlgorithmGroup",
+    "CalibrationAlgorithmEntry",
+    "CalibrationConfig",
+    "CalibrationInteractionKind",
+    "CalibrationMode",
+    "CalibrationRecord",
+    "CalibrationRequirement",
+    "CalibrationResult",
+    "CalibrationStore",
+    "CalibrationController",
+    "CalibrationInteraction",
+    "CalibrationStage",
+    "CalibrationStageSample",
+    "Calibrator",
+    "BuilderContext",
+    "BufferRecord",
+    "ConnectionKind",
+    "ConnectionSpec",
+    "CommandGate",
+    "ControlGate",
+    "DataKeys",
+    "DebugConfig",
+    "Device",
+    "DeviceCommandController",
+    "DeviceCommandWriter",
+    "DeviceDriver",
+    "DeviceKind",
+    "DeviceSpec",
+    "DeviceStatus",
+    "DeviceFactory",
+    "ExternalConnection",
+    "DiagnosticsEmitter",
+    "DiagnosticEvent",
+    "DiagnosticLevel",
+    "DiagnosticSample",
+    "DriverFactory",
+    "DriverFactoryKey",
+    "GloveHapticsCommand",
+    "HandJointCommand",
+    "HapticsCommand",
+    "HapticsController",
+    "InputManager",
+    "ModuleRegistry",
+    "MissingRequiredCalibration",
+    "OutputManager",
+    "QnBotConfig",
+    "QnBotModule",
+    "QnBotSDK",
+    "RecordingController",
+    "ResolvedRetargetingBinding",
+    "Retargeter",
+    "RetargeterRegistry",
+    "SourcePattern",
+    "TargetPattern",
+    "RetargetingAlgorithmEntry",
+    "RetargetingBinding",
+    "RetargetingBindingResolver",
+    "RetargetingContext",
+    "RetargetingPipeline",
+    "RetargetingPlan",
+    "RetargetingPlanResult",
+    "RetargetingPreparation",
+    "RetargetingResult",
+    "RobotSystem",
+    "RuntimeLoop",
+    "SafetyState",
+    "SafetyController",
+    "SerialConnection",
+    "SerialDiscoveryHook",
+    "SerialEndpoint",
+    "SerialFactory",
+    "Side",
+    "Source",
+    "SourceKind",
+    "Target",
+    "TargetKind",
+    "Telemetry",
+    "TelemetryMeta",
+    "TimeSeriesBuffer",
+    "SystemBuilder",
+    "WorkflowFacade",
+    "load_python_algorithm",
+    "load_wheel_algorithm",
+    "normalize_algorithm_manifest",
+    "prepare_retargeting",
+    "serial_connection_label",
+]

qnbot_sdk/core/buffer.py

@@ -0,0 +1,172 @@
+"""In-memory time-series buffer for SDK runtime state."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from math import inf, isfinite, nextafter
+from threading import Condition
+from time import monotonic
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class BufferRecord:
+    key: str
+    value: Any
+    timestamp: float
+    sequence: int
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+class TimeSeriesBuffer:
+    def __init__(
+        self,
+        *,
+        default_capacity: int = 1024,
+        capacities: Mapping[str, int] | None = None,
+        clock: Callable[[], float] = monotonic,
+    ) -> None:
+        if default_capacity <= 0:
+            raise ValueError("default_capacity must be positive")
+
+        self._default_capacity = default_capacity
+        self._capacities = dict(capacities or {})
+        for key, capacity in self._capacities.items():
+            if capacity <= 0:
+                raise ValueError(f"capacity for {key} must be positive")
+
+        self._clock = clock
+        self._records: dict[str, deque[BufferRecord]] = defaultdict(deque)
+        self._last_input_timestamps: dict[str, float] = {}
+        self._sequence = 0
+        self._condition = Condition()
+        self._subscribers: dict[str, list[Callable[[Any], None]]] = defaultdict(list)
+
+    def append(
+        self,
+        key: str,
+        value: Any,
+        *,
+        timestamp: float | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> BufferRecord:
+        with self._condition:
+            input_timestamp = float(self._clock() if timestamp is None else timestamp)
+            if not isfinite(input_timestamp):
+                raise ValueError(f"timestamp for {key} must be finite")
+
+            key_records = self._records[key]
+            last_input_timestamp = self._last_input_timestamps.get(key)
+            if (
+                last_input_timestamp is not None
+                and input_timestamp < last_input_timestamp
+            ):
+                raise ValueError(
+                    f"timestamps for {key} must be monotonic non-decreasing"
+                )
+
+            stored_timestamp = input_timestamp
+            if key_records and stored_timestamp <= key_records[-1].timestamp:
+                stored_timestamp = nextafter(key_records[-1].timestamp, inf)
+                if not isfinite(stored_timestamp):
+                    raise ValueError(f"timestamp precision exhausted for {key}")
+
+            self._sequence += 1
+            record = BufferRecord(
+                key=key,
+                value=value,
+                timestamp=stored_timestamp,
+                sequence=self._sequence,
+                metadata=dict(metadata or {}),
+            )
+
+            key_records.append(record)
+            self._last_input_timestamps[key] = input_timestamp
+            while len(key_records) > self._capacity_for(key):
+                key_records.popleft()
+            self._condition.notify_all()
+            subscribers = tuple(self._subscribers.get(key, ()))
+        for subscriber in subscribers:
+            subscriber(value)
+        return record
+
+    def latest(self, key: str, default: Any = None) -> Any:
+        record = self.latest_record(key)
+        if record is None:
+            return default
+        return record.value
+
+    def latest_record(self, key: str) -> BufferRecord | None:
+        with self._condition:
+            return self._latest_record_unlocked(key)
+
+    def records(self, key: str) -> list[BufferRecord]:
+        with self._condition:
+            return list(self._records.get(key, ()))
+
+    def keys(self) -> tuple[str, ...]:
+        with self._condition:
+            return tuple(self._records.keys())
+
+    def subscribe(self, key: str, callback: Callable[[Any], None]) -> None:
+        with self._condition:
+            self._subscribers[key].append(callback)
+
+    def unsubscribe(self, key: str, callback: Callable[[Any], None]) -> None:
+        with self._condition:
+            subscribers = self._subscribers.get(key, [])
+            remaining = [subscriber for subscriber in subscribers if subscriber is not callback]
+            if remaining:
+                self._subscribers[key] = remaining
+            else:
+                self._subscribers.pop(key, None)
+
+    def wait_next_data(
+        self,
+        key: str,
+        *,
+        after_sequence: int | None = None,
+        timeout: float | None = None,
+    ) -> BufferRecord | None:
+        deadline = None if timeout is None else monotonic() + timeout
+        with self._condition:
+            if after_sequence is None:
+                start_record = self._latest_record_unlocked(key)
+                start_sequence = 0 if start_record is None else start_record.sequence
+            else:
+                start_sequence = after_sequence
+            while True:
+                record = self._first_record_after_unlocked(key, start_sequence)
+                if record is not None:
+                    return record
+                if deadline is None:
+                    self._condition.wait()
+                    continue
+                remaining = deadline - monotonic()
+                if remaining <= 0:
+                    return None
+                self._condition.wait(remaining)
+
+    def _latest_record_unlocked(self, key: str) -> BufferRecord | None:
+        key_records = self._records.get(key)
+        if not key_records:
+            return None
+        return key_records[-1]
+
+    def _first_record_after_unlocked(
+        self,
+        key: str,
+        sequence: int,
+    ) -> BufferRecord | None:
+        key_records = self._records.get(key)
+        if not key_records:
+            return None
+        for record in key_records:
+            if record.sequence > sequence:
+                return record
+        return None
+
+    def _capacity_for(self, key: str) -> int:
+        return self._capacities.get(key, self._default_capacity)

qnbot_sdk/core/calibration.py

@@ -0,0 +1,296 @@
+"""Calibration record storage contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from time import monotonic
+from typing import Any
+from uuid import uuid4
+
+import yaml
+from packaging.version import InvalidVersion, Version
+
+from qnbot_sdk.core.config import Side, Source, SourceKind, Target, TargetKind
+
+
+@dataclass(frozen=True, slots=True)
+class CalibrationRecord:
+    source: Source
+    target: Target
+    retargeting_algorithm_id: str
+    retargeting_algorithm_version: str | None = None
+    calibration_algorithm_id: str | None = None
+    calibration_algorithm_version: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+    diagnostics: dict[str, Any] = field(default_factory=dict)
+    operator_id: str | None = None
+    record_id: str = field(default_factory=lambda: uuid4().hex)
+    created_at: float = field(default_factory=monotonic)
+
+
+class CalibrationStore:
+    def __init__(
+        self,
+        records: list[CalibrationRecord] | tuple[CalibrationRecord, ...] = (),
+        *,
+        path: str | Path | None = None,
+    ) -> None:
+        self.path = None if path is None else Path(path)
+        self._records = list(records)
+
+    @classmethod
+    def default(cls, *, load: bool = True) -> CalibrationStore:
+        store = cls(path=Path.home() / ".qnbot" / "calibrations")
+        if load:
+            store.load()
+        return store
+
+    @property
+    def records(self) -> tuple[CalibrationRecord, ...]:
+        return tuple(self._records)
+
+    def find(
+        self,
+        *,
+        source: Source,
+        target: Target,
+        retargeting_algorithm_id: str | None = None,
+        retargeting_algorithm_version: str | None = None,
+        calibration_algorithm_id: str | None = None,
+        calibration_algorithm_version: str | None = None,
+        minimum_calibration_version: str | None = None,
+        operator_id: str | None = None,
+        match_operator: bool = False,
+    ) -> CalibrationRecord | None:
+        matches = [
+            record
+            for record in self._records
+            if record.source == source
+            and record.target == target
+            and (
+                calibration_algorithm_id is not None
+                or retargeting_algorithm_id is None
+                or record.retargeting_algorithm_id == retargeting_algorithm_id
+            )
+            and (
+                calibration_algorithm_id is None
+                or record.calibration_algorithm_id == calibration_algorithm_id
+            )
+            and (
+                calibration_algorithm_version is None
+                or _version_at_most(
+                    record.calibration_algorithm_version,
+                    calibration_algorithm_version,
+                )
+            )
+            and (
+                minimum_calibration_version is None
+                or _version_at_least(
+                    record.calibration_algorithm_version,
+                    minimum_calibration_version,
+                )
+            )
+            and (not match_operator or record.operator_id == operator_id)
+        ]
+        if not matches:
+            return None
+        return matches[0]
+
+    def add(self, record: CalibrationRecord) -> CalibrationRecord:
+        self._records = [
+            existing
+            for existing in self._records
+            if _record_identity(existing) != _record_identity(record)
+        ]
+        self._records.append(record)
+        self.save()
+        return record
+
+    def load(self) -> None:
+        if self.path is None or not self.path.exists():
+            return
+        records: list[CalibrationRecord] = []
+        for path in sorted(self.path.glob("*/hand_system.yaml")):
+            record = _record_from_hand_system_yaml(
+                yaml.safe_load(path.read_text(encoding="utf-8")),
+            )
+            if record is not None:
+                records.append(record)
+        self._records = records
+
+    def save(self) -> None:
+        if self.path is None:
+            return
+        self.path.mkdir(parents=True, exist_ok=True)
+        for record in self._records:
+            hand_system_path = self.hand_system_path_for(record)
+            hand_system_path.parent.mkdir(parents=True, exist_ok=True)
+            hand_system_path.write_text(
+                yaml.safe_dump(
+                    _record_to_hand_system_yaml(record),
+                    allow_unicode=True,
+                    sort_keys=True,
+                ),
+                encoding="utf-8",
+            )
+
+    def path_for(self, record: CalibrationRecord) -> Path:
+        if self.path is None:
+            raise ValueError("calibration store path is not configured")
+        return self.hand_system_path_for(record)
+
+    def hand_system_path_for(self, record: CalibrationRecord) -> Path:
+        if self.path is None:
+            raise ValueError("calibration store path is not configured")
+        return self.path / _identity_stem(record) / "hand_system.yaml"
+
+
+def default_hand_system_path(record: CalibrationRecord) -> Path:
+    return CalibrationStore.default(load=False).hand_system_path_for(record)
+
+
+def _record_to_hand_system_yaml(record: CalibrationRecord) -> dict[str, Any]:
+    return {
+        "_metadata": {
+            "schema": "qnbot.hand_system.v1",
+            "record_id": record.record_id,
+            "source": _source_to_yaml(record.source),
+            "target": _target_to_yaml(record.target),
+            "retargeting_algorithm": {
+                "id": record.retargeting_algorithm_id,
+                "version": record.retargeting_algorithm_version,
+            },
+            "calibration_algorithm": {
+                "id": record.calibration_algorithm_id,
+                "version": record.calibration_algorithm_version,
+            },
+            "operator_id": record.operator_id,
+            "created_at": record.created_at,
+            "diagnostics": record.diagnostics,
+        },
+        "data": record.data,
+    }
+
+
+def _record_identity(
+    record: CalibrationRecord,
+) -> tuple[Source, Target, str | None, str | None]:
+    return (
+        record.source,
+        record.target,
+        record.calibration_algorithm_id,
+        record.operator_id,
+    )
+
+
+def _identity_stem(record: CalibrationRecord) -> str:
+    parts = [
+        "operator",
+        _filename_part(record.operator_id),
+        "source",
+        _filename_part(record.source.id),
+        "target",
+        _filename_part(record.target.id),
+        "calibration",
+        _filename_part(record.calibration_algorithm_id),
+    ]
+    return "__".join(parts)
+
+
+def _filename_part(value: str | None) -> str:
+    if value is None or value == "":
+        return "none"
+    return "".join(
+        character
+        if character.isalnum() or character in {".", "-", "_"}
+        else "-"
+        for character in value
+    )
+
+
+def _record_from_hand_system_yaml(data: object) -> CalibrationRecord | None:
+    if not isinstance(data, dict):
+        return None
+    metadata = data.get("_metadata")
+    if not isinstance(metadata, dict) or metadata.get("schema") != "qnbot.hand_system.v1":
+        return None
+    calibration_algorithm = metadata.get("calibration_algorithm", {})
+    retargeting_algorithm = metadata.get("retargeting_algorithm", {})
+    if not isinstance(calibration_algorithm, dict) or not isinstance(
+        retargeting_algorithm,
+        dict,
+    ):
+        return None
+    return CalibrationRecord(
+        source=_source_from_yaml(metadata["source"]),
+        target=_target_from_yaml(metadata["target"]),
+        retargeting_algorithm_id=retargeting_algorithm.get("id"),
+        retargeting_algorithm_version=retargeting_algorithm.get("version"),
+        calibration_algorithm_id=calibration_algorithm.get("id"),
+        calibration_algorithm_version=calibration_algorithm.get("version"),
+        data=dict(data.get("data", {})),
+        diagnostics=dict(metadata.get("diagnostics", {})),
+        operator_id=metadata.get("operator_id"),
+        record_id=metadata["record_id"],
+        created_at=float(metadata["created_at"]),
+    )
+
+
+def _source_to_yaml(source: Source) -> dict[str, str | None]:
+    return {
+        "kind": source.kind.value,
+        "name": source.name,
+        "side": None if source.side is None else source.side.value,
+        "id": source.id,
+    }
+
+
+def _target_to_yaml(target: Target) -> dict[str, str | None]:
+    return {
+        "kind": target.kind.value,
+        "name": target.name,
+        "side": None if target.side is None else target.side.value,
+        "id": target.id,
+    }
+
+
+def _source_from_yaml(data: dict[str, Any]) -> Source:
+    return Source(
+        kind=SourceKind(data["kind"]),
+        name=data.get("name"),
+        side=_optional_side(data.get("side")),
+    )
+
+
+def _target_from_yaml(data: dict[str, Any]) -> Target:
+    return Target(
+        kind=TargetKind(data["kind"]),
+        name=data.get("name"),
+        side=_optional_side(data.get("side")),
+    )
+
+
+def _optional_side(value: Any) -> Side | None:
+    if value is None:
+        return None
+    return Side(value)
+
+
+def _version_at_least(actual: str | None, minimum: str) -> bool:
+    if actual is None:
+        return False
+    return _parse_calibration_version(actual) >= _parse_calibration_version(minimum)
+
+
+def _version_at_most(actual: str | None, maximum: str) -> bool:
+    if actual is None:
+        return False
+    return _parse_calibration_version(actual) <= _parse_calibration_version(maximum)
+
+
+def _parse_calibration_version(version: str) -> Version:
+    try:
+        return Version(version)
+    except InvalidVersion as exc:
+        raise ValueError(f"invalid calibration version: {version}") from exc

qnbot_sdk/core/compat.py

@@ -0,0 +1,14 @@
+"""Compatibility helpers for supported Python versions."""
+
+from __future__ import annotations
+
+try:
+    from enum import StrEnum
+except ImportError:  # pragma: no cover - exercised on Python 3.10.
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        pass
+
+
+__all__ = ["StrEnum"]