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

homesec/plugins/filters/yolo.py

@@ -1,4 +1,4 @@
-"""YOLOv8 object detection filter plugin."""
+"""YOLO object detection filter plugin."""
 
 from __future__ import annotations
 
@@ -151,7 +151,7 @@ def _get_model(model_path: str, device: str) -> Any:
 
 
 @plugin(plugin_type=PluginType.FILTER, name="yolo")
-class YOLOv8Filter(ObjectFilter):
+class YOLOFilter(ObjectFilter):
     """YOLO-based object detection filter.
 
     Uses ProcessPoolExecutor internally for CPU/GPU-bound inference.

{homesec-1.2.0.dist-info → homesec-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: homesec
-Version: 1.2.0
+Version: 1.2.1
 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
@@ -243,25 +243,70 @@ Description-Content-Type: text/markdown
 
 # HomeSec
 
+[![PyPI](https://img.shields.io/pypi/v/homesec)](https://pypi.org/project/homesec/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![Typing: Typed](https://img.shields.io/badge/typing-typed-2b825b)](https://peps.python.org/pep-0561/)
 [![codecov](https://codecov.io/gh/lan17/HomeSec/branch/main/graph/badge.svg)](https://codecov.io/gh/lan17/HomeSec)
 
-HomeSec is a self-hosted, extensible network video recorder that puts you in control. Store clips wherever you want, analyze them with AI, and get smart notifications—all while keeping your footage private and off third-party clouds.
+HomeSec is a self-hosted, extensible video pipeline for home security cameras. You can connect cameras directly via RTSP, receive clips over FTP, or implement your own ClipSource. From there, the pipeline filters events with AI and sends smart notifications. Your footage stays private and off third-party clouds.
+
+## Design Principles
+
+- **Local-Only Data Processing**: Video footage remains on the local network by default. Cloud usage (Storage, VLM/OpenAI) is strictly opt-in.
+- **Modular Architecture**: All major components (sources, filters, analyzers, notifiers) are decoupled plugins defined by strict interfaces. If you want to use a different AI model or storage backend, you can swap it out with a few lines of Python.
+- **Resilience**: The primary resilience feature is backing up clips to storage. The pipeline handles intermittent stream failures and network instability without crashing or stalling.
+
+## Pipeline at a glance
+
+
+
+```mermaid
+graph TD
+    %% Layout Wrapper for horizontal alignment
+    subgraph Wrapper [" "]
+        direction LR
+        style Wrapper fill:none,stroke:none
+        
+        S[Clip Source]
+        
+        subgraph Pipeline [Media Processing Pipeline]
+            direction TB
+            C(Clip File) --> U([Upload to Storage])
+            C --> F([Detect objects: YOLO])
+            F -->|Detected objects| AI{Trigger classes filter}
+            AI -->|Yes| V([VLM Analysis])
+            AI -->|No| D([Discard])
+            V -->|Risk level, detected objects| P{Alert Policy filter}
+            P -->|No| D
+            P -->|YES| N[Notifiers]
+        end
+        
+        S -->|New Clip File| Pipeline
+        
+        PG[(Postgres)]
+        Pipeline -.->|State & Events| PG
+    end
+```
+
+- **Parallel Processing**: Upload and filter run in parallel.
+- **Resilience**: Upload failures do not block alerts; filter failures stop expensive VLM calls.
+- **State**: Metadata is stored in Postgres (`clip_states` + `clip_events`) for full observability.
 
-Under the hood, it's a pluggable async pipeline for home security cameras. It records short clips, runs object detection, optionally calls a vision-language model ([VLM](https://en.wikipedia.org/wiki/Vision%E2%80%93language_model)) for a structured summary, and sends alerts via [MQTT](https://en.wikipedia.org/wiki/MQTT) or email. The design prioritizes reliability and extensibility.
 
 ## Table of Contents
 
 - [Highlights](#highlights)
 - [Pipeline at a glance](#pipeline-at-a-glance)
 - [Quickstart](#quickstart)
+  - [30-Second Start (Docker)](#30-second-start-docker)
+  - [Manual Setup](#manual-setup)
 - [Configuration](#configuration)
-- [Extensible by design](#extensible-by-design)
-- [CLI](#cli)
-- [Built-in plugins](#built-in-plugins)
-- [Writing a plugin](#writing-a-plugin)
+  - [Commands](#commands)
+- [Plugins](#plugins)
+  - [Built-in plugins](#built-in-plugins)
+  - [Plugin interfaces](#plugin-interfaces)
+  - [Writing a custom plugin](#writing-a-custom-plugin)
 - [Observability](#observability)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -270,227 +315,229 @@ Under the hood, it's a pluggable async pipeline for home security cameras. It re
 ## Highlights
 
 - Multiple pluggable video clip sources: [RTSP](https://en.wikipedia.org/wiki/Real-Time_Streaming_Protocol) motion detection, [FTP](https://en.wikipedia.org/wiki/File_Transfer_Protocol) uploads, or a watched folder
-- Parallel upload + filter ([YOLOv8](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
+- Parallel upload + filter ([YOLO](https://en.wikipedia.org/wiki/You_Only_Look_Once)) with frame sampling and early exit
 - OpenAI-compatible VLM analysis with structured output
 - Policy-driven alerts with per-camera overrides
 - Fan-out notifiers (MQTT for Home Assistant, SendGrid email)
 - Postgres-backed state + events with graceful degradation
-- Built around small, stable interfaces so new plugins drop in cleanly
 - Health endpoint plus optional Postgres telemetry logging
 
-## Pipeline at a glance
 
-```
-ClipSource -> (Upload + Filter) -> VLM (optional) -> Alert Policy -> Notifier(s)
-```
-
-- Upload and filter run in parallel; VLM runs only when trigger classes are detected.
-- Upload failures do not block alerts; filter failures stop processing.
-- State is stored in Postgres (`clip_states` + `clip_events`) when available.
 
 ## Quickstart
 
-### Requirements
+### 30-Second Start (Docker)
+The fastest way to see it in action. Includes a pre-configured Postgres and a dummy local source.
+
+```bash
+git clone https://github.com/lan17/homesec.git
+cd homesec
+make up
+```
+*Modify `config/config.yaml` to add your real cameras, then restart.*
 
-- Raspberry Pi 4 (or equivalent) or higher; any x86_64 system works as well
-- Docker and Docker Compose
-- Optional: MQTT broker, Dropbox credentials, OpenAI-compatible API key
+### Manual Setup
+For standard production usage without Docker Compose:
 
-### Setup
+1. **Prerequisites**:
+   - Python 3.10+
+   - ffmpeg
+   - PostgreSQL (running and accessible)
 
-1. Create a config file:
+2. **Install**
    ```bash
-   cp config/example.yaml config/config.yaml
-   # Edit config/config.yaml with your settings
+   pip install homesec
    ```
-2. Set environment variables:
+
+3. **Configure**
    ```bash
-   cp .env.example .env
-   # Edit .env with your credentials
+   # Download example config & env
+   curl -O https://raw.githubusercontent.com/lan17/homesec/main/config/example.yaml
+   mv example.yaml config.yaml
+   
+   curl -O https://raw.githubusercontent.com/lan17/homesec/main/.env.example
+   mv .env.example .env
+
+   # Setup environment (DB_DSN is required)
+   # Edit .env to set your secrets!
+   export DB_DSN="postgresql://user:pass@localhost/homesec"
    ```
-3. Start HomeSec + Postgres:
+
+4. **Run**
    ```bash
-   make up
+   homesec run --config config.yaml
    ```
-4. Stop:
+
+### Developer Setup
+If you are contributing or running from source:
+
+1. **Install dependencies**
    ```bash
-   make down
+   uv sync
    ```
 
-### Running without Docker
+2. **Start Infrastructure**
+   ```bash
+   make db  # Starts just Postgres in Docker
+   ```
 
-If you prefer to run locally:
+3. **Run**
+   ```bash
+   uv run python -m homesec.cli run --config config/config.yaml
+   ```
 
-1. Install Python 3.10+ and ffmpeg
-2. `uv sync`
-3. `make db` (starts Postgres)
-4. `make run`
 
 ## Configuration
 
-Configs are YAML and validated with Pydantic. See `config/example.yaml` for all options.
+Configuration is YAML-based and strictly validated. Secrets (API keys, passwords) should always be loaded from environment variables (`_env` suffix).
 
-Minimal example (RTSP + Dropbox + MQTT):
+### Configuration Examples
 
-```yaml
-version: 1
+#### 1. The "Power User" (Robust RTSP)
+Best for real-world setups with flaky cameras.
 
+```yaml
 cameras:
-  - name: front_door
+  - name: driveway
     source:
       type: rtsp
       config:
-        rtsp_url_env: FRONT_DOOR_RTSP_URL
+        rtsp_url_env: DRIVEWAY_RTSP_URL
         output_dir: "./recordings"
+        # Critical for camera compatibility:
+        ffmpeg_flags: ["-rtsp_transport", "tcp", "-vsync", "0"]
+        reconnect_backoff_s: 5
 
+filter:
+  plugin: yolo
+  config:
+    classes: ["person", "car"]
+    min_confidence: 0.6
+```
+
+In your `.env`:
+```bash
+DRIVEWAY_RTSP_URL="rtsp://user:pass@192.168.1.100:554/stream"
+```
+
+#### 2. The "Cloud Storage" (Dropbox)
+Uploads to Cloud but keeps analysis local.
+
+```yaml
 storage:
   backend: dropbox
   dropbox:
-    root: "/homecam"
     token_env: DROPBOX_TOKEN
-    app_key_env: DROPBOX_APP_KEY
-    app_secret_env: DROPBOX_APP_SECRET
-    refresh_token_env: DROPBOX_REFRESH_TOKEN
-
-state_store:
-  dsn_env: DB_DSN
+    root: "/SecurityCam"
 
 notifiers:
-  - backend: mqtt
-    config:
-      host: "localhost"
-      port: 1883
+    - backend: sendgrid_email
+      config:
+        api_key_env: SENDGRID_API_KEY
+        to_emails: ["me@example.com"]
+```
 
-filter:
-  plugin: yolo
-  config:
-    classes: ["person"]
-    min_confidence: 0.5
-
-vlm:
-  backend: openai
-  llm:
-    api_key_env: OPENAI_API_KEY
-    model: gpt-4o
-
-alert_policy:
-  backend: default
-  enabled: true
-  config:
-    min_risk_level: medium
+In your `.env`:
+```bash
+DROPBOX_TOKEN="sl.Al..."
+SENDGRID_API_KEY="SG.xyz..."
+```
+
+See [`config/example.yaml`](config/example.yaml) for a complete reference of all options.
+
+### Tips
+
+- **Secrets**: Never put secrets in YAML. Use env vars (`*_env`) and set them in your shell or `.env`.
+- **Notifiers**: At least one notifier (mqtt/email) must be enabled unless `alert_policy.enabled` is false.
+- **YOLO Classes**: Built-in classes include `person`, `car`, `truck`, `motorcycle`, `bicycle`, `dog`, `cat`, `bird`, `backpack`, `handbag`, `suitcase`.
 
-per_camera_alert:
-  front_door:
-    min_risk_level: low
-    notify_on_activity_types: ["person_at_door", "delivery"]
+After installation, the `homesec` command is available:
+
+```bash
+homesec --help
 ```
 
-A few things worth knowing:
-- Secrets never go in YAML. Use env var names (`*_env`) and set values in your shell or `.env`.
-- At least one notifier must be enabled (`mqtt` or `sendgrid_email`).
-- Built-in YOLO classes: `person`, `car`, `truck`, `motorcycle`, `bicycle`,
-  `dog`, `cat`, `bird`, `backpack`, `handbag`, `suitcase`.
-- Local storage for development:
+### Commands
 
-```yaml
-storage:
-  backend: local
-  local:
-    root: "./storage"
+**Run the pipeline:**
+```bash
+homesec run --config config.yaml
 ```
 
-- Set `alert_policy.enabled: false` to disable notifications (a noop policy is used).
-- For a quick local run, pair `local_folder` with `local` storage and drop a clip
-  into `recordings/`.
-
-## Extensible by design
-
-HomeSec is intentionally modular. Each major capability is an interface
-(`ClipSource`, `StorageBackend`, `ObjectFilter`, `VLMAnalyzer`, `AlertPolicy`,
-`Notifier`) defined in `src/homesec/interfaces.py`, and plugins are discovered at
-runtime via entry points. This keeps the core pipeline small while making it
-easy to add new backends without editing core code.
-
-What this means in practice:
-- Swap storage or notifications by changing config, not code.
-- Add a new plugin type as a separate package and register it.
-- Keep config validation strict by pairing each plugin with a Pydantic model.
-
-Extension points (all pluggable):
-- Sources: RTSP motion detection, FTP uploads, local folders
-- Storage backends: Dropbox, local disk, or your own
-- Filters: object detection (YOLO or custom models)
-- VLM analyzers: OpenAI-compatible APIs or local models
-- Alert policies: per-camera rules and thresholds
-- Notifiers: MQTT, email, or anything else you can send from Python
-
-## CLI
-
-- Run the pipeline:
-  `uv run python -m homesec.cli run --config config/config.yaml --log_level INFO`
-- Validate config:
-  `uv run python -m homesec.cli validate --config config/config.yaml`
-- Cleanup (reanalyze and optionally delete empty clips):
-  `uv run python -m homesec.cli cleanup --config config/config.yaml --older_than_days 7 --dry_run True`
-
-## Built-in plugins
-
-- Filters: `yolo`
-- VLM analyzers: `openai` (OpenAI-compatible API)
-- Storage: `dropbox`, `local`
-- Notifiers: `mqtt`, `sendgrid_email`
-- Alert policies: `default`, `noop`
-
-## Writing a plugin
-
-HomeSec discovers plugins via entry points in the `homesec.plugins` group. A plugin
-module just needs to import and register itself.
-
-Each plugin provides:
-- A unique name (used in config)
-- A Pydantic config model for validation
-- A factory that builds the concrete implementation
-
-```python
-# my_package/filters/custom.py
-from pydantic import BaseModel
-from homesec.interfaces import ObjectFilter
-from homesec.plugins.filters import FilterPlugin, filter_plugin
-
-class CustomConfig(BaseModel):
-    threshold: float = 0.5
-
-class CustomFilter(ObjectFilter):
-    ...
-
-@filter_plugin(name="custom")
-def register() -> FilterPlugin:
-    return FilterPlugin(
-        name="custom",
-        config_model=CustomConfig,
-        factory=lambda cfg: CustomFilter(cfg),
-    )
+**Validate config:**
+```bash
+homesec validate --config config.yaml
 ```
 
-```toml
-# pyproject.toml
-[project.entry-points."homesec.plugins"]
-my_filters = "my_package.filters.custom"
+**Cleanup old clips** (reanalyze and optionally delete empty clips):
+```bash
+homesec cleanup --config config.yaml --older_than_days 7 --dry_run=False
 ```
 
+Use `homesec <command> --help` for detailed options on each command.
+
+## Plugins
+
+### Extensible by design
+
+We designed HomeSec to be modular. Each major capability is an interface (`ClipSource`, `StorageBackend`, `ObjectFilter`, `VLMAnalyzer`, `AlertPolicy`, `Notifier`) defined in `src/homesec/interfaces.py`. This means you can swap out components (like replacing YOLO with a different detector) without changing the core pipeline.
+  
+HomeSec uses a plugin architecture where every component is discovered at runtime via entry points.
+
+### Built-in plugins
+
+| Type | Plugins |
+|------|---------|
+| Sources | [`rtsp`](src/homesec/sources/rtsp.py), [`ftp`](src/homesec/sources/ftp.py), [`local_folder`](src/homesec/sources/local_folder.py) |
+| Filters | [`yolo`](src/homesec/plugins/filters/yolo.py) |
+| Storage | [`dropbox`](src/homesec/plugins/storage/dropbox.py), [`local`](src/homesec/plugins/storage/local.py) |
+| VLM analyzers | [`openai`](src/homesec/plugins/analyzers/openai.py) |
+| Notifiers | [`mqtt`](src/homesec/plugins/notifiers/mqtt.py), [`sendgrid_email`](src/homesec/plugins/notifiers/sendgrid_email.py) |
+| Alert policies | [`default`](src/homesec/plugins/alert_policies/default.py), [`noop`](src/homesec/plugins/alert_policies/noop.py) |
+
+### Plugin interfaces
+
+All interfaces are defined in [`src/homesec/interfaces.py`](src/homesec/interfaces.py).
+
+| Type | Interface | Decorator |
+|------|-----------|-----------|
+| Sources | `ClipSource` | `@source_plugin` |
+| Filters | `ObjectFilter` | `@filter_plugin` |
+| Storage | `StorageBackend` | `@storage_plugin` |
+| VLM analyzers | `VLMAnalyzer` | `@vlm_plugin` |
+| Notifiers | `Notifier` | `@notifier_plugin` |
+| Alert policies | `AlertPolicy` | `@alert_policy_plugin` |
+
+### Writing a custom plugin
+
+Extending HomeSec is designed to be easy. You can write custom sources, filters, storage backends, and more.
+
+👉 **See [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) for a complete guide.**
+
 ## Observability
 
-- Health endpoint: `GET /health` (configurable in `health.host`/`health.port`)
-- Optional telemetry logs to Postgres when `DB_DSN` is set:
-  - Start local DB: `make db`
-  - Run migrations: `make db-migrate`
+- Health endpoint: `GET /health` (configurable via `health.host`/`health.port` in config)
+- Telemetry logs to Postgres when `DB_DSN` is set
 
 ## Development
 
+### Setup
+
+1. Clone the repository
+2. Install [uv](https://docs.astral.sh/uv/) for dependency management
+3. `uv sync` to install dependencies
+4. `make db` to start Postgres locally
+
+### Commands
+
 - Run tests: `make test`
 - Run type checking (strict): `make typecheck`
 - Run both: `make check`
-- Tests must include Given/When/Then comments.
+- Run the pipeline: `make run`
+
+### Notes
+
+- Tests must include Given/When/Then comments
 - Architecture notes: `DESIGN.md`
 
 ## Contributing

{homesec-1.2.0.dist-info → homesec-1.2.1.dist-info}/RECORD

@@ -35,7 +35,7 @@ homesec/plugins/alert_policies/noop.py,sha256=xcdyZAlQf6X_AqQWUPkRMHLK8J6d7PTXWo
 homesec/plugins/analyzers/__init__.py,sha256=GLC01lACmqZjKjMbkUnB_yYnOTxW_XEOwOfHK-I9SX0,915
 homesec/plugins/analyzers/openai.py,sha256=qLN9Qhj-DvqEE6nHXIfW0QPp2EhSVwIVVXzq-QSqdzQ,15979
 homesec/plugins/filters/__init__.py,sha256=JgPJTcW8yKa6JRIED4w8o5j_n_k5J7xwQbhAqDYofA4,866
-homesec/plugins/filters/yolo.py,sha256=gCuFHtqZsJVimaX1p7XvP9MTP9vliLiwniZWioAH5RA,11130
+homesec/plugins/filters/yolo.py,sha256=RUJqP9vtHDEoTqR9U3zt2ae_4Y8DGaJ2bsmJGVlfYMw,11126
 homesec/plugins/notifiers/__init__.py,sha256=6T3OX4Vg1XKZeSG6AlZzw0o2KlaRr_mePBDIZEbr5Rw,1066
 homesec/plugins/notifiers/mqtt.py,sha256=1zUKUHFvT65ysawFXEwWHvY8rg310fRsSSKhIFeaUL4,5946
 homesec/plugins/notifiers/multiplex.py,sha256=LlnwozjkMDQwz7__v7mT4AohZbiWZK39CZunamRp7FM,3676
@@ -61,8 +61,8 @@ homesec/telemetry/db_log_handler.py,sha256=KM8g4kcOyPzFJbpGxpSzecx_hrEWY0YfpoIKy
 homesec/telemetry/postgres_settings.py,sha256=EVD2_oi_KReFJvQmXxW026aurl_YD-KexT7rkbGQPHc,1198
 homesec/telemetry/db/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 homesec/telemetry/db/log_table.py,sha256=wcZLwRht7FMa0z2gf37f_RxdVTNIdDiK4i_N3c_ibwg,473
-homesec-1.2.0.dist-info/METADATA,sha256=0N3Lg00FUl57PUV4VWe_vbIfQDOq-xib2wnkSU6dQS4,23274
-homesec-1.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-homesec-1.2.0.dist-info/entry_points.txt,sha256=8ocCj_fP1qxIuL-DVDAUiaUbEdTMX_kg_BzVrJsbQYg,45
-homesec-1.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-homesec-1.2.0.dist-info/RECORD,,
+homesec-1.2.1.dist-info/METADATA,sha256=UqWtHMZ6XjaykxI7ya_Fu-fwUTHVAEMl15sBfEbysjI,25121
+homesec-1.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+homesec-1.2.1.dist-info/entry_points.txt,sha256=8ocCj_fP1qxIuL-DVDAUiaUbEdTMX_kg_BzVrJsbQYg,45
+homesec-1.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+homesec-1.2.1.dist-info/RECORD,,