homesec 0.1.0__py3-none-any.whl

homesec/plugins/alert_policies/__init__.py

@@ -0,0 +1,80 @@
+"""Alert policy 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 AlertPolicy
+from homesec.models.config import AlertPolicyOverrides
+
+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.
+
+    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)
+
+    Returns:
+        Decorator function that registers the plugin
+    """
+
+    def decorator(factory_fn: T) -> T:
+        plugin = factory_fn()
+        register_alert_policy(plugin)
+        return factory_fn
+
+    return decorator
+
+
+__all__ = [
+    "AlertPolicyPlugin",
+    "ALERT_POLICY_REGISTRY",
+    "register_alert_policy",
+    "alert_policy_plugin",
+]

homesec/plugins/alert_policies/default.py

@@ -0,0 +1,111 @@
+"""Default alert policy plugin."""
+
+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.filter import FilterResult
+from homesec.models.vlm import AnalysisResult
+
+# Risk level ordering for comparison
+RISK_LEVELS = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+
+
+class DefaultAlertPolicy(AlertPolicy):
+    """Default alert policy implementation."""
+
+    def __init__(
+        self,
+        settings: DefaultAlertPolicySettings,
+        overrides: dict[str, AlertPolicyOverrides],
+        trigger_classes: list[str],
+    ) -> None:
+        self._settings = settings
+        self._overrides = overrides
+        self._trigger_classes = list(trigger_classes)
+
+    def should_notify(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> tuple[bool, str]:
+        policy = self._policy_for(camera_name)
+
+        # Check notify_on_motion first (bypasses VLM)
+        if policy.notify_on_motion:
+            return True, "notify_on_motion=true"
+
+        # If no analysis, check if filter detected trigger classes (VLM failure fallback)
+        if analysis is None:
+            if filter_result and self._filter_detected_trigger_classes(filter_result):
+                return True, "filter_detected_trigger_vlm_failed"
+            return False, "no_analysis"
+
+        # Check risk level threshold
+        if self._risk_meets_threshold(analysis.risk_level, policy.min_risk_level):
+            return True, f"risk_level={analysis.risk_level}"
+
+        # Check activity type list
+        if analysis.activity_type in policy.notify_on_activity_types:
+            return True, f"activity_type={analysis.activity_type} (per-camera)"
+
+        return False, "below_threshold"
+
+    def make_decision(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> AlertDecision:
+        notify, reason = self.should_notify(camera_name, filter_result, analysis)
+        return AlertDecision(notify=notify, notify_reason=reason)
+
+    def _policy_for(self, camera_name: str) -> DefaultAlertPolicySettings:
+        overrides = self._overrides.get(camera_name)
+        if overrides is None:
+            return self._settings
+        merged = {
+            **self._settings.model_dump(),
+            **overrides.model_dump(exclude_none=True),
+        }
+        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 _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.plugins.alert_policies import AlertPolicyPlugin, alert_policy_plugin
+from homesec.interfaces import AlertPolicy
+
+
+@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 AlertPolicyOverrides, 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

@@ -0,0 +1,60 @@
+"""No-op alert policy."""
+
+from __future__ import annotations
+
+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
+
+
+class NoopAlertPolicy(AlertPolicy):
+    """Alert policy that never notifies."""
+
+    def should_notify(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> tuple[bool, str]:
+        return False, "alert_policy_disabled"
+
+    def make_decision(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> AlertDecision:
+        return AlertDecision(notify=False, notify_reason="alert_policy_disabled")
+
+
+# Plugin registration
+from pydantic import BaseModel
+from homesec.plugins.alert_policies import AlertPolicyPlugin, alert_policy_plugin
+from homesec.interfaces import AlertPolicy
+
+
+@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

@@ -0,0 +1,126 @@
+"""VLM analyzer plugins and registry."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Callable, TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel
+
+from homesec.interfaces import VLMAnalyzer
+
+if TYPE_CHECKING:
+    from homesec.models.vlm import VLMConfig
+
+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(...)
+
+    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_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
+
+    Raises:
+        ValueError: If plugin name is unknown or 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 plugin.factory(validated_config)
+
+
+__all__ = [
+    "VLMPlugin",
+    "VLMFactory",
+    "VLM_REGISTRY",
+    "register_vlm",
+    "vlm_plugin",
+    "load_vlm_plugin",
+]