homesec 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

homesec/plugins/filters/__init__.py

@@ -3,121 +3,37 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, TypeVar
-
-from pydantic import BaseModel
+from typing import cast
 
 from homesec.interfaces import ObjectFilter
-
-if TYPE_CHECKING:
-    from homesec.models.filter import FilterConfig
+from homesec.models.filter import FilterConfig
+from homesec.plugins.registry import PluginType, load_plugin
 
 logger = logging.getLogger(__name__)
 
-# Type alias for clarity
-FilterFactory = Callable[["FilterConfig"], ObjectFilter]
-
-
-@dataclass(frozen=True)
-class FilterPlugin:
-    """Metadata for a filter plugin."""
-
-    name: str
-    config_model: type[BaseModel]
-    factory: FilterFactory
-
-
-FILTER_REGISTRY: dict[str, FilterPlugin] = {}
-
-
-def register_filter(plugin: FilterPlugin) -> None:
-    """Register a filter plugin with collision detection.
-
-    Args:
-        plugin: Filter plugin to register
-
-    Raises:
-        ValueError: If a plugin with the same name is already registered
-    """
-    if plugin.name in FILTER_REGISTRY:
-        raise ValueError(
-            f"Filter plugin '{plugin.name}' is already registered. "
-            f"Plugin names must be unique across all filter plugins."
-        )
-    FILTER_REGISTRY[plugin.name] = plugin
-
-
-T = TypeVar("T", bound=Callable[[], FilterPlugin])
-
 
-def filter_plugin(name: str) -> Callable[[T], T]:
-    """Decorator to register a filter plugin.
-
-    Usage:
-        @filter_plugin(name="my_filter")
-        def my_filter_plugin() -> FilterPlugin:
-            return FilterPlugin(...)
+def load_filter(config: FilterConfig) -> ObjectFilter:
+    """Load and instantiate a filter plugin.
 
     Args:
-        name: Plugin name (for validation only - must match plugin.name)
+        config: Filter configuration
 
     Returns:
-        Decorator function that registers the plugin
-    """
-
-    def decorator(factory_fn: T) -> T:
-        plugin = factory_fn()
-        register_filter(plugin)
-        return factory_fn
-
-    return decorator
-
-
-def load_filter_plugin(config: FilterConfig) -> ObjectFilter:
-    """Load filter plugin by name from config.
-
-    Validates the config dict against the plugin's config_model and creates
-    a FilterConfig with the validated settings object.
-
-    Args:
-        config: Filter configuration with plugin name and raw config dict
-
-    Returns:
-        Instantiated filter plugin
+        Configured ObjectFilter instance
 
     Raises:
-        ValueError: If plugin name is unknown or config validation fails
+        ValueError: If plugin not found in registry
+        ValidationError: If config validation fails
     """
-    plugin_name = config.plugin.lower()
-
-    if plugin_name not in FILTER_REGISTRY:
-        available = ", ".join(sorted(FILTER_REGISTRY.keys()))
-        raise ValueError(f"Unknown filter plugin: '{plugin_name}'. Available: {available}")
-
-    plugin = FILTER_REGISTRY[plugin_name]
-
-    # Validate config.config dict against plugin's config_model
-    validated_settings = plugin.config_model.model_validate(config.config)
-
-    # Create new FilterConfig with validated settings object
-    from homesec.models.filter import FilterConfig as FilterConfigModel
-
-    validated_config = FilterConfigModel(
-        plugin=config.plugin,
-        max_workers=config.max_workers,
-        config=validated_settings,
+    return cast(
+        ObjectFilter,
+        load_plugin(
+            PluginType.FILTER,
+            config.plugin,
+            config.config,
+            max_workers=config.max_workers,
+        ),
     )
 
-    return plugin.factory(validated_config)
-
 
-__all__ = [
-    "FilterPlugin",
-    "FilterFactory",
-    "FILTER_REGISTRY",
-    "register_filter",
-    "filter_plugin",
-    "load_filter_plugin",
-]
+__all__ = ["load_filter"]

homesec/plugins/filters/yolo.py

@@ -5,17 +5,31 @@ from __future__ import annotations
 import asyncio
 import logging
 import shutil
-from collections.abc import Callable
+import threading
 from concurrent.futures import ProcessPoolExecutor
 from pathlib import Path
-from typing import cast
-
-import cv2
-import torch
-from ultralytics import YOLO  # type: ignore[attr-defined]
+from typing import Any
+
+cv2: Any
+torch: Any
+YOLO_CLASS: Any
+
+try:
+    import cv2 as _cv2
+    import torch as _torch
+    from ultralytics import YOLO as _YOLO  # type: ignore[attr-defined]
+except Exception:
+    cv2 = None
+    torch = None
+    YOLO_CLASS = None
+else:
+    cv2 = _cv2
+    torch = _torch
+    YOLO_CLASS = _YOLO
 
 from homesec.interfaces import ObjectFilter
-from homesec.models.filter import FilterConfig, FilterOverrides, FilterResult, YoloFilterSettings
+from homesec.models.filter import FilterOverrides, FilterResult, YoloFilterSettings
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
@@ -34,10 +48,20 @@ HUMAN_ANIMAL_CLASSES = {
     23: "giraffe",
 }
 
-_MODEL_CACHE: dict[tuple[str, str], YOLO] = {}
+_MODEL_CACHE: dict[tuple[str, str], Any] = {}
+_MODEL_CACHE_LOCK = threading.Lock()
 _YOLO_CACHE_DIR = Path.cwd() / "yolo_cache"
 
 
+def _ensure_yolo_dependencies() -> None:
+    """Fail fast with a clear error if YOLO dependencies are missing."""
+    if cv2 is None or torch is None or YOLO_CLASS is None:
+        raise RuntimeError(
+            "Missing dependency for YOLO filter. "
+            "Install with: uv pip install ultralytics opencv-python"
+        )
+
+
 def _resolve_requested_path(model_path: str) -> Path:
     requested = Path(model_path)
     if not requested.is_absolute() and requested.parent == Path("."):
@@ -45,6 +69,23 @@ def _resolve_requested_path(model_path: str) -> Path:
     return requested
 
 
+def _check_file_safe(key: str) -> str | None:
+    """Call ultralytics check_file with type-safe result handling.
+
+    Returns the resolved path string if found, None otherwise.
+    """
+    try:
+        from ultralytics.utils.checks import check_file
+
+        result = check_file(key)  # type: ignore[no-untyped-call]
+        # Validate result is string (ultralytics may return various types)
+        if isinstance(result, str):
+            return result
+        return None
+    except Exception:
+        return None
+
+
 def _resolve_weights_path(model_path: str) -> Path:
     requested_path = _resolve_requested_path(model_path)
     if requested_path.exists():
@@ -52,23 +93,18 @@ def _resolve_weights_path(model_path: str) -> 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
+            candidate = _check_file_safe(key)
             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 YOLO_CLASS is None:
+                    raise RuntimeError("YOLO dependencies are not available")
+                _ = YOLO_CLASS(requested_path.name)
+                candidate = _check_file_safe(requested_path.name)
                 if candidate and Path(candidate).exists():
                     resolved = Path(candidate)
             except Exception:
@@ -90,15 +126,31 @@ def _resolve_weights_path(model_path: str) -> Path:
     return resolved
 
 
-def _get_model(model_path: str, device: str) -> YOLO:
+def _get_model(model_path: str, device: str) -> Any:
+    """Get or create a cached YOLO model instance.
+
+    Thread-safe: uses a lock to prevent duplicate model loading when
+    multiple threads access the cache simultaneously.
+    """
     key = (model_path, device)
+    # Fast path: check without lock (safe for reads)
     model = _MODEL_CACHE.get(key)
-    if model is None:
-        model = YOLO(model_path).to(device)
-        _MODEL_CACHE[key] = model
-    return model
-
-
+    if model is not None:
+        return model
+
+    # Slow path: acquire lock for potential write
+    with _MODEL_CACHE_LOCK:
+        # Double-check after acquiring lock
+        model = _MODEL_CACHE.get(key)
+        if model is None:
+            if YOLO_CLASS is None:
+                raise RuntimeError("YOLO dependencies are not available")
+            model = YOLO_CLASS(model_path).to(device)
+            _MODEL_CACHE[key] = model
+        return model
+
+
+@plugin(plugin_type=PluginType.FILTER, name="yolo")
 class YOLOv8Filter(ObjectFilter):
     """YOLO-based object detection filter.
 
@@ -107,34 +159,29 @@ class YOLOv8Filter(ObjectFilter):
     Bare model filenames resolve under ./yolo_cache and auto-download if missing.
     """
 
-    def __init__(self, config: FilterConfig) -> None:
-        """Initialize YOLO filter with config validation.
+    config_cls = YoloFilterSettings
 
-        Required config:
-            model_path: Path to .pt model file
+    @classmethod
+    def create(cls, config: YoloFilterSettings) -> ObjectFilter:
+        return cls(config)
 
-        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)
+    def __init__(self, settings: YoloFilterSettings) -> None:
+        """Initialize YOLO filter with validated settings.
+
+        Args:
+            settings: YOLO-specific configuration (model_path, classes, thresholds)
+                      Also assumes settings.max_workers is populated.
         """
-        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))
+        _ensure_yolo_dependencies()
+        self._settings = settings
+        self.model_path = _resolve_weights_path(str(settings.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._executor = ProcessPoolExecutor(max_workers=settings.max_workers)
         self._shutdown_called = False
 
         logger.info(
@@ -187,6 +234,15 @@ class YOLOv8Filter(ObjectFilter):
         self._executor.shutdown(wait=True, cancel_futures=False)
         logger.info("YOLOv8Filter shutdown complete")
 
+    async def ping(self) -> bool:
+        """Health check - verify executor is alive and model path exists."""
+        if self._shutdown_called:
+            return False
+        if not self.model_path.exists():
+            return False
+        # Executor is considered healthy if not shut down
+        return True
+
     def _apply_overrides(self, overrides: FilterOverrides | None) -> YoloFilterSettings:
         if overrides is None:
             return self._settings
@@ -218,6 +274,9 @@ def _detect_worker(
 
     This runs in a separate process, so it needs to load the model fresh.
     """
+    if cv2 is None or torch is None:
+        raise RuntimeError("YOLO dependencies are not available")
+
     # Determine device
     device = (
         "mps"
@@ -291,25 +350,3 @@ def _detect_worker(
         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

@@ -3,79 +3,43 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import TypeVar
+from typing import cast
 
 from pydantic import BaseModel
 
 from homesec.interfaces import Notifier
 from homesec.plugins.notifiers.multiplex import MultiplexNotifier, NotifierEntry
+from homesec.plugins.registry import PluginType, load_plugin
 
 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(...)
+def load_notifier_plugin(backend: str, config: dict[str, object] | BaseModel) -> Notifier:
+    """Load and instantiate a notifier plugin.
 
     Args:
-        name: Plugin name (for validation only - must match plugin.name)
+        backend: Notifier backend name (e.g., "mqtt", "sendgrid_email")
+        config: Raw config dict or already-validated BaseModel
 
     Returns:
-        Decorator function that registers the plugin
-    """
-
-    def decorator(factory_fn: T) -> T:
-        plugin = factory_fn()
-        register_notifier(plugin)
-        return factory_fn
+        Configured Notifier instance
 
-    return decorator
+    Raises:
+        ValueError: If backend not found in registry
+        ValidationError: If config validation fails
+    """
+    return cast(
+        Notifier,
+        load_plugin(
+            PluginType.NOTIFIER,
+            backend,
+            config,
+        ),
+    )
 
 
 __all__ = [
     "MultiplexNotifier",
     "NotifierEntry",
-    "NotifierPlugin",
-    "NOTIFIER_REGISTRY",
-    "register_notifier",
-    "notifier_plugin",
+    "load_notifier_plugin",
 ]

homesec/plugins/notifiers/mqtt.py

@@ -6,28 +6,49 @@ import asyncio
 import logging
 import os
 import threading
+from typing import Any
 
-import paho.mqtt.client as mqtt
+mqtt: Any
+
+try:
+    import paho.mqtt.client as _mqtt
+except Exception:
+    mqtt = None
+else:
+    mqtt = _mqtt
 
 from homesec.interfaces import Notifier
 from homesec.models.alert import Alert
 from homesec.models.config import MQTTConfig
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
 
+@plugin(plugin_type=PluginType.NOTIFIER, name="mqtt")
 class MQTTNotifier(Notifier):
     """MQTT notifier for Home Assistant alerts.
 
     Publishes alert messages to configured topics with QoS settings.
     """
 
+    config_cls = MQTTConfig
+
+    @classmethod
+    def create(cls, config: MQTTConfig) -> Notifier:
+        return cls(config)
+
     def __init__(self, config: MQTTConfig) -> None:
         """Initialize MQTT notifier with config validation.
 
         Args:
             config: MQTTConfig instance
         """
+        if mqtt is None:
+            raise RuntimeError(
+                "Missing dependency: paho-mqtt. Install with: uv pip install paho-mqtt"
+            )
+
         self.host = config.host
         self.port = int(config.port)
         self.topic_template = config.topic_template
@@ -157,32 +178,3 @@ class MQTTNotifier(Notifier):
             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.interfaces import Notifier
-from homesec.plugins.notifiers import NotifierPlugin, notifier_plugin
-
-
-@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/sendgrid_email.py

@@ -7,21 +7,47 @@ import html
 import logging
 import os
 from collections import defaultdict
+from typing import Any
+
+aiohttp: Any
+
+try:
+    import aiohttp as _aiohttp
+except Exception:
+    aiohttp = None
+else:
+    aiohttp = _aiohttp
 
-import aiohttp
 
 from homesec.interfaces import Notifier
 from homesec.models.alert import Alert
 from homesec.models.config import SendGridEmailConfig
 from homesec.models.vlm import SequenceAnalysis
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
 
+def _ensure_sendgrid_dependencies() -> None:
+    """Fail fast with a clear error if SendGrid dependencies are missing."""
+    if aiohttp is None:
+        raise RuntimeError(
+            "Missing dependency for SendGrid notifier. Install with: uv pip install aiohttp"
+        )
+
+
+@plugin(plugin_type=PluginType.NOTIFIER, name="sendgrid_email")
 class SendGridEmailNotifier(Notifier):
     """SendGrid email notifier for HomeSec alerts."""
 
+    config_cls = SendGridEmailConfig
+
+    @classmethod
+    def create(cls, config: SendGridEmailConfig) -> Notifier:
+        return cls(config)
+
     def __init__(self, config: SendGridEmailConfig) -> None:
+        _ensure_sendgrid_dependencies()
         self._api_key_env = config.api_key_env
         self._from_email = config.from_email
         self._from_name = config.from_name
@@ -62,7 +88,8 @@ class SendGridEmailNotifier(Notifier):
         async with session.post(url, json=payload, headers=headers) as response:
             if response.status >= 400:
                 details = await response.text()
-                raise RuntimeError(f"SendGrid email send failed ({response.status}): {details}")
+                logger.debug("SendGrid API error details: %s", details)
+                raise RuntimeError(f"SendGrid email send failed: HTTP {response.status}")
 
         logger.info(
             "Sent SendGrid email alert: to=%s clip_id=%s",
@@ -74,6 +101,8 @@ class SendGridEmailNotifier(Notifier):
         """Health check - verify SendGrid credentials and connectivity."""
         if self._shutdown_called or not self._api_key:
             return False
+        if aiohttp is None:
+            return False
 
         url = f"{self._api_base}/user/profile"
         headers = {"Authorization": f"Bearer {self._api_key}"}
@@ -100,6 +129,8 @@ class SendGridEmailNotifier(Notifier):
 
     async def _get_session(self) -> aiohttp.ClientSession:
         if self._session is None or self._session.closed:
+            if aiohttp is None:
+                raise RuntimeError("aiohttp dependency is required for SendGrid notifier")
             timeout = aiohttp.ClientTimeout(total=self._timeout_s)
             self._session = aiohttp.ClientSession(timeout=timeout)
         return self._session
@@ -138,7 +169,7 @@ class SendGridEmailNotifier(Notifier):
             {
                 "camera_name": alert.camera_name,
                 "clip_id": alert.clip_id,
-                "risk_level": alert.risk_level or "unknown",
+                "risk_level": str(alert.risk_level) if alert.risk_level is not None else "unknown",
                 "activity_type": alert.activity_type or "unknown",
                 "notify_reason": alert.notify_reason,
                 "summary": alert.summary or "",
@@ -195,32 +226,3 @@ class SendGridEmailNotifier(Notifier):
             else:
                 rendered_items.append(f"<li>{rendered_value}</li>")
         return "<ul>" + "".join(rendered_items) + "</ul>"
-
-
-# Plugin registration
-from typing import cast
-
-from pydantic import BaseModel
-
-from homesec.interfaces import Notifier
-from homesec.plugins.notifiers import NotifierPlugin, notifier_plugin
-
-
-@notifier_plugin(name="sendgrid_email")
-def sendgrid_email_plugin() -> NotifierPlugin:
-    """SendGrid email notifier plugin factory.
-
-    Returns:
-        NotifierPlugin for SendGrid email notifications
-    """
-    from homesec.models.config import SendGridEmailConfig
-
-    def factory(cfg: BaseModel) -> Notifier:
-        # Config is already validated by app.py, just cast
-        return SendGridEmailNotifier(cast(SendGridEmailConfig, cfg))
-
-    return NotifierPlugin(
-        name="sendgrid_email",
-        config_model=SendGridEmailConfig,
-        factory=factory,
-    )