private-assistant-picture-display-skill 0.4.1__py3-none-any.whl

private_assistant_picture_display_skill/main.py

@@ -0,0 +1,152 @@
+"""CLI entrypoint for the Picture Display Skill."""
+
+import asyncio
+import pathlib
+from typing import Annotated
+
+import jinja2
+import sqlalchemy
+import typer
+from private_assistant_commons import (
+    MqttConfig,
+    create_skill_engine,
+    mqtt_connection_handler,
+    skill_config,
+    skill_logger,
+)
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from private_assistant_picture_display_skill.config import PictureSkillConfig
+from private_assistant_picture_display_skill.immich import ImmichSyncService
+from private_assistant_picture_display_skill.models.device import DeviceDisplayState
+from private_assistant_picture_display_skill.models.image import Image
+from private_assistant_picture_display_skill.models.immich_sync_job import ImmichSyncJob
+from private_assistant_picture_display_skill.picture_skill import PictureSkill
+
+app = typer.Typer(help="Picture Display Skill for Inky e-ink devices")
+
+
+@app.command()
+def main(config_path: Annotated[pathlib.Path, typer.Argument(envvar="PRIVATE_ASSISTANT_CONFIG_PATH")]) -> None:
+    """Run the Picture Display Skill.
+
+    Args:
+        config_path: Path to YAML configuration file or directory
+    """
+    asyncio.run(start_skill(config_path))
+
+
+async def start_skill(config_path: pathlib.Path) -> None:
+    """Start the Picture Display Skill with all required services.
+
+    Args:
+        config_path: Path to YAML configuration file or directory
+    """
+    # Set up logger early on
+    logger = skill_logger.SkillLogger.get_logger("Private Assistant PictureSkill")
+
+    # Load configuration from YAML
+    config_obj = skill_config.load_config(config_path, PictureSkillConfig)
+
+    # Create async database engine with connection pooling and resilience
+    # AIDEV-NOTE: create_skill_engine uses PostgresConfig from env (POSTGRES_*) and adds pool_pre_ping, pool_recycle
+    db_engine_async = create_skill_engine()
+
+    # Create only skill-specific tables, not all SQLModel metadata
+    # AIDEV-NOTE: Global device registry tables are managed by BaseSkill and commons
+    async with db_engine_async.begin() as conn:
+        # __table__ is a SQLAlchemy runtime attribute that mypy doesn't recognize
+        for table in [Image.__table__, DeviceDisplayState.__table__]:  # type: ignore[attr-defined]
+            await conn.run_sync(table.create, checkfirst=True)
+
+    logger.info("Database tables initialized for Picture Display Skill")
+
+    # Set up Jinja2 template environment
+    template_env = jinja2.Environment(
+        loader=jinja2.PackageLoader("private_assistant_picture_display_skill", "templates"),
+        autoescape=True,
+    )
+
+    # Start the skill using the async MQTT connection handler
+    # AIDEV-NOTE: mqtt_connection_handler manages MQTT lifecycle with auto-reconnect
+    mqtt_config = MqttConfig()
+    await mqtt_connection_handler.mqtt_connection_handler(
+        PictureSkill,
+        config_obj,
+        mqtt_config=mqtt_config,
+        retry_interval=5,
+        logger=logger,
+        template_env=template_env,
+        engine=db_engine_async,
+    )
+
+
+@app.command()
+def immich_sync(
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show jobs that would be synced")] = False,
+) -> None:
+    """Sync images from Immich to local storage.
+
+    Executes all active sync jobs from the database. Each job defines filters
+    and selection criteria for fetching images from Immich.
+
+    Configuration is via environment variables:
+    - IMMICH_BASE_URL: Immich server URL
+    - IMMICH_API_KEY: API key for authentication
+    - MINIO_WRITER_*: MinIO connection for image storage
+    - POSTGRES_*: Database connection (from commons)
+    """
+    results = asyncio.run(run_immich_sync(dry_run))
+    typer.Exit(code=results)
+
+
+async def run_immich_sync(dry_run: bool) -> int:
+    """Run the Immich sync operation for all active jobs.
+
+    Args:
+        dry_run: If True, only show what would be synced
+
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    logger = skill_logger.SkillLogger.get_logger("Immich Sync")
+
+    # Create database engine
+    db_engine = create_skill_engine()
+
+    # Ensure required tables exist
+    async with db_engine.begin() as conn:
+        for table in [Image.__table__, ImmichSyncJob.__table__]:  # type: ignore[attr-defined]
+            await conn.run_sync(table.create, checkfirst=True)
+
+    if dry_run:
+        async with AsyncSession(db_engine) as session:
+            stmt = select(ImmichSyncJob).where(ImmichSyncJob.is_active == sqlalchemy.true())
+            db_result = await session.exec(stmt)
+            jobs = list(db_result.all())
+
+        if not jobs:
+            logger.warning("No active sync jobs found")
+            return 0
+
+        logger.info("Dry run mode - would process %d job(s):", len(jobs))
+        for job in jobs:
+            logger.info("  - %s: strategy=%s, count=%d", job.name, job.strategy, job.count)
+        return 0
+
+    # Run sync for all active jobs
+    sync_service = ImmichSyncService(
+        engine=db_engine,
+        logger=logger,
+    )
+
+    results = await sync_service.sync_all_active_jobs()
+
+    # Return non-zero exit code if any job had errors
+    has_errors = any(not r.success for r in results.values())
+    return 1 if has_errors else 0
+
+
+if __name__ == "__main__":
+    app()

private_assistant_picture_display_skill/models/__init__.py

@@ -0,0 +1,24 @@
+"""Database models and command schemas for the Picture Display Skill."""
+
+from .commands import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+from .device import DeviceDisplayState
+from .image import Image
+from .immich_sync_job import ImmichSyncJob, SyncStrategy
+
+__all__ = [
+    "DeviceAcknowledge",
+    "DeviceDisplayState",
+    "DeviceRegistration",
+    "DisplayCommand",
+    "DisplayInfo",
+    "Image",
+    "ImmichSyncJob",
+    "RegistrationResponse",
+    "SyncStrategy",
+]

private_assistant_picture_display_skill/models/commands.py

@@ -0,0 +1,63 @@
+"""MQTT command and response models for device communication."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class DisplayInfo(BaseModel):
+    """Display characteristics sent during device registration."""
+
+    width: int = Field(description="Display width in pixels")
+    height: int = Field(description="Display height in pixels")
+    orientation: Literal["landscape", "portrait"] = Field(description="Display orientation")
+    model: str | None = Field(default=None, description="Display model identifier")
+
+
+class DeviceRegistration(BaseModel):
+    """Device registration payload from Pi agent.
+
+    Sent to topic: inky/register
+    """
+
+    device_id: str = Field(description="Unique device identifier")
+    display: DisplayInfo = Field(description="Display characteristics")
+    room: str | None = Field(default=None, description="Room where device is located")
+
+
+class RegistrationResponse(BaseModel):
+    """Response sent after successful device registration.
+
+    Sent to topic: inky/{device_id}/registered
+    """
+
+    status: Literal["registered", "updated"] = Field(description="Registration result")
+    minio_endpoint: str = Field(description="MinIO server endpoint")
+    minio_bucket: str = Field(description="Bucket containing images")
+    minio_access_key: str = Field(description="Read-only access key")
+    minio_secret_key: str = Field(description="Read-only secret key")
+    minio_secure: bool = Field(default=False, description="Use HTTPS for MinIO")
+
+
+class DisplayCommand(BaseModel):
+    """Command sent to device to display an image.
+
+    Sent to topic: inky/{device_id}/command
+    """
+
+    action: Literal["display", "clear", "status"] = Field(description="Command action")
+    image_path: str | None = Field(default=None, description="MinIO object path for display action")
+    image_id: str | None = Field(default=None, description="Image UUID for tracking")
+    title: str | None = Field(default=None, description="Image title for device logging")
+
+
+class DeviceAcknowledge(BaseModel):
+    """Acknowledge after DisplayCommand from device.
+
+    Sent to topic: inky/{device_id}/status
+    """
+
+    device_id: str = Field(description="Device identifier")
+    image_id: str | None = Field(default=None, description="Currently displayed image UUID")
+    successful_display_change: bool = Field(description="Was display change successful?")
+    error: str | None = Field(default=None, description="Error message if any")

private_assistant_picture_display_skill/models/device.py

@@ -0,0 +1,30 @@
+"""Device display state model for Inky displays."""
+
+from datetime import datetime
+from uuid import UUID
+
+from sqlmodel import Field, SQLModel
+
+
+class DeviceDisplayState(SQLModel, table=True):
+    """Current display state for a device.
+
+    Tracks what image is currently displayed, online status, and scheduling
+    information for automatic image rotation. Links to GlobalDevice from
+    commons via global_device_id.
+
+    Attributes:
+        global_device_id: Foreign key to global_devices.id
+        is_online: Whether device is currently reachable
+        current_image_id: Currently displayed image (nullable)
+        displayed_since: When current image was displayed
+        scheduled_next_at: When to show next image
+    """
+
+    __tablename__ = "device_display_states"
+
+    global_device_id: UUID = Field(primary_key=True, foreign_key="global_devices.id")
+    is_online: bool = Field(default=True, description="Whether device is currently reachable")
+    current_image_id: UUID | None = Field(default=None, foreign_key="images.id")
+    displayed_since: datetime | None = Field(default=None, description="When current image was displayed")
+    scheduled_next_at: datetime = Field(default_factory=datetime.now, description="Scheduled time for next image")

private_assistant_picture_display_skill/models/image.py

@@ -0,0 +1,62 @@
+"""Image model for storing picture metadata."""
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, SQLModel
+
+
+class Image(SQLModel, table=True):
+    """Image metadata stored in the database.
+
+    Images are fetched from various sources (manual upload, Immich, Unsplash, etc.)
+    and stored in MinIO. This table tracks metadata for display scheduling and
+    voice command responses.
+
+    Attributes:
+        id: Unique identifier for the image
+        source_name: Source identifier (e.g., "manual", "immich", "unsplash")
+        storage_path: Path to image in MinIO bucket
+        title: Optional title for voice responses
+        description: Optional description for "what am I seeing?" queries
+        author: Optional author/photographer name
+        source_url: Optional URL to original source
+        display_duration_seconds: How long to show this image (default 3600)
+        priority: Weight for future priority-based selection (default 0)
+        original_width: Image width in pixels
+        original_height: Image height in pixels
+        last_displayed_at: When the image was last shown (for FIFO selection)
+        expires_at: Optional expiration time for auto-cleanup
+        created_at: When record was created (replaces fetched_at)
+        updated_at: When record was last updated
+        tags: Comma-separated tags for categorization
+    """
+
+    __tablename__ = "images"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    source_name: str = Field(index=True, description="Source identifier (e.g. manual, unsplash)")
+    storage_path: str = Field(description="MinIO object path")
+
+    # Metadata for voice responses
+    title: str | None = Field(default=None, description="Image title for voice responses")
+    description: str | None = Field(default=None, description="Description for 'what am I seeing?'")
+    author: str | None = Field(default=None, description="Author/photographer name")
+    source_url: str | None = Field(default=None, description="Original source URL")
+
+    # Display settings
+    display_duration_seconds: int = Field(default=600, description="Display duration in seconds")
+    priority: int = Field(default=0, description="Priority weight for selection (higher = more likely)")
+
+    # Image dimensions for device compatibility
+    original_width: int | None = Field(default=None, description="Image width in pixels")
+    original_height: int | None = Field(default=None, description="Image height in pixels")
+
+    # Timestamps
+    last_displayed_at: datetime | None = Field(default=None, description="Last display time for FIFO")
+    expires_at: datetime | None = Field(default=None, description="Expiration time for cleanup")
+    created_at: datetime = Field(default_factory=datetime.now, description="When record was created")
+    updated_at: datetime = Field(default_factory=datetime.now, description="When record was last updated")
+
+    # Categorization
+    tags: str | None = Field(default=None, description="Comma-separated tags for categorization")

private_assistant_picture_display_skill/models/immich_sync_job.py

@@ -0,0 +1,109 @@
+"""Immich sync job configuration model."""
+
+import enum
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import Column
+from sqlalchemy.types import JSON
+from sqlmodel import Field, SQLModel
+
+
+class SyncStrategy(str, enum.Enum):
+    """Strategy for selecting images from Immich.
+
+    Values are uppercase to match PostgreSQL enum labels created by SQLAlchemy.
+    """
+
+    RANDOM = "RANDOM"
+    SMART = "SMART"  # CLIP semantic search
+
+
+class ImmichSyncJob(SQLModel, table=True):
+    """Immich sync job configuration stored in database.
+
+    Each job defines a set of filters and selection criteria for syncing
+    images from Immich. Jobs can be activated/deactivated and target
+    specific devices to determine display requirements.
+
+    Attributes:
+        id: Unique job identifier
+        name: Human-readable job name (unique)
+        is_active: Whether job should be executed during sync
+        target_device_id: Device this job syncs for (determines dimensions/orientation)
+        strategy: Selection strategy - 'random' or 'smart' (CLIP search)
+        query: Semantic search query (required for 'smart' strategy)
+        count: Number of images to sync per run
+        random_pick: Randomly sample from smart search results
+        overfetch_multiplier: Fetch more images to allow for client-side filtering
+        album_ids: Filter by album UUIDs
+        person_ids: Filter by recognized person UUIDs
+        tag_ids: Filter by tag UUIDs
+        is_favorite: Filter favorites only
+        city: Filter by city name
+        state: Filter by state/region
+        country: Filter by country
+        taken_after: Photos taken after this date
+        taken_before: Photos taken before this date
+        make: Camera make filter
+        camera_model: Camera model filter
+        rating: Minimum rating filter (0-5)
+        min_color_score: Minimum color compatibility for Spectra 6 (0.0-1.0)
+    """
+
+    __tablename__ = "immich_sync_jobs"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    name: str = Field(unique=True, index=True, description="Unique job name")
+    is_active: bool = Field(default=True, description="Whether job is active")
+
+    # Target device - determines display requirements (width, height, orientation)
+    target_device_id: UUID = Field(
+        foreign_key="global_devices.id",
+        description="Device this job syncs for. Display requirements from device_attributes.",
+    )
+
+    # Selection strategy
+    strategy: SyncStrategy = Field(
+        default=SyncStrategy.RANDOM,
+        description="Selection strategy: 'random' or 'smart' (CLIP semantic search)",
+    )
+    query: str | None = Field(
+        default=None,
+        description="Semantic search query for 'smart' strategy",
+    )
+    count: int = Field(default=10, ge=1, le=1000, description="Images to sync per run")
+    random_pick: bool = Field(
+        default=False,
+        description="Randomly sample from smart search results",
+    )
+    overfetch_multiplier: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Multiplier for overfetching when client-side filters active",
+    )
+
+    # API filters (stored as JSON for list types)
+    album_ids: list[str] | None = Field(default=None, sa_column=Column(JSON))
+    person_ids: list[str] | None = Field(default=None, sa_column=Column(JSON))
+    tag_ids: list[str] | None = Field(default=None, sa_column=Column(JSON))
+    is_favorite: bool | None = Field(default=None, description="Filter favorites only")
+    city: str | None = Field(default=None, description="Filter by city")
+    state: str | None = Field(default=None, description="Filter by state/region")
+    country: str | None = Field(default=None, description="Filter by country")
+    taken_after: datetime | None = Field(default=None, description="Photos taken after")
+    taken_before: datetime | None = Field(default=None, description="Photos taken before")
+    rating: int | None = Field(default=None, ge=0, le=5, description="Minimum rating")
+
+    # Client-side filter
+    min_color_score: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Minimum color compatibility score for Spectra 6 palette",
+    )
+
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.now, description="When created")
+    updated_at: datetime = Field(default_factory=datetime.now, description="When last updated")