inky-image-display-shared 0.2.0__tar.gz

inky_image_display_shared-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: inky-image-display-shared
+Version: 0.2.0
+Summary: Shared models and schemas for Inky Image Display services.
+Author: stkr22
+Author-email: stkr22 <stkr22@github.com>
+License-Expression: GPL-3.0-only
+Requires-Dist: pydantic~=2.12.5
+Requires-Dist: sqlmodel~=0.0.38
+Requires-Python: >=3.12, <3.14

inky_image_display_shared-0.2.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "inky-image-display-shared"
+version = "0.2.0"
+description = "Shared models and schemas for Inky Image Display services."
+authors = [
+    { name = "stkr22", email = "stkr22@github.com" }
+]
+license = "GPL-3.0-only"
+requires-python = ">=3.12,<3.14"
+dependencies = [
+    "pydantic~=2.12.5",
+    "sqlmodel~=0.0.38",
+]

inky_image_display_shared-0.2.0/src/inky_image_display_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared models and schemas for Inky Image Display services."""

inky_image_display_shared-0.2.0/src/inky_image_display_shared/models/__init__.py

@@ -0,0 +1,13 @@
+"""SQLModel database models for Inky Image Display."""
+
+from .device import Device, DeviceDisplayState
+from .image import Image
+from .immich_sync_job import ImmichSyncJob, SyncStrategy
+
+__all__ = [
+    "Device",
+    "DeviceDisplayState",
+    "Image",
+    "ImmichSyncJob",
+    "SyncStrategy",
+]

inky_image_display_shared-0.2.0/src/inky_image_display_shared/models/device.py

@@ -0,0 +1,71 @@
+"""Device display state model for Inky displays."""
+
+from datetime import datetime
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, SQLModel
+
+
+class DeviceDisplayState(SQLModel, table=True):
+    """Legacy display state for a device.
+
+    Used by the skill package. New services should use the ``Device`` model
+    instead.
+
+    Attributes:
+        global_device_id: Primary key (UUID, previously FK to global_devices)
+        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)
+    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")
+
+
+class Device(SQLModel, table=True):
+    """API-managed device record.
+
+    Replaces the combination of GlobalDevice + DeviceDisplayState for the API
+    service. The skill continues to use DeviceDisplayState + GlobalDevice
+    unchanged.
+
+    Attributes:
+        id: Unique identifier
+        device_id: String device identifier (e.g. 'inky-kitchen')
+        room: Room where device is located
+        display_width: Display width in pixels
+        display_height: Display height in pixels
+        display_orientation: Display orientation
+        display_model: Display hardware model
+        is_online: Whether device is currently connected
+        current_image_id: Currently displayed image
+        displayed_since: When current image was displayed
+        scheduled_next_at: When to show next image
+        created_at: When record was created
+        updated_at: When record was last updated
+
+    """
+
+    __tablename__ = "devices"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    device_id: str = Field(unique=True, index=True, description="Device string identifier, e.g. 'inky-kitchen'")
+    room: str | None = Field(default=None)
+    display_width: int = Field(default=1600)
+    display_height: int = Field(default=1200)
+    display_orientation: str = Field(default="landscape")
+    display_model: str = Field(default="inky_impression_13_spectra6")
+    is_online: bool = Field(default=False)
+    current_image_id: UUID | None = Field(default=None, foreign_key="images.id")
+    displayed_since: datetime | None = Field(default=None)
+    scheduled_next_at: datetime = Field(default_factory=datetime.now)
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)

inky_image_display_shared-0.2.0/src/inky_image_display_shared/models/image.py

@@ -0,0 +1,64 @@
+"""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=5, description="Priority weight for selection (higher = more likely)")
+
+    # Image dimensions and orientation 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")
+    is_portrait: bool = Field(default=False, description="True if image is portrait-oriented (height > width)")
+
+    # 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")

inky_image_display_shared-0.2.0/src/inky_image_display_shared/models/immich_sync_job.py

@@ -0,0 +1,117 @@
+"""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(enum.StrEnum):
+    """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)
+        min_vibrancy_score: Minimum vibrancy (saturation/contrast) for e-ink (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="devices.id",
+        description="Device this job syncs for. Display dimensions from the device record.",
+    )
+
+    # 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 filters
+    min_color_score: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Minimum color compatibility score for Spectra 6 palette",
+    )
+    min_vibrancy_score: float = Field(
+        default=0.2,
+        ge=0.0,
+        le=1.0,
+        description="Minimum vibrancy score (saturation or contrast) for e-ink suitability",
+    )
+
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.now, description="When created")
+    updated_at: datetime = Field(default_factory=datetime.now, description="When last updated")

inky_image_display_shared-0.2.0/src/inky_image_display_shared/schemas/__init__.py

@@ -0,0 +1,17 @@
+"""Pydantic schemas for inter-service communication."""
+
+from .commands import (
+    DeviceAcknowledge,
+    DeviceRegistration,
+    DisplayCommand,
+    DisplayInfo,
+    RegistrationResponse,
+)
+
+__all__ = [
+    "DeviceAcknowledge",
+    "DeviceRegistration",
+    "DisplayCommand",
+    "DisplayInfo",
+    "RegistrationResponse",
+]

inky_image_display_shared-0.2.0/src/inky_image_display_shared/schemas/commands.py

@@ -0,0 +1,59 @@
+"""Command and response schemas for device communication.
+
+These models define the contract between skill/API and device controllers.
+Used for both MQTT and WebSocket communication.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class DisplayInfo(BaseModel):
+    """Display hardware characteristics sent during device registration."""
+
+    width: int = Field(default=1600, description="Display width in pixels")
+    height: int = Field(default=1200, description="Display height in pixels")
+    orientation: Literal["landscape", "portrait"] = Field(default="landscape", description="Display orientation")
+    model: str = Field(default="inky_impression_13_spectra6", description="Display model identifier")
+
+
+class DeviceRegistration(BaseModel):
+    """Device registration payload.
+
+    Sent by the device on startup to announce itself.
+    """
+
+    device_id: str = Field(description="Unique device identifier")
+    display: DisplayInfo = Field(default_factory=DisplayInfo, description="Display hardware characteristics")
+    room: str | None = Field(default=None, description="Room where device is located")
+
+
+class RegistrationResponse(BaseModel):
+    """Response sent after successful device registration."""
+
+    status: Literal["registered", "updated"] = Field(description="Registration result")
+    s3_endpoint: str = Field(description="S3 server endpoint")
+    s3_bucket: str = Field(description="Bucket containing images")
+    s3_access_key: str = Field(description="Read-only access key")
+    s3_secret_key: str = Field(description="Read-only secret key")
+    s3_secure: bool = Field(default=False, description="Use HTTPS for S3")
+    s3_region: str | None = Field(default=None, description="S3 region")
+
+
+class DisplayCommand(BaseModel):
+    """Command sent to device to control the display."""
+
+    action: Literal["display", "clear", "status"] = Field(description="Command action")
+    image_path: str | None = Field(default=None, description="S3 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):
+    """Acknowledgment sent by device after processing a command."""
+
+    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="Whether the display change was successful")
+    error: str | None = Field(default=None, description="Error message if any")