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

homesec/models/config.py

@@ -2,22 +2,20 @@
 
 from __future__ import annotations
 
-from typing import Literal, TypeVar
+from typing import Any, TypeVar
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
+from homesec.models.enums import RiskLevel, RiskLevelField
 from homesec.models.filter import FilterConfig
 from homesec.models.source import FtpSourceConfig, LocalFolderSourceConfig, RTSPSourceConfig
-from homesec.models.vlm import (
-    RiskLevel,
-    VLMConfig,
-)
+from homesec.models.vlm import VLMConfig
 
 
 class AlertPolicyOverrides(BaseModel):
     """Per-camera alert policy overrides (only non-None fields override base)."""
 
-    min_risk_level: RiskLevel | None = None
+    min_risk_level: RiskLevelField | None = None
     notify_on_activity_types: list[str] | None = None
     notify_on_motion: bool | None = None
 
@@ -25,9 +23,11 @@ class AlertPolicyOverrides(BaseModel):
 class DefaultAlertPolicySettings(BaseModel):
     """Default alert policy settings."""
 
-    min_risk_level: RiskLevel = "medium"
+    min_risk_level: RiskLevelField = RiskLevel.MEDIUM
     notify_on_activity_types: list[str] = Field(default_factory=list)
     notify_on_motion: bool = False
+    overrides: dict[str, AlertPolicyOverrides] = Field(default_factory=dict, exclude=True)
+    trigger_classes: list[str] = Field(default_factory=list, exclude=True)
 
 
 class AlertPolicyConfig(BaseModel):
@@ -35,12 +35,21 @@ class AlertPolicyConfig(BaseModel):
 
     backend: str = "default"
     enabled: bool = True
-    config: dict[str, object] = Field(default_factory=dict)
+    config: dict[str, Any] | BaseModel = Field(default_factory=dict)
+
+    @field_validator("backend", mode="before")
+    @classmethod
+    def _normalize_backend(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value
 
     @model_validator(mode="after")
     def _validate_alert_policy(self) -> AlertPolicyConfig:
-        if self.backend == "default":
-            DefaultAlertPolicySettings.model_validate(self.config)
+        # Validate and reassign config for built-in backends
+        if self.backend == "default" and isinstance(self.config, dict):
+            validated = DefaultAlertPolicySettings.model_validate(self.config)
+            object.__setattr__(self, "config", validated)
         return self
 
 
@@ -83,11 +92,18 @@ class StorageConfig(BaseModel):
     local: LocalStorageConfig | None = None
     paths: StoragePathsConfig = Field(default_factory=StoragePathsConfig)
 
+    @field_validator("backend", mode="before")
+    @classmethod
+    def _normalize_backend(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value
+
     @model_validator(mode="after")
     def _validate_builtin_backends(self) -> StorageConfig:
         """Validate that built-in backends have their required config.
 
-        Third-party backends are validated later in create_storage().
+        Third-party backends are validated later in load_storage_plugin().
         """
         match self.backend:
             case "dropbox":
@@ -103,7 +119,7 @@ class StorageConfig(BaseModel):
                         "Add 'storage.local' section to your config."
                     )
             case _:
-                # Third-party backend - validation happens in create_storage()
+                # Third-party backend - validation happens in load_storage_plugin()
                 pass
         return self
 
@@ -195,7 +211,14 @@ class NotifierConfig(BaseModel):
 
     backend: str
     enabled: bool = True
-    config: dict[str, object] = Field(default_factory=dict)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("backend", mode="before")
+    @classmethod
+    def _normalize_backend(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value
 
 
 class RetentionConfig(BaseModel):
@@ -229,12 +252,17 @@ class HealthConfig(BaseModel):
 
 
 class CameraSourceConfig(BaseModel):
-    """Camera source configuration wrapper."""
+    """Camera source configuration wrapper.
+
+    The `type` field is a string to allow external plugins to register new source types.
+    Built-in types ("rtsp", "local_folder", "ftp") have their configs validated here.
+    External plugin configs are validated by the plugin at load time.
+    """
 
     model_config = {"extra": "forbid"}
 
-    type: Literal["rtsp", "local_folder", "ftp"]
-    config: RTSPSourceConfig | LocalFolderSourceConfig | FtpSourceConfig
+    type: str
+    config: RTSPSourceConfig | LocalFolderSourceConfig | FtpSourceConfig | dict[str, Any]
 
     @model_validator(mode="before")
     @classmethod
@@ -248,6 +276,9 @@ class CameraSourceConfig(BaseModel):
 
         config_data = raw_config or {}
         updated = dict(data)
+        if isinstance(source_type, str):
+            source_type = source_type.lower()
+            updated["type"] = source_type
         match source_type:
             case "rtsp":
                 updated["config"] = RTSPSourceConfig.model_validate(config_data)
@@ -255,8 +286,19 @@ class CameraSourceConfig(BaseModel):
                 updated["config"] = LocalFolderSourceConfig.model_validate(config_data)
             case "ftp":
                 updated["config"] = FtpSourceConfig.model_validate(config_data)
+            case _:
+                # External plugin source type - keep config as dict
+                # Plugin will validate at load time
+                updated["config"] = config_data if isinstance(config_data, dict) else {}
         return updated
 
+    @field_validator("type", mode="before")
+    @classmethod
+    def _normalize_type(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value
+
     @model_validator(mode="after")
     def _validate_source_config(self) -> CameraSourceConfig:
         match self.type:
@@ -271,6 +313,9 @@ class CameraSourceConfig(BaseModel):
             case "ftp":
                 if not isinstance(self.config, FtpSourceConfig):
                     raise ValueError("camera.source.config must be FtpSourceConfig for type=ftp")
+            case _:
+                # External plugin source type - validation happens at plugin load time
+                pass
         return self
 
 

homesec/models/enums.py

@@ -0,0 +1,114 @@
+"""Centralized enums for type safety and IDE support."""
+
+from enum import IntEnum, StrEnum
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator, PlainSerializer
+
+
+def _validate_risk_level(value: Any) -> "RiskLevel":
+    """Validate and convert input to RiskLevel.
+
+    Accepts:
+        - RiskLevel enum member
+        - Integer (0-3)
+        - String ("low", "medium", "high", "critical", case-insensitive)
+    """
+    if isinstance(value, RiskLevel):
+        return value
+    if isinstance(value, int):
+        return RiskLevel(value)
+    if isinstance(value, str):
+        return RiskLevel.from_string(value)
+    raise ValueError(f"Cannot convert {type(value).__name__} to RiskLevel")
+
+
+def _serialize_risk_level(value: "RiskLevel") -> str:
+    """Serialize RiskLevel to lowercase string for config compatibility."""
+    return str(value)
+
+
+class EventType(StrEnum):
+    """All clip lifecycle event types.
+
+    Used in event models and the event store for type-safe event handling.
+    """
+
+    CLIP_RECORDED = "clip_recorded"
+    CLIP_DELETED = "clip_deleted"
+    CLIP_RECHECKED = "clip_rechecked"
+    UPLOAD_STARTED = "upload_started"
+    UPLOAD_COMPLETED = "upload_completed"
+    UPLOAD_FAILED = "upload_failed"
+    FILTER_STARTED = "filter_started"
+    FILTER_COMPLETED = "filter_completed"
+    FILTER_FAILED = "filter_failed"
+    VLM_STARTED = "vlm_started"
+    VLM_COMPLETED = "vlm_completed"
+    VLM_FAILED = "vlm_failed"
+    VLM_SKIPPED = "vlm_skipped"
+    ALERT_DECISION_MADE = "alert_decision_made"
+    NOTIFICATION_SENT = "notification_sent"
+    NOTIFICATION_FAILED = "notification_failed"
+
+
+class ClipStatus(StrEnum):
+    """Clip processing status values.
+
+    Represents the high-level status of a clip in the processing pipeline.
+    """
+
+    QUEUED_LOCAL = "queued_local"
+    UPLOADED = "uploaded"
+    ANALYZED = "analyzed"
+    DONE = "done"
+    ERROR = "error"
+    DELETED = "deleted"
+
+
+class RiskLevel(IntEnum):
+    """VLM risk assessment levels.
+
+    Uses IntEnum for natural ordering and comparison:
+        RiskLevel.HIGH > RiskLevel.LOW  # True
+        RiskLevel.MEDIUM >= RiskLevel.MEDIUM  # True
+
+    String serialization is handled by Pydantic for config compatibility.
+    """
+
+    LOW = 0
+    MEDIUM = 1
+    HIGH = 2
+    CRITICAL = 3
+
+    def __str__(self) -> str:
+        """Return lowercase name for human-readable output."""
+        return self.name.lower()
+
+    @classmethod
+    def from_string(cls, value: str) -> "RiskLevel":
+        """Parse risk level from string (case-insensitive).
+
+        Args:
+            value: Risk level string (e.g., "low", "MEDIUM", "High")
+
+        Returns:
+            Corresponding RiskLevel enum member
+
+        Raises:
+            ValueError: If value is not a valid risk level
+        """
+        try:
+            return cls[value.upper()]
+        except KeyError:
+            valid = ", ".join(member.name.lower() for member in cls)
+            raise ValueError(f"Invalid risk level '{value}'. Valid values: {valid}") from None
+
+
+# Pydantic-compatible type that accepts strings, ints, and RiskLevel
+# Use this in Pydantic models instead of raw RiskLevel
+RiskLevelField = Annotated[
+    RiskLevel,
+    BeforeValidator(_validate_risk_level),
+    PlainSerializer(_serialize_risk_level, return_type=str),
+]

homesec/models/events.py

@@ -7,6 +7,7 @@ from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, Field
 
+from homesec.models.enums import EventType, RiskLevelField
 from homesec.models.filter import FilterResult
 
 
@@ -22,7 +23,7 @@ class ClipEvent(BaseModel):
 class ClipRecordedEvent(ClipEvent):
     """Clip was recorded and queued for processing."""
 
-    event_type: Literal["clip_recorded"] = "clip_recorded"
+    event_type: Literal[EventType.CLIP_RECORDED] = EventType.CLIP_RECORDED
     camera_name: str
     duration_s: float
     source_type: str
@@ -31,7 +32,7 @@ class ClipRecordedEvent(ClipEvent):
 class ClipDeletedEvent(ClipEvent):
     """Clip was deleted by a maintenance workflow (e.g., cleanup CLI)."""
 
-    event_type: Literal["clip_deleted"] = "clip_deleted"
+    event_type: Literal[EventType.CLIP_DELETED] = EventType.CLIP_DELETED
     camera_name: str
     reason: str
     run_id: str
@@ -44,7 +45,7 @@ class ClipDeletedEvent(ClipEvent):
 class ClipRecheckedEvent(ClipEvent):
     """Clip was re-analyzed by a maintenance workflow."""
 
-    event_type: Literal["clip_rechecked"] = "clip_rechecked"
+    event_type: Literal[EventType.CLIP_RECHECKED] = EventType.CLIP_RECHECKED
     camera_name: str
     reason: str
     run_id: str
@@ -55,7 +56,7 @@ class ClipRecheckedEvent(ClipEvent):
 class UploadStartedEvent(ClipEvent):
     """Upload to storage backend started."""
 
-    event_type: Literal["upload_started"] = "upload_started"
+    event_type: Literal[EventType.UPLOAD_STARTED] = EventType.UPLOAD_STARTED
     dest_key: str
     attempt: int
 
@@ -63,7 +64,7 @@ class UploadStartedEvent(ClipEvent):
 class UploadCompletedEvent(ClipEvent):
     """Upload to storage backend completed successfully."""
 
-    event_type: Literal["upload_completed"] = "upload_completed"
+    event_type: Literal[EventType.UPLOAD_COMPLETED] = EventType.UPLOAD_COMPLETED
     storage_uri: str
     view_url: str | None
     attempt: int
@@ -73,7 +74,7 @@ class UploadCompletedEvent(ClipEvent):
 class UploadFailedEvent(ClipEvent):
     """Upload to storage backend failed."""
 
-    event_type: Literal["upload_failed"] = "upload_failed"
+    event_type: Literal[EventType.UPLOAD_FAILED] = EventType.UPLOAD_FAILED
     attempt: int
     error_message: str
     error_type: str
@@ -83,14 +84,14 @@ class UploadFailedEvent(ClipEvent):
 class FilterStartedEvent(ClipEvent):
     """Object detection filter started."""
 
-    event_type: Literal["filter_started"] = "filter_started"
+    event_type: Literal[EventType.FILTER_STARTED] = EventType.FILTER_STARTED
     attempt: int
 
 
 class FilterCompletedEvent(ClipEvent):
     """Object detection filter completed."""
 
-    event_type: Literal["filter_completed"] = "filter_completed"
+    event_type: Literal[EventType.FILTER_COMPLETED] = EventType.FILTER_COMPLETED
     detected_classes: list[str]
     confidence: float
     model: str
@@ -102,7 +103,7 @@ class FilterCompletedEvent(ClipEvent):
 class FilterFailedEvent(ClipEvent):
     """Object detection filter failed."""
 
-    event_type: Literal["filter_failed"] = "filter_failed"
+    event_type: Literal[EventType.FILTER_FAILED] = EventType.FILTER_FAILED
     attempt: int
     error_message: str
     error_type: str
@@ -112,15 +113,15 @@ class FilterFailedEvent(ClipEvent):
 class VLMStartedEvent(ClipEvent):
     """VLM analysis started."""
 
-    event_type: Literal["vlm_started"] = "vlm_started"
+    event_type: Literal[EventType.VLM_STARTED] = EventType.VLM_STARTED
     attempt: int
 
 
 class VLMCompletedEvent(ClipEvent):
     """VLM analysis completed."""
 
-    event_type: Literal["vlm_completed"] = "vlm_completed"
-    risk_level: str
+    event_type: Literal[EventType.VLM_COMPLETED] = EventType.VLM_COMPLETED
+    risk_level: RiskLevelField
     activity_type: str
     summary: str
     analysis: dict[str, Any]
@@ -133,7 +134,7 @@ class VLMCompletedEvent(ClipEvent):
 class VLMFailedEvent(ClipEvent):
     """VLM analysis failed."""
 
-    event_type: Literal["vlm_failed"] = "vlm_failed"
+    event_type: Literal[EventType.VLM_FAILED] = EventType.VLM_FAILED
     attempt: int
     error_message: str
     error_type: str
@@ -143,24 +144,24 @@ class VLMFailedEvent(ClipEvent):
 class VLMSkippedEvent(ClipEvent):
     """VLM analysis skipped (no trigger classes detected)."""
 
-    event_type: Literal["vlm_skipped"] = "vlm_skipped"
+    event_type: Literal[EventType.VLM_SKIPPED] = EventType.VLM_SKIPPED
     reason: str
 
 
 class AlertDecisionMadeEvent(ClipEvent):
     """Alert policy decision made."""
 
-    event_type: Literal["alert_decision_made"] = "alert_decision_made"
+    event_type: Literal[EventType.ALERT_DECISION_MADE] = EventType.ALERT_DECISION_MADE
     should_notify: bool
     reason: str
     detected_classes: list[str] | None
-    vlm_risk: str | None
+    vlm_risk: RiskLevelField | None
 
 
 class NotificationSentEvent(ClipEvent):
     """Notification sent successfully."""
 
-    event_type: Literal["notification_sent"] = "notification_sent"
+    event_type: Literal[EventType.NOTIFICATION_SENT] = EventType.NOTIFICATION_SENT
     notifier_name: str
     dedupe_key: str
     attempt: int = 1
@@ -169,7 +170,7 @@ class NotificationSentEvent(ClipEvent):
 class NotificationFailedEvent(ClipEvent):
     """Notification send failed."""
 
-    event_type: Literal["notification_failed"] = "notification_failed"
+    event_type: Literal[EventType.NOTIFICATION_FAILED] = EventType.NOTIFICATION_FAILED
     notifier_name: str
     error_message: str
     error_type: str

homesec/models/filter.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, Field
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
 
 
 class FilterResult(BaseModel):
@@ -28,6 +30,7 @@ class YoloFilterSettings(BaseModel):
     sample_fps: int = Field(default=2, ge=1)
     min_box_h_ratio: float = Field(default=0.1, ge=0.0, le=1.0)
     min_hits: int = Field(default=1, ge=1)
+    max_workers: int = Field(default=4, ge=1)
 
 
 class FilterOverrides(BaseModel):
@@ -46,7 +49,7 @@ class FilterConfig(BaseModel):
     """Base filter configuration (plugin-agnostic).
 
     Plugin-specific config is stored in the 'config' field.
-    - During YAML parsing: dict[str, object] (preserves all third-party fields)
+    - During YAML parsing: dict[str, Any] (preserves all third-party fields)
     - After plugin discovery: BaseModel subclass (validated against plugin.config_model)
 
     Note: Plugin names are validated against the registry at runtime via
@@ -57,4 +60,11 @@ class FilterConfig(BaseModel):
 
     plugin: str
     max_workers: int = Field(default=4, ge=1)
-    config: dict[str, object] | BaseModel  # Dict before validation, BaseModel after
+    config: dict[str, Any] | BaseModel  # Dict before validation, BaseModel after
+
+    @field_validator("plugin", mode="before")
+    @classmethod
+    def _normalize_plugin(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value

homesec/models/source.py

@@ -10,6 +10,7 @@ class RTSPSourceConfig(BaseModel):
 
     model_config = {"extra": "forbid"}
 
+    camera_name: str | None = None
     rtsp_url_env: str | None = None
     rtsp_url: str | None = None
     detect_rtsp_url_env: str | None = None
@@ -29,6 +30,7 @@ class RTSPSourceConfig(BaseModel):
     heartbeat_s: float = 30.0
     rtsp_connect_timeout_s: float = 2.0
     rtsp_io_timeout_s: float = 2.0
+    ffmpeg_flags: list[str] = Field(default_factory=list)
 
 
 class LocalFolderSourceConfig(BaseModel):
@@ -36,6 +38,7 @@ class LocalFolderSourceConfig(BaseModel):
 
     model_config = {"extra": "forbid"}
 
+    camera_name: str | None = None
     watch_dir: str = "recordings"
     poll_interval: float = 1.0
     stability_threshold_s: float = 3.0
@@ -46,6 +49,7 @@ class FtpSourceConfig(BaseModel):
 
     model_config = {"extra": "forbid"}
 
+    camera_name: str | None = None
     host: str = "0.0.0.0"
     port: int = 2121
     root_dir: str = "./ftp_incoming"

homesec/models/vlm.py

@@ -2,17 +2,19 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import Any, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
-RiskLevel = Literal["low", "medium", "high", "critical"]
+from homesec.models.enums import RiskLevelField
+
+__all__ = ["AnalysisResult", "VLMConfig", "VLMPreprocessConfig"]
 
 
 class AnalysisResult(BaseModel):
     """Structured result from VLM analysis of a video clip."""
 
-    risk_level: RiskLevel
+    risk_level: RiskLevelField
     activity_type: str
     summary: str
     analysis: SequenceAnalysis | None = None
@@ -38,7 +40,7 @@ class SequenceAnalysis(BaseModel):
 
     model_config = {"extra": "forbid"}
     sequence_description: str
-    max_risk_level: RiskLevel
+    max_risk_level: RiskLevelField
     primary_activity: Literal[
         "normal_delivery",
         "normal_visitor",
@@ -77,13 +79,15 @@ class OpenAILLMConfig(BaseModel):
     max_tokens: int | None = None
     temperature: float | None = 0.0
     request_timeout: float = 60.0
+    trigger_classes: list[str] = Field(default_factory=lambda: ["person"])
+    max_workers: int = Field(default=2, ge=1)
 
 
 class VLMConfig(BaseModel):
     """Base VLM configuration.
 
     LLM-specific config is stored in the 'llm' field.
-    - During YAML parsing: dict[str, object] (preserves all third-party fields)
+    - During YAML parsing: dict[str, Any] (preserves all third-party fields)
     - After plugin discovery: BaseModel subclass (validated against plugin.config_model)
 
     Note: Backend names are validated against the registry at runtime via
@@ -94,5 +98,12 @@ class VLMConfig(BaseModel):
     backend: str
     trigger_classes: list[str] = Field(default_factory=lambda: ["person"])
     max_workers: int = Field(default=2, ge=1)
-    llm: dict[str, object] | BaseModel  # Dict before validation, BaseModel after
+    llm: dict[str, Any] | BaseModel  # Dict before validation, BaseModel after
     preprocessing: VLMPreprocessConfig = Field(default_factory=VLMPreprocessConfig)
+
+    @field_validator("backend", mode="before")
+    @classmethod
+    def _normalize_backend(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower()
+        return value

homesec/plugins/__init__.py

@@ -19,44 +19,18 @@ def discover_all_plugins() -> None:
     triggers registration automatically.
     """
     # 1. Discover built-in plugins by importing all modules
-    plugin_types = ["filters", "analyzers", "storage", "notifiers", "alert_policies"]
+    plugin_types = ["filters", "analyzers", "storage", "notifiers", "alert_policies", "sources"]
 
     for plugin_type in plugin_types:
-        try:
-            package = importlib.import_module(f"homesec.plugins.{plugin_type}")
-            for _, module_name, _ in pkgutil.iter_modules(package.__path__):
-                if module_name.startswith("_"):
-                    continue  # Skip private modules
-                try:
-                    importlib.import_module(f"homesec.plugins.{plugin_type}.{module_name}")
-                except Exception as exc:
-                    logger.error(
-                        "Failed to import built-in plugin module %s.%s: %s",
-                        plugin_type,
-                        module_name,
-                        exc,
-                        exc_info=True,
-                    )
-        except Exception as exc:
-            logger.error(
-                "Failed to discover built-in plugins for %s: %s",
-                plugin_type,
-                exc,
-                exc_info=True,
-            )
+        package = importlib.import_module(f"homesec.plugins.{plugin_type}")
+        for _, module_name, _ in pkgutil.iter_modules(package.__path__):
+            if module_name.startswith("_"):
+                continue  # Skip private modules
+            importlib.import_module(f"homesec.plugins.{plugin_type}.{module_name}")
 
     # 2. Discover external plugins via entry points
     for point in iter_entry_points("homesec.plugins"):
-        try:
-            importlib.import_module(point.module)
-        except Exception as exc:
-            logger.error(
-                "Failed to load external plugin %s from %s: %s",
-                point.name,
-                point.module,
-                exc,
-                exc_info=True,
-            )
+        importlib.import_module(point.module)
 
 
 __all__ = ["discover_all_plugins"]