homesec 0.1.0__py3-none-any.whl

homesec/__init__.py

@@ -0,0 +1,20 @@
+"""HomeSec camera pipeline."""
+
+__version__ = "0.1.0"
+
+# Export commonly used types
+from homesec.errors import PipelineError
+from homesec.models.alert import Alert
+from homesec.models.clip import Clip, ClipStateData
+from homesec.models.filter import FilterResult
+from homesec.models.vlm import AnalysisResult
+
+__all__ = [
+    "__version__",
+    "Alert",
+    "AnalysisResult",
+    "Clip",
+    "ClipStateData",
+    "FilterResult",
+    "PipelineError",
+]

homesec/app.py

@@ -0,0 +1,393 @@
+"""Main application that wires all components together."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, cast
+
+from pydantic import BaseModel
+
+from homesec.config import (
+    load_config,
+    resolve_env_var,
+    validate_camera_references,
+    validate_plugin_names,
+)
+from homesec.health import HealthServer
+from homesec.pipeline import ClipPipeline
+from homesec.plugins.analyzers import VLM_REGISTRY, load_vlm_plugin
+from homesec.plugins.alert_policies import ALERT_POLICY_REGISTRY
+from homesec.plugins.filters import FILTER_REGISTRY, load_filter_plugin
+from homesec.plugins.notifiers import (
+    NOTIFIER_REGISTRY,
+    MultiplexNotifier,
+    NotifierEntry,
+    NotifierPlugin,
+)
+from homesec.plugins.storage import STORAGE_REGISTRY, create_storage
+from homesec.sources import FtpSource, LocalFolderSource, RTSPSource
+from homesec.models.config import NotifierConfig
+from homesec.models.source import FtpSourceConfig, LocalFolderSourceConfig, RTSPSourceConfig
+from homesec.interfaces import EventStore
+from homesec.repository import ClipRepository
+from homesec.state import NoopEventStore, NoopStateStore, PostgresStateStore
+
+if TYPE_CHECKING:
+    from homesec.models.config import Config
+    from homesec.interfaces import (
+        AlertPolicy,
+        ClipSource,
+        Notifier,
+        ObjectFilter,
+        StateStore,
+        StorageBackend,
+        VLMAnalyzer,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class Application:
+    """Main application that orchestrates all components.
+    
+    Handles component creation, lifecycle, and graceful shutdown.
+    """
+
+    def __init__(self, config_path: Path) -> None:
+        """Initialize application with config file path.
+        
+        Args:
+            config_path: Path to YAML config file
+        """
+        self._config_path = config_path
+        self._config: Config | None = None
+        
+        # Components (created in _create_components)
+        self._storage: StorageBackend | None = None
+        self._state_store: StateStore = NoopStateStore()
+        self._event_store: EventStore = NoopEventStore()
+        self._repository: ClipRepository | None = None
+        self._notifier: Notifier | None = None
+        self._notifier_entries: list[NotifierEntry] = []
+        self._filter: ObjectFilter | None = None
+        self._vlm: VLMAnalyzer | None = None
+        self._sources: list[ClipSource] = []
+        self._pipeline: ClipPipeline | None = None
+        self._health_server: HealthServer | None = None
+        
+        # Shutdown state
+        self._shutdown_event = asyncio.Event()
+        self._shutdown_started = False
+
+    async def run(self) -> None:
+        """Run the application.
+        
+        Loads config, creates components, and runs until shutdown signal.
+        """
+        logger.info("Starting HomeSec application...")
+        
+        # Load config
+        self._config = load_config(self._config_path)
+        logger.info("Config loaded from %s", self._config_path)
+        
+        # Create components
+        await self._create_components()
+        
+        # Set up signal handlers
+        self._setup_signal_handlers()
+        
+        # Start health server
+        if self._health_server:
+            await self._health_server.start()
+        
+        # Start sources
+        for source in self._sources:
+            await source.start()
+        
+        logger.info("Application started. Waiting for clips...")
+        
+        # Wait for shutdown signal
+        await self._shutdown_event.wait()
+        
+        # Graceful shutdown
+        await self.shutdown()
+
+    async def _create_components(self) -> None:
+        """Create all components based on config."""
+        config = self._require_config()
+
+        # Discover plugins before validation
+        from homesec.plugins import discover_all_plugins
+
+        discover_all_plugins()
+
+        # Validate config references and plugin names before instantiating components
+        self._validate_config(config)
+
+        # Create storage backend
+        self._storage = self._create_storage(config)
+
+        # Create state store
+        self._state_store = await self._create_state_store(config)
+        self._event_store = self._create_event_store(self._state_store)
+        self._repository = ClipRepository(
+            self._state_store,
+            self._event_store,
+            retry=config.retry,
+        )
+        assert self._storage is not None
+        assert self._repository is not None
+
+        # Create notifier
+        self._notifier = self._create_notifier(config)
+        assert self._notifier is not None
+        await self._log_notifier_health()
+
+        # Create filter, VLM, and alert policy plugins
+        filter_plugin = load_filter_plugin(config.filter)
+        vlm_plugin = load_vlm_plugin(config.vlm)
+        self._filter = filter_plugin
+        self._vlm = vlm_plugin
+        alert_policy = self._create_alert_policy(config)
+        
+        # Create pipeline
+        self._pipeline = ClipPipeline(
+            config=config,
+            storage=self._storage,
+            repository=self._repository,
+            filter_plugin=filter_plugin,
+            vlm_plugin=vlm_plugin,
+            notifier=self._notifier,
+            alert_policy=alert_policy,
+            notifier_entries=self._notifier_entries,
+        )
+        # Set event loop for thread-safe callbacks from sources
+        self._pipeline.set_event_loop(asyncio.get_running_loop())
+        
+        # Create sources and register callback
+        self._sources = self._create_sources(config)
+        for source in self._sources:
+            source.register_callback(self._pipeline.on_new_clip)
+        
+        # Create health server
+        health_cfg = config.health
+        self._health_server = HealthServer(
+            host=health_cfg.host,
+            port=health_cfg.port,
+        )
+        self._health_server.set_components(
+            state_store=self._state_store,
+            storage=self._storage,
+            notifier=self._notifier,
+            sources=self._sources,
+            mqtt_is_critical=health_cfg.mqtt_is_critical,
+        )
+        
+        logger.info("All components created")
+
+    def _create_storage(self, config: Config) -> StorageBackend:
+        """Create storage backend based on config."""
+        return create_storage(config.storage)
+
+    async def _create_state_store(self, config: Config) -> StateStore:
+        """Create state store based on config."""
+        state_cfg = config.state_store
+        dsn = state_cfg.dsn
+        if state_cfg.dsn_env:
+            dsn = resolve_env_var(state_cfg.dsn_env)
+        if not dsn:
+            raise RuntimeError("Postgres DSN is required for state_store backend")
+        store = PostgresStateStore(dsn)
+        await store.initialize()
+        return store
+
+    def _create_event_store(self, state_store: StateStore) -> EventStore:
+        """Create event store based on state store backend."""
+        create_event_store = getattr(state_store, "create_event_store", None)
+        if callable(create_event_store):
+            event_store = cast(Callable[[], EventStore], create_event_store)()
+            if isinstance(event_store, NoopEventStore):
+                logger.warning("Event store unavailable; events will be dropped")
+            return event_store
+        logger.warning("Unsupported state store for events; events will be dropped")
+        return NoopEventStore()
+
+    def _create_notifier(self, config: Config) -> Notifier:
+        """Create notifier(s) based on config."""
+        entries: list[NotifierEntry] = []
+        for index, notifier_cfg in enumerate(config.notifiers):
+            plugin, validated_cfg = self._validate_notifier_config(notifier_cfg)
+            if not notifier_cfg.enabled:
+                continue
+            notifier = plugin.factory(validated_cfg)
+            name = f"{notifier_cfg.backend}[{index}]"
+            entries.append(NotifierEntry(name=name, notifier=notifier))
+
+        self._notifier_entries = entries
+        if not entries:
+            raise RuntimeError("No enabled notifiers configured")
+        if len(entries) == 1:
+            return entries[0].notifier
+        return MultiplexNotifier(entries)
+
+    async def _log_notifier_health(self) -> None:
+        if not self._notifier_entries:
+            return
+
+        tasks = [
+            asyncio.create_task(entry.notifier.ping())
+            for entry in self._notifier_entries
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for entry, result in zip(self._notifier_entries, results, strict=True):
+            match result:
+                case bool() as ok:
+                    if ok:
+                        logger.info("Notifier reachable at startup: %s", entry.name)
+                    else:
+                        logger.error("Notifier unreachable at startup: %s", entry.name)
+                case BaseException() as err:
+                    logger.error(
+                        "Notifier ping failed at startup: %s error=%s",
+                        entry.name,
+                        err,
+                        exc_info=err,
+                    )
+
+    def _validate_notifier_config(
+        self, notifier_cfg: NotifierConfig
+    ) -> tuple[NotifierPlugin, BaseModel]:
+        """Validate notifier config and return the plugin and validated config."""
+        plugin = NOTIFIER_REGISTRY.get(notifier_cfg.backend)
+        if plugin is None:
+            raise RuntimeError(f"Unsupported notifier backend: {notifier_cfg.backend}")
+        validated_cfg = plugin.config_model.model_validate(notifier_cfg.config)
+        return plugin, validated_cfg
+
+    def _create_alert_policy(self, config: Config) -> AlertPolicy:
+        policy_cfg = config.alert_policy
+
+        # Use noop backend when alert policy is disabled
+        backend = "noop" if not policy_cfg.enabled else policy_cfg.backend
+
+        plugin = ALERT_POLICY_REGISTRY.get(backend)
+        if plugin is None:
+            raise RuntimeError(f"Unsupported alert policy backend: {backend}")
+
+        # Always validate to ensure proper BaseModel contract
+        if policy_cfg.enabled:
+            settings = plugin.config_model.model_validate(policy_cfg.config)
+        else:
+            # Noop uses empty BaseModel, validate empty dict to get BaseModel instance
+            settings = plugin.config_model.model_validate({})
+
+        return plugin.factory(settings, config.per_camera_alert, config.vlm.trigger_classes)
+
+    def _create_sources(self, config: Config) -> list[ClipSource]:
+        """Create clip sources based on config."""
+        sources: list[ClipSource] = []
+
+        for camera in config.cameras:
+            source_cfg = camera.source
+            match source_cfg.type:
+                case "local_folder":
+                    local_cfg = source_cfg.config
+                    assert isinstance(local_cfg, LocalFolderSourceConfig)
+                    sources.append(
+                        LocalFolderSource(
+                            local_cfg,
+                            camera_name=camera.name,
+                            state_store=self._state_store,
+                        )
+                    )
+
+                case "rtsp":
+                    rtsp_cfg = source_cfg.config
+                    assert isinstance(rtsp_cfg, RTSPSourceConfig)
+                    sources.append(RTSPSource(rtsp_cfg, camera_name=camera.name))
+
+                case "ftp":
+                    ftp_cfg = source_cfg.config
+                    assert isinstance(ftp_cfg, FtpSourceConfig)
+                    sources.append(FtpSource(ftp_cfg, camera_name=camera.name))
+
+                case _:
+                    raise RuntimeError(f"Unsupported source type: {source_cfg.type}")
+
+        return sources
+
+    def _require_config(self) -> Config:
+        if self._config is None:
+            raise RuntimeError("Config not loaded")
+        return self._config
+
+    def _validate_config(self, config: Config) -> None:
+        validate_camera_references(config)
+        validate_plugin_names(
+            config,
+            valid_filters=sorted(FILTER_REGISTRY.keys()),
+            valid_vlms=sorted(VLM_REGISTRY.keys()),
+            valid_storage=sorted(STORAGE_REGISTRY.keys()),
+            valid_notifiers=sorted(NOTIFIER_REGISTRY.keys()),
+            valid_alert_policies=sorted(ALERT_POLICY_REGISTRY.keys()),
+        )
+
+    def _setup_signal_handlers(self) -> None:
+        """Set up signal handlers for graceful shutdown."""
+        loop = asyncio.get_running_loop()
+        
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, self._handle_signal, sig)
+
+    def _handle_signal(self, sig: signal.Signals) -> None:
+        """Handle shutdown signal."""
+        if self._shutdown_started:
+            logger.warning("Shutdown already in progress, ignoring signal")
+            return
+        
+        logger.info("Received signal %s, initiating shutdown...", sig.name)
+        self._shutdown_started = True
+        self._shutdown_event.set()
+
+    async def shutdown(self) -> None:
+        """Graceful shutdown of all components."""
+        logger.info("Shutting down application...")
+        
+        # Stop sources first
+        if self._sources:
+            await asyncio.gather(
+                *(source.shutdown() for source in self._sources),
+                return_exceptions=True,
+            )
+        
+        # Shutdown pipeline (waits for in-flight clips)
+        if self._pipeline:
+            await self._pipeline.shutdown()
+        
+        # Stop health server
+        if self._health_server:
+            await self._health_server.stop()
+
+        # Close filter and VLM plugins
+        if self._filter:
+            await self._filter.shutdown()
+        if self._vlm:
+            await self._vlm.shutdown()
+
+        # Close state store
+        if self._state_store:
+            await self._state_store.shutdown()
+        
+        # Close storage
+        if self._storage:
+            await self._storage.shutdown()
+        
+        # Close notifier
+        if self._notifier:
+            await self._notifier.shutdown()
+        
+        logger.info("Application shutdown complete")

homesec/cli.py

@@ -0,0 +1,159 @@
+"""CLI entrypoint for HomeSec application."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import fire  # type: ignore[import-untyped]
+
+from homesec.logging_setup import configure_logging
+from homesec.app import Application
+from homesec.config import ConfigError, load_config
+from homesec.config.validation import validate_camera_references, validate_plugin_names
+from homesec.maintenance.cleanup_clips import CleanupOptions, run_cleanup
+from homesec.plugins.analyzers import VLM_REGISTRY
+from homesec.plugins.alert_policies import ALERT_POLICY_REGISTRY
+from homesec.plugins.filters import FILTER_REGISTRY
+from homesec.plugins.notifiers import NOTIFIER_REGISTRY
+from homesec.plugins.storage import STORAGE_REGISTRY
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure logging for CLI."""
+    configure_logging(log_level=level)
+
+
+class HomeSec:
+    """HomeSec CLI - Home Security Camera Pipeline."""
+
+    def run(self, config: str, log_level: str = "INFO") -> None:
+        """Run the HomeSec pipeline.
+        
+        Args:
+            config: Path to YAML config file
+            log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        """
+        setup_logging(log_level)
+        
+        config_path = Path(config)
+        
+        app = Application(config_path)
+        
+        try:
+            asyncio.run(app.run())
+        except ConfigError as e:
+            print(f"✗ Config invalid: {e}", file=sys.stderr)
+            sys.exit(1)
+        except KeyboardInterrupt:
+            pass  # Handled by signal handlers
+
+    def validate(self, config: str) -> None:
+        """Validate config file without running.
+        
+        Args:
+            config: Path to YAML config file
+        """
+        config_path = Path(config)
+        
+        try:
+            cfg = load_config(config_path)
+
+            # Discover all plugins
+            from homesec.plugins import discover_all_plugins
+
+            discover_all_plugins()
+
+            # Additional validation checks
+            validate_camera_references(cfg)
+            validate_plugin_names(
+                cfg,
+                sorted(FILTER_REGISTRY.keys()),
+                sorted(VLM_REGISTRY.keys()),
+                valid_storage=sorted(STORAGE_REGISTRY.keys()),
+                valid_notifiers=sorted(NOTIFIER_REGISTRY.keys()),
+                valid_alert_policies=sorted(ALERT_POLICY_REGISTRY.keys()),
+            )
+            
+            print(f"✓ Config valid: {config_path}")
+            camera_names = [camera.name for camera in cfg.cameras]
+            print(f"  Cameras: {camera_names}")
+            notifier_backends = [
+                f"{notifier.backend} (enabled={notifier.enabled})"
+                for notifier in cfg.notifiers
+            ]
+            print(f"  Storage backend: {cfg.storage.backend}")
+            print(f"  Notifiers: {notifier_backends}")
+            print(f"  Filter plugin: {cfg.filter.plugin}")
+            print(f"  VLM backend: {cfg.vlm.backend}")
+            print(f"  VLM trigger classes: {cfg.vlm.trigger_classes}")
+            print(f"  Alert policy backend: {cfg.alert_policy.backend}")
+            print(f"  Alert policy enabled: {cfg.alert_policy.enabled}")
+        except ConfigError as e:
+            print(f"✗ Config invalid: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    def cleanup(
+        self,
+        config: str,
+        older_than_days: int | None = None,
+        camera_name: str | None = None,
+        batch_size: int = 100,
+        workers: int = 2,
+        dry_run: bool = True,
+        recheck_model_path: str | None = None,
+        recheck_min_confidence: float | None = None,
+        recheck_sample_fps: int | None = None,
+        recheck_min_box_h_ratio: float | None = None,
+        recheck_min_hits: int | None = None,
+        log_level: str = "INFO",
+    ) -> None:
+        """Re-analyze and optionally delete clips that appear empty.
+
+        Args:
+            config: Path to YAML config file
+            older_than_days: Only consider clips older than this many days
+            camera_name: Optional camera name filter
+            batch_size: Postgres paging size
+            workers: Concurrency for re-analysis/deletion
+            dry_run: If True, log actions but do not delete or mutate state
+            recheck_model_path: Override YOLO model path for recheck (default: yolo11x.pt)
+            recheck_min_confidence: Override YOLO confidence for recheck
+            recheck_sample_fps: Override frame sampling step for recheck
+            recheck_min_box_h_ratio: Override minimum box height ratio
+            recheck_min_hits: Override minimum hits setting
+            log_level: Logging level
+        """
+        setup_logging(log_level)
+
+        opts = CleanupOptions(
+            config_path=Path(config),
+            older_than_days=older_than_days,
+            camera_name=camera_name,
+            batch_size=batch_size,
+            workers=workers,
+            dry_run=dry_run,
+            recheck_model_path=recheck_model_path,
+            recheck_min_confidence=recheck_min_confidence,
+            recheck_sample_fps=recheck_sample_fps,
+            recheck_min_box_h_ratio=recheck_min_box_h_ratio,
+            recheck_min_hits=recheck_min_hits,
+        )
+
+        try:
+            asyncio.run(run_cleanup(opts))
+        except ConfigError as e:
+            print(f"✗ Config invalid: {e}", file=sys.stderr)
+            sys.exit(1)
+        except KeyboardInterrupt:
+            pass
+
+
+def main() -> None:
+    """Main CLI entrypoint."""
+    fire.Fire(HomeSec)
+
+
+if __name__ == "__main__":
+    main()

homesec/config/__init__.py

@@ -0,0 +1,18 @@
+"""Configuration loading and validation."""
+
+from homesec.config.loader import (
+    ConfigError,
+    load_config,
+    load_config_from_dict,
+    resolve_env_var,
+)
+from homesec.config.validation import validate_camera_references, validate_plugin_names
+
+__all__ = [
+    "ConfigError",
+    "load_config",
+    "load_config_from_dict",
+    "resolve_env_var",
+    "validate_camera_references",
+    "validate_plugin_names",
+]

homesec/config/loader.py

@@ -0,0 +1,109 @@
+"""Configuration loading and validation."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from homesec.models.config import Config
+
+
+class ConfigError(Exception):
+    """Configuration loading or validation error."""
+
+    def __init__(self, message: str, path: Path | None = None) -> None:
+        super().__init__(message)
+        self.path = path
+
+
+def load_config(path: Path) -> Config:
+    """Load and validate configuration from YAML file.
+    
+    Args:
+        path: Path to YAML config file
+        
+    Returns:
+        Validated Config instance
+        
+    Raises:
+        ConfigError: If file not found, YAML invalid, or validation fails
+    """
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}", path=path)
+
+    try:
+        with path.open() as f:
+            raw = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Invalid YAML in {path}: {e}", path=path) from e
+
+    if raw is None:
+        raise ConfigError(f"Config file is empty: {path}", path=path)
+
+    if not isinstance(raw, dict):
+        raise ConfigError(f"Config must be a YAML mapping, got {type(raw).__name__}", path=path)
+
+    try:
+        return Config.model_validate(raw)
+    except ValidationError as e:
+        raise ConfigError(format_validation_error(e, path), path=path) from e
+
+
+def load_config_from_dict(data: dict[str, Any]) -> Config:
+    """Load and validate configuration from a dict (useful for testing).
+    
+    Args:
+        data: Configuration dictionary
+        
+    Returns:
+        Validated Config instance
+        
+    Raises:
+        ConfigError: If validation fails
+    """
+    try:
+        return Config.model_validate(data)
+    except ValidationError as e:
+        raise ConfigError(format_validation_error(e, path=None)) from e
+
+
+def resolve_env_var(env_var_name: str, required: bool = True) -> str | None:
+    """Resolve environment variable by name.
+    
+    Args:
+        env_var_name: Name of the environment variable
+        required: If True, raise if not found
+        
+    Returns:
+        Environment variable value, or None if not required and not found
+        
+    Raises:
+        ConfigError: If required and not found
+    """
+    value = os.environ.get(env_var_name)
+    if value is None and required:
+        raise ConfigError(f"Required environment variable not set: {env_var_name}")
+    return value
+
+
+def format_validation_error(e: ValidationError, path: Path | None = None) -> str:
+    """Format Pydantic validation error for human readability.
+    
+    Args:
+        e: Pydantic ValidationError
+        path: Optional config file path for context
+        
+    Returns:
+        Human-readable error message
+    """
+    prefix = f"Config validation failed ({path}):" if path else "Config validation failed:"
+    errors = []
+    for err in e.errors():
+        loc = " -> ".join(str(x) for x in err["loc"])
+        msg = err["msg"]
+        errors.append(f"  {loc}: {msg}")
+    return prefix + "\n" + "\n".join(errors)