homesec 1.1.0__tar.gz → 1.1.2__tar.gz

{homesec-1.1.0 → homesec-1.1.2}/.github/workflows/release.yaml

@@ -21,6 +21,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.GH_TOKEN }}
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -43,7 +44,7 @@ jobs:
         if: ${{ !inputs.dry_run }}
         id: semrel
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
           semantic-release version
           echo "version=$(grep 'version = ' pyproject.toml | head -1 | cut -d'\"' -f2)" >> $GITHUB_OUTPUT
@@ -63,7 +64,7 @@ jobs:
       - name: Upload to GitHub Release
         if: ${{ !inputs.dry_run }}
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |
           VERSION=${{ steps.semrel.outputs.version }}
           # Upload dist files to the release that semantic-release created

{homesec-1.1.0 → homesec-1.1.2}/.gitignore

@@ -9,3 +9,4 @@ video_cache
 yolo_cache
 ftp_incoming
 config/config.yaml
+.coverage

{homesec-1.1.0 → homesec-1.1.2}/AGENTS.md

@@ -1,6 +1,6 @@
 # HomeSec Development Guidelines
 
-**Last reviewed:** 2025-01-11
+**Last reviewed:** 2026-01-18
 **Purpose:** Critical patterns to prevent runtime bugs when extending HomeSec. For architecture overview, see `DESIGN.md`.
 
 ---
@@ -12,6 +12,7 @@
 - **Repository pattern**: Use `ClipRepository` for all state/event writes. Never touch `StateStore`/`EventStore` directly.
 - **Preserve stack traces**: Custom errors must set `self.__cause__ = cause` to preserve original exception.
 - **Tests must use Given/When/Then comments**: Every test must include these comments and follow behavioral testing principles (see `TESTING.md`).
+- **Import from canonical source**: Import types from their defining module, not re-exports. For example, import `RiskLevel` from `models.enums`, not from `models.vlm`. Avoid creating re-exports in `__all__`.
 - **Postgres for state**: Use `clip_states` table with `clip_id` (primary key) + `data` (jsonb) for evolvable schema.
 - **Pydantic everywhere**: Validate config, DB payloads, VLM outputs, and MQTT payloads with Pydantic models.
 - **Clarify before complexity**: Ask user for clarification when simpler design may exist. Don't proceed with complex workarounds.
@@ -232,14 +233,13 @@ await self._event_store.append(event)  # What if this fails? State already updat
 
 ### 4. Plugin Registration
 
-**Rule:** Use entry point discovery for all plugin types. Allows users to add custom plugins without modifying core code.
+**Rule:** Use decorator-based registration with typed factories. All plugins follow the same pattern: `@<type>_plugin` decorator + `load_<type>_plugin()` loader.
 
-**✅ Template: Entry Point Discovery**
+**✅ Template: Decorator-Based Registration**
 
 ```python
 # In src/homesec/plugins/notifiers/__init__.py
 from dataclasses import dataclass
-from importlib.metadata import entry_points
 from pydantic import BaseModel
 
 @dataclass(frozen=True)
@@ -250,28 +250,71 @@ class NotifierPlugin:
 
 NOTIFIER_REGISTRY: dict[str, NotifierPlugin] = {}
 
-def register_notifier(name: str, config_model: type, factory: Callable):
-    NOTIFIER_REGISTRY[name] = NotifierPlugin(name, config_model, factory)
-
-def discover_notifiers(import_paths: list[str]):
-    # Discover from pyproject.toml entry points
-    for ep in entry_points(group="homesec.notifiers"):
-        register_fn = ep.load()
-        register_fn()
+def register_notifier(plugin: NotifierPlugin) -> None:
+    """Register with collision detection."""
+    if plugin.name in NOTIFIER_REGISTRY:
+        raise ValueError(f"Plugin '{plugin.name}' already registered")
+    NOTIFIER_REGISTRY[plugin.name] = plugin
+
+def notifier_plugin(name: str) -> Callable[[T], T]:
+    """Decorator to register a notifier plugin."""
+    def decorator(factory_fn: T) -> T:
+        plugin = factory_fn()
+        register_notifier(plugin)
+        return factory_fn
+    return decorator
+
+def load_notifier_plugin(backend: str, config: dict | BaseModel) -> Notifier:
+    """Load and instantiate a notifier plugin with config validation."""
+    plugin = NOTIFIER_REGISTRY[backend.lower()]
+    validated = plugin.config_model.model_validate(config) if isinstance(config, dict) else config
+    return plugin.factory(validated)
+```
 
-# In custom plugin package:
-def register():
-    from homesec.plugins.notifiers import register_notifier
-    register_notifier("mqtt", MQTTConfig, lambda cfg: MQTTNotifier(cfg))
+**✅ Template: Plugin Implementation with Type Safety**
 
-# In user's pyproject.toml:
-# [project.entry-points."homesec.notifiers"]
-# mqtt = "homesec_mqtt:register"
+```python
+# In src/homesec/plugins/notifiers/mqtt.py
+from pydantic import BaseModel
+from homesec.plugins.notifiers import NotifierPlugin, notifier_plugin
+
+class MQTTNotifierConfig(BaseModel):
+    broker_url: str
+    topic_prefix: str = "homesec"
+
+@notifier_plugin(name="mqtt")
+def mqtt_notifier_plugin() -> NotifierPlugin:
+    def factory(cfg: BaseModel) -> Notifier:
+        # Type-safe: validate config type at runtime
+        if not isinstance(cfg, MQTTNotifierConfig):
+            raise TypeError(f"Expected MQTTNotifierConfig, got {type(cfg).__name__}")
+        return MQTTNotifier(cfg)
+
+    return NotifierPlugin(
+        name="mqtt",
+        config_model=MQTTNotifierConfig,
+        factory=factory,
+    )
 ```
 
-**Note:** All plugin types (filters, VLMs, storage, notifiers, alert policies) use this unified pattern. For shared utilities, see `src/homesec/plugins/utils.py` which provides `iter_entry_points()` and `load_plugin_from_entry_point()` helpers.
+**Plugin Types and Context Objects:**
+
+| Plugin Type | Decorator | Context | Factory Signature |
+|-------------|-----------|---------|-------------------|
+| Filters | `@filter_plugin` | `FilterContext` | `(BaseModel, FilterContext) -> ObjectFilter` |
+| Analyzers | `@vlm_plugin` | `VLMContext` | `(BaseModel, VLMContext) -> VLMAnalyzer` |
+| Sources | `@source_plugin` | `SourceContext` | `(BaseModel, SourceContext) -> ClipSource` |
+| Alert Policies | `@alert_policy_plugin` | `AlertPolicyContext` | `(BaseModel, AlertPolicyContext) -> AlertPolicy` |
+| Notifiers | `@notifier_plugin` | None | `(BaseModel) -> Notifier` |
+| Storage | `@storage_plugin` | None | `(BaseModel) -> StorageBackend` |
 
-**Reference:** See any plugin `__init__.py` file for complete implementations: `src/homesec/plugins/filters/__init__.py`, `src/homesec/plugins/analyzers/__init__.py`, `src/homesec/plugins/storage/__init__.py`, `src/homesec/plugins/notifiers/__init__.py`, or `src/homesec/plugins/alert_policies/__init__.py`.
+**Why some plugins have Context and others don't:**
+- **With Context** (Filters, Analyzers, Sources, AlertPolicies): These plugins need runtime information beyond their config—camera names, executor pools, file paths, or pipeline state. Context objects provide this without polluting config models.
+- **Without Context** (Notifiers, Storage): These are stateless services that only need their own config. They don't depend on which camera or pipeline invokes them.
+
+**Note:** Always use `isinstance()` checks in factories instead of `cast()` to ensure type safety at runtime.
+
+**Reference:** See `PLUGIN_DEVELOPMENT.md` for complete guide. Example implementations: `src/homesec/plugins/filters/yolo.py`, `src/homesec/plugins/notifiers/mqtt.py`.
 
 ---
 
@@ -381,6 +424,13 @@ make db-migrate         # Run Alembic migrations
 - `UPPER_SNAKE_CASE` for constants
 - 4-space indentation
 
+### Import Organization
+
+- **All imports at top of file** - Never use local/inline imports except when absolutely necessary to avoid circular imports
+- **Standard ordering**: stdlib → third-party → homesec (ruff handles this with `ruff check --fix`)
+- **No re-imports at end of file** - Plugin registration decorators should use imports from the top
+- **Circular import avoidance**: Use `TYPE_CHECKING` blocks for type-only imports when needed
+
 ### Security
 
 ```python

{homesec-1.1.0 → homesec-1.1.2}/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 <!-- version list -->
 
+## v1.1.2 (2026-01-19)
+
+### Bug Fixes
+
+- Use PAT token for release workflow to bypass branch protection
+  ([#13](https://github.com/lan17/homesec/pull/13),
+  [`511ac6d`](https://github.com/lan17/homesec/commit/511ac6d8899365d324ede41aefdbe8fab910f1cb))
+
+### Refactoring
+
+- Complete plugin architecture standardization ([#10](https://github.com/lan17/homesec/pull/10),
+  [`4e5b85f`](https://github.com/lan17/homesec/commit/4e5b85fd9a32d4f71c4365222a735c2e01eba583))
+
+
+## v1.1.1 (2026-01-16)
+
+### Bug Fixes
+
+- Improve CLI help output to show available commands ([#8](https://github.com/lan17/homesec/pull/8),
+  [`4c8342f`](https://github.com/lan17/homesec/commit/4c8342f71274f2110231f112b77d68c8bb119c17))
+
+### Chores
+
+- Sync uv.lock version ([#8](https://github.com/lan17/homesec/pull/8),
+  [`4c8342f`](https://github.com/lan17/homesec/commit/4c8342f71274f2110231f112b77d68c8bb119c17))
+
+### Refactoring
+
+- Use Fire's native help output for CLI commands ([#8](https://github.com/lan17/homesec/pull/8),
+  [`4c8342f`](https://github.com/lan17/homesec/commit/4c8342f71274f2110231f112b77d68c8bb119c17))
+
+
 ## v1.1.0 (2026-01-12)
 
 ### Bug Fixes

{homesec-1.1.0 → homesec-1.1.2}/DESIGN.md

@@ -8,6 +8,95 @@
 4. **Single async flow per clip.** In-process handoff with bounded concurrency (global + per-stage `asyncio.Semaphore`). Callback-based ClipSource interface for extensibility.
 5. **Pluggable object detection and VLM analysis.** Specific models (YOLO, GPT-4, etc.) are abstracted behind async plugin interfaces. Pipeline is model-agnostic; plugins manage their own resources (GPU, process pools, API clients).
 6. **Errors as values.** Stage methods return `Result | StageError` instead of raising exceptions. This enables partial failures (e.g., upload fails but filter succeeds → still send alert). Stack traces are preserved in error objects. **Strict type checking required** (mypy --strict or pyright) to prevent runtime errors from missing `isinstance()` checks.
+7. **Type-safe enums for domain values.** Use `StrEnum`/`IntEnum` from `models/enums.py` for type safety, IDE support, and maintainability. See [Type Safety & Enums](#type-safety--enums) below.
+
+## Type Safety & Enums
+
+Domain values that appear in multiple places use centralized enums in `models/enums.py`:
+
+| Enum | Type | Purpose | Example |
+|------|------|---------|---------|
+| `EventType` | `StrEnum` | Clip lifecycle event types | `EventType.CLIP_RECORDED` |
+| `ClipStatus` | `StrEnum` | Clip processing status | `ClipStatus.UPLOADED` |
+| `RiskLevel` | `IntEnum` | VLM risk assessment (ordered) | `RiskLevel.HIGH > RiskLevel.LOW` |
+
+### Benefits
+
+- **Type safety**: Catch typos at compile time with mypy/pyright
+- **IDE support**: Autocomplete and refactoring
+- **Single source of truth**: No duplicate string literals
+- **Natural comparison**: `RiskLevel` uses `IntEnum` for `>=` comparisons
+
+### Usage Examples
+
+```python
+from homesec.models.enums import EventType, ClipStatus, RiskLevel
+
+# Event types in event models
+class ClipRecordedEvent(ClipEvent):
+    event_type: Literal[EventType.CLIP_RECORDED] = EventType.CLIP_RECORDED
+
+# Status comparisons
+if state.status == ClipStatus.UPLOADED:
+    ...
+
+# Risk level comparison (IntEnum)
+if analysis.risk_level >= RiskLevel.MEDIUM:
+    send_alert()
+
+# Parse from string (for config)
+level = RiskLevel.from_string("high")  # Returns RiskLevel.HIGH
+```
+
+### Serialization
+
+- `StrEnum` values serialize to their string value automatically
+- `RiskLevel` (IntEnum) uses custom Pydantic serialization to maintain string representation in configs (`"medium"` not `1`)
+
+## Plugin Architecture & Philosophy
+
+For detailed implementation guides and how-tos, see **[PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md)**.
+
+HomeSec employs a **Class-Based Plugin Architecture (V2)** designed for strict type safety, runtime validation, and clear separation of concerns. This section details the design patterns and philosophies driving the system.
+
+### 1. Core Philosophy: "Configuration is the Contract"
+
+In V1, plugins were factories accepting raw dictionaries and loose context objects. In V2, the **Configuration Model** (Pydantic) defines the entire contract for a plugin.
+
+-   **Type Safety**: Every plugin defines a `config_cls` (Pydantic model). The registry validates raw JSON/YAML against this model *before* the plugin is instantiated.
+-   **Dependency Injection**: Runtime dependencies (like `camera_name` for sources, or `trigger_classes` for analyzers) are injected into the configuration dictionary *before* validation.
+    -   *Benefit*: The plugin implementation doesn't need a separate `context` argument. It just declares `camera_name: str` in its config model, and the system ensures it's present.
+-   **Fail Fast**: Invalid configs cause a `ValidationError` at loading time, preventing partial start-ups.
+
+### 2. The Unified Registry Pattern
+
+Instead of maintaining separate registries for each plugin type (`SOURCE_REGISTRY`, `FILTER_REGISTRY`), we use a single, generic `PluginRegistry[ConfigT, PluginInterfaceT]`.
+
+-   **Generics for Safety**: The registry is generic over the configuration type and the plugin interface.
+    ```python
+    # strict typing ensures that load_plugin(PluginType.SOURCE, ...) returns a ClipSource
+    source = registry.load_plugin(PluginType.SOURCE, "my_source", config_dict)
+    ```
+-   **Declarative Registration**: Plugins register themselves using the `@plugin` decorator, which captures metadata (name, type) and creates the association without manual mapping code.
+
+### 3. Factory Pattern vs. Class Creation
+
+We transitioned from functional factories (`make_source()`) to class-based factories (`Class.create()`).
+
+-   **Encapsulation**: The class handles its own construction logic in `create()`, keeping `__init__` clean or free for dependency injection.
+-   **State Management**: Plugins often hold state (database connections, ML model handles). Classes naturally encapsulate this state and provide lifecycle methods (`shutdown()`) to clean it up.
+
+### 4. Decoupling & Local State
+
+A key design validation was separating `LocalFolderSource` from the global `StateStore`.
+
+-   **Philosophy**: Components should own their local truth.
+-   **Implementation**: `LocalFolderSource` uses a "Local State Manifest" (`.homesec_state.json`) to track processed files. This means the source can function even if the central database is down, fulfilling the "P0: Never miss new clips" requirement.
+
+### 5. Error Handling Philosophy
+
+-   **Boundaries must never crash**: Top-level loops wrap plugin calls in broad exception handlers (specifically catching `PipelineError`).
+-   **Errors as Values**: Where possible, return error objects/states rather than raising exceptions, allowing the pipeline to degrade gracefully (e.g., skip analysis but still upload).
 
 ## Goals
 
@@ -47,9 +136,9 @@ Build a reliable, pluggable pipeline to:
 
 ## Current Building Blocks (Repo)
 
-- Motion + recording: `src/motion_recorder.py` (OpenCV motion detection + ffmpeg recording; optional Dropbox upload via `src/dropbox_uploader.py`).
-- Object detection plugin (reference implementation): `src/human_filter/human_filter.py` (YOLOv8 sampling to detect people/animals).
-- VLM plugin (reference implementation): `src/vlm.py` (structured output with `risk_level`, `activity_type`, timeline, and `alert_threshold`).
+- Motion + recording: `src/homesec/sources/rtsp.py` (OpenCV motion detection + ffmpeg recording).
+- Object detection plugin (reference): `src/homesec/plugins/filters/yolo.py` (YOLOv8 sampling to detect people/animals).
+- VLM plugin (reference): `src/homesec/plugins/analyzers/openai.py` (structured output with `risk_level`, `activity_type`, timeline).
 - Postgres (workflow state when available): Alembic migrations (`alembic/`) + telemetry logging (`src/db_log_handler.py`) + workflow state table `clip_states` (best-effort; DB outages may drop state updates).
 
 ## Proposed Architecture (Event-Driven Pipeline)
@@ -277,13 +366,11 @@ class AlertPolicy(Protocol):
 
 # === Plugin Interfaces ===
 
-class ObjectFilter(Protocol):
+class ObjectFilter(Shutdownable, Protocol):
     """Plugin interface for object detection in video clips."""
     
     async def detect(
-        self, 
-        video_path: Path, 
-        config: FilterConfig
+        self, video_path: Path, overrides: FilterOverrides | None = None
     ) -> FilterResult:
         """
         Detect objects in video clip.
@@ -292,8 +379,9 @@ class ObjectFilter(Protocol):
         - 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 config.max_workers if managing worker pool
+        - 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
@@ -303,24 +391,14 @@ class ObjectFilter(Protocol):
     async def shutdown(self) -> None:
         """
         Cleanup resources (process pools, GPU memory, file handles).
-        
-        Called once during application shutdown. Implementation should:
-        - Shutdown ProcessPoolExecutor if used (wait=True to finish in-flight work)
-        - Release GPU memory
-        - Close any open file handles or connections
-        
-        Example:
-            self._executor.shutdown(wait=True, cancel_futures=False)
         """
+        ...
 
-class VLMAnalyzer(Protocol):
+class VLMAnalyzer(Shutdownable, Protocol):
     """Plugin interface for VLM-based clip analysis."""
     
     async def analyze(
-        self,
-        video_path: Path,
-        filter_result: FilterResult,
-        config: VLMConfig
+        self, video_path: Path, filter_result: FilterResult, config: VLMConfig
     ) -> AnalysisResult:
         """
         Analyze clip and produce structured assessment.
@@ -340,15 +418,8 @@ class VLMAnalyzer(Protocol):
     async def shutdown(self) -> None:
         """
         Cleanup resources (HTTP sessions, process pools, model memory).
-        
-        Called once during application shutdown. Implementation should:
-        - Close HTTP sessions (aiohttp.ClientSession.close())
-        - Shutdown ProcessPoolExecutor if using local models
-        - Unload models from GPU/RAM
-        
-        Example:
-            await self._session.close()
         """
+        ...
 ```
 
 **Reference Implementations (MVP):**
@@ -361,7 +432,7 @@ class VLMAnalyzer(Protocol):
 - `MockFilter` / `MockVLM`: For testing (instant responses, no actual inference)
   - `shutdown()` implementation: no-op (no resources to clean up)
 
-## Configuration (Proposed)
+## Configuration
 
 Prefer a single YAML file for non-secret configuration (cameras, sources, policies, MQTT). Keep secrets in `.env` and reference them by env var name from YAML.
 

{homesec-1.1.0 → homesec-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: homesec
-Version: 1.1.0
+Version: 1.1.2
 Summary: Pluggable async home security camera pipeline with detection, VLM analysis, and alerts.
 Project-URL: Homepage, https://github.com/lan17/homesec
 Project-URL: Source, https://github.com/lan17/homesec