homesec 0.1.0__py3-none-any.whl

homesec/models/events.py

@@ -0,0 +1,184 @@
+"""Event models for clip lifecycle tracking."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from homesec.models.filter import FilterResult
+
+
+class ClipEvent(BaseModel):
+    """Base class for all clip lifecycle events."""
+    id: int | None = None
+    clip_id: str
+    timestamp: datetime
+    event_type: str
+
+
+class ClipRecordedEvent(ClipEvent):
+    """Clip was recorded and queued for processing."""
+
+    event_type: Literal["clip_recorded"] = "clip_recorded"
+    camera_name: str
+    duration_s: float
+    source_type: str
+
+
+class ClipDeletedEvent(ClipEvent):
+    """Clip was deleted by a maintenance workflow (e.g., cleanup CLI)."""
+
+    event_type: Literal["clip_deleted"] = "clip_deleted"
+    camera_name: str
+    reason: str
+    run_id: str
+    local_path: str
+    storage_uri: str | None
+    deleted_local: bool
+    deleted_storage: bool
+
+
+class ClipRecheckedEvent(ClipEvent):
+    """Clip was re-analyzed by a maintenance workflow."""
+
+    event_type: Literal["clip_rechecked"] = "clip_rechecked"
+    camera_name: str
+    reason: str
+    run_id: str
+    prior_filter: FilterResult | None
+    recheck_filter: FilterResult
+
+
+class UploadStartedEvent(ClipEvent):
+    """Upload to storage backend started."""
+    event_type: Literal["upload_started"] = "upload_started"
+    dest_key: str
+    attempt: int
+
+
+class UploadCompletedEvent(ClipEvent):
+    """Upload to storage backend completed successfully."""
+    event_type: Literal["upload_completed"] = "upload_completed"
+    storage_uri: str
+    view_url: str | None
+    attempt: int
+    duration_ms: int
+
+
+class UploadFailedEvent(ClipEvent):
+    """Upload to storage backend failed."""
+    event_type: Literal["upload_failed"] = "upload_failed"
+    attempt: int
+    error_message: str
+    error_type: str
+    will_retry: bool
+
+
+class FilterStartedEvent(ClipEvent):
+    """Object detection filter started."""
+    event_type: Literal["filter_started"] = "filter_started"
+    attempt: int
+
+
+class FilterCompletedEvent(ClipEvent):
+    """Object detection filter completed."""
+    event_type: Literal["filter_completed"] = "filter_completed"
+    detected_classes: list[str]
+    confidence: float
+    model: str
+    sampled_frames: int
+    attempt: int
+    duration_ms: int
+
+
+class FilterFailedEvent(ClipEvent):
+    """Object detection filter failed."""
+    event_type: Literal["filter_failed"] = "filter_failed"
+    attempt: int
+    error_message: str
+    error_type: str
+    will_retry: bool
+
+
+class VLMStartedEvent(ClipEvent):
+    """VLM analysis started."""
+    event_type: Literal["vlm_started"] = "vlm_started"
+    attempt: int
+
+
+class VLMCompletedEvent(ClipEvent):
+    """VLM analysis completed."""
+    event_type: Literal["vlm_completed"] = "vlm_completed"
+    risk_level: str
+    activity_type: str
+    summary: str
+    analysis: dict[str, Any]
+    prompt_tokens: int | None
+    completion_tokens: int | None
+    attempt: int
+    duration_ms: int
+
+
+class VLMFailedEvent(ClipEvent):
+    """VLM analysis failed."""
+    event_type: Literal["vlm_failed"] = "vlm_failed"
+    attempt: int
+    error_message: str
+    error_type: str
+    will_retry: bool
+
+
+class VLMSkippedEvent(ClipEvent):
+    """VLM analysis skipped (no trigger classes detected)."""
+    event_type: Literal["vlm_skipped"] = "vlm_skipped"
+    reason: str
+
+
+class AlertDecisionMadeEvent(ClipEvent):
+    """Alert policy decision made."""
+    event_type: Literal["alert_decision_made"] = "alert_decision_made"
+    should_notify: bool
+    reason: str
+    detected_classes: list[str] | None
+    vlm_risk: str | None
+
+
+class NotificationSentEvent(ClipEvent):
+    """Notification sent successfully."""
+    event_type: Literal["notification_sent"] = "notification_sent"
+    notifier_name: str
+    dedupe_key: str
+    attempt: int = 1
+
+
+class NotificationFailedEvent(ClipEvent):
+    """Notification send failed."""
+    event_type: Literal["notification_failed"] = "notification_failed"
+    notifier_name: str
+    error_message: str
+    error_type: str
+    attempt: int = 1
+    will_retry: bool = False
+
+
+ClipLifecycleEvent = Annotated[
+    ClipRecordedEvent
+    | ClipDeletedEvent
+    | ClipRecheckedEvent
+    | UploadStartedEvent
+    | UploadCompletedEvent
+    | UploadFailedEvent
+    | FilterStartedEvent
+    | FilterCompletedEvent
+    | FilterFailedEvent
+    | VLMStartedEvent
+    | VLMCompletedEvent
+    | VLMFailedEvent
+    | VLMSkippedEvent
+    | AlertDecisionMadeEvent
+    | NotificationSentEvent
+    | NotificationFailedEvent,
+    Field(discriminator="event_type"),
+]

homesec/models/filter.py

@@ -0,0 +1,62 @@
+"""Object detection filter data and config models."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class FilterResult(BaseModel):
+    """Result from object detection filter on a video clip."""
+
+    detected_classes: list[str]
+    confidence: float
+    model: str
+    sampled_frames: int
+
+
+class YoloFilterSettings(BaseModel):
+    """YOLO filter settings.
+
+    model_path accepts a filename; bare names resolve under ./yolo_cache.
+    """
+
+    model_config = {"extra": "forbid"}
+
+    model_path: str = "yolo11n.pt"
+    classes: list[str] = Field(default_factory=lambda: ["person"], min_length=1)
+    min_confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+    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)
+
+
+class FilterOverrides(BaseModel):
+    """Runtime overrides for filter settings (model path not allowed)."""
+
+    model_config = {"extra": "forbid"}
+
+    classes: list[str] | None = Field(default=None, min_length=1)
+    min_confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    sample_fps: int | None = Field(default=None, ge=1)
+    min_box_h_ratio: float | None = Field(default=None, ge=0.0, le=1.0)
+    min_hits: int | None = Field(default=None, ge=1)
+
+
+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)
+    - After plugin discovery: BaseModel subclass (validated against plugin.config_model)
+
+    Note: Plugin names are validated against the registry at runtime via
+    validate_plugin_names(). This allows third-party plugins via entry points.
+    """
+
+    model_config = {"extra": "forbid"}
+
+    plugin: str
+    max_workers: int = Field(default=4, ge=1)
+    config: dict[str, object] | BaseModel  # Dict before validation, BaseModel after

homesec/models/source.py

@@ -0,0 +1,77 @@
+"""Source configuration models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class RTSPSourceConfig(BaseModel):
+    """RTSP source configuration."""
+
+    model_config = {"extra": "forbid"}
+
+    rtsp_url_env: str | None = None
+    rtsp_url: str | None = None
+    detect_rtsp_url_env: str | None = None
+    detect_rtsp_url: str | None = None
+    output_dir: str = "./recordings"
+    pixel_threshold: int = 45
+    min_changed_pct: float = 1.0
+    blur_kernel: int = 5
+    stop_delay: float = 10.0
+    max_recording_s: float = 60.0
+    max_reconnect_attempts: int = 20
+    disable_hwaccel: bool = False
+    frame_timeout_s: float = 2.0
+    frame_queue_size: int = 20
+    reconnect_backoff_s: float = 1.0
+    debug_motion: bool = False
+    heartbeat_s: float = 30.0
+    rtsp_connect_timeout_s: float = 2.0
+    rtsp_io_timeout_s: float = 2.0
+
+
+class LocalFolderSourceConfig(BaseModel):
+    """Local folder source configuration."""
+
+    model_config = {"extra": "forbid"}
+
+    watch_dir: str = "recordings"
+    poll_interval: float = 1.0
+    stability_threshold_s: float = 3.0
+
+
+class FtpSourceConfig(BaseModel):
+    """FTP source configuration."""
+
+    model_config = {"extra": "forbid"}
+
+    host: str = "0.0.0.0"
+    port: int = 2121
+    root_dir: str = "./ftp_incoming"
+    ftp_subdir: str | None = None
+    anonymous: bool = True
+    username_env: str | None = None
+    password_env: str | None = None
+    perms: str = "elw"
+    passive_ports: str | None = None
+    masquerade_address: str | None = None
+    heartbeat_s: float = 30.0
+    allowed_extensions: list[str] = Field(default_factory=lambda: [".mp4"])
+    delete_non_matching: bool = True
+    delete_incomplete: bool = True
+    default_duration_s: float = 10.0
+    log_level: str = "INFO"
+
+    @field_validator("allowed_extensions")
+    @classmethod
+    def _normalize_extensions(cls, value: list[str]) -> list[str]:
+        cleaned: list[str] = []
+        for item in value:
+            ext = str(item).strip().lower()
+            if not ext:
+                continue
+            if not ext.startswith("."):
+                ext = f".{ext}"
+            cleaned.append(ext)
+        return cleaned

homesec/models/storage.py

@@ -0,0 +1,12 @@
+"""Storage-related data models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class StorageUploadResult(BaseModel):
+    """Result of a storage upload."""
+
+    storage_uri: str
+    view_url: str | None = None

homesec/models/vlm.py

@@ -0,0 +1,99 @@
+"""VLM analysis data and config models."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+RiskLevel = Literal["low", "medium", "high", "critical"]
+
+
+class AnalysisResult(BaseModel):
+    """Structured result from VLM analysis of a video clip."""
+
+    risk_level: RiskLevel
+    activity_type: str
+    summary: str
+    analysis: SequenceAnalysis | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+
+
+class EntityTimeline(BaseModel):
+    """Timeline of an entity across multiple frames."""
+
+    model_config = {"extra": "forbid"}
+    type: Literal["person", "vehicle", "animal", "package", "object", "unknown"]
+    first_seen_timestamp: str
+    last_seen_timestamp: str
+    description: str
+    movement: str
+    location: str
+    interaction: str
+
+
+class SequenceAnalysis(BaseModel):
+    """Structured analysis of a sequence of security camera frames."""
+
+    model_config = {"extra": "forbid"}
+    sequence_description: str
+    max_risk_level: RiskLevel
+    primary_activity: Literal[
+        "normal_delivery",
+        "normal_visitor",
+        "passerby",
+        "suspicious_behavior",
+        "dangerous_activity",
+        "no_activity",
+        "unknown",
+    ]
+    observations: list[str]
+    entities_timeline: list[EntityTimeline]
+    requires_review: bool
+    frame_count: int
+    video_start_time: str
+    video_end_time: str
+
+
+class VLMPreprocessConfig(BaseModel):
+    """Preprocessing configuration for VLM frame extraction."""
+
+    model_config = {"extra": "forbid"}
+    max_frames: int = 10
+    max_size: int = 1024
+    quality: int = 85
+
+
+class OpenAILLMConfig(BaseModel):
+    """OpenAI-compatible LLM configuration."""
+
+    model_config = {"extra": "forbid"}
+    api_key_env: str
+    model: str
+    base_url: str = "https://api.openai.com/v1"
+    token_param: Literal["max_tokens", "max_completion_tokens"] = "max_completion_tokens"
+    max_completion_tokens: int = 10_000
+    max_tokens: int | None = None
+    temperature: float | None = 0.0
+    request_timeout: float = 60.0
+
+
+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)
+    - After plugin discovery: BaseModel subclass (validated against plugin.config_model)
+
+    Note: Backend names are validated against the registry at runtime via
+    validate_plugin_names(). This allows third-party VLM plugins via entry points.
+    """
+
+    model_config = {"extra": "forbid"}
+    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
+    preprocessing: VLMPreprocessConfig = Field(default_factory=VLMPreprocessConfig)

homesec/pipeline/__init__.py

@@ -0,0 +1,6 @@
+"""Pipeline module - clip processing orchestration."""
+
+from homesec.pipeline.alert_policy import DefaultAlertPolicy
+from homesec.pipeline.core import ClipPipeline
+
+__all__ = ["ClipPipeline", "DefaultAlertPolicy"]

homesec/pipeline/alert_policy.py

@@ -0,0 +1,5 @@
+"""Alert policy implementation (re-export)."""
+
+from homesec.plugins.alert_policies.default import DefaultAlertPolicy
+
+__all__ = ["DefaultAlertPolicy"]