@camera.ui/server 2.0.22 → 2.0.24

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/plugin/interfaces.py

@@ -16,6 +16,7 @@ from typing import (
 from typing_extensions import TypeVar as ExtTypeVar
 
 from ..sensor import ClassifierDetection, Detection, FaceDetection, LicensePlateDetection
+from ..sensor.audio import AudioFrameData
 from ..sensor.clip import ClipEmbedding
 from ..sensor.motion import VideoFrameData
 from .api import PluginAPI
@@ -23,89 +24,121 @@ from .api import PluginAPI
 if TYPE_CHECKING:
     from ..camera import CameraConfig, CameraDevice
     from ..manager import DiscoveredCamera
+    from ..sensor.base import SensorLike
     from ..storage import DeviceStorage, JsonSchemaWithoutCallbacks
     from ..types import LoggerService
 
 from ..storage import JsonSchema
 
-# TypeVar for generic storage typing in BasePlugin
-# Using Mapping as bound since TypedDict is compatible with Mapping but not dict
+# bound is Mapping, not dict: TypedDict is compatible with Mapping only
 StorageT = ExtTypeVar("StorageT", bound=Mapping[str, Any], default=dict[str, Any])
-"""TypeVar for plugin storage values type. Defaults to dict[str, Any]."""
+"""Type of the plugin's storage values. Defaults to dict[str, Any]."""
 
 
 class ImageMetadata(TypedDict):
-    """Image metadata for detection test requests."""
+    """Image metadata passed to detector test methods."""
 
     width: int
+    """Image width in pixels."""
+
     height: int
+    """Image height in pixels."""
 
 
 class AudioMetadata(TypedDict):
-    """Audio metadata for detection test requests."""
+    """Audio metadata passed to audio detector test methods."""
 
     mimeType: Literal["audio/mpeg", "audio/wav", "audio/ogg"]
+    """Container format of the audio buffer."""
 
 
 class MotionDetectionPluginResponse(TypedDict):
-    """Response from a motion detection test."""
+    """Result of a motion detection run."""
 
     detected: bool
+    """True when the run produced at least one detection."""
+
     detections: list[Detection]
+    """Motion regions found in the input."""
+
     videoData: NotRequired[bytes]
+    """Annotated re-encoded clip for the UI test panel, when the plugin renders one."""
 
 
 class ObjectDetectionPluginResponse(TypedDict):
-    """Response from an object detection test."""
+    """Result of an object detection run."""
 
     detected: bool
+    """True when the run produced at least one detection."""
+
     detections: list[Detection]
+    """Detected objects with label, score and bounding box."""
 
 
 class AudioDetectionPluginResponse(TypedDict):
-    """Response from an audio detection test."""
+    """Result of an audio detection run."""
 
     detected: bool
+    """True when the run produced at least one detection."""
+
     detections: list[Detection]
+    """Detected audio events."""
+
     decibels: NotRequired[float]
+    """Loudness of the analysed buffer in dBFS."""
 
 
 class FaceDetectionPluginResponse(TypedDict):
-    """Response from a face detection test."""
+    """Result of a face detection run."""
 
     detected: bool
+    """True when the run produced at least one detection."""
+
     detections: list[FaceDetection]
+    """Detected faces, each with its embedding."""
+
     embeddingModel: NotRequired[str]
+    """Model that produced the embeddings; consumers must not mix models."""
 
 
 class LicensePlateDetectionPluginResponse(TypedDict):
-    """Response from a license plate detection test."""
+    """Result of a license plate detection run."""
 
     detected: bool
+    """True when the run produced at least one detection."""
+
     detections: list[LicensePlateDetection]
+    """Detected plates with their OCR text."""
 
 
 class ClassifierDetectionPluginResponse(TypedDict):
-    """Response from a classifier detection test."""
+    """Result of a classifier detection run."""
 
     detected: bool
+    """True when the run produced at least one classification."""
+
     detections: list[ClassifierDetection]
+    """Attribute/label pairs the classifier emitted."""
 
 
 class ClipDetectionPluginResponse(TypedDict):
-    """Response from a CLIP embedding test."""
+    """Result of a CLIP image embedding run."""
 
     embeddings: list[ClipEmbedding]
+    """Embedding vectors generated for the input."""
+
     embeddingModel: str
+    """Model that produced the embeddings; consumers must not mix models."""
 
 
 class ClipTextEmbeddingResult(TypedDict):
-    """Result of text-to-embedding conversion — a single embedding vector
-    plus the model name used to produce it, so downstream code can refuse to
-    mix embeddings from different models."""
+    """Result of a CLIP text embedding request."""
 
     embedding: list[float]
+    """Embedding vector for the query text."""
+
     embeddingModel: str
+    """Model that produced the embedding; consumers must not mix models."""
 
 
 class BasePlugin(ABC, Generic[StorageT]):
@@ -115,35 +148,25 @@ class BasePlugin(ABC, Generic[StorageT]):
     DeviceStorage) and declares the lifecycle methods the host calls on the
     plugin.
 
-    Lifecycle order: the host calls :meth:`configureCameras` once at startup
-    with every camera already assigned to this plugin, then calls
-    :meth:`onCameraAdded` / :meth:`onCameraReleased` as the user adds or
-    removes cameras at runtime.
-
-    The generic type parameter ``StorageT`` types ``storage.values`` so plugin
-    code gets autocompletion for its own settings shape.
+    The host calls :meth:`configureCameras` once at startup with every camera
+    already assigned to this plugin, then :meth:`onCameraAdded` /
+    :meth:`onCameraReleased` as the user adds or removes cameras at runtime.
+    ``StorageT`` types ``storage.values`` so plugin code gets autocompletion
+    for its own settings shape.
 
     Example:
         ```python
-        class MyStorageValues(TypedDict):
-            model_path: str
-            threshold: float
-
-
         class MyPlugin(BasePlugin[MyStorageValues]):
             async def configureCameras(self, cameras: list[CameraDevice]) -> None:
-                # storage.values is typed as MyStorageValues
-                model_path = self.storage.values.get("model_path")  # str
+                self.model_path = self.storage.values.get("model_path")
                 for camera in cameras:
                     await self.onCameraAdded(camera)
 
             async def onCameraAdded(self, camera: CameraDevice) -> None:
-                # Initialize camera controller
-                pass
+                self.state[camera.id] = await self.attach(camera)
 
             async def onCameraReleased(self, camera_id: str) -> None:
-                # Cleanup camera controller
-                pass
+                self.state.pop(camera_id, None)
         ```
     """
 
@@ -154,15 +177,14 @@ class BasePlugin(ABC, Generic[StorageT]):
 
     @property
     def storage_schema(self) -> list[JsonSchema]:
-        """Override to register a JSON schema for the plugin-level settings
-        form rendered in the UI. Default: no schema."""
+        """Override to register a JSON schema for the plugin-level settings form rendered in the UI. Default: no schema."""
         return []
 
     @abstractmethod
     async def configureCameras(self, cameras: list[CameraDevice]) -> None:
         """Called once on startup with every camera already assigned to this
-        plugin. The plugin should attach handlers, open vendor sessions, and
-        warm up models. Raising aborts plugin startup.
+        plugin. Attach handlers, open vendor sessions, warm up models here.
+        Raising aborts plugin startup.
 
         Args:
             cameras: Cameras already assigned to this plugin.
@@ -171,11 +193,10 @@ class BasePlugin(ABC, Generic[StorageT]):
 
     @abstractmethod
     async def onCameraAdded(self, camera: CameraDevice) -> None:
-        """Called whenever a camera is assigned to this plugin at runtime —
+        """Called whenever a camera is assigned to this plugin at runtime,
         after a discovery adoption (:meth:`DiscoveryProvider.onAdoptCamera`)
-        or after the user re-assigns an existing camera in the UI. The
-        plugin should set up the same per-camera state as in
-        :meth:`configureCameras`.
+        or after the user re-assigns an existing camera. Set up the same
+        per-camera state as in :meth:`configureCameras`.
 
         Args:
             camera: The camera device that was added.
@@ -185,14 +206,46 @@ class BasePlugin(ABC, Generic[StorageT]):
     @abstractmethod
     async def onCameraReleased(self, cameraId: str) -> None:
         """Called when a camera is unassigned from this plugin or deleted
-        from the system. The plugin must release per-camera resources
-        (sessions, timers, decoders) before returning.
+        from the system. Release per-camera resources (sessions, timers,
+        decoders) before returning.
 
         Args:
             cameraId: ID of the camera that was released.
         """
         ...
 
+    async def configureSensors(self, sensors: list[SensorLike]) -> None:
+        """Called once on startup with every sensor this plugin may consume:
+        sensors whose type is listed in ``contract.consumes`` and that are
+        exposed. Each sensor carries ``type``, ``assignedCameraIds`` and
+        ``connected``, so consumers decide rendering purely from that data.
+        Optional, only bridge plugins override it.
+
+        Args:
+            sensors: Consumable sensors known at startup.
+        """
+        return None
+
+    async def onSensorAdded(self, sensor: SensorLike) -> None:
+        """Called when a sensor enters this plugin's consumable view at
+        runtime: it was created, became exposed, or its type became
+        consumable.
+
+        Args:
+            sensor: The sensor that appeared.
+        """
+        return None
+
+    async def onSensorReleased(self, sensorId: str) -> None:
+        """Called when a sensor permanently leaves the consumable view: it
+        was deleted or unexposed. Plugin connectivity does NOT fire this,
+        watch ``sensor.onConnectedChanged`` for that.
+
+        Args:
+            sensorId: Persistent id of the sensor that left.
+        """
+        return None
+
 
 @runtime_checkable
 class DiscoveryProvider(Protocol):
@@ -212,7 +265,7 @@ class DiscoveryProvider(Protocol):
 
     async def onGetCameraSettings(self, camera: DiscoveredCamera) -> list[JsonSchemaWithoutCallbacks]:
         """Return a JSON schema describing the form fields (credentials,
-        transport options, ...) the user must fill in to adopt this specific
+        transport options, ...) the user must fill in to adopt this
         discovered camera.
 
         Args:
@@ -228,8 +281,7 @@ class DiscoveryProvider(Protocol):
     ) -> CameraConfig:
         """Probe the device with the user-provided settings and return the
         camera configuration the host should persist. The host then creates
-        the camera and invokes :meth:`BasePlugin.onCameraAdded` on the
-        plugin.
+        the camera and invokes :meth:`BasePlugin.onCameraAdded` on the plugin.
 
         Args:
             camera: The discovered camera being adopted.
@@ -243,85 +295,80 @@ class DiscoveryProvider(Protocol):
 
 @runtime_checkable
 class MotionDetectionInterface(Protocol):
-    """Interface implemented by plugins that perform video-based motion
-    detection. The host invokes :meth:`testMotionDetection` from the UI test
-    panel and :meth:`detectMotion` from automation / benchmark pipelines."""
+    """Implemented by plugins that perform video-based motion detection. The
+    host invokes :meth:`testMotionDetection` from the UI test panel and
+    :meth:`detectMotion` from automation / benchmark pipelines."""
 
     async def testMotionDetection(
         self, video_data: bytes, config: dict[str, Any]
     ) -> MotionDetectionPluginResponse | None:
-        """Run detection on a raw video buffer captured by the UI test panel
-        and return the result for preview rendering."""
+        """Run detection on a raw video buffer captured by the UI test panel and return the result for preview rendering."""
         ...
 
     async def detectMotion(
         self, frames: list[VideoFrameData], config: dict[str, Any] | None = None
     ) -> MotionDetectionPluginResponse | None:
-        """Run detection on already-decoded :class:`VideoFrameData`. Called
-        from automation / benchmark pipelines that supply pre-decoded frames
-        directly to avoid re-encoding."""
+        """Run detection on already-decoded frames, supplied by automation / benchmark pipelines to avoid re-encoding."""
         ...
 
     async def motionDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema used to render the motion-detection
-        settings form in the UI. Return None for no schema."""
+        """Return the JSON schema used to render the motion-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class ObjectDetectionInterface(Protocol):
-    """Interface implemented by plugins that perform object detection
-    (person, vehicle, animal, ...)."""
+    """Implemented by plugins that perform object detection (person, vehicle,
+    animal, ...)."""
 
     async def testObjectDetection(
         self, image_data: bytes, metadata: ImageMetadata, config: dict[str, Any]
     ) -> ObjectDetectionPluginResponse | None:
-        """Run detection on a single image captured by the UI test panel;
-        ``metadata`` carries the image dimensions."""
+        """Run detection on a single image captured by the UI test panel; ``metadata`` carries the image dimensions."""
         ...
 
     async def detectObjects(
         self, frame: VideoFrameData, config: dict[str, Any] | None = None
     ) -> ObjectDetectionPluginResponse | None:
-        """Run detection on a pre-decoded video frame. Called from
-        automation / benchmark pipelines."""
+        """Run detection on a pre-decoded video frame. Called from automation / benchmark pipelines."""
         ...
 
     async def objectDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema used to render the object-detection
-        settings form in the UI. Return None for no schema."""
+        """Return the JSON schema used to render the object-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class AudioDetectionInterface(Protocol):
-    """Interface implemented by plugins that perform audio event or keyword
-    detection."""
+    """Implemented by plugins that perform audio event or keyword detection."""
 
     async def testAudioDetection(
         self, audio_data: bytes, metadata: AudioMetadata, config: dict[str, Any]
     ) -> AudioDetectionPluginResponse | None:
-        """Run detection on an audio buffer captured by the UI test panel;
-        ``metadata`` carries the input MIME type (mpeg/wav/ogg)."""
+        """Run detection on an audio buffer captured by the UI test panel; ``metadata`` carries the input MIME type."""
+        ...
+
+    async def detectAudio(
+        self, audio: AudioFrameData, config: dict[str, Any] | None = None
+    ) -> AudioDetectionPluginResponse | None:
+        """Run detection on a pre-decoded audio frame. Called from automation / benchmark pipelines."""
         ...
 
     async def audioDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema used to render the audio-detection
-        settings form in the UI. Return None for no schema."""
+        """Return the JSON schema used to render the audio-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class FaceDetectionInterface(Protocol):
-    """Interface implemented by plugins that locate faces and emit per-face
-    embeddings. The NVR owns matching against enrolled faces; the plugin
-    only emits raw detections + embeddings."""
+    """Implemented by plugins that locate faces and emit per-face embeddings.
+    The NVR owns matching against enrolled faces, the plugin only emits raw
+    detections and embeddings."""
 
     async def testFaceDetection(
         self, image_data: bytes, metadata: ImageMetadata, config: dict[str, Any]
     ) -> FaceDetectionPluginResponse | None:
-        """Run face detection on a single image captured by the UI test
-        panel and return the result for preview rendering."""
+        """Run face detection on a single image captured by the UI test panel and return the result for preview rendering."""
         ...
 
     async def detectFaces(
@@ -331,21 +378,19 @@ class FaceDetectionInterface(Protocol):
         ...
 
     async def faceDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema for the face-detection settings form in
-        the UI. Return None for no schema."""
+        """Return the JSON schema for the face-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class LicensePlateDetectionInterface(Protocol):
-    """Interface implemented by plugins that locate license plates and run
-    OCR on them."""
+    """Implemented by plugins that locate license plates and run OCR on
+    them."""
 
     async def testLicensePlateDetection(
         self, image_data: bytes, metadata: ImageMetadata, config: dict[str, Any]
     ) -> LicensePlateDetectionPluginResponse | None:
-        """Run detection on a single image captured by the UI test panel and
-        return the result for preview rendering."""
+        """Run detection on a single image captured by the UI test panel and return the result for preview rendering."""
         ...
 
     async def detectLicensePlates(
@@ -355,21 +400,19 @@ class LicensePlateDetectionInterface(Protocol):
         ...
 
     async def licensePlateDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema for the license-plate-detection settings
-        form in the UI. Return None for no schema."""
+        """Return the JSON schema for the license-plate-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class ClassifierDetectionInterface(Protocol):
-    """Interface implemented by plugins that run a generic image classifier
-    and emit attribute/label pairs (e.g. weather, scene, activity)."""
+    """Implemented by plugins that run a generic image classifier and emit
+    attribute/label pairs (e.g. weather, scene, activity)."""
 
     async def testClassifierDetection(
         self, image_data: bytes, metadata: ImageMetadata, config: dict[str, Any]
     ) -> ClassifierDetectionPluginResponse | None:
-        """Run classification on a single image captured by the UI test
-        panel and return the result for preview rendering."""
+        """Run classification on a single image captured by the UI test panel and return the result for preview rendering."""
         ...
 
     async def detectClassifications(
@@ -379,21 +422,19 @@ class ClassifierDetectionInterface(Protocol):
         ...
 
     async def classifierDetectionSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema for the classifier-detection settings
-        form in the UI. Return None for no schema."""
+        """Return the JSON schema for the classifier-detection settings form in the UI, or None for no schema."""
         ...
 
 
 @runtime_checkable
 class ClipDetectionInterface(Protocol):
-    """Interface implemented by plugins that generate CLIP image and text
-    embeddings used for semantic search over recorded events."""
+    """Implemented by plugins that generate CLIP image and text embeddings
+    used for semantic search over recorded events."""
 
     async def testClipEmbedding(
         self, image_data: bytes, metadata: ImageMetadata, config: dict[str, Any]
     ) -> ClipDetectionPluginResponse | None:
-        """Run the CLIP image branch on a single image captured by the UI
-        test panel."""
+        """Run the CLIP image branch on a single image captured by the UI test panel."""
         ...
 
     async def detectClipEmbedding(
@@ -403,18 +444,14 @@ class ClipDetectionInterface(Protocol):
         ...
 
     async def getTextEmbedding(self, text: str) -> ClipTextEmbeddingResult:
-        """Run the CLIP text branch and return a single embedding vector
-        usable for semantic-search queries against previously stored image
-        embeddings."""
+        """Run the CLIP text branch and return a vector usable for semantic-search queries against stored image embeddings."""
         ...
 
     async def clipSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema for the CLIP settings form in the UI.
-        Return None for no schema."""
+        """Return the JSON schema for the CLIP settings form in the UI, or None for no schema."""
         ...
 
 
-# Union of all optional plugin interfaces.
 PluginInterfaces = (
     MotionDetectionInterface
     | ObjectDetectionInterface
@@ -425,3 +462,4 @@ PluginInterfaces = (
     | ClipDetectionInterface
     | DiscoveryProvider
 )
+"""Union of all optional plugin interfaces."""