@camera.ui/server 2.0.22 → 2.0.23

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/battery.py

@@ -11,7 +11,7 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class BatteryCapability(StrEnum):
-    """Optional capabilities for battery info sensors."""
+    """Optional capabilities of a battery info sensor."""
 
     LowBattery = "lowBattery"
     """Sensor reports low-battery alerts."""
@@ -20,14 +20,14 @@ class BatteryCapability(StrEnum):
 
 
 class BatteryProperty(StrEnum):
-    """Properties for battery info sensors."""
+    """Property names of a battery info sensor."""
 
     Level = "level"
     """Battery level percentage (0-100)."""
     Charging = "charging"
     """Current charging state."""
     Low = "low"
-    """Whether battery is critically low."""
+    """Whether the battery is critically low."""
 
 
 class ChargingState(StrEnum):
@@ -44,7 +44,7 @@ class ChargingState(StrEnum):
 
 
 class BatteryInfoProperties(TypedDict):
-    """Property value map for battery info sensors."""
+    """Property values of a battery info sensor."""
 
     level: int
     charging: ChargingState
@@ -52,10 +52,12 @@ class BatteryInfoProperties(TypedDict):
 
 
 class BatteryPropertyChangeData(TypedDict):
-    """Emitted on BatteryInfoLike.onPropertyChanged."""
+    """Property change payload emitted on BatteryInfoLike.onPropertyChanged."""
 
-    property: str  # BatteryProperty value
+    property: str
+    """Name of the changed property, a BatteryProperty value."""
     value: int | ChargingState | bool
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -69,6 +71,12 @@ class BatteryInfoLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Battery
 
+    @property
+    def onPropertyChanged(self) -> Observable[BatteryPropertyChangeData]: ...
+
+    @property
+    def onCapabilitiesChanged(self) -> Observable[list[BatteryCapability]]: ...
+
     @overload
     def getValue(self, property: Literal[BatteryProperty.Level]) -> int | None: ...
     @overload
@@ -78,24 +86,18 @@ class BatteryInfoLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[BatteryPropertyChangeData]: ...
-
-    @property
-    def onCapabilitiesChanged(self) -> Observable[list[BatteryCapability]]: ...
-
 
 class BatteryInfo(Sensor[BatteryInfoProperties, TStorage, BatteryCapability], Generic[TStorage]):
     """Battery info sensor. Reports battery level, charging state, and low-battery alerts.
 
-    Plugin authors call `setLevel(value)`, `setCharging(state)`, and `setLow(value)`
+    Plugin authors call ``setLevel(value)``, ``setCharging(state)``, and ``setLow(value)``
     to push updates from the device.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Battery") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Battery", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 BatteryProperty.Level.value: 100,
@@ -167,4 +169,3 @@ class BatteryInfo(Sensor[BatteryInfoProperties, TStorage, BatteryCapability], Ge
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — battery state is reported by the plugin, not set externally.

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/classifier.py

@@ -16,20 +16,25 @@ from .spec import ModelSpec
 class ClassifierProperty(StrEnum):
     """Property names of a classifier sensor."""
 
-    Detected = "detected"  # Whether any classification result is active
-    Detections = "detections"  # List of classification results with labels and confidence
-    Labels = "labels"  # Unique labels of the current detections (auto-derived when reporting detections)
+    Detected = "detected"
+    """Whether any classification result is active."""
+    Detections = "detections"
+    """List of classification results with labels and confidence."""
+    Labels = "labels"
+    """Unique labels of the current detections (auto-derived when reporting detections)."""
 
 
 class ClassifierDetection(Detection):
     """A classifier detection result with an open attribute for classifier categories."""
 
-    attribute: str  # type: ignore[misc]  # Classifier category (e.g. "bird", "delivery") — open string for any classifier
-    subAttribute: str  # Classifier sub-category (e.g. "woodpecker", "amazon")
+    attribute: str  # type: ignore[misc]
+    """Classifier category (e.g. "bird", "delivery"). Open string for any classifier."""
+    subAttribute: str
+    """Classifier sub-category (e.g. "woodpecker", "amazon")."""
 
 
 class ClassifierSensorProperties(TypedDict):
-    """Property shape carried by a ClassifierSensor."""
+    """Property values of a classifier sensor."""
 
     detected: bool
     detections: list[ClassifierDetection]
@@ -39,8 +44,10 @@ class ClassifierSensorProperties(TypedDict):
 class ClassifierPropertyChangeData(TypedDict):
     """Property change payload emitted on ClassifierSensorLike.onPropertyChanged."""
 
-    property: str  # ClassifierProperty value
+    property: str
+    """Name of the changed property, a ClassifierProperty value."""
     value: bool | list[ClassifierDetection] | list[str]
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -54,6 +61,9 @@ class ClassifierSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Classifier
 
+    @property
+    def onPropertyChanged(self) -> Observable[ClassifierPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[ClassifierProperty.Detected]) -> bool | None: ...
     @overload
@@ -65,21 +75,18 @@ class ClassifierSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[ClassifierPropertyChangeData]: ...
-
 
 class ClassifierSensor(Sensor[ClassifierSensorProperties, TStorage, str], Generic[TStorage]):
     """General-purpose image classifier sensor.
 
-    Plugin authors call `reportDetections(list)` to push classification results.
-    `detected` and `labels` are auto-derived from the detection list.
+    Plugin authors call ``reportDetections(list)`` to push classification results.
+    ``detected`` and ``labels`` are auto-derived from the detection list.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Classifier") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Classifier", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 ClassifierProperty.Detected.value: False,
@@ -98,28 +105,25 @@ class ClassifierSensor(Sensor[ClassifierSensorProperties, TStorage, str], Generi
 
     @property
     def detected(self) -> bool:
-        """Whether any classification result is active."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[ClassifierDetection]:
-        """Current detection list."""
         return self.props.detections or []
 
     @property
     def labels(self) -> list[str]:
-        """Unique labels of the current detections."""
         return self.props.labels or []
 
     def reportDetections(self, detected: bool, detections: list[ClassifierDetection] | None = None) -> None:
         """Report classification results. Auto-derives ``detected`` and
         ``labels`` from the list.
 
-        - ``reportDetections(True)`` — generic classification trigger. The SDK
+        - ``reportDetections(True)``: generic classification trigger. The SDK
           synthesizes a single full-frame detection with empty attribute and
           sub-attribute.
-        - ``reportDetections(True, [...])`` — explicit classifier detections.
-        - ``reportDetections(False)`` — clear.
+        - ``reportDetections(True, [...])``: explicit classifier detections.
+        - ``reportDetections(False)``: clear.
 
         Args:
             detected: Whether any classification result is active.
@@ -163,30 +167,30 @@ class ClassifierSensor(Sensor[ClassifierSensorProperties, TStorage, str], Generi
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — classifier state is reported by the plugin, not set externally.
 
 
 class ClassifierResult(TypedDict):
     """Return type for ClassifierDetectorSensor.detectClassifications()."""
 
-    detected: bool  # Whether any classification result is emitted for this frame
-    detections: list[ClassifierDetection]  # Detections emitted for this frame
+    detected: bool
+    """Whether any classification result is emitted for this frame."""
+    detections: list[ClassifierDetection]
+    """Detections emitted for this frame."""
 
 
 class ClassifierDetectorSensor(ClassifierSensor[TStorage], Generic[TStorage]):
     """Classifier detector that receives video frames from the backend pipeline.
 
     Extend this class and implement ``detectClassifications`` to run image
-    classification models against trigger regions.
+    classification models against trigger regions. The backend scales frames
+    to match ``modelSpec.input`` dimensions before each call.
     """
 
     _requires_frames = True
 
     @property
     @abstractmethod
-    def modelSpec(self) -> ModelSpec:
-        """Declares the expected input dimensions and trigger labels. The backend scales frames to match."""
-        ...
+    def modelSpec(self) -> ModelSpec: ...
 
     @abstractmethod
     async def detectClassifications(self, frames: list[VideoFrameData]) -> list[ClassifierResult]:

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/clip.py

@@ -14,16 +14,21 @@ from .spec import ModelSpec
 class ClipEmbedding(TypedDict):
     """A CLIP embedding result for a detected region."""
 
-    label: str  # Detection label this embedding was computed for (e.g. "person", "vehicle")
-    box: BoundingBox  # Bounding box of the detected region in normalized coordinates
-    embedding: list[float]  # CLIP embedding vector
+    label: str
+    """Detection label this embedding was computed for (e.g. "person", "vehicle")."""
+    box: BoundingBox
+    """Bounding box of the detected region in normalized coordinates."""
+    embedding: list[float]
+    """CLIP embedding vector."""
 
 
 class ClipResult(TypedDict):
     """Return type for ClipDetectorSensor.detectEmbeddings()."""
 
-    embeddings: list[ClipEmbedding]  # Embeddings emitted for this frame
-    embeddingModel: str  # Identifier of the embedding model used to produce the vectors
+    embeddings: list[ClipEmbedding]
+    """Embeddings emitted for this frame."""
+    embeddingModel: str
+    """Identifier of the embedding model used to produce the vectors."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -38,8 +43,8 @@ class ClipDetectorSensor(Sensor[dict[str, Any], TStorage, str], Generic[TStorage
 
     _requires_frames = True
 
-    def __init__(self, name: str = "CLIP Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "CLIP Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
 
     @property
     def type(self) -> SensorType:
@@ -51,9 +56,7 @@ class ClipDetectorSensor(Sensor[dict[str, Any], TStorage, str], Generic[TStorage
 
     @property
     @abstractmethod
-    def modelSpec(self) -> ModelSpec:
-        """Declares the expected input dimensions and trigger labels."""
-        ...
+    def modelSpec(self) -> ModelSpec: ...
 
     @abstractmethod
     async def detectEmbeddings(self, frames: list[VideoFrameData]) -> list[ClipResult]:
@@ -64,5 +67,4 @@ class ClipDetectorSensor(Sensor[dict[str, Any], TStorage, str], Generic[TStorage
         ...
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Frame-only sensor: no externally writable properties."""
-        # No-op — clip detector has no state.
+        """Read-only sensor: external writes are ignored."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/contact.py

@@ -11,23 +11,25 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class ContactProperty(StrEnum):
-    """Properties for contact sensors."""
+    """Property names of a contact sensor."""
 
     Detected = "detected"
     """Whether the contact is open (true = open, false = closed)."""
 
 
 class ContactSensorProperties(TypedDict):
-    """Property value map for contact sensors."""
+    """Property values of a contact sensor."""
 
     detected: bool
 
 
 class ContactPropertyChangeData(TypedDict):
-    """Emitted on ContactSensorLike.onPropertyChanged."""
+    """Property change payload emitted on ContactSensorLike.onPropertyChanged."""
 
-    property: str  # ContactProperty value
+    property: str
+    """Name of the changed property, a ContactProperty value."""
     value: bool
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -41,22 +43,22 @@ class ContactSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Contact
 
+    @property
+    def onPropertyChanged(self) -> Observable[ContactPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[ContactProperty.Detected]) -> bool | None: ...
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[ContactPropertyChangeData]: ...
-
 
 class ContactSensor(Sensor[ContactSensorProperties, TStorage, str], Generic[TStorage]):
     """Contact sensor for door/window open-close state."""
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Contact Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Contact Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state({ContactProperty.Detected.value: False})
 
     @property
@@ -86,4 +88,3 @@ class ContactSensor(Sensor[ContactSensorProperties, TStorage, str], Generic[TSto
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — contact state is reported by the plugin, not set externally.

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/detection.py

@@ -30,37 +30,49 @@ class BoundingBox(TypedDict):
     so they are independent of resolution.
     """
 
-    x: float  # X coordinate of the top-left corner (0-1)
-    y: float  # Y coordinate of the top-left corner (0-1)
-    width: float  # Width as a fraction of frame width (0-1)
-    height: float  # Height as a fraction of frame height (0-1)
+    x: float
+    """X coordinate of the top-left corner (0-1)."""
+    y: float
+    """Y coordinate of the top-left corner (0-1)."""
+    width: float
+    """Width as a fraction of frame width (0-1)."""
+    height: float
+    """Height as a fraction of frame height (0-1)."""
 
 
 class Detection(TypedDict):
     """A single detection result emitted by any detection sensor."""
 
-    label: DetectionLabel  # Detection label (e.g. "person", "vehicle")
-    confidence: float  # Confidence score in the range 0-1
-    box: BoundingBox  # Bounding box in normalized coordinates
-    attribute: NotRequired[
-        str
-    ]  # Optional sub-detection attribute (DetectionAttribute or classifier-specific)
+    label: DetectionLabel
+    """Detection label (e.g. "person", "vehicle")."""
+    confidence: float
+    """Confidence score in the range 0-1."""
+    box: BoundingBox
+    """Bounding box in normalized coordinates."""
+    attribute: NotRequired[str]
+    """Optional sub-detection attribute (DetectionAttribute or classifier-specific)."""
 
 
 class VideoFrameData(TypedDict):
     """Video frame data delivered to detector sensors by the backend pipeline.
 
-    The backend handles capture, decoding, and scaling — detectors only need
-    to process the pixel payload.
+    The backend handles capture, decoding and scaling. Detectors only process
+    the pixel payload.
     """
 
-    id: str  # Unique frame or crop identifier used to map batch results back to inputs
-    cameraId: NotRequired[str]  # Camera the frame originated from
-    data: bytes  # Raw pixel buffer
-    width: int  # Frame width in pixels
-    height: int  # Frame height in pixels
-    format: Literal[
-        "nv12", "rgb", "rgba", "gray"
-    ]  # Pixel format: rgb=3 bytes/pixel, rgba=4 bytes/pixel, gray=1 byte/pixel, nv12=YUV semi-planar
-    timestamp: NotRequired[int]  # Capture timestamp in milliseconds since epoch
-    label: NotRequired[str]  # Trigger label propagated by the coordinator for secondary detectors
+    id: str
+    """Unique frame or crop identifier used to map batch results back to inputs."""
+    cameraId: NotRequired[str]
+    """Camera the frame originated from."""
+    data: bytes
+    """Raw pixel buffer."""
+    width: int
+    """Frame width in pixels."""
+    height: int
+    """Frame height in pixels."""
+    format: Literal["nv12", "rgb", "rgba", "gray"]
+    """Pixel format: rgb=3 bytes/pixel, rgba=4 bytes/pixel, gray=1 byte/pixel, nv12=YUV semi-planar."""
+    timestamp: NotRequired[int]
+    """Capture timestamp in milliseconds since epoch."""
+    label: NotRequired[str]
+    """Trigger label propagated by the coordinator for secondary detectors."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/doorbell.py

@@ -12,23 +12,25 @@ from .base import Sensor, SensorCategory, SensorLike, SensorType
 
 
 class DoorbellProperty(StrEnum):
-    """Properties for doorbell triggers."""
+    """Property names of a doorbell trigger."""
 
     Ring = "ring"
     """Whether the doorbell is currently ringing."""
 
 
 class DoorbellTriggerProperties(TypedDict):
-    """Property value map for doorbell triggers."""
+    """Property values of a doorbell trigger."""
 
     ring: bool
 
 
 class DoorbellPropertyChangeData(TypedDict):
-    """Emitted on DoorbellTriggerLike.onPropertyChanged."""
+    """Property change payload emitted on DoorbellTriggerLike.onPropertyChanged."""
 
-    property: str  # DoorbellProperty value
+    property: str
+    """Name of the changed property, a DoorbellProperty value."""
     value: bool
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -42,32 +44,32 @@ class DoorbellTriggerLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Doorbell
 
+    @property
+    def onPropertyChanged(self) -> Observable[DoorbellPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[DoorbellProperty.Ring]) -> bool | None: ...
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[DoorbellPropertyChangeData]: ...
-
 
-#: Auto-reset duration after `trigger()` is called (ms).
+#: Auto-reset duration after ``trigger()`` is called (ms).
 RING_AUTO_RESET_MS = 2000
 
 
 class DoorbellTrigger(Sensor[DoorbellTriggerProperties, TStorage, str], Generic[TStorage]):
     """Doorbell trigger sensor.
 
-    Plugin authors call `trigger()` to fire a doorbell event. The `ring` property
-    is set to True and automatically reset to False after a short delay
-    (``RING_AUTO_RESET_MS``). Calling `trigger()` again while still ringing
-    resets the timer (extends the ring phase).
+    Plugin authors call ``trigger()`` to fire a doorbell event. The ``ring``
+    property is set to True and automatically reset to False after a short
+    delay (``RING_AUTO_RESET_MS``). Calling ``trigger()`` again while still
+    ringing resets the timer (extends the ring phase).
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Doorbell") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Doorbell", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._ring_reset_timer: threading.Timer | None = None
         self._write_state({DoorbellProperty.Ring.value: False})
 
@@ -107,11 +109,9 @@ class DoorbellTrigger(Sensor[DoorbellTriggerProperties, TStorage, str], Generic[
         self._ring_reset_timer.start()
 
     async def updateValue(self, property: str, value: Any) -> None:
-        """Cross-process consumer entry point. Writing ``ring=true`` (any
-        truthy value) dispatches to ``trigger()`` so a UI test button or
-        external automation can fire the doorbell using the same flow as a
-        real hardware ring (auto-reset included). Writing ``ring=false`` is
-        ignored — the auto-reset timer owns the off transition.
+        """Routes generic property writes to the semantic setters.
+
+        Writing ring=false is ignored, the auto-reset timer owns the off transition.
         """
         if property == DoorbellProperty.Ring.value and value:
             self.trigger()