@camera.ui/server 0.0.70 → 0.0.71

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

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    NotRequired,
+    Protocol,
+    TypedDict,
+    runtime_checkable,
+)
+
+from typing_extensions import TypeVar as ExtTypeVar
+
+from ..sensor import ClassifierDetection, Detection, FaceDetection, LicensePlateDetection
+from ..sensor.clip import ClipEmbedding
+from ..sensor.motion import VideoFrameData
+from .api import PluginAPI
+
+if TYPE_CHECKING:
+    from ..camera import CameraConfig, CameraDevice
+    from ..manager import DiscoveredCamera
+    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
+StorageT = ExtTypeVar("StorageT", bound=Mapping[str, Any], default=dict[str, Any])
+"""TypeVar for plugin storage values type. Defaults to dict[str, Any]."""
+
+
+class ImageMetadata(TypedDict):
+    """Image metadata for detection test requests."""
+
+    width: int
+    height: int
+
+
+class AudioMetadata(TypedDict):
+    """Audio metadata for detection test requests."""
+
+    mimeType: Literal["audio/mpeg", "audio/wav", "audio/ogg"]
+
+
+class MotionDetectionPluginResponse(TypedDict):
+    """Response from a motion detection test."""
+
+    detected: bool
+    detections: list[Detection]
+    videoData: NotRequired[bytes]
+
+
+class ObjectDetectionPluginResponse(TypedDict):
+    """Response from an object detection test."""
+
+    detected: bool
+    detections: list[Detection]
+
+
+class AudioDetectionPluginResponse(TypedDict):
+    """Response from an audio detection test."""
+
+    detected: bool
+    detections: list[Detection]
+    decibels: NotRequired[float]
+
+
+class FaceDetectionPluginResponse(TypedDict):
+    """Response from a face detection test."""
+
+    detected: bool
+    detections: list[FaceDetection]
+    embeddingModel: NotRequired[str]
+
+
+class LicensePlateDetectionPluginResponse(TypedDict):
+    """Response from a license plate detection test."""
+
+    detected: bool
+    detections: list[LicensePlateDetection]
+
+
+class ClassifierDetectionPluginResponse(TypedDict):
+    """Response from a classifier detection test."""
+
+    detected: bool
+    detections: list[ClassifierDetection]
+
+
+class ClipDetectionPluginResponse(TypedDict):
+    """Response from a CLIP embedding test."""
+
+    embeddings: list[ClipEmbedding]
+    embeddingModel: str
+
+
+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."""
+
+    embedding: list[float]
+    embeddingModel: str
+
+
+class BasePlugin(ABC, Generic[StorageT]):
+    """Base class every plugin extends.
+
+    It wires up the three dependencies the host injects (logger, PluginAPI,
+    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.
+
+    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
+                for camera in cameras:
+                    await self.onCameraAdded(camera)
+
+            async def onCameraAdded(self, camera: CameraDevice) -> None:
+                # Initialize camera controller
+                pass
+
+            async def onCameraReleased(self, camera_id: str) -> None:
+                # Cleanup camera controller
+                pass
+        ```
+    """
+
+    def __init__(self, logger: LoggerService, api: PluginAPI, storage: DeviceStorage[StorageT]) -> None:
+        self.logger = logger
+        self.api = api
+        self.storage: DeviceStorage[StorageT] = storage
+
+    @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."""
+        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.
+
+        Args:
+            cameras: Cameras already assigned to this plugin.
+        """
+        ...
+
+    @abstractmethod
+    async def onCameraAdded(self, camera: CameraDevice) -> None:
+        """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`.
+
+        Args:
+            camera: The camera device that was added.
+        """
+        ...
+
+    @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.
+
+        Args:
+            cameraId: ID of the camera that was released.
+        """
+        ...
+
+
+@runtime_checkable
+class DiscoveryProvider(Protocol):
+    """Implemented by plugins that can scan the network for new cameras and
+    adopt them. Only plugins with a camera-controlling role
+    (CameraController or CameraAndSensorProvider) are queried for discovery."""
+
+    async def onDiscoverCameras(self) -> list[DiscoveredCamera]:
+        """Scan the network and return the cameras the plugin can offer for
+        adoption. Called by the host on demand (UI rescan button) or on a
+        polling schedule.
+
+        Returns:
+            Cameras currently discoverable by this plugin.
+        """
+        ...
+
+    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
+        discovered camera.
+
+        Args:
+            camera: The discovered camera the user is about to adopt.
+
+        Returns:
+            Schema for the adoption form.
+        """
+        ...
+
+    async def onAdoptCamera(
+        self, camera: DiscoveredCamera, cameraSettings: dict[str, object]
+    ) -> 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.
+
+        Args:
+            camera: The discovered camera being adopted.
+            cameraSettings: Values entered into the adoption form.
+
+        Returns:
+            Final camera configuration for the host to persist.
+        """
+        ...
+
+
+@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."""
+
+    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."""
+        ...
+
+    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."""
+        ...
+
+    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."""
+        ...
+
+
+@runtime_checkable
+class ObjectDetectionInterface(Protocol):
+    """Interface 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."""
+        ...
+
+    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."""
+        ...
+
+    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."""
+        ...
+
+
+@runtime_checkable
+class AudioDetectionInterface(Protocol):
+    """Interface 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)."""
+        ...
+
+    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."""
+        ...
+
+
+@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."""
+
+    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."""
+        ...
+
+    async def detectFaces(
+        self, frame: VideoFrameData, config: dict[str, Any] | None = None
+    ) -> FaceDetectionPluginResponse | None:
+        """Run face detection on a pre-decoded video frame."""
+        ...
+
+    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."""
+        ...
+
+
+@runtime_checkable
+class LicensePlateDetectionInterface(Protocol):
+    """Interface 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."""
+        ...
+
+    async def detectLicensePlates(
+        self, frame: VideoFrameData, config: dict[str, Any] | None = None
+    ) -> LicensePlateDetectionPluginResponse | None:
+        """Run detection on a pre-decoded video frame."""
+        ...
+
+    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."""
+        ...
+
+
+@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)."""
+
+    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."""
+        ...
+
+    async def detectClassifications(
+        self, frame: VideoFrameData, config: dict[str, Any] | None = None
+    ) -> ClassifierDetectionPluginResponse | None:
+        """Run classification on a pre-decoded video frame."""
+        ...
+
+    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."""
+        ...
+
+
+@runtime_checkable
+class ClipDetectionInterface(Protocol):
+    """Interface 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."""
+        ...
+
+    async def detectClipEmbedding(
+        self, frame: VideoFrameData, config: dict[str, Any] | None = None
+    ) -> ClipDetectionPluginResponse | None:
+        """Run the CLIP image branch on a pre-decoded video frame."""
+        ...
+
+    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."""
+        ...
+
+    async def clipSettings(self) -> list[JsonSchema] | None:
+        """Return the JSON schema for the CLIP settings form in the UI.
+        Return None for no schema."""
+        ...
+
+
+# Union of all optional plugin interfaces.
+PluginInterfaces = (
+    MotionDetectionInterface
+    | ObjectDetectionInterface
+    | AudioDetectionInterface
+    | FaceDetectionInterface
+    | LicensePlateDetectionInterface
+    | ClassifierDetectionInterface
+    | ClipDetectionInterface
+    | DiscoveryProvider
+)

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

@@ -0,0 +1,142 @@
+"""Generic notification types — domain-agnostic.
+
+The NotificationManager and notifier plugins talk over RPC and JSON-encode
+these types directly.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, NotRequired, Protocol, TypedDict, runtime_checkable
+
+
+class Severity(str, Enum):
+    """Classifies how urgent a Notification is.
+
+    Notifiers map this to platform-specific delivery characteristics; the
+    host bypasses user-configured Quiet Hours for ``Critical``.
+    """
+
+    Info = "info"
+    """Standard notification — default delivery (sound + banner)."""
+
+    Warn = "warn"
+    """Heightened attention; notifiers may use a different sound/colour."""
+
+    Error = "error"
+    """Failure or action-required notification."""
+
+    Critical = "critical"
+    """Highest-priority delivery on supporting notifiers; bypasses
+    user-configured Quiet Hours on the host."""
+
+
+class NotifierDevice(TypedDict):
+    """A push-target managed by a notifier plugin (one phone, one chat, ...).
+
+    Devices are owned by the plugin that registered them; the manager queries
+    plugins for their device list rather than maintaining a shared registry.
+    """
+
+    id: str
+    ownerUserId: str
+    name: str
+    active: bool
+    metadata: NotRequired[dict[str, Any]]
+
+
+class Notification(TypedDict):
+    """Payload published via ``api.notificationManager.publish`` or routed by
+    the host. Plugins fill the user-visible fields; the host stamps the
+    message id, timestamp and source identifier on receive — plugins do not
+    set those.
+    """
+
+    title: str
+    """Headline shown by every notifier."""
+
+    subtitle: NotRequired[str]
+    """Optional second bold line between title and body. Honoured natively
+    on iOS (APNs ``alert.subtitle``); other notifiers may fold it into the
+    body or ignore it."""
+
+    body: NotRequired[str]
+    """Optional secondary text."""
+
+    severity: NotRequired[Severity]
+    """Drives DND / Critical-Alerts behaviour and Quiet-Hours bypass.
+    Defaults to :attr:`Severity.Info` if omitted."""
+
+    tag: NotRequired[str]
+    """Collapse-key for dedup at both manager and notifier level (e.g.
+    ``motion:cam-1`` — multiple events with the same tag inside the throttle
+    window collapse into one notification on the device)."""
+
+    thumbnail: NotRequired[bytes]
+    """Optional inline JPEG attached to the notification."""
+
+    imageUrl: NotRequired[str]
+    """Publicly-fetchable URL to a rich image (e.g. a detection snapshot).
+    Notifier-agnostic: FCM/APNs and other notifiers fetch it to render the
+    image. Preferred over inline ``thumbnail`` bytes when a URL is available;
+    empty renders text-only."""
+
+    deepLink: NotRequired[str]
+    """Router-relative path consumed by mobile / web tap-handlers (e.g.
+    ``/cameras/cam-1?startTs=...``). No host, no scheme."""
+
+    data: NotRequired[dict[str, str]]
+    """Plugin-specific context (cameraId, eventId, plugin-defined keys).
+    String values keep the wire format predictable across notifier
+    implementations."""
+
+    adminOnly: NotRequired[bool]
+    """Restricts delivery to users with the master or admin role. Use it for
+    operational alerts that concern whoever runs the instance — camera
+    offline, disk full, plugin failures — so they don't reach guests the
+    instance is merely shared with. Defaults to ``False`` (every user of the
+    instance receives it, subject to their own notification settings)."""
+
+
+@runtime_checkable
+class NotifierInterface(Protocol):
+    """Implemented by plugins that deliver notifications.
+
+    The NotificationManager invokes these methods over RPC. Plugins own their
+    device storage — the manager never persists devices itself.
+    """
+
+    async def get_devices(self, owner_user_ids: list[str]) -> list[NotifierDevice]:
+        """Return every device this notifier knows about for the given users.
+        Each device carries its ``ownerUserId`` so the caller can map results
+        back. May return [] when the notifier is unavailable (e.g. license
+        invalid). Called frequently — keep cheap."""
+        ...
+
+    async def get_device(self, device_id: str) -> NotifierDevice | None:
+        """Return a single device by id, or None if not found."""
+        ...
+
+    async def send_notification(self, device_ids: list[str], n: Notification) -> None:
+        """Deliver a notification to the given devices in one call. Errors are
+        logged; the manager never aborts a fan-out because one notifier
+        failed."""
+        ...
+
+    async def register_device(self, owner_user_id: str, input: dict[str, Any]) -> NotifierDevice:
+        """Create a new device on this notifier. ``input`` is plugin-specific
+        JSON whose schema the notifier defines; the NotificationManager
+        forwards it opaquely."""
+        ...
+
+    async def revoke_device(self, device_id: str) -> None:
+        """Permanently remove a device. Called when the user revokes the
+        device through their notifier-specific UI."""
+        ...
+
+    async def update_device(self, device_id: str, patch: dict[str, Any]) -> NotifierDevice | None:
+        """Mutate a subset of fields on an existing device. ``patch`` is
+        plugin-agnostic (``name``, ``active``); plugins ignore unknown keys.
+        Returns the updated device, or None if the id isn't ours so the
+        manager can probe the next plugin."""
+        ...