homesec 0.1.0__py3-none-any.whl

homesec/plugins/filters/yolo.py

@@ -0,0 +1,317 @@
+"""YOLOv8 object detection filter plugin."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+from typing import Callable, cast
+
+import cv2
+import torch
+from ultralytics import YOLO  # type: ignore[attr-defined]
+
+from homesec.models.filter import FilterConfig, FilterOverrides, FilterResult, YoloFilterSettings
+from homesec.interfaces import ObjectFilter
+
+logger = logging.getLogger(__name__)
+
+# COCO classes for humans and animals
+HUMAN_ANIMAL_CLASSES = {
+    0: "person",
+    14: "bird",
+    15: "cat",
+    16: "dog",
+    17: "horse",
+    18: "sheep",
+    19: "cow",
+    20: "elephant",
+    21: "bear",
+    22: "zebra",
+    23: "giraffe",
+}
+
+_MODEL_CACHE: dict[tuple[str, str], YOLO] = {}
+_YOLO_CACHE_DIR = Path.cwd() / "yolo_cache"
+
+
+def _resolve_requested_path(model_path: str) -> Path:
+    requested = Path(model_path)
+    if not requested.is_absolute() and requested.parent == Path("."):
+        return _YOLO_CACHE_DIR / requested.name
+    return requested
+
+
+def _resolve_weights_path(model_path: str) -> Path:
+    requested_path = _resolve_requested_path(model_path)
+    if requested_path.exists():
+        return requested_path
+
+    resolved: Path | None = None
+    try:
+        from ultralytics.utils.checks import check_file
+
+        check_file_fn = cast(Callable[[str], str | None], check_file)
+
+        for key in (str(requested_path), requested_path.name):
+            try:
+                candidate = check_file_fn(key)
+            except Exception:
+                continue
+            if candidate and Path(candidate).exists():
+                resolved = Path(candidate)
+                break
+
+        if resolved is None and requested_path.suffix.lower() == ".pt":
+            try:
+                _ = YOLO(requested_path.name)
+                candidate = check_file_fn(requested_path.name)
+                if candidate and Path(candidate).exists():
+                    resolved = Path(candidate)
+            except Exception:
+                resolved = None
+    except Exception:
+        resolved = None
+
+    if resolved is None:
+        return requested_path
+
+    if requested_path.suffix.lower() == ".pt" and resolved != requested_path:
+        try:
+            requested_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(resolved, requested_path)
+            return requested_path
+        except Exception:
+            return resolved
+
+    return resolved
+
+
+def _get_model(model_path: str, device: str) -> YOLO:
+    key = (model_path, device)
+    model = _MODEL_CACHE.get(key)
+    if model is None:
+        model = YOLO(model_path).to(device)
+        _MODEL_CACHE[key] = model
+    return model
+
+
+class YOLOv8Filter(ObjectFilter):
+    """YOLO-based object detection filter.
+    
+    Uses ProcessPoolExecutor internally for CPU/GPU-bound inference.
+    Supports frame sampling and early exit on detection.
+    Bare model filenames resolve under ./yolo_cache and auto-download if missing.
+    """
+
+    def __init__(self, config: FilterConfig) -> None:
+        """Initialize YOLO filter with config validation.
+        
+        Required config:
+            model_path: Path to .pt model file
+            
+        Optional config:
+            classes: List of class names to detect (default: person)
+            min_confidence: Minimum confidence threshold (default: 0.5)
+            sample_fps: Frame sampling rate (default: 2)
+            min_box_h_ratio: Minimum box height ratio (default: 0.1)
+            min_hits: Minimum detections to confirm (default: 1)
+        """
+        match config.config:
+            case YoloFilterSettings() as settings:
+                cfg = settings
+            case _:
+                raise ValueError("YOLOv8Filter requires YoloFilterSettings config")
+
+        self._settings = cfg
+        self.model_path = _resolve_weights_path(str(cfg.model_path))
+        if not self.model_path.exists():
+            raise FileNotFoundError(f"Model not found: {self.model_path}")
+
+        self._class_id_cache: dict[tuple[str, ...], list[int]] = {}
+        
+        # Initialize executor
+        self._executor = ProcessPoolExecutor(max_workers=config.max_workers)
+        self._shutdown_called = False
+        
+        logger.info(
+            "YOLOv8Filter initialized: model=%s, classes=%s, confidence=%.2f",
+            self.model_path,
+            self._settings.classes,
+            self._settings.min_confidence,
+        )
+
+    async def detect(
+        self,
+        video_path: Path,
+        overrides: FilterOverrides | None = None,
+    ) -> FilterResult:
+        """Detect objects in video clip.
+        
+        Runs inference in ProcessPoolExecutor to avoid blocking event loop.
+        Samples frames at configured rate and exits early on first detection.
+        """
+        if self._shutdown_called:
+            raise RuntimeError("Filter has been shut down")
+        
+        # Run blocking work in executor
+        loop = asyncio.get_running_loop()
+        effective = self._apply_overrides(overrides)
+        target_class_ids = self._class_ids_for(effective.classes)
+
+        result = await loop.run_in_executor(
+            self._executor,
+            _detect_worker,
+            str(video_path),
+            str(self.model_path),
+            target_class_ids,
+            float(effective.min_confidence),
+            int(effective.sample_fps),
+            float(effective.min_box_h_ratio),
+            int(effective.min_hits),
+        )
+        
+        return result
+
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Cleanup resources - shutdown executor."""
+        _ = timeout
+        if self._shutdown_called:
+            return
+        
+        self._shutdown_called = True
+        logger.info("Shutting down YOLOv8Filter...")
+        self._executor.shutdown(wait=True, cancel_futures=False)
+        logger.info("YOLOv8Filter shutdown complete")
+
+    def _apply_overrides(self, overrides: FilterOverrides | None) -> YoloFilterSettings:
+        if overrides is None:
+            return self._settings
+        update = overrides.model_dump(exclude_none=True)
+        return self._settings.model_copy(update=update)
+
+    def _class_ids_for(self, classes: list[str]) -> list[int]:
+        key = tuple(classes)
+        cached = self._class_id_cache.get(key)
+        if cached is not None:
+            return cached
+        target_class_ids = [
+            cid for cid, name in HUMAN_ANIMAL_CLASSES.items()
+            if name in classes
+        ]
+        if not target_class_ids:
+            raise ValueError(f"No valid classes found in config: {classes}")
+        self._class_id_cache[key] = target_class_ids
+        return target_class_ids
+
+
+def _detect_worker(
+    video_path: str,
+    model_path: str,
+    target_class_ids: list[int],
+    min_confidence: float,
+    sample_fps: int,
+    min_box_h_ratio: float,
+    min_hits: int,
+) -> FilterResult:
+    """Worker function for video analysis (must be at module level for pickling).
+    
+    This runs in a separate process, so it needs to load the model fresh.
+    """
+    # Determine device
+    device = (
+        "mps"
+        if torch.backends.mps.is_available()
+        else "cuda"
+        if torch.cuda.is_available()
+        else "cpu"
+    )
+    
+    # Load model (cached per process)
+    model = _get_model(model_path, device)
+    
+    # Open video
+    cap = cv2.VideoCapture(video_path)
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    frame_h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    min_box_h = frame_h * min_box_h_ratio
+    
+    detected_classes: list[str] = []
+    max_confidence = 0.0
+    sampled_frames = 0
+    
+    frame_idx = 0
+    while frame_idx < total_frames:
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_idx)
+        ret, frame = cap.read()
+        if not ret:
+            break
+        
+        sampled_frames += 1
+        
+        # Run inference
+        results = model(frame, verbose=False, conf=min_confidence, classes=target_class_ids)
+        
+        for result in results:
+            for box in result.boxes:
+                cls = int(box.cls[0])
+                class_name = HUMAN_ANIMAL_CLASSES.get(cls)
+                if not class_name:
+                    continue
+                
+                # Check box height
+                xyxy = box.xyxy[0].tolist()
+                box_h = xyxy[3] - xyxy[1]
+                if box_h < min_box_h:
+                    continue
+                
+                # Track detection
+                confidence = float(box.conf[0])
+                if class_name not in detected_classes:
+                    detected_classes.append(class_name)
+                max_confidence = max(max_confidence, confidence)
+                
+                # Early exit if we have enough hits
+                if len(detected_classes) >= min_hits:
+                    cap.release()
+                    return FilterResult(
+                        detected_classes=detected_classes,
+                        confidence=max_confidence,
+                        model=Path(model_path).name,
+                        sampled_frames=sampled_frames,
+                    )
+        
+        frame_idx += sample_fps
+    
+    cap.release()
+    
+    return FilterResult(
+        detected_classes=detected_classes,
+        confidence=max_confidence if detected_classes else 0.0,
+        model=Path(model_path).name,
+        sampled_frames=sampled_frames,
+    )
+
+
+# Plugin registration
+from homesec.plugins.filters import FilterPlugin, filter_plugin
+
+
+@filter_plugin(name="yolo")
+def yolo_filter_plugin() -> FilterPlugin:
+    """YOLO filter plugin factory.
+
+    Returns:
+        FilterPlugin for YOLOv8 object detection
+    """
+
+    def factory(cfg: FilterConfig) -> ObjectFilter:
+        return YOLOv8Filter(cfg)
+
+    return FilterPlugin(
+        name="yolo",
+        config_model=YoloFilterSettings,
+        factory=factory,
+    )

homesec/plugins/notifiers/__init__.py

@@ -0,0 +1,80 @@
+"""Notifier plugins and registry."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Callable, TypeVar
+
+from pydantic import BaseModel
+
+from homesec.interfaces import Notifier
+from homesec.plugins.notifiers.multiplex import MultiplexNotifier, NotifierEntry
+
+logger = logging.getLogger(__name__)
+
+
+NotifierFactory = Callable[[BaseModel], Notifier]
+
+
+@dataclass(frozen=True)
+class NotifierPlugin:
+    name: str
+    config_model: type[BaseModel]
+    factory: NotifierFactory
+
+
+NOTIFIER_REGISTRY: dict[str, NotifierPlugin] = {}
+
+
+def register_notifier(plugin: NotifierPlugin) -> None:
+    """Register a notifier plugin with collision detection.
+
+    Args:
+        plugin: Notifier plugin to register
+
+    Raises:
+        ValueError: If a plugin with the same name is already registered
+    """
+    if plugin.name in NOTIFIER_REGISTRY:
+        raise ValueError(
+            f"Notifier plugin '{plugin.name}' is already registered. "
+            f"Plugin names must be unique across all notifier plugins."
+        )
+    NOTIFIER_REGISTRY[plugin.name] = plugin
+
+
+T = TypeVar("T", bound=Callable[[], NotifierPlugin])
+
+
+def notifier_plugin(name: str) -> Callable[[T], T]:
+    """Decorator to register a notifier plugin.
+
+    Usage:
+        @notifier_plugin(name="my_notifier")
+        def my_notifier_plugin() -> NotifierPlugin:
+            return NotifierPlugin(...)
+
+    Args:
+        name: Plugin name (for validation only - must match plugin.name)
+
+    Returns:
+        Decorator function that registers the plugin
+    """
+
+    def decorator(factory_fn: T) -> T:
+        plugin = factory_fn()
+        register_notifier(plugin)
+        return factory_fn
+
+    return decorator
+
+
+__all__ = [
+    "MultiplexNotifier",
+    "NotifierEntry",
+    "NotifierPlugin",
+    "NOTIFIER_REGISTRY",
+    "register_notifier",
+    "notifier_plugin",
+]

homesec/plugins/notifiers/mqtt.py

@@ -0,0 +1,189 @@
+"""MQTT notifier plugin for Home Assistant integration."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import threading
+
+import paho.mqtt.client as mqtt
+
+from homesec.models.alert import Alert
+from homesec.models.config import MQTTConfig
+from homesec.interfaces import Notifier
+
+logger = logging.getLogger(__name__)
+
+
+class MQTTNotifier(Notifier):
+    """MQTT notifier for Home Assistant alerts.
+    
+    Publishes alert messages to configured topics with QoS settings.
+    """
+
+    def __init__(self, config: MQTTConfig) -> None:
+        """Initialize MQTT notifier with config validation.
+        
+        Args:
+            config: MQTTConfig instance
+        """
+        self.host = config.host
+        self.port = int(config.port)
+        self.topic_template = config.topic_template
+        self.qos = int(config.qos)
+        self.retain = bool(config.retain)
+        self.connection_timeout = float(config.connection_timeout)
+        
+        # Get credentials from env if provided
+        self.username: str | None = None
+        self.password: str | None = None
+        
+        if config.auth and config.auth.username_env:
+            username_var = config.auth.username_env
+            self.username = os.getenv(username_var)
+            if not self.username:
+                logger.warning("MQTT username not found in env: %s", username_var)
+
+        if config.auth and config.auth.password_env:
+            password_var = config.auth.password_env
+            self.password = os.getenv(password_var)
+            if not self.password:
+                logger.warning("MQTT password not found in env: %s", password_var)
+        
+        # Initialize MQTT client
+        self.client = mqtt.Client()
+        
+        if self.username and self.password:
+            self.client.username_pw_set(self.username, self.password)
+        
+        # Connection state
+        self._connected = False
+        self._connected_event = threading.Event()
+        self._shutdown_called = False
+        self._loop_started = False
+
+        def _on_connect(
+            client: mqtt.Client, userdata: object, flags: dict[str, object], rc: int
+        ) -> None:
+            if rc == 0:
+                self._connected = True
+                self._connected_event.set()
+                logger.info("MQTTNotifier connected: %s:%d", self.host, self.port)
+                return
+            self._connected = False
+            logger.warning("MQTTNotifier connection failed: rc=%s", rc)
+
+        def _on_disconnect(client: mqtt.Client, userdata: object, rc: int) -> None:
+            self._connected = False
+            if rc != 0:
+                logger.warning("MQTTNotifier disconnected unexpectedly: rc=%s", rc)
+
+        self.client.on_connect = _on_connect
+        self.client.on_disconnect = _on_disconnect
+
+        # Connect to broker
+        try:
+            self.client.connect(self.host, self.port, keepalive=60)
+            self.client.loop_start()
+            self._loop_started = True
+        except Exception as e:
+            logger.error("Failed to connect to MQTT broker: %s", e, exc_info=True)
+            self._connected = False
+
+    async def send(self, alert: Alert) -> None:
+        """Send alert notification to MQTT topic."""
+        await self._ensure_connected()
+        
+        # Format topic
+        topic = self.topic_template.format(camera_name=alert.camera_name)
+        
+        # Serialize alert to JSON
+        payload = alert.model_dump_json()
+        
+        # Publish message
+        await asyncio.to_thread(
+            self._publish,
+            topic,
+            payload,
+            self.qos,
+            self.retain,
+        )
+        
+        logger.info(
+            "Published alert to MQTT: topic=%s, clip_id=%s",
+            topic,
+            alert.clip_id,
+        )
+
+    def _publish(self, topic: str, payload: str, qos: int, retain: bool) -> None:
+        """Publish message (blocking operation)."""
+        result = self.client.publish(topic, payload, qos=qos, retain=retain)
+        result.wait_for_publish()
+
+    async def ping(self) -> bool:
+        """Health check - verify MQTT connection."""
+        if self._shutdown_called:
+            return False
+        if self._connected and self.client.is_connected():
+            return True
+        await asyncio.to_thread(self._connected_event.wait, 2.0)
+        return self._connected and self.client.is_connected()
+
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Cleanup resources - disconnect from broker."""
+        _ = timeout
+        if self._shutdown_called:
+            return
+
+        self._shutdown_called = True
+        logger.info("Shutting down MQTTNotifier...")
+
+        # Stop loop if it was started (prevents thread leak even if never connected)
+        if self._loop_started:
+            await asyncio.to_thread(self.client.loop_stop)
+            await asyncio.to_thread(self.client.disconnect)
+
+        logger.info("MQTTNotifier shutdown complete")
+
+    async def _ensure_connected(self) -> None:
+        if self._shutdown_called:
+            raise RuntimeError("Notifier has been shut down")
+        if self._connected:
+            return
+        # Wait for connection with timeout
+        connected = await asyncio.to_thread(
+            self._connected_event.wait, self.connection_timeout
+        )
+        if not connected or not self._connected:
+            raise RuntimeError(
+                f"MQTT broker not connected after {self.connection_timeout}s timeout"
+            )
+
+
+# Plugin registration
+from typing import cast
+from pydantic import BaseModel
+from homesec.plugins.notifiers import NotifierPlugin, notifier_plugin
+from homesec.interfaces import Notifier
+
+
+@notifier_plugin(name="mqtt")
+def mqtt_plugin() -> NotifierPlugin:
+    """MQTT notifier plugin factory.
+
+    Returns:
+        NotifierPlugin for MQTT notifications
+    """
+    from homesec.models.config import MQTTConfig
+
+    def factory(cfg: BaseModel) -> Notifier:
+        # Config is already validated by app.py, just cast
+        return MQTTNotifier(cast(MQTTConfig, cfg))
+
+    return NotifierPlugin(
+        name="mqtt",
+        config_model=MQTTConfig,
+        factory=factory,
+    )

homesec/plugins/notifiers/multiplex.py

@@ -0,0 +1,106 @@
+"""Fan-out notifier that sends alerts to multiple notifiers in parallel."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Coroutine
+
+from homesec.models.alert import Alert
+from homesec.interfaces import Notifier
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class NotifierEntry:
+    """Notifier entry with a name for logging."""
+
+    name: str
+    notifier: Notifier
+
+
+class MultiplexNotifier(Notifier):
+    """Send notifications to multiple notifiers in parallel."""
+
+    def __init__(self, entries: list[NotifierEntry]) -> None:
+        if not entries:
+            raise ValueError("MultiplexNotifier requires at least one notifier")
+        self._entries = list(entries)
+        self._shutdown_called = False
+
+    async def send(self, alert: Alert) -> None:
+        """Send alert notification via all notifiers in parallel."""
+        if self._shutdown_called:
+            raise RuntimeError("Notifier has been shut down")
+
+        results = await self._call_all(lambda notifier: notifier.send(alert))
+
+        failures: list[tuple[str, BaseException]] = []
+        for entry, result in results:
+            match result:
+                case BaseException() as err:
+                    failures.append((entry.name, err))
+                    logger.error(
+                        "Notifier send failed: notifier=%s error=%s",
+                        entry.name,
+                        err,
+                        exc_info=err,
+                    )
+
+        if failures:
+            detail = "; ".join(
+                f"{name}={type(error).__name__}: {error}" for name, error in failures
+            )
+            raise RuntimeError(f"Notifier failures: {detail}") from failures[0][1]
+
+    async def ping(self) -> bool:
+        """Health check - verify all notifiers are reachable."""
+        if self._shutdown_called:
+            return False
+
+        results = await self._call_all(lambda notifier: notifier.ping())
+
+        healthy = True
+        for entry, result in results:
+            match result:
+                case bool() as ok:
+                    if not ok:
+                        healthy = False
+                        logger.warning("Notifier ping failed: notifier=%s", entry.name)
+                case BaseException() as err:
+                    healthy = False
+                    logger.warning(
+                        "Notifier ping failed: notifier=%s error=%s",
+                        entry.name,
+                        err,
+                    )
+
+        return healthy
+
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Cleanup resources for all notifiers."""
+        _ = timeout
+        if self._shutdown_called:
+            return
+        self._shutdown_called = True
+
+        results = await self._call_all(lambda notifier: notifier.shutdown())
+        for entry, result in results:
+            match result:
+                case BaseException() as err:
+                    logger.warning(
+                        "Notifier close failed: notifier=%s error=%s",
+                        entry.name,
+                        err,
+                    )
+
+    async def _call_all(
+        self, func: Callable[[Notifier], Coroutine[Any, Any, object]]
+    ) -> list[tuple[NotifierEntry, object | BaseException]]:
+        tasks: list[asyncio.Task[object]] = [
+            asyncio.create_task(func(entry.notifier)) for entry in self._entries
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return list(zip(self._entries, results, strict=True))