embodied-ops 0.2.0__py3-none-any.whl

embodied_ops/__init__.py

@@ -0,0 +1,66 @@
+"""Public capability protocols for embodied systems."""
+
+from ._version import __version__
+from .device import (
+    API_VERSION,
+    CalibratableDevice,
+    Capability,
+    CommandDevice,
+    CommandLeaseDevice,
+    DeviceManifest,
+    HealthReport,
+    HealthStatus,
+    ObservableDevice,
+    OperationalDevice,
+    ResettableDevice,
+)
+from .errors import (
+    BackendConflictError,
+    BackendNotFoundError,
+    ContractError,
+    EmbodiedOpsError,
+    LifecycleError,
+    RpcError,
+)
+from .endpoints import unix_socket_path
+from .features import FeatureKind, FeatureSpec, index_features, validate_feature_values
+from .registry import (
+    BACKEND_ENTRY_POINT_GROUP,
+    BackendFactory,
+    BackendRegistry,
+    create_device,
+    default_registry,
+    device_session,
+)
+
+__all__ = [
+    "API_VERSION",
+    "BACKEND_ENTRY_POINT_GROUP",
+    "BackendConflictError",
+    "BackendFactory",
+    "BackendNotFoundError",
+    "BackendRegistry",
+    "CalibratableDevice",
+    "Capability",
+    "CommandDevice",
+    "CommandLeaseDevice",
+    "ContractError",
+    "DeviceManifest",
+    "EmbodiedOpsError",
+    "FeatureKind",
+    "FeatureSpec",
+    "HealthReport",
+    "HealthStatus",
+    "LifecycleError",
+    "ObservableDevice",
+    "OperationalDevice",
+    "ResettableDevice",
+    "RpcError",
+    "__version__",
+    "create_device",
+    "default_registry",
+    "device_session",
+    "index_features",
+    "unix_socket_path",
+    "validate_feature_values",
+]

embodied_ops/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

embodied_ops/device.py

@@ -0,0 +1,134 @@
+"""Capability-oriented device contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from types import MappingProxyType
+from typing import Protocol, runtime_checkable
+
+from .errors import ContractError
+from .features import FeatureSpec, index_features
+
+API_VERSION = 1
+
+
+class Capability(str, Enum):
+    OBSERVE = "observe"
+    COMMAND = "command"
+    HEALTH = "health"
+    CALIBRATE = "calibrate"
+    RESET = "reset"
+
+
+class HealthStatus(str, Enum):
+    UNKNOWN = "unknown"
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    FAULT = "fault"
+
+
+@dataclass(frozen=True, slots=True)
+class HealthReport:
+    status: HealthStatus
+    summary: str
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.summary:
+            raise ContractError("health summary must not be empty")
+        object.__setattr__(self, "details", MappingProxyType(dict(self.details)))
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceManifest:
+    """Backend-neutral description of one operational device."""
+
+    identifier: str
+    capabilities: tuple[Capability, ...]
+    observation_features: tuple[FeatureSpec, ...] = ()
+    action_features: tuple[FeatureSpec, ...] = ()
+    metadata: Mapping[str, str] = field(default_factory=dict)
+    api_version: int = API_VERSION
+
+    def __post_init__(self) -> None:
+        if not self.identifier or self.identifier.strip() != self.identifier:
+            raise ContractError(f"invalid device identifier: {self.identifier!r}")
+        if self.api_version != API_VERSION:
+            raise ContractError(
+                f"unsupported manifest API version {self.api_version}; expected {API_VERSION}"
+            )
+        if len(set(self.capabilities)) != len(self.capabilities):
+            raise ContractError("device capabilities must be unique")
+        index_features(self.observation_features)
+        index_features(self.action_features)
+        if self.observation_features and Capability.OBSERVE not in self.capabilities:
+            raise ContractError("observation features require the observe capability")
+        if self.action_features and Capability.COMMAND not in self.capabilities:
+            raise ContractError("action features require the command capability")
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "api_version": self.api_version,
+            "identifier": self.identifier,
+            "capabilities": [capability.value for capability in self.capabilities],
+            "observation_features": [feature.to_dict() for feature in self.observation_features],
+            "action_features": [feature.to_dict() for feature in self.action_features],
+            "metadata": dict(self.metadata),
+        }
+
+
+@runtime_checkable
+class OperationalDevice(Protocol):
+    """Minimum lifecycle and health surface implemented by every backend."""
+
+    @property
+    def manifest(self) -> DeviceManifest: ...
+
+    @property
+    def is_connected(self) -> bool: ...
+
+    def connect(self) -> None: ...
+
+    def health(self) -> HealthReport: ...
+
+    def disconnect(self) -> None: ...
+
+
+@runtime_checkable
+class ObservableDevice(OperationalDevice, Protocol):
+    def observe(self) -> Mapping[str, object]: ...
+
+
+@runtime_checkable
+class CommandDevice(OperationalDevice, Protocol):
+    def command(self, action: Mapping[str, object]) -> Mapping[str, object]: ...
+
+
+@runtime_checkable
+class CommandLeaseDevice(CommandDevice, Protocol):
+    """Optional hooks for transports that grant exclusive command ownership.
+
+    Observation resources may remain connected while a transport acquires and
+    releases the command path independently. Implementations must make release
+    fail closed and idempotent.
+    """
+
+    def acquire_command_lease(self) -> None: ...
+
+    def release_command_lease(self) -> None: ...
+
+
+@runtime_checkable
+class CalibratableDevice(OperationalDevice, Protocol):
+    @property
+    def is_calibrated(self) -> bool: ...
+
+    def calibrate(self) -> None: ...
+
+
+@runtime_checkable
+class ResettableDevice(OperationalDevice, Protocol):
+    def reset(self, target: str | None = None) -> None: ...

embodied_ops/endpoints.py

@@ -0,0 +1,22 @@
+"""Dependency-free transport endpoint validation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import ContractError
+
+UNIX_PREFIX = "unix://"
+
+
+def unix_socket_path(endpoint: str) -> Path:
+    if not isinstance(endpoint, str) or endpoint.strip() != endpoint:
+        raise ContractError(f"invalid RPC endpoint: {endpoint!r}")
+    if not endpoint.startswith("unix:///"):
+        raise ContractError("RPC endpoint must use an absolute unix:/// path")
+    path = Path(endpoint.removeprefix(UNIX_PREFIX))
+    if not path.is_absolute() or str(path) == "/":
+        raise ContractError("RPC Unix socket path must be absolute and non-root")
+    if len(str(path).encode()) > 100:
+        raise ContractError("RPC Unix socket path is too long for portable AF_UNIX use")
+    return path

embodied_ops/errors.py

@@ -0,0 +1,25 @@
+"""Public exception hierarchy for embodied-ops."""
+
+
+class EmbodiedOpsError(Exception):
+    """Base class for SDK errors."""
+
+
+class ContractError(EmbodiedOpsError, ValueError):
+    """A manifest, feature value, or backend violates the public contract."""
+
+
+class BackendNotFoundError(EmbodiedOpsError, LookupError):
+    """No installed backend is registered under the requested name."""
+
+
+class BackendConflictError(EmbodiedOpsError):
+    """More than one installed distribution owns the same backend name."""
+
+
+class LifecycleError(EmbodiedOpsError, RuntimeError):
+    """A device lifecycle operation is invalid or failed."""
+
+
+class RpcError(EmbodiedOpsError, RuntimeError):
+    """A versioned device RPC could not be completed."""

embodied_ops/features.py

@@ -0,0 +1,115 @@
+"""Feature manifests and hardware-free value validation."""
+
+from __future__ import annotations
+
+import math
+import numbers
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from types import MappingProxyType
+
+from .errors import ContractError
+
+
+class FeatureKind(str, Enum):
+    """Portable feature categories understood by SDK adapters."""
+
+    SCALAR = "scalar"
+    VECTOR = "vector"
+    IMAGE = "image"
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureSpec:
+    """Describes one named observation or action feature."""
+
+    name: str
+    kind: FeatureKind = FeatureKind.SCALAR
+    dtype: str = "float32"
+    shape: tuple[int, ...] = ()
+    unit: str | None = None
+    minimum: float | None = None
+    maximum: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name or self.name.strip() != self.name or any(c.isspace() for c in self.name):
+            raise ContractError(f"invalid feature name: {self.name!r}")
+        if not self.dtype:
+            raise ContractError(f"feature {self.name!r} requires a dtype")
+        if any(
+            not isinstance(size, int) or isinstance(size, bool) or size <= 0 for size in self.shape
+        ):
+            raise ContractError(f"feature {self.name!r} has an invalid shape: {self.shape!r}")
+        if self.kind is FeatureKind.SCALAR and self.shape:
+            raise ContractError(f"scalar feature {self.name!r} must have shape=()")
+        if self.kind is not FeatureKind.SCALAR and not self.shape:
+            raise ContractError(f"{self.kind.value} feature {self.name!r} requires a shape")
+        for label, value in (("minimum", self.minimum), ("maximum", self.maximum)):
+            if value is not None and not math.isfinite(float(value)):
+                raise ContractError(f"feature {self.name!r} has non-finite {label}")
+        if self.minimum is not None and self.maximum is not None and self.minimum > self.maximum:
+            raise ContractError(f"feature {self.name!r} minimum exceeds maximum")
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "kind": self.kind.value,
+            "dtype": self.dtype,
+            "shape": list(self.shape),
+            "unit": self.unit,
+            "minimum": self.minimum,
+            "maximum": self.maximum,
+        }
+
+
+def index_features(features: tuple[FeatureSpec, ...]) -> Mapping[str, FeatureSpec]:
+    """Return an immutable name index and reject ambiguous manifests."""
+
+    indexed: dict[str, FeatureSpec] = {}
+    for feature in features:
+        if feature.name in indexed:
+            raise ContractError(f"duplicate feature name: {feature.name!r}")
+        indexed[feature.name] = feature
+    return MappingProxyType(indexed)
+
+
+def validate_feature_values(
+    values: Mapping[str, object],
+    features: tuple[FeatureSpec, ...],
+    *,
+    exact: bool = True,
+) -> dict[str, object]:
+    """Validate a feature mapping without rewriting or clamping it.
+
+    Scalar values are checked exhaustively. Vector and image payload ownership stays
+    with the backend because this dependency-free SDK does not impose an array library.
+    """
+
+    specs = index_features(features)
+    keys = set(values)
+    expected = set(specs)
+    missing = expected - keys
+    unknown = keys - expected
+    if missing:
+        raise ContractError(f"missing feature values: {sorted(missing)}")
+    if exact and unknown:
+        raise ContractError(f"unknown feature values: {sorted(unknown)}")
+
+    validated: dict[str, object] = {}
+    for name, spec in specs.items():
+        value = values[name]
+        if spec.kind is FeatureKind.SCALAR:
+            if isinstance(value, bool) or not isinstance(value, numbers.Real):
+                raise ContractError(f"feature {name!r} must be a real scalar")
+            numeric = float(value)
+            if not math.isfinite(numeric):
+                raise ContractError(f"feature {name!r} must be finite")
+            if spec.minimum is not None and numeric < spec.minimum:
+                raise ContractError(f"feature {name!r} is below minimum {spec.minimum}")
+            if spec.maximum is not None and numeric > spec.maximum:
+                raise ContractError(f"feature {name!r} is above maximum {spec.maximum}")
+        validated[name] = value
+    if not exact:
+        validated.update((name, values[name]) for name in unknown)
+    return validated

embodied_ops/registry.py

@@ -0,0 +1,91 @@
+"""Backend discovery through standard Python package entry points."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from importlib import metadata
+
+from .device import OperationalDevice
+from .errors import BackendConflictError, BackendNotFoundError, ContractError
+
+BACKEND_ENTRY_POINT_GROUP = "embodied_ops.backends"
+BackendFactory = Callable[[Mapping[str, object]], OperationalDevice]
+
+
+class BackendRegistry:
+    """Resolve local factories and installed backend entry points by stable name."""
+
+    def __init__(self) -> None:
+        self._local: dict[str, BackendFactory] = {}
+
+    def register(self, name: str, factory: BackendFactory) -> None:
+        if not name or name.strip() != name or any(character.isspace() for character in name):
+            raise ContractError(f"invalid backend name: {name!r}")
+        if name in self._local:
+            raise BackendConflictError(f"backend {name!r} is already registered locally")
+        self._local[name] = factory
+
+    def unregister(self, name: str) -> None:
+        self._local.pop(name, None)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(set(self._local) | {entry.name for entry in self._entry_points()}))
+
+    def load(self, name: str) -> BackendFactory:
+        if name in self._local:
+            return self._local[name]
+        matches = [entry for entry in self._entry_points() if entry.name == name]
+        if not matches:
+            raise BackendNotFoundError(
+                f"backend {name!r} is not installed; available backends: {list(self.names())}"
+            )
+        if len(matches) > 1:
+            owners = sorted(
+                entry.dist.name if entry.dist is not None else "unknown" for entry in matches
+            )
+            raise BackendConflictError(
+                f"backend {name!r} is provided by multiple packages: {owners}"
+            )
+        factory = matches[0].load()
+        if not callable(factory):
+            raise ContractError(f"backend entry point {name!r} did not load a callable factory")
+        return factory
+
+    @staticmethod
+    def _entry_points() -> tuple[metadata.EntryPoint, ...]:
+        return tuple(metadata.entry_points(group=BACKEND_ENTRY_POINT_GROUP))
+
+
+default_registry = BackendRegistry()
+
+
+def create_device(
+    backend: str,
+    config: Mapping[str, object] | None = None,
+    *,
+    registry: BackendRegistry = default_registry,
+) -> OperationalDevice:
+    """Instantiate an installed backend without connecting to hardware."""
+
+    device = registry.load(backend)(dict(config or {}))
+    if not isinstance(device, OperationalDevice):
+        raise ContractError(f"backend {backend!r} does not implement OperationalDevice")
+    return device
+
+
+@contextmanager
+def device_session(
+    backend: str,
+    config: Mapping[str, object] | None = None,
+    *,
+    registry: BackendRegistry = default_registry,
+) -> Iterator[OperationalDevice]:
+    """Connect a backend and guarantee disconnect after success or failure."""
+
+    device = create_device(backend, config, registry=registry)
+    device.connect()
+    try:
+        yield device
+    finally:
+        device.disconnect()

embodied_ops/rpc/__init__.py

@@ -0,0 +1,13 @@
+"""Optional versioned RPC transport for embodied-ops devices."""
+
+from .client import RemoteDevice
+from .server import DeviceRpcServer
+from .types import PROTOCOL_VERSION, SessionMode, TensorValue
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "DeviceRpcServer",
+    "RemoteDevice",
+    "SessionMode",
+    "TensorValue",
+]

embodied_ops/rpc/_codec.py

@@ -0,0 +1,158 @@
+"""Strict protobuf conversion at the transport boundary."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from google.protobuf.json_format import MessageToDict, ParseDict
+from google.protobuf.struct_pb2 import Struct
+
+from embodied_ops.device import (
+    Capability,
+    DeviceManifest,
+    HealthReport,
+    HealthStatus,
+)
+from embodied_ops.errors import ContractError
+from embodied_ops.features import (
+    FeatureKind,
+    FeatureSpec,
+    index_features,
+    validate_feature_values,
+)
+from embodied_ops.rpc.types import TensorValue
+from embodied_ops.rpc.v1 import device_pb2
+
+
+def manifest_to_proto(manifest: DeviceManifest) -> device_pb2.DeviceManifest:
+    return device_pb2.DeviceManifest(
+        api_version=manifest.api_version,
+        identifier=manifest.identifier,
+        capabilities=[capability.value for capability in manifest.capabilities],
+        observation_features=[
+            feature_to_proto(feature) for feature in manifest.observation_features
+        ],
+        action_features=[feature_to_proto(feature) for feature in manifest.action_features],
+        metadata=dict(manifest.metadata),
+    )
+
+
+def manifest_from_proto(message: device_pb2.DeviceManifest) -> DeviceManifest:
+    return DeviceManifest(
+        api_version=message.api_version,
+        identifier=message.identifier,
+        capabilities=tuple(Capability(value) for value in message.capabilities),
+        observation_features=tuple(
+            feature_from_proto(feature) for feature in message.observation_features
+        ),
+        action_features=tuple(feature_from_proto(feature) for feature in message.action_features),
+        metadata=dict(message.metadata),
+    )
+
+
+def feature_to_proto(feature: FeatureSpec) -> device_pb2.FeatureSpec:
+    message = device_pb2.FeatureSpec(
+        name=feature.name,
+        kind=feature.kind.value,
+        dtype=feature.dtype,
+        shape=feature.shape,
+    )
+    if feature.unit is not None:
+        message.unit = feature.unit
+    if feature.minimum is not None:
+        message.minimum = feature.minimum
+    if feature.maximum is not None:
+        message.maximum = feature.maximum
+    return message
+
+
+def feature_from_proto(message: device_pb2.FeatureSpec) -> FeatureSpec:
+    return FeatureSpec(
+        name=message.name,
+        kind=FeatureKind(message.kind),
+        dtype=message.dtype,
+        shape=tuple(message.shape),
+        unit=message.unit if message.HasField("unit") else None,
+        minimum=message.minimum if message.HasField("minimum") else None,
+        maximum=message.maximum if message.HasField("maximum") else None,
+    )
+
+
+def values_to_proto(
+    values: Mapping[str, object], features: tuple[FeatureSpec, ...]
+) -> list[device_pb2.FeatureValue]:
+    validated = validate_feature_values(values, features)
+    messages: list[device_pb2.FeatureValue] = []
+    for feature in features:
+        value = validated[feature.name]
+        message = device_pb2.FeatureValue(name=feature.name)
+        if feature.kind is FeatureKind.SCALAR:
+            message.scalar = float(value)
+        else:
+            if not isinstance(value, TensorValue):
+                raise ContractError(
+                    f"feature {feature.name!r} requires an embodied_ops.rpc.TensorValue"
+                )
+            if value.dtype != feature.dtype or value.shape != feature.shape:
+                raise ContractError(
+                    f"feature {feature.name!r} tensor metadata does not match its manifest"
+                )
+            message.tensor.CopyFrom(
+                device_pb2.TensorPayload(
+                    dtype=value.dtype,
+                    shape=value.shape,
+                    data=value.data,
+                )
+            )
+        messages.append(message)
+    return messages
+
+
+def values_from_proto(
+    messages: Sequence[device_pb2.FeatureValue],
+    features: tuple[FeatureSpec, ...],
+) -> dict[str, object]:
+    specs = index_features(features)
+    values: dict[str, object] = {}
+    for message in messages:
+        if message.name in values:
+            raise ContractError(f"duplicate feature value: {message.name!r}")
+        try:
+            feature = specs[message.name]
+        except KeyError as exc:
+            raise ContractError(f"unknown feature value: {message.name!r}") from exc
+        payload = message.WhichOneof("payload")
+        if feature.kind is FeatureKind.SCALAR:
+            if payload != "scalar":
+                raise ContractError(f"feature {message.name!r} requires a scalar payload")
+            values[message.name] = message.scalar
+        else:
+            if payload != "tensor":
+                raise ContractError(f"feature {message.name!r} requires a tensor payload")
+            values[message.name] = TensorValue(
+                dtype=message.tensor.dtype,
+                shape=tuple(message.tensor.shape),
+                data=bytes(message.tensor.data),
+            )
+    return validate_feature_values(values, features)
+
+
+def health_to_proto(report: HealthReport) -> device_pb2.HealthResponse:
+    details = Struct()
+    try:
+        ParseDict(dict(report.details), details)
+    except (TypeError, ValueError) as exc:
+        raise ContractError("health details must be protobuf-Struct compatible") from exc
+    return device_pb2.HealthResponse(
+        status=report.status.value,
+        summary=report.summary,
+        details=details,
+    )
+
+
+def health_from_proto(message: device_pb2.HealthResponse) -> HealthReport:
+    return HealthReport(
+        status=HealthStatus(message.status),
+        summary=message.summary,
+        details=MessageToDict(message.details),
+    )