homesec 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

homesec/__init__.py

@@ -10,11 +10,11 @@ from homesec.models.filter import FilterResult
 from homesec.models.vlm import AnalysisResult
 
 __all__ = [
-    "__version__",
     "Alert",
     "AnalysisResult",
     "Clip",
     "ClipStateData",
     "FilterResult",
     "PipelineError",
+    "__version__",
 ]

homesec/app.py

@@ -5,11 +5,8 @@ from __future__ import annotations
 import asyncio
 import logging
 import signal
-from collections.abc import Callable
 from pathlib import Path
-from typing import TYPE_CHECKING, cast
-
-from pydantic import BaseModel
+from typing import TYPE_CHECKING
 
 from homesec.config import (
     load_config,
@@ -19,21 +16,19 @@ from homesec.config import (
 )
 from homesec.health import HealthServer
 from homesec.interfaces import EventStore
-from homesec.models.config import NotifierConfig
-from homesec.models.source import FtpSourceConfig, LocalFolderSourceConfig, RTSPSourceConfig
 from homesec.pipeline import ClipPipeline
-from homesec.plugins.alert_policies import ALERT_POLICY_REGISTRY
-from homesec.plugins.analyzers import VLM_REGISTRY, load_vlm_plugin
-from homesec.plugins.filters import FILTER_REGISTRY, load_filter_plugin
+from homesec.plugins.alert_policies import load_alert_policy
+from homesec.plugins.analyzers import load_analyzer
+from homesec.plugins.filters import load_filter
 from homesec.plugins.notifiers import (
-    NOTIFIER_REGISTRY,
     MultiplexNotifier,
     NotifierEntry,
-    NotifierPlugin,
+    load_notifier_plugin,
 )
-from homesec.plugins.storage import STORAGE_REGISTRY, create_storage
+from homesec.plugins.registry import PluginType, get_plugin_names
+from homesec.plugins.sources import load_source_plugin
+from homesec.plugins.storage import load_storage_plugin
 from homesec.repository import ClipRepository
-from homesec.sources import FtpSource, LocalFolderSource, RTSPSource
 from homesec.state import NoopEventStore, NoopStateStore, PostgresStateStore
 
 if TYPE_CHECKING:
@@ -148,8 +143,8 @@ class Application:
         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)
+        filter_plugin = load_filter(config.filter)
+        vlm_plugin = load_analyzer(config.vlm)
         self._filter = filter_plugin
         self._vlm = vlm_plugin
         alert_policy = self._create_alert_policy(config)
@@ -191,7 +186,7 @@ class Application:
 
     def _create_storage(self, config: Config) -> StorageBackend:
         """Create storage backend based on config."""
-        return create_storage(config.storage)
+        return load_storage_plugin(config.storage)
 
     async def _create_state_store(self, config: Config) -> StateStore:
         """Create state store based on config."""
@@ -207,23 +202,20 @@ class Application:
 
     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()
+        event_store = state_store.create_event_store()
+        if isinstance(event_store, NoopEventStore):
+            logger.warning(
+                "Event store unavailable (NoopEventStore returned); events will be dropped"
+            )
+        return event_store
 
     def _create_notifier(self, config: Config) -> Notifier:
-        """Create notifier(s) based on config."""
+        """Create notifier(s) based on config using plugin registry."""
         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)
+            notifier = load_notifier_plugin(notifier_cfg.backend, notifier_cfg.config)
             name = f"{notifier_cfg.backend}[{index}]"
             entries.append(NotifierEntry(name=name, notifier=notifier))
 
@@ -256,65 +248,26 @@ class Application:
                         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)
+        """Create alert policy using the plugin registry."""
+        return load_alert_policy(
+            config.alert_policy,
+            per_camera_overrides=config.per_camera_alert,
+            trigger_classes=config.vlm.trigger_classes,
+        )
 
     def _create_sources(self, config: Config) -> list[ClipSource]:
-        """Create clip sources based on config."""
+        """Create clip sources based on config using plugin registry."""
         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}")
+            source = load_source_plugin(
+                source_type=source_cfg.type,
+                config=source_cfg.config,
+                camera_name=camera.name,
+            )
+            sources.append(source)
 
         return sources
 
@@ -327,11 +280,12 @@ class Application:
         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()),
+            valid_filters=get_plugin_names(PluginType.FILTER),
+            valid_vlms=get_plugin_names(PluginType.ANALYZER),
+            valid_storage=get_plugin_names(PluginType.STORAGE),
+            valid_notifiers=get_plugin_names(PluginType.NOTIFIER),
+            valid_alert_policies=get_plugin_names(PluginType.ALERT_POLICY),
+            valid_sources=get_plugin_names(PluginType.SOURCE),
         )
 
     def _setup_signal_handlers(self) -> None:

homesec/cli.py

@@ -17,11 +17,7 @@ from homesec.config import ConfigError, load_config
 from homesec.config.validation import validate_camera_references, validate_plugin_names
 from homesec.logging_setup import configure_logging
 from homesec.maintenance.cleanup_clips import CleanupOptions, run_cleanup
-from homesec.plugins.alert_policies import ALERT_POLICY_REGISTRY
-from homesec.plugins.analyzers import VLM_REGISTRY
-from homesec.plugins.filters import FILTER_REGISTRY
-from homesec.plugins.notifiers import NOTIFIER_REGISTRY
-from homesec.plugins.storage import STORAGE_REGISTRY
+from homesec.plugins.registry import PluginType, get_plugin_names
 
 
 def setup_logging(level: str = "INFO") -> None:
@@ -73,11 +69,11 @@ class HomeSec:
             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()),
+                sorted(get_plugin_names(PluginType.FILTER)),
+                sorted(get_plugin_names(PluginType.ANALYZER)),
+                valid_storage=sorted(get_plugin_names(PluginType.STORAGE)),
+                valid_notifiers=sorted(get_plugin_names(PluginType.NOTIFIER)),
+                valid_alert_policies=sorted(get_plugin_names(PluginType.ALERT_POLICY)),
             )
 
             print(f"✓ Config valid: {config_path}")
@@ -155,6 +151,9 @@ class HomeSec:
 
 def main() -> None:
     """Main CLI entrypoint."""
+    # Strip --help/-h when it's the only arg so Fire shows its commands list
+    if len(sys.argv) == 2 and sys.argv[1] in ("--help", "-h"):
+        sys.argv.pop()
     fire.Fire(HomeSec)
 
 

homesec/config/validation.py

@@ -37,6 +37,7 @@ def validate_plugin_names(
     valid_storage: list[str] | None = None,
     valid_notifiers: list[str] | None = None,
     valid_alert_policies: list[str] | None = None,
+    valid_sources: list[str] | None = None,
 ) -> None:
     """Validate that plugin names are recognized.
 
@@ -46,34 +47,59 @@ def validate_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
+        valid_alert_policies: Optional list of valid alert policy backends
+        valid_sources: Optional list of valid source types
 
     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})")
+    valid_filters_lower = {name.lower() for name in valid_filters}
+    if config.filter.plugin.lower() not in valid_filters_lower:
+        errors.append(
+            f"Unknown filter plugin: {config.filter.plugin} (valid: {sorted(valid_filters_lower)})"
+        )
+
+    valid_vlms_lower = {name.lower() for name in valid_vlms}
+    if config.vlm.backend.lower() not in valid_vlms_lower:
+        errors.append(
+            f"Unknown VLM plugin: {config.vlm.backend} (valid: {sorted(valid_vlms_lower)})"
+        )
+
+    if valid_storage is not None:
+        valid_storage_lower = {name.lower() for name in valid_storage}
+        if config.storage.backend.lower() not in valid_storage_lower:
+            errors.append(
+                f"Unknown storage backend: {config.storage.backend} "
+                f"(valid: {sorted(valid_storage_lower)})"
+            )
 
     if valid_notifiers is not None:
+        valid_notifiers_lower = {name.lower() for name in valid_notifiers}
         for notifier in config.notifiers:
-            if notifier.backend not in valid_notifiers:
+            if notifier.backend.lower() not in valid_notifiers_lower:
                 errors.append(
-                    f"Unknown notifier backend: {notifier.backend} (valid: {valid_notifiers})"
+                    f"Unknown notifier backend: {notifier.backend} "
+                    f"(valid: {sorted(valid_notifiers_lower)})"
                 )
 
     if valid_alert_policies is not None:
-        if config.alert_policy.backend not in valid_alert_policies:
+        valid_alert_policies_lower = {name.lower() for name in valid_alert_policies}
+        if config.alert_policy.backend.lower() not in valid_alert_policies_lower:
             errors.append(
                 "Unknown alert policy backend: "
-                f"{config.alert_policy.backend} (valid: {valid_alert_policies})"
+                f"{config.alert_policy.backend} (valid: {sorted(valid_alert_policies_lower)})"
             )
 
+    if valid_sources is not None:
+        valid_sources_lower = {name.lower() for name in valid_sources}
+        for camera in config.cameras:
+            if camera.source.type.lower() not in valid_sources_lower:
+                errors.append(
+                    f"Unknown source type for camera '{camera.name}': "
+                    f"{camera.source.type} (valid: {sorted(valid_sources_lower)})"
+                )
+
     if errors:
         raise ConfigError("Invalid plugin configuration:\n  " + "\n  ".join(errors))

homesec/interfaces.py

@@ -69,6 +69,19 @@ class ClipSource(Shutdownable, ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check for the clip source.
+
+        Returns True if the source is operational:
+        - Connection/watcher is alive
+        - Can receive new clips
+
+        This is similar to is_healthy() but async and follows the standard
+        ping() pattern used by other interfaces.
+        """
+        raise NotImplementedError
+
 
 class StorageBackend(Shutdownable, ABC):
     """Stores raw clips and derived artifacts."""
@@ -137,8 +150,18 @@ class StateStore(Shutdownable, ABC):
         """Health check. Returns True if database is reachable."""
         raise NotImplementedError
 
+    @abstractmethod
+    def create_event_store(self) -> EventStore:
+        """Create an event store associated with this state store.
+
+        Returns NoopEventStore if not supported.
+        """
+        from homesec.state import NoopEventStore
+
+        return NoopEventStore()
 
-class EventStore(ABC):
+
+class EventStore(Shutdownable, ABC):
     """Manages clip lifecycle events in Postgres."""
 
     @abstractmethod
@@ -162,6 +185,11 @@ class EventStore(ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check. Returns True if event store is reachable."""
+        raise NotImplementedError
+
 
 class Notifier(Shutdownable, ABC):
     """Sends notifications (e.g., MQTT, email, SMS)."""
@@ -229,6 +257,17 @@ class ObjectFilter(Shutdownable, ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check for the filter.
+
+        Returns True if the filter is operational:
+        - Model is loaded
+        - Executor pool is alive (if applicable)
+        - Ready to process detection requests
+        """
+        raise NotImplementedError
+
 
 class VLMAnalyzer(Shutdownable, ABC):
     """Plugin interface for VLM-based clip analysis."""
@@ -251,4 +290,13 @@ class VLMAnalyzer(Shutdownable, ABC):
         """
         raise NotImplementedError
 
-    # shutdown() defined in Shutdownable
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Health check for the analyzer.
+
+        Returns True if the analyzer is operational:
+        - API endpoint reachable (for API-based analyzers)
+        - Model loaded (for local analyzers)
+        - HTTP session alive
+        """
+        raise NotImplementedError

homesec/maintenance/cleanup_clips.py

@@ -21,8 +21,8 @@ from homesec.interfaces import ObjectFilter, StorageBackend
 from homesec.models.clip import ClipStateData
 from homesec.models.filter import FilterConfig, YoloFilterSettings
 from homesec.plugins import discover_all_plugins
-from homesec.plugins.filters import load_filter_plugin
-from homesec.plugins.storage import create_storage
+from homesec.plugins.filters import load_filter
+from homesec.plugins.storage import load_storage_plugin
 from homesec.repository.clip_repository import ClipRepository
 from homesec.state.postgres import PostgresStateStore
 
@@ -168,7 +168,7 @@ async def run_cleanup(opts: CleanupOptions) -> None:
     if not dsn:
         raise RuntimeError("Postgres DSN is required for cleanup")
 
-    storage = create_storage(cfg.storage)
+    storage = load_storage_plugin(cfg.storage)
     state_store = PostgresStateStore(dsn)
     ok = await state_store.initialize()
     if not ok:
@@ -178,7 +178,7 @@ async def run_cleanup(opts: CleanupOptions) -> None:
     repo = ClipRepository(state_store, event_store, retry=cfg.retry)
 
     recheck_cfg = _build_recheck_filter_config(cfg.filter, opts)
-    filter_plugin = load_filter_plugin(recheck_cfg)
+    filter_plugin = load_filter(recheck_cfg)
 
     sem = asyncio.Semaphore(int(opts.workers))
 

homesec/models/__init__.py

@@ -23,13 +23,13 @@ from homesec.models.config import (
     StorageConfig,
     StoragePathsConfig,
 )
+from homesec.models.enums import RiskLevel, RiskLevelField
 from homesec.models.filter import FilterConfig, FilterOverrides, FilterResult, YoloFilterSettings
 from homesec.models.source import FtpSourceConfig, LocalFolderSourceConfig, RTSPSourceConfig
 from homesec.models.vlm import (
     AnalysisResult,
     EntityTimeline,
     OpenAILLMConfig,
-    RiskLevel,
     SequenceAnalysis,
     VLMConfig,
     VLMPreprocessConfig,
@@ -43,7 +43,6 @@ __all__ = [
     "AlertDecision",
     "AlertPolicyConfig",
     "AlertPolicyOverrides",
-    "DefaultAlertPolicySettings",
     "AnalysisResult",
     "CameraConfig",
     "CameraSourceConfig",
@@ -51,24 +50,26 @@ __all__ = [
     "ClipStateData",
     "ConcurrencyConfig",
     "Config",
+    "DefaultAlertPolicySettings",
     "DropboxStorageConfig",
     "EntityTimeline",
     "FilterConfig",
     "FilterOverrides",
-    "FtpSourceConfig",
     "FilterResult",
+    "FtpSourceConfig",
     "HealthConfig",
-    "LocalStorageConfig",
     "LocalFolderSourceConfig",
+    "LocalStorageConfig",
     "MQTTAuthConfig",
     "MQTTConfig",
     "NotifierConfig",
     "OpenAILLMConfig",
     "RTSPSourceConfig",
-    "SendGridEmailConfig",
     "RetentionConfig",
     "RetryConfig",
     "RiskLevel",
+    "RiskLevelField",
+    "SendGridEmailConfig",
     "SequenceAnalysis",
     "StateStoreConfig",
     "StorageConfig",

homesec/models/alert.py

@@ -6,7 +6,8 @@ from datetime import datetime
 
 from pydantic import BaseModel
 
-from homesec.models.vlm import RiskLevel, SequenceAnalysis
+from homesec.models.enums import RiskLevelField
+from homesec.models.vlm import SequenceAnalysis
 
 
 class AlertDecision(BaseModel):
@@ -23,7 +24,7 @@ class Alert(BaseModel):
     camera_name: str
     storage_uri: str | None
     view_url: str | None
-    risk_level: RiskLevel | None  # None if VLM skipped
+    risk_level: RiskLevelField | None  # None if VLM skipped
     activity_type: str | None
     notify_reason: str
     summary: str | None

homesec/models/clip.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel
 
+from homesec.models.enums import ClipStatus
+
 if TYPE_CHECKING:
     from homesec.models.alert import AlertDecision
     from homesec.models.filter import FilterResult
@@ -33,7 +35,7 @@ class ClipStateData(BaseModel):
     camera_name: str
 
     # High-level status for queries
-    status: Literal["queued_local", "uploaded", "analyzed", "done", "error", "deleted"]
+    status: ClipStatus
 
     # Pointers
     local_path: str