homesec 0.1.0__tar.gz → 1.0.0__tar.gz

homesec-1.0.0/.dockerignore

@@ -0,0 +1,57 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv
+venv
+ENV
+env
+
+# Development
+.env
+.env.*
+.mypy_cache
+.pytest_cache
+.ruff_cache
+*.egg-info
+dist
+build
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# Tests
+tests
+pytest.ini
+
+# Documentation
+docs
+DESIGN.md
+CLAUDE.md
+
+# Local data (should be mounted as volumes)
+recordings
+storage
+*.mp4
+*.avi
+*.mov
+video_cache
+yolo_cache
+ftp_incoming
+
+# Notebooks
+notebooks
+*.ipynb
+
+# Config examples (actual config mounted at runtime)
+config/*.yaml
+!config/example.yaml

{homesec-0.1.0 → homesec-1.0.0}/.env.example

@@ -30,20 +30,19 @@ MQTT_PASSWORD="..."
 # SendGrid email (if using sendgrid_email notifier)
 SENDGRID_API_KEY="..."
 
-# Twilio SMS (if using Twilio notifier)
-TWILIO_ACCOUNT_SID="..."
-TWILIO_AUTH_TOKEN="..."
-
-# --- Telemetry logging (optional) ---
-# If DB_DSN is set, the process will attempt to write structured JSON logs to Postgres.
-# Run a local Postgres with: make db-up
-POSTGRES_USER="telemetry"
-POSTGRES_PASSWORD="telemetry"
-POSTGRES_DB="telemetry"
+# --- Database (optional) ---
+# If DB_DSN is set, the process will store clip state/events in Postgres.
+# Run a local Postgres with: make db
+POSTGRES_USER="homesec"
+POSTGRES_PASSWORD="homesec"
+POSTGRES_DB="homesec"
 POSTGRES_PORT="5432"
 
-# Example (local docker):
-DB_DSN="postgresql+asyncpg://telemetry:telemetry@127.0.0.1:5432/telemetry"
+# For local dev (make db + make run):
+DB_DSN="postgresql+asyncpg://homesec:homesec@localhost:5432/homesec"
+
+# For docker-compose (make up) - set automatically, but can override:
+# DB_DSN="postgresql+asyncpg://homesec:homesec@postgres:5432/homesec"
 
 # Optional tuning:
 # DB_LOG_LEVEL="INFO"         # only logs >= this level go to DB

homesec-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: homesec
+          POSTGRES_USER: homesec
+          POSTGRES_PASSWORD: homesec
+        ports:
+          - "5432:5432"
+        # No health check - Postgres boots while lint/typecheck run
+
+    env:
+      DB_DSN: postgresql+asyncpg://homesec:homesec@localhost:5432/homesec
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv and Python
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Cache venv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-py3.14-${{ hashFiles('uv.lock') }}
+
+      - name: Sync dependencies
+        run: uv sync
+
+      # Lint and typecheck run while Postgres boots
+      - name: Lint
+        run: make lint
+
+      - name: Type check
+        run: make typecheck
+
+      # Wait for Postgres before migrations
+      - name: Wait for Postgres
+        run: |
+          for i in {1..30}; do
+            pg_isready -h localhost -p 5432 -U homesec && break
+            echo "Waiting for Postgres..."
+            sleep 1
+          done
+
+      - name: Run migrations
+        run: uv run alembic -c alembic.ini upgrade head
+
+      - name: Test
+        run: make test

homesec-1.0.0/.github/workflows/release.yaml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run (no actual release)'
+        required: false
+        default: 'false'
+        type: boolean
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install python-semantic-release
+        run: pip install python-semantic-release
+
+      - name: Semantic Release (dry run)
+        if: ${{ inputs.dry_run == 'true' }}
+        run: semantic-release version --noop
+
+      - name: Semantic Release
+        if: ${{ inputs.dry_run != 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          semantic-release version
+
+      - name: Build Package
+        if: ${{ inputs.dry_run != 'true' }}
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        if: ${{ inputs.dry_run != 'true' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+
+      - name: Create GitHub Release
+        if: ${{ inputs.dry_run != 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(grep 'version = ' pyproject.toml | head -1 | cut -d'"' -f2)
+          gh release create "v$VERSION" \
+            --title "v$VERSION" \
+            --generate-notes \
+            dist/*

homesec-1.0.0/.github/workflows/validate-pr-title.yaml

@@ -0,0 +1,20 @@
+name: Validate PR Title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

homesec-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+video_cache/
+*.pt
+.env
+__pycache__/
+dist
+.idea
+recordings
+video_cache
+yolo_cache
+ftp_incoming
+config/config.yaml

homesec-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-01-11)
+
+- Initial Release

homesec-1.0.0/Dockerfile

@@ -0,0 +1,96 @@
+# HomeSec Dockerfile
+# Multi-stage build for minimal image size
+#
+# Build: docker build -t homesec .
+# Run:   docker run \
+#          -v ./config.yaml:/config/config.yaml \
+#          -v ./.env:/config/.env \
+#          -v ./recordings:/data/recordings \
+#          -v ./storage:/data/storage \
+#          -v ./yolo_cache:/app/yolo_cache \
+#          -p 8080:8080 homesec
+
+# =============================================================================
+# Stage 1: Builder
+# =============================================================================
+FROM python:3.14-slim-bookworm AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast dependency management
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy dependency files first for better caching
+COPY pyproject.toml uv.lock* LICENSE README.md ./
+
+# Install dependencies into a virtual environment
+RUN uv venv /app/.venv
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH="/app/.venv/bin:$PATH"
+
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy source code
+COPY src/ ./src/
+COPY alembic/ ./alembic/
+COPY alembic.ini ./
+
+# Install the project
+RUN uv sync --frozen --no-dev
+
+# =============================================================================
+# Stage 2: Runtime
+# =============================================================================
+FROM python:3.14-slim-bookworm AS runtime
+
+# Install runtime dependencies
+# - ffmpeg: required for RTSP source video processing
+# - libgl1: required by OpenCV
+# - libglib2.0-0: required by OpenCV
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user for security
+RUN useradd --create-home --shell /bin/bash homesec
+
+WORKDIR /app
+
+# Copy virtual environment from builder
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/alembic /app/alembic
+COPY --from=builder /app/alembic.ini /app/alembic.ini
+
+# Copy entrypoint script
+COPY docker-entrypoint.sh /app/docker-entrypoint.sh
+
+# Set up environment
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+# Create directories for volume mounts and make entrypoint executable
+RUN chmod +x /app/docker-entrypoint.sh \
+    && mkdir -p /config /data/recordings /data/storage /app/yolo_cache \
+    && chown -R homesec:homesec /config /data /app
+
+# Switch to non-root user
+USER homesec
+
+# Health check endpoint
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')" || exit 1
+
+# Entrypoint runs migrations then starts app
+# Config and env are expected to be mounted at /config/
+ENTRYPOINT ["/app/docker-entrypoint.sh"]
+CMD ["run", "--config", "/config/config.yaml", "--log_level", "INFO"]

homesec-1.0.0/Makefile

@@ -0,0 +1,98 @@
+SHELL := /bin/bash
+.SHELLFLAGS := -eu -o pipefail -c
+
+.PHONY: help up down docker-build docker-push run db test typecheck lint check db-migrate db-migration publish
+
+help:
+	@echo "Targets:"
+	@echo ""
+	@echo "  Docker:"
+	@echo "    make up            Start HomeSec + Postgres"
+	@echo "    make down          Stop all services"
+	@echo "    make docker-build  Build Docker image"
+	@echo "    make docker-push   Push to DockerHub"
+	@echo ""
+	@echo "  Local dev:"
+	@echo "    make run           Run HomeSec locally (requires Postgres)"
+	@echo "    make db            Start just Postgres"
+	@echo "    make test          Run tests"
+	@echo "    make typecheck     Run mypy"
+	@echo "    make lint          Run ruff linter"
+	@echo "    make check         Run lint + typecheck + test"
+	@echo ""
+	@echo "  Database:"
+	@echo "    make db-migrate    Run migrations"
+	@echo "    make db-migration m=\"description\"  Generate new migration"
+	@echo ""
+	@echo "  Release:"
+	@echo "    make publish       Build and upload to PyPI"
+
+# Config
+HOMESEC_CONFIG ?= config/config.yaml
+HOMESEC_LOG_LEVEL ?= INFO
+DOCKER_IMAGE ?= homesec
+DOCKER_TAG ?= latest
+DOCKERHUB_USER ?= $(shell echo $${DOCKERHUB_USER:-})
+
+# Docker
+up:
+	docker compose up -d --build
+
+down:
+	docker compose down
+
+docker-build:
+	docker build -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+docker-push: docker-build
+	@if [ -z "$(DOCKERHUB_USER)" ]; then \
+		echo "Error: DOCKERHUB_USER not set. Run: export DOCKERHUB_USER=yourusername"; \
+		exit 1; \
+	fi
+	docker tag $(DOCKER_IMAGE):$(DOCKER_TAG) $(DOCKERHUB_USER)/$(DOCKER_IMAGE):$(DOCKER_TAG)
+	docker tag $(DOCKER_IMAGE):$(DOCKER_TAG) $(DOCKERHUB_USER)/$(DOCKER_IMAGE):latest
+	docker push $(DOCKERHUB_USER)/$(DOCKER_IMAGE):$(DOCKER_TAG)
+	docker push $(DOCKERHUB_USER)/$(DOCKER_IMAGE):latest
+
+# Local dev
+run:
+	@echo "Running database migrations..."
+	@uv run alembic -c alembic.ini upgrade head
+	uv run python -m homesec.cli run --config $(HOMESEC_CONFIG) --log_level $(HOMESEC_LOG_LEVEL)
+
+db:
+	docker compose up -d postgres
+
+test:
+	uv run pytest tests/homesec/ -v
+
+typecheck:
+	uv run mypy --package homesec --strict
+
+lint:
+	uv run ruff check src tests
+	uv run ruff format --check src tests
+
+lint-fix:
+	uv run ruff check --fix src tests
+	uv run ruff format src tests
+
+check: lint typecheck test
+
+# Database
+db-migrate:
+	uv run --with alembic --with sqlalchemy --with asyncpg --with python-dotenv alembic -c alembic.ini upgrade head
+
+db-migration:
+	@if [ -z "$(m)" ]; then \
+		echo "Error: message required. Run: make db-migration m=\"your description\""; \
+		exit 1; \
+	fi
+	uv run --with alembic --with sqlalchemy --with asyncpg --with python-dotenv alembic -c alembic.ini revision --autogenerate -m "$(m)"
+
+# Release
+publish: check
+	rm -rf dist build
+	uv run --with build python -m build
+	uv run --with twine python -m twine check dist/*
+	uv run --with twine python -m twine upload dist/*

{homesec-0.1.0 → homesec-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: homesec
-Version: 0.1.0
+Version: 1.0.0
 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
@@ -247,11 +247,9 @@ Description-Content-Type: text/markdown
 [![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/)
 
-HomeSec is a pluggable, async pipeline for home security cameras. It records
-short clips, runs object detection, optionally calls a vision-language model
-(VLM) for a structured summary, and sends alerts via MQTT or email. The design
-leans toward reliability: clips land on disk first, state/event writes are
-best-effort, and non-critical stages can fail without losing the alert.
+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.
+
+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) for a structured summary, and sends alerts via MQTT or email. The design leans toward reliability: clips land on disk first, state/event writes are best-effort, and non-critical stages can fail without losing the alert.
 
 ## Highlights
 
@@ -261,6 +259,7 @@ best-effort, and non-critical stages can fail without losing the alert.
 - 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
@@ -277,32 +276,42 @@ ClipSource -> (Upload + Filter) -> VLM (optional) -> Alert Policy -> Notifier(s)
 
 ### Requirements
 
-- Python 3.10+ (newest available is best; 3.14 is fine if your deps support it)
-- ffmpeg in PATH (required for RTSP source)
-- Postgres for state/events (`make db-up` starts a local instance). The pipeline
-  continues if the DB is down, but a DSN is still required.
+- Docker and Docker Compose
 - Optional: MQTT broker, Dropbox credentials, OpenAI-compatible API key
 
 ### Setup
 
-1. Install dependencies:
-   `uv sync`
-2. Create a config file:
-   - Start from `config/example.yaml` or `config/sample.yaml`
-3. Set environment variables (use `.env.example` as a template):
-   `cp .env.example .env`
-4. Start Postgres:
-   `make db-up`
-5. Validate config:
-   `uv run python -m homesec.cli validate --config config/example.yaml`
-6. Run:
-   `uv run python -m homesec.cli run --config config/example.yaml --log_level INFO`
-
-Tip: `make homesec` loads `.env` and runs `config/production.yaml`.
+1. Create a config file:
+   ```bash
+   cp config/example.yaml config/config.yaml
+   # Edit config/config.yaml with your settings
+   ```
+2. Set environment variables:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your credentials
+   ```
+3. Start HomeSec + Postgres:
+   ```bash
+   make up
+   ```
+4. Stop:
+   ```bash
+   make down
+   ```
+
+### Running without Docker
+
+If you prefer to run locally:
+
+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. Start with any file in `config/`.
+Configs are YAML and validated with Pydantic. See `config/example.yaml` for all options.
 
 Minimal example (RTSP + Dropbox + MQTT):
 
@@ -362,8 +371,8 @@ per_camera_alert:
 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`, `bird`, `cat`, `dog`, `horse`, `sheep`, `cow`,
-  `elephant`, `bear`, `zebra`, `giraffe`.
+- Built-in YOLO classes: `person`, `car`, `truck`, `motorcycle`, `bicycle`,
+  `dog`, `cat`, `bird`, `backpack`, `handbag`, `suitcase`.
 - Local storage for development:
 
 ```yaml
@@ -377,14 +386,35 @@ storage:
 - 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/example.yaml --log_level INFO`
+  `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/example.yaml`
+  `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/example.yaml --older_than_days 7 --dry_run True`
+  `uv run python -m homesec.cli cleanup --config config/config.yaml --older_than_days 7 --dry_run True`
 
 ## Built-in plugins
 
@@ -399,6 +429,11 @@ storage:
 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
@@ -430,7 +465,7 @@ my_filters = "my_package.filters.custom"
 
 - 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-up`
+  - Start local DB: `make db`
   - Run migrations: `make db-migrate`
 
 ## Development