homesec 0.1.0__py3-none-any.whl

homesec/config/validation.py

@@ -0,0 +1,82 @@
+"""Custom configuration validation helpers."""
+
+from __future__ import annotations
+
+from homesec.config.loader import ConfigError
+from homesec.models.config import Config
+
+
+def validate_camera_references(config: Config, camera_names: list[str] | None = None) -> None:
+    """Validate that per-camera config keys reference valid camera names.
+
+    Args:
+        config: Config instance to validate
+        camera_names: Optional list of valid camera names from cameras config
+
+    Raises:
+        ConfigError: If per-camera keys reference unknown cameras
+    """
+    if camera_names is None:
+        camera_names = [camera.name for camera in config.cameras]
+
+    camera_set = set(camera_names)
+    errors = []
+
+    for camera in config.per_camera_alert:
+        if camera not in camera_set:
+            errors.append(f"per_camera_alert references unknown camera: {camera}")
+
+    if errors:
+        raise ConfigError("Invalid camera references:\n  " + "\n  ".join(errors))
+
+
+def validate_plugin_names(
+    config: Config,
+    valid_filters: list[str],
+    valid_vlms: list[str],
+    valid_storage: list[str] | None = None,
+    valid_notifiers: list[str] | None = None,
+    valid_alert_policies: list[str] | None = None,
+) -> None:
+    """Validate that plugin names are recognized.
+
+    Args:
+        config: Config instance to validate
+        valid_filters: List of valid filter plugin names
+        valid_vlms: List of valid VLM plugin names
+        valid_storage: Optional list of valid storage backends
+        valid_notifiers: Optional list of valid notifier backends
+
+    Raises:
+        ConfigError: If plugin names are not recognized
+    """
+    errors = []
+
+    if config.filter.plugin not in valid_filters:
+        errors.append(f"Unknown filter plugin: {config.filter.plugin} (valid: {valid_filters})")
+
+    if config.vlm.backend not in valid_vlms:
+        errors.append(f"Unknown VLM plugin: {config.vlm.backend} (valid: {valid_vlms})")
+
+    if valid_storage is not None and config.storage.backend not in valid_storage:
+        errors.append(
+            f"Unknown storage backend: {config.storage.backend} (valid: {valid_storage})"
+        )
+
+    if valid_notifiers is not None:
+        for notifier in config.notifiers:
+            if notifier.backend not in valid_notifiers:
+                errors.append(
+                    "Unknown notifier backend: "
+                    f"{notifier.backend} (valid: {valid_notifiers})"
+                )
+
+    if valid_alert_policies is not None:
+        if config.alert_policy.backend not in valid_alert_policies:
+            errors.append(
+                "Unknown alert policy backend: "
+                f"{config.alert_policy.backend} (valid: {valid_alert_policies})"
+            )
+
+    if errors:
+        raise ConfigError("Invalid plugin configuration:\n  " + "\n  ".join(errors))

homesec/errors.py

@@ -0,0 +1,71 @@
+"""Error hierarchy for HomeSec pipeline stages."""
+
+from __future__ import annotations
+
+
+class PipelineError(Exception):
+    """Base exception for all pipeline errors.
+    
+    Compatible with error-as-value pattern: instances can be returned as values
+    instead of raised. Preserves stack traces via exception chaining.
+    """
+
+    def __init__(
+        self, message: str, stage: str, clip_id: str, cause: Exception | None = None
+    ) -> None:
+        super().__init__(message)
+        self.stage = stage
+        self.clip_id = clip_id
+        self.cause = cause
+        self.__cause__ = cause  # Python's exception chaining
+
+
+class UploadError(PipelineError):
+    """Storage upload failed."""
+
+    def __init__(
+        self, clip_id: str, storage_uri: str | None, cause: Exception
+    ) -> None:
+        super().__init__(
+            f"Upload failed for {clip_id}", stage="upload", clip_id=clip_id, cause=cause
+        )
+        self.storage_uri = storage_uri
+
+
+class FilterError(PipelineError):
+    """Object detection filter failed."""
+
+    def __init__(self, clip_id: str, plugin_name: str, cause: Exception) -> None:
+        super().__init__(
+            f"Filter failed for {clip_id} (plugin: {plugin_name})",
+            stage="filter",
+            clip_id=clip_id,
+            cause=cause,
+        )
+        self.plugin_name = plugin_name
+
+
+class VLMError(PipelineError):
+    """VLM analysis failed."""
+
+    def __init__(self, clip_id: str, plugin_name: str, cause: Exception) -> None:
+        super().__init__(
+            f"VLM analysis failed for {clip_id} (plugin: {plugin_name})",
+            stage="vlm",
+            clip_id=clip_id,
+            cause=cause,
+        )
+        self.plugin_name = plugin_name
+
+
+class NotifyError(PipelineError):
+    """Notification delivery failed."""
+
+    def __init__(self, clip_id: str, notifier_name: str, cause: Exception) -> None:
+        super().__init__(
+            f"Notify failed for {clip_id} (notifier: {notifier_name})",
+            stage="notify",
+            clip_id=clip_id,
+            cause=cause,
+        )
+        self.notifier_name = notifier_name

homesec/health/__init__.py

@@ -0,0 +1,5 @@
+"""Health check components."""
+
+from homesec.health.server import HealthServer
+
+__all__ = ["HealthServer"]

homesec/health/server.py

@@ -0,0 +1,226 @@
+"""HTTP health check endpoint."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+from aiohttp import web
+
+if TYPE_CHECKING:
+    from homesec.interfaces import ClipSource, Notifier, StateStore, StorageBackend
+
+logger = logging.getLogger(__name__)
+
+
+class HealthServer:
+    """HTTP server for health checks.
+    
+    Provides /health endpoint returning component status.
+    """
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8080,
+    ) -> None:
+        """Initialize health server.
+        
+        Args:
+            host: Host to bind to
+            port: Port to bind to
+        """
+        self.host = host
+        self.port = port
+        
+        # Components to check (set via set_components)
+        self._state_store: StateStore | None = None
+        self._storage: StorageBackend | None = None
+        self._notifier: Notifier | None = None
+        self._sources: list[ClipSource] = []
+        self._mqtt_is_critical = False
+        
+        # Server state
+        self._app: web.Application | None = None
+        self._runner: web.AppRunner | None = None
+        self._site: web.TCPSite | None = None
+        
+        logger.info("HealthServer initialized: %s:%d", host, port)
+
+    def set_components(
+        self,
+        *,
+        state_store: StateStore | None = None,
+        storage: StorageBackend | None = None,
+        notifier: Notifier | None = None,
+        sources: list[ClipSource] | None = None,
+        mqtt_is_critical: bool = False,
+    ) -> None:
+        """Set components to check.
+        
+        Args:
+            state_store: State store to ping
+            storage: Storage backend to ping
+            notifier: Notifier to ping
+            sources: List of clip sources to check
+            mqtt_is_critical: Whether MQTT failure is critical (unhealthy vs degraded)
+        """
+        self._state_store = state_store
+        self._storage = storage
+        self._notifier = notifier
+        self._sources = sources or []
+        self._mqtt_is_critical = mqtt_is_critical
+
+    async def start(self) -> None:
+        """Start HTTP server."""
+        self._app = web.Application()
+        self._app.router.add_get("/health", self._health_handler)
+        
+        self._runner = web.AppRunner(self._app)
+        await self._runner.setup()
+        
+        self._site = web.TCPSite(self._runner, self.host, self.port)
+        await self._site.start()
+        
+        logger.info("HealthServer started: http://%s:%d/health", self.host, self.port)
+
+    async def stop(self) -> None:
+        """Stop HTTP server."""
+        if self._runner:
+            await self._runner.cleanup()
+        
+        self._app = None
+        self._runner = None
+        self._site = None
+        
+        logger.info("HealthServer stopped")
+
+    async def _health_handler(self, request: web.Request) -> web.Response:
+        """Handle GET /health request."""
+        health_data = await self.compute_health()
+        return web.json_response(health_data)
+
+    async def compute_health(self) -> dict[str, Any]:
+        """Compute health status and return JSON data.
+
+        Returns:
+            Health data dict with status, checks, warnings
+        """
+        sources = self._get_source_health()
+        # Run component checks
+        checks = {
+            "db": await self._check_db(),
+            "storage": await self._check_storage(),
+            "mqtt": await self._check_mqtt(),
+            "sources": self._check_sources(),
+        }
+
+        # Compute overall status
+        status = self._compute_status(checks)
+
+        # Generate warnings
+        warnings = self._compute_warnings()
+
+        return {
+            "status": status,
+            "checks": checks,
+            "warnings": warnings,
+            "sources": sources,
+        }
+
+    async def _check_db(self) -> bool:
+        """Check if state store is healthy."""
+        return await self._check_component(self._state_store, "State store")
+
+    async def _check_storage(self) -> bool:
+        """Check if storage backend is healthy."""
+        return await self._check_component(self._storage, "Storage")
+
+    async def _check_mqtt(self) -> bool:
+        """Check if notifier is healthy."""
+        return await self._check_component(self._notifier, "Notifier")
+
+    def _check_sources(self) -> bool:
+        """Check if all clip sources are healthy."""
+        if not self._sources:
+            return True  # No sources configured
+        
+        # All sources must be healthy
+        return all(source.is_healthy() for source in self._sources)
+
+    def _get_source_health(self) -> list[dict[str, object]]:
+        """Return per-source health detail."""
+        if not self._sources:
+            return []
+
+        current_time = time.monotonic()
+        details: list[dict[str, object]] = []
+        for source in self._sources:
+            camera_name = getattr(source, "camera_name", "unknown")
+            last_heartbeat = source.last_heartbeat()
+            details.append({
+                "name": camera_name,
+                "healthy": source.is_healthy(),
+                "last_heartbeat": last_heartbeat,
+                "last_heartbeat_age_s": round(current_time - last_heartbeat, 3),
+            })
+        return details
+
+    async def _check_component(
+        self,
+        component: StateStore | StorageBackend | Notifier | None,
+        label: str,
+    ) -> bool:
+        if component is None:
+            return True
+
+        try:
+            return await component.ping()
+        except Exception as e:
+            logger.warning("%s health check failed: %s", label, e, exc_info=True)
+            return False
+
+    def _compute_status(self, checks: dict[str, bool]) -> str:
+        """Compute overall health status.
+        
+        Args:
+            checks: Dict of component check results
+            
+        Returns:
+            "healthy", "degraded", or "unhealthy"
+        """
+        # Critical checks (unhealthy if fail)
+        if not checks["sources"]:
+            return "unhealthy"
+        
+        if not checks["storage"]:
+            return "unhealthy"
+        
+        # MQTT can be critical (configurable)
+        if not checks["mqtt"] and self._mqtt_is_critical:
+            return "unhealthy"
+        
+        # Non-critical checks (degraded if fail)
+        if not checks["db"] or not checks["mqtt"]:
+            return "degraded"
+        
+        return "healthy"
+
+    def _compute_warnings(self) -> list[str]:
+        """Generate warnings for stale heartbeats.
+        
+        Returns:
+            List of warning messages
+        """
+        warnings: list[str] = []
+        
+        # Check source heartbeats (warn if > 2 minutes)
+        current_time = time.monotonic()
+        for source in self._sources:
+            heartbeat_age = current_time - source.last_heartbeat()
+            if heartbeat_age > 120:  # 2 minutes
+                camera_name = getattr(source, "camera_name", "unknown")
+                warnings.append(f"source_{camera_name}_heartbeat_stale")
+        
+        return warnings

homesec/interfaces.py

@@ -0,0 +1,249 @@
+"""Interface definitions for HomeSec pipeline components."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from homesec.models.alert import Alert, AlertDecision
+    from homesec.models.clip import Clip, ClipStateData
+    from homesec.models.events import ClipLifecycleEvent
+    from homesec.models.filter import FilterOverrides, FilterResult
+    from homesec.models.storage import StorageUploadResult
+    from homesec.models.vlm import AnalysisResult, VLMConfig
+
+
+class Shutdownable(ABC):
+    """Async shutdown interface for managed components."""
+
+    @abstractmethod
+    async def shutdown(self, timeout: float | None = None) -> None:
+        """Release resources and stop background work."""
+        raise NotImplementedError
+
+
+class ClipSource(Shutdownable, ABC):
+    """Produces finalized clips and notifies pipeline via callback."""
+
+    @abstractmethod
+    def register_callback(self, callback: Callable[[Clip], None]) -> None:
+        """Register callback to be invoked when a new clip is finalized."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start producing clips (long-running, blocks or runs in background)."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_healthy(self) -> bool:
+        """Check if source is actively able to receive clips.
+
+        Implementation should check:
+        - Process/thread is alive
+        - Receiving data recently (e.g., RTSP frames within timeout)
+        - NOT dependent on motion/clip activity
+
+        Examples:
+        - RTSP: frame pipeline running + receiving frames recently
+        - FTP: server thread alive + accepting connections
+
+        Returns False if source has failed and needs restart.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def last_heartbeat(self) -> float:
+        """Return timestamp (monotonic) of last successful operation.
+
+        Examples:
+        - RTSP: timestamp of last frame received
+        - FTP: timestamp of last connection check
+
+        Updated continuously (every ~60s), independent of motion/clips.
+        Used for observability, not health status.
+        """
+        raise NotImplementedError
+
+
+class StorageBackend(Shutdownable, ABC):
+    """Stores raw clips and derived artifacts."""
+
+    @abstractmethod
+    async def put_file(self, local_path: Path, dest_path: str) -> "StorageUploadResult":
+        """Upload file to storage. Returns storage result."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_view_url(self, storage_uri: str) -> str | None:
+        """Return a web-accessible view URL for the given storage URI."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get(self, storage_uri: str, local_path: Path) -> None:
+        """Download file from storage to local path."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def exists(self, storage_uri: str) -> bool:
+        """Check if file exists in storage."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete(self, storage_uri: str) -> None:
+        """Delete an object from storage.
+
+        Must be idempotent: deleting a missing object should succeed.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check. Returns True if storage is reachable."""
+        raise NotImplementedError
+
+
+class StateStore(Shutdownable, ABC):
+    """Manages clip workflow state in Postgres."""
+
+    @abstractmethod
+    async def upsert(self, clip_id: str, data: ClipStateData) -> None:
+        """Insert or update clip state."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get(self, clip_id: str) -> ClipStateData | None:
+        """Retrieve clip state. Returns None if not found."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_candidate_clips_for_cleanup(
+        self,
+        *,
+        older_than_days: int | None,
+        camera_name: str | None,
+        batch_size: int,
+        cursor: tuple[datetime, str] | None = None,
+    ) -> list[tuple[str, ClipStateData, datetime]]:
+        """List clip states for cleanup scanning."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check. Returns True if database is reachable."""
+        raise NotImplementedError
+
+
+class EventStore(ABC):
+    """Manages clip lifecycle events in Postgres."""
+
+    @abstractmethod
+    async def append(self, event: ClipLifecycleEvent) -> None:
+        """Append a lifecycle event.
+        
+        Events are appended with database-assigned ids.
+        Raises on database errors (should be retried by caller).
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_events(
+        self,
+        clip_id: str,
+        after_id: int | None = None,
+    ) -> list[ClipLifecycleEvent]:
+        """Get all events for a clip, optionally after an event id.
+        
+        Returns events ordered by id. Returns empty list on error.
+        """
+        raise NotImplementedError
+
+
+class Notifier(Shutdownable, ABC):
+    """Sends notifications (e.g., MQTT, email, SMS)."""
+
+    @abstractmethod
+    async def send(self, alert: Alert) -> None:
+        """Send notification. Raises on failure."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check. Returns True if notifier is reachable."""
+        raise NotImplementedError
+
+class AlertPolicy(ABC):
+    """Decides whether to notify based on analysis results."""
+
+    @abstractmethod
+    def should_notify(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> tuple[bool, str]:
+        """Determine if notification should be sent.
+
+        Returns:
+            (notify, reason) tuple where reason explains the decision.
+        """
+        raise NotImplementedError
+
+    def make_decision(
+        self,
+        camera_name: str,
+        filter_result: FilterResult | None,
+        analysis: AnalysisResult | None,
+    ) -> "AlertDecision":
+        """Build an AlertDecision from should_notify output."""
+        from homesec.models.alert import AlertDecision
+
+        notify, reason = self.should_notify(camera_name, filter_result, analysis)
+        return AlertDecision(notify=notify, notify_reason=reason)
+
+
+class ObjectFilter(Shutdownable, ABC):
+    """Plugin interface for object detection in video clips."""
+
+    @abstractmethod
+    async def detect(self, video_path: Path, overrides: FilterOverrides | None = None) -> FilterResult:
+        """Detect objects in video clip.
+
+        Implementation notes:
+        - MUST be async (use asyncio.to_thread or run_in_executor for blocking code)
+        - CPU/GPU-bound plugins should manage their own ProcessPoolExecutor internally
+        - I/O-bound plugins can use async HTTP clients directly
+        - Should respect the instance config max_workers if managing worker pool
+        - Should support early exit on first detection for efficiency
+        - overrides apply per-call (model path cannot be overridden)
+
+        Returns:
+            FilterResult with detected_classes, confidence, sampled_frames, model name
+        """
+        raise NotImplementedError
+
+class VLMAnalyzer(Shutdownable, ABC):
+    """Plugin interface for VLM-based clip analysis."""
+
+    @abstractmethod
+    async def analyze(
+        self, video_path: Path, filter_result: FilterResult, config: VLMConfig
+    ) -> AnalysisResult:
+        """Analyze clip and produce structured assessment.
+
+        Implementation notes:
+        - MUST be async (use asyncio.to_thread or run_in_executor for blocking code)
+        - Local models: manage ProcessPoolExecutor internally
+        - API-based: use async HTTP clients (aiohttp, httpx)
+        - Should respect config.max_workers if managing worker pool
+        - Should use filter_result to focus analysis (e.g., detected person at timestamp X)
+
+        Returns:
+            AnalysisResult with risk_level, activity_type, summary, etc.
+        """
+        raise NotImplementedError
+
+    # shutdown() defined in Shutdownable