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

homesec/plugins/alert_policies/__init__.py

@@ -3,77 +3,52 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import TypeVar
-
-from pydantic import BaseModel
+from typing import Any, cast
 
 from homesec.interfaces import AlertPolicy
 from homesec.models.config import AlertPolicyOverrides
+from homesec.plugins.alert_policies.noop import NoopAlertPolicySettings
+from homesec.plugins.registry import PluginType, load_plugin
 
 logger = logging.getLogger(__name__)
 
 
-AlertPolicyFactory = Callable[[BaseModel, dict[str, AlertPolicyOverrides], list[str]], AlertPolicy]
-
-
-@dataclass(frozen=True)
-class AlertPolicyPlugin:
-    name: str
-    config_model: type[BaseModel]
-    factory: AlertPolicyFactory
-
-
-ALERT_POLICY_REGISTRY: dict[str, AlertPolicyPlugin] = {}
-
-
-def register_alert_policy(plugin: AlertPolicyPlugin) -> None:
-    """Register an alert policy plugin with collision detection.
+def load_alert_policy(
+    config: Any,  # AlertPolicyConfig but trying to avoid circular import if possible
+    per_camera_overrides: dict[str, AlertPolicyOverrides],
+    trigger_classes: list[str],
+) -> AlertPolicy:
+    """Load and instantiate an alert policy plugin.
 
     Args:
-        plugin: Alert policy plugin to register
-
-    Raises:
-        ValueError: If a plugin with the same name is already registered
-    """
-    if plugin.name in ALERT_POLICY_REGISTRY:
-        raise ValueError(
-            f"Alert policy plugin '{plugin.name}' is already registered. "
-            f"Plugin names must be unique across all alert policy plugins."
-        )
-    ALERT_POLICY_REGISTRY[plugin.name] = plugin
-
-
-T = TypeVar("T", bound=Callable[[], AlertPolicyPlugin])
-
-
-def alert_policy_plugin(name: str) -> Callable[[T], T]:
-    """Decorator to register an alert policy plugin.
-
-    Usage:
-        @alert_policy_plugin(name="my_policy")
-        def my_policy_plugin() -> AlertPolicyPlugin:
-            return AlertPolicyPlugin(...)
-
-    Args:
-        name: Plugin name (for validation only - must match plugin.name)
+        config: Alert policy configuration (AlertPolicyConfig)
+        per_camera_overrides: Map of camera name to override settings
+        trigger_classes: List of object classes that trigger analysis
 
     Returns:
-        Decorator function that registers the plugin
+        Configured AlertPolicy instance
     """
+    # Handle disabled -> noop fallback
+    if not config.enabled:
+        return cast(
+            AlertPolicy,
+            load_plugin(
+                PluginType.ALERT_POLICY,
+                "noop",
+                NoopAlertPolicySettings(),
+            ),
+        )
 
-    def decorator(factory_fn: T) -> T:
-        plugin = factory_fn()
-        register_alert_policy(plugin)
-        return factory_fn
-
-    return decorator
+    return cast(
+        AlertPolicy,
+        load_plugin(
+            PluginType.ALERT_POLICY,
+            config.backend,
+            config.config,
+            overrides=per_camera_overrides,
+            trigger_classes=trigger_classes,
+        ),
+    )
 
 
-__all__ = [
-    "AlertPolicyPlugin",
-    "ALERT_POLICY_REGISTRY",
-    "register_alert_policy",
-    "alert_policy_plugin",
-]
+__all__ = ["load_alert_policy"]

homesec/plugins/alert_policies/default.py

@@ -4,26 +4,27 @@ from __future__ import annotations
 
 from homesec.interfaces import AlertPolicy
 from homesec.models.alert import AlertDecision
-from homesec.models.config import AlertPolicyOverrides, DefaultAlertPolicySettings
+from homesec.models.config import DefaultAlertPolicySettings
+from homesec.models.enums import RiskLevel
 from homesec.models.filter import FilterResult
 from homesec.models.vlm import AnalysisResult
-
-# Risk level ordering for comparison
-RISK_LEVELS = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+from homesec.plugins.registry import PluginType, plugin
 
 
+@plugin(plugin_type=PluginType.ALERT_POLICY, name="default")
 class DefaultAlertPolicy(AlertPolicy):
     """Default alert policy implementation."""
 
-    def __init__(
-        self,
-        settings: DefaultAlertPolicySettings,
-        overrides: dict[str, AlertPolicyOverrides],
-        trigger_classes: list[str],
-    ) -> None:
+    config_cls = DefaultAlertPolicySettings
+
+    @classmethod
+    def create(cls, config: DefaultAlertPolicySettings) -> AlertPolicy:
+        return cls(config)
+
+    def __init__(self, settings: DefaultAlertPolicySettings) -> None:
         self._settings = settings
-        self._overrides = overrides
-        self._trigger_classes = list(trigger_classes)
+        self._overrides = settings.overrides
+        self._trigger_classes = list(settings.trigger_classes)
 
     def should_notify(
         self,
@@ -72,41 +73,15 @@ class DefaultAlertPolicy(AlertPolicy):
         }
         return DefaultAlertPolicySettings.model_validate(merged)
 
-    def _risk_meets_threshold(self, actual: str, threshold: str) -> bool:
-        return RISK_LEVELS.get(actual, 0) >= RISK_LEVELS.get(threshold, 0)
+    def _risk_meets_threshold(self, actual: RiskLevel, threshold: RiskLevel) -> bool:
+        """Check if actual risk level meets or exceeds threshold.
+
+        Uses IntEnum comparison for natural ordering:
+            RiskLevel.HIGH >= RiskLevel.MEDIUM  # True
+        """
+        return actual >= threshold
 
     def _filter_detected_trigger_classes(self, filter_result: FilterResult) -> bool:
         detected = set(filter_result.detected_classes)
         trigger = set(self._trigger_classes)
         return bool(detected & trigger)
-
-
-# Plugin registration
-from pydantic import BaseModel
-
-from homesec.interfaces import AlertPolicy
-from homesec.plugins.alert_policies import AlertPolicyPlugin, alert_policy_plugin
-
-
-@alert_policy_plugin(name="default")
-def default_alert_policy_plugin() -> AlertPolicyPlugin:
-    """Default alert policy plugin factory.
-
-    Returns:
-        AlertPolicyPlugin for default risk-based alert policy
-    """
-    from homesec.models.config import DefaultAlertPolicySettings
-
-    def factory(
-        cfg: BaseModel,
-        overrides: dict[str, AlertPolicyOverrides],
-        trigger_classes: list[str],
-    ) -> AlertPolicy:
-        settings = DefaultAlertPolicySettings.model_validate(cfg)
-        return DefaultAlertPolicy(settings, overrides, trigger_classes)
-
-    return AlertPolicyPlugin(
-        name="default",
-        config_model=DefaultAlertPolicySettings,
-        factory=factory,
-    )

homesec/plugins/alert_policies/noop.py

@@ -6,14 +6,27 @@ from pydantic import BaseModel
 
 from homesec.interfaces import AlertPolicy
 from homesec.models.alert import AlertDecision
-from homesec.models.config import AlertPolicyOverrides
 from homesec.models.filter import FilterResult
 from homesec.models.vlm import AnalysisResult
+from homesec.plugins.registry import PluginType, plugin
 
 
+class NoopAlertPolicySettings(BaseModel):
+    """Settings for no-op alert policy (empty - no configuration needed)."""
+
+    model_config = {"extra": "forbid"}
+
+
+@plugin(plugin_type=PluginType.ALERT_POLICY, name="noop")
 class NoopAlertPolicy(AlertPolicy):
     """Alert policy that never notifies."""
 
+    config_cls = NoopAlertPolicySettings
+
+    @classmethod
+    def create(cls, config: NoopAlertPolicySettings) -> AlertPolicy:
+        return cls()
+
     def should_notify(
         self,
         camera_name: str,
@@ -29,31 +42,3 @@ class NoopAlertPolicy(AlertPolicy):
         analysis: AnalysisResult | None,
     ) -> AlertDecision:
         return AlertDecision(notify=False, notify_reason="alert_policy_disabled")
-
-
-# Plugin registration
-from homesec.interfaces import AlertPolicy
-from homesec.plugins.alert_policies import AlertPolicyPlugin, alert_policy_plugin
-
-
-@alert_policy_plugin(name="noop")
-def noop_alert_policy_plugin() -> AlertPolicyPlugin:
-    """Noop alert policy plugin that never sends alerts.
-
-    Returns:
-        AlertPolicyPlugin for no-op alert policy
-    """
-
-    def factory(
-        cfg: BaseModel,
-        overrides: dict[str, AlertPolicyOverrides],
-        trigger_classes: list[str],
-    ) -> AlertPolicy:
-        # NoopAlertPolicy doesn't use any config
-        return NoopAlertPolicy()
-
-    return AlertPolicyPlugin(
-        name="noop",
-        config_model=BaseModel,  # No config needed
-        factory=factory,
-    )

homesec/plugins/analyzers/__init__.py

@@ -1,125 +1,40 @@
-"""VLM analyzer plugins and registry."""
+"""Analyzer plugins and registry."""
 
 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 VLMAnalyzer
-
-if TYPE_CHECKING:
-    from homesec.models.vlm import VLMConfig
+from homesec.models.vlm import VLMConfig
+from homesec.plugins.registry import PluginType, load_plugin
 
 logger = logging.getLogger(__name__)
 
-# Type alias for clarity
-VLMFactory = Callable[["VLMConfig"], VLMAnalyzer]
-
-
-@dataclass(frozen=True)
-class VLMPlugin:
-    """Metadata for a VLM analyzer plugin."""
-
-    name: str
-    config_model: type[BaseModel]
-    factory: VLMFactory
-
-
-VLM_REGISTRY: dict[str, VLMPlugin] = {}
-
-
-def register_vlm(plugin: VLMPlugin) -> None:
-    """Register a VLM plugin with collision detection.
-
-    Args:
-        plugin: VLM plugin to register
-
-    Raises:
-        ValueError: If a plugin with the same name is already registered
-    """
-    if plugin.name in VLM_REGISTRY:
-        raise ValueError(
-            f"VLM plugin '{plugin.name}' is already registered. "
-            f"Plugin names must be unique across all VLM plugins."
-        )
-    VLM_REGISTRY[plugin.name] = plugin
-
-
-T = TypeVar("T", bound=Callable[[], VLMPlugin])
-
 
-def vlm_plugin(name: str) -> Callable[[T], T]:
-    """Decorator to register a VLM analyzer plugin.
-
-    Usage:
-        @vlm_plugin(name="my_vlm")
-        def my_vlm_plugin() -> VLMPlugin:
-            return VLMPlugin(...)
+def load_analyzer(config: VLMConfig) -> VLMAnalyzer:
+    """Load and instantiate a VLM analyzer plugin.
 
     Args:
-        name: Plugin name (for validation only - must match plugin.name)
+        config: VLM configuration
 
     Returns:
-        Decorator function that registers the plugin
-    """
-
-    def decorator(factory_fn: T) -> T:
-        plugin = factory_fn()
-        register_vlm(plugin)
-        return factory_fn
-
-    return decorator
-
-
-def load_vlm_plugin(config: VLMConfig) -> VLMAnalyzer:
-    """Load VLM plugin by name from config.
-
-    Validates the llm dict against the plugin's config_model and creates
-    a VLMConfig with the validated settings object.
-
-    Args:
-        config: VLM configuration with backend name and raw llm dict
-
-    Returns:
-        Instantiated VLM plugin
+        Configured VLMAnalyzer instance
 
     Raises:
-        ValueError: If plugin name is unknown or config validation fails
+        ValueError: If backend not found in registry
+        ValidationError: If config validation fails
     """
-    plugin_name = config.backend.lower()
-
-    if plugin_name not in VLM_REGISTRY:
-        available = ", ".join(sorted(VLM_REGISTRY.keys()))
-        raise ValueError(f"Unknown VLM plugin: '{plugin_name}'. Available: {available}")
-
-    plugin = VLM_REGISTRY[plugin_name]
-
-    # Validate config.llm dict against plugin's config_model
-    validated_llm_settings = plugin.config_model.model_validate(config.llm)
-
-    # Create new VLMConfig with validated llm settings object
-    from homesec.models.vlm import VLMConfig as VLMConfigModel
-
-    validated_config = VLMConfigModel(
-        backend=config.backend,
-        trigger_classes=config.trigger_classes,
-        max_workers=config.max_workers,
-        llm=validated_llm_settings,
-        preprocessing=config.preprocessing,
+    return cast(
+        VLMAnalyzer,
+        load_plugin(
+            PluginType.ANALYZER,
+            config.backend,
+            config.llm,
+            trigger_classes=config.trigger_classes,
+            max_workers=config.max_workers,
+        ),
     )
 
-    return plugin.factory(validated_config)
-
 
-__all__ = [
-    "VLMPlugin",
-    "VLMFactory",
-    "VLM_REGISTRY",
-    "register_vlm",
-    "vlm_plugin",
-    "load_vlm_plugin",
-]
+__all__ = ["load_analyzer"]

homesec/plugins/analyzers/openai.py

@@ -8,10 +8,25 @@ import json
 import logging
 import os
 from pathlib import Path
+from typing import Any
+
+aiohttp: Any
+cv2: Any
+Image: Any
+
+try:
+    import aiohttp as _aiohttp
+    import cv2 as _cv2
+    from PIL import Image as _Image
+except Exception:
+    aiohttp = None
+    cv2 = None
+    Image = None
+else:
+    aiohttp = _aiohttp
+    cv2 = _cv2
+    Image = _Image
 
-import aiohttp
-import cv2
-from PIL import Image
 from pydantic import BaseModel
 
 from homesec.interfaces import VLMAnalyzer
@@ -23,6 +38,7 @@ from homesec.models.vlm import (
     VLMConfig,
     VLMPreprocessConfig,
 )
+from homesec.plugins.registry import PluginType, plugin
 
 logger = logging.getLogger(__name__)
 
@@ -45,6 +61,15 @@ Focus on KEY EVENTS ONLY:
 Keep observations list concise (short bullet points of security-relevant actions)."""
 
 
+def _ensure_openai_dependencies() -> None:
+    """Fail fast with a clear error if OpenAI VLM dependencies are missing."""
+    if aiohttp is None or cv2 is None or Image is None:
+        raise RuntimeError(
+            "Missing dependency for OpenAI VLM. "
+            "Install with: uv pip install aiohttp opencv-python pillow"
+        )
+
+
 def _create_json_schema_format(
     schema_model: type[BaseModel], schema_name: str
 ) -> dict[str, object]:
@@ -59,6 +84,7 @@ def _create_json_schema_format(
     }
 
 
+@plugin(plugin_type=PluginType.ANALYZER, name="openai")
 class OpenAIVLM(VLMAnalyzer):
     """OpenAI-compatible VLM analyzer plugin.
 
@@ -66,49 +92,43 @@ class OpenAIVLM(VLMAnalyzer):
     Supports structured output with Pydantic schemas.
     """
 
-    def __init__(self, config: VLMConfig) -> None:
-        """Initialize OpenAI VLM with config validation.
-
-        Required config:
-            llm.api_key_env: Env var name with API key
-            llm.model: Model name (e.g., gpt-4o)
-
-        Optional config:
-            llm.base_url: API base URL (default: https://api.openai.com/v1)
-            llm.token_param: max_tokens or max_completion_tokens
-            llm.max_completion_tokens/max_tokens: Token limits
-            llm.temperature: Temperature (None to omit)
-            preprocessing.max_frames: Maximum frames to send (default: 10)
-            preprocessing.max_size: Max image dimension (default: 1024)
-            preprocessing.quality: JPEG quality (default: 85)
+    config_cls = OpenAILLMConfig
+
+    @classmethod
+    def create(cls, config: OpenAILLMConfig) -> VLMAnalyzer:
+        return cls(config)
+
+    def __init__(self, llm_config: OpenAILLMConfig) -> None:
+        """Initialize OpenAI VLM with validated LLM config.
+
+        Args:
+            llm_config: OpenAI-specific configuration (API key, model, etc.)
+                        Also assumes injected runtime fields (trigger_classes, max_workers)
         """
-        if not isinstance(config.llm, OpenAILLMConfig):
-            raise ValueError("OpenAIVLM requires llm=OpenAILLMConfig")
-        llm = config.llm
-        preprocess = config.preprocessing
+        _ensure_openai_dependencies()
+        self._config = llm_config
 
         # Get API key from env
-        self._api_key_env = llm.api_key_env
+        self._api_key_env = llm_config.api_key_env
         self.api_key = os.getenv(self._api_key_env)
         if not self.api_key:
             raise ValueError(f"API key not found in env: {self._api_key_env}")
 
-        self.model = llm.model
-        self.base_url = llm.base_url
+        self.model = llm_config.model
+        self.base_url = llm_config.base_url
         self.system_prompt = DEFAULT_SYSTEM_PROMPT
-        self.temperature = llm.temperature
-        self.token_param = llm.token_param
-        self.max_tokens = self._resolve_token_limit(llm)
-        self.request_timeout = float(llm.request_timeout)
+        self.temperature = llm_config.temperature
+        self.token_param = llm_config.token_param
+        self.max_tokens = self._resolve_token_limit(llm_config)
+        self.request_timeout = float(llm_config.request_timeout)
 
         # Create HTTP session
         self._session: aiohttp.ClientSession | None = None
         self._shutdown_called = False
 
         logger.info(
-            "OpenAIVLM initialized: model=%s, max_frames=%d, token_param=%s, temperature=%s",
+            "OpenAIVLM initialized: model=%s, token_param=%s, temperature=%s",
             self.model,
-            preprocess.max_frames,
             self.token_param,
             self.temperature if self.temperature is not None else "default",
         )
@@ -116,6 +136,8 @@ class OpenAIVLM(VLMAnalyzer):
     async def _ensure_session(self) -> aiohttp.ClientSession:
         """Lazy-create aiohttp session with timeout."""
         if self._session is None:
+            if aiohttp is None:
+                raise RuntimeError("aiohttp dependency is required for OpenAI VLM")
             timeout = aiohttp.ClientTimeout(total=self.request_timeout)
             self._session = aiohttp.ClientSession(timeout=timeout)
         return self._session
@@ -256,7 +278,8 @@ class OpenAIVLM(VLMAnalyzer):
         async with session.post(url, json=payload, headers=headers) as resp:
             if resp.status != 200:
                 error_text = await resp.text()
-                raise RuntimeError(f"OpenAI API error {resp.status}: {error_text}")
+                logger.debug("OpenAI API error details: %s", error_text)
+                raise RuntimeError(f"OpenAI API error: HTTP {resp.status}")
 
             data = await resp.json()
             if not isinstance(data, dict):
@@ -330,6 +353,9 @@ class OpenAIVLM(VLMAnalyzer):
 
         Returns list of (base64 JPEG, timestamp) tuples.
         """
+        if cv2 is None or Image is None:
+            raise RuntimeError("OpenAI VLM dependencies are not available")
+
         cap = cv2.VideoCapture(str(video_path))
         total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
 
@@ -413,25 +439,16 @@ class OpenAIVLM(VLMAnalyzer):
 
         logger.info("OpenAIVLM shutdown complete")
 
+    async def ping(self) -> bool:
+        """Health check - verify API is reachable.
 
-# Plugin registration
-from homesec.plugins.analyzers import VLMPlugin, vlm_plugin
-
-
-@vlm_plugin(name="openai")
-def openai_vlm_plugin() -> VLMPlugin:
-    """OpenAI VLM plugin factory.
-
-    Returns:
-        VLMPlugin for OpenAI vision-language model
-    """
-    from homesec.models.vlm import OpenAILLMConfig
-
-    def factory(cfg: VLMConfig) -> VLMAnalyzer:
-        return OpenAIVLM(cfg)
-
-    return VLMPlugin(
-        name="openai",
-        config_model=OpenAILLMConfig,
-        factory=factory,
-    )
+        Note: This checks if session is alive and not shut down.
+        A full API connectivity check would require an API call.
+        """
+        if self._shutdown_called:
+            return False
+        # Session being None is fine - it's lazy-created
+        # If session exists and is closed, that's a problem
+        if self._session is not None and self._session.closed:
+            return False
+        return True