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

private_assistant_picture_display_skill/__init__.py

@@ -0,0 +1,15 @@
+"""Skill to dynamically display images from various sources via external agents."""
+
+from private_assistant_picture_display_skill.config import (
+    DeviceMqttConfig,
+    MinioConfig,
+    PictureSkillConfig,
+)
+from private_assistant_picture_display_skill.picture_skill import PictureSkill
+
+__all__ = [
+    "DeviceMqttConfig",
+    "MinioConfig",
+    "PictureSkill",
+    "PictureSkillConfig",
+]

private_assistant_picture_display_skill/config.py

@@ -0,0 +1,61 @@
+"""Configuration for the Picture Display Skill."""
+
+from private_assistant_commons import SkillConfig
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DeviceMqttConfig(BaseSettings):
+    """Configuration for the authenticated device MQTT broker.
+
+    Loads from environment variables with DEVICE_MQTT_ prefix:
+    - DEVICE_MQTT_HOST (default: localhost)
+    - DEVICE_MQTT_PORT (default: 1883)
+    - DEVICE_MQTT_USERNAME (required)
+    - DEVICE_MQTT_PASSWORD (required)
+    """
+
+    model_config = SettingsConfigDict(env_prefix="DEVICE_MQTT_")
+
+    host: str = Field(description="Device MQTT broker host")
+    port: int = Field(description="Device MQTT broker port")
+    username: str = Field(description="Device MQTT username for authentication")
+    password: str = Field(description="Device MQTT password for authentication")
+
+
+class MinioConfig(BaseSettings):
+    """Configuration for MinIO image storage.
+
+    Loads from environment variables with MINIO_ prefix:
+    - MINIO_ENDPOINT (default: localhost:9000)
+    - MINIO_BUCKET (default: inky-images)
+    - MINIO_SECURE (default: false)
+    - MINIO_READER_ACCESS_KEY (required)
+    - MINIO_READER_SECRET_KEY (required)
+    """
+
+    model_config = SettingsConfigDict(env_prefix="MINIO_")
+
+    endpoint: str = Field(description="MinIO server endpoint")
+    bucket: str = Field(default="inky-images", description="Bucket for image storage")
+    secure: bool = Field(default=False, description="Use HTTPS for MinIO connection")
+    reader_access_key: str = Field(description="Access key for device read access")
+    reader_secret_key: str = Field(description="Secret key for device read access")
+
+
+class PictureSkillConfig(SkillConfig):
+    """Extended configuration for Picture Display Skill.
+
+    Inherits MQTT configuration from SkillConfig and adds:
+    - Default display duration for images
+    - Device timeout for online status tracking
+    """
+
+    default_display_duration: int = Field(
+        default=3600,
+        description="Default image display duration in seconds",
+    )
+    device_timeout_seconds: int = Field(
+        default=120,
+        description="Seconds without heartbeat before device marked offline",
+    )

private_assistant_picture_display_skill/immich/__init__.py

@@ -0,0 +1,20 @@
+"""Immich integration for fetching images from self-hosted Immich instances."""
+
+from private_assistant_picture_display_skill.immich.client import ImmichClient
+from private_assistant_picture_display_skill.immich.config import (
+    DeviceRequirements,
+    ImmichConnectionConfig,
+    ImmichSyncConfig,
+    MinioWriterConfig,
+)
+from private_assistant_picture_display_skill.immich.sync_service import ImmichSyncService, SyncResult
+
+__all__ = [
+    "DeviceRequirements",
+    "ImmichClient",
+    "ImmichConnectionConfig",
+    "ImmichSyncConfig",
+    "ImmichSyncService",
+    "MinioWriterConfig",
+    "SyncResult",
+]

private_assistant_picture_display_skill/immich/client.py

@@ -0,0 +1,250 @@
+"""Async HTTP client for Immich API."""
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from private_assistant_picture_display_skill.immich.config import ImmichConnectionConfig
+from private_assistant_picture_display_skill.immich.models import (
+    AlbumsResponse,
+    ImmichAlbum,
+    ImmichAsset,
+    RandomSearchResponse,
+    SmartSearchResponse,
+)
+from private_assistant_picture_display_skill.immich.payloads import RandomSearchPayload, SmartSearchPayload
+from private_assistant_picture_display_skill.models.immich_sync_job import ImmichSyncJob
+
+
+class ImmichClientError(Exception):
+    """Base exception for Immich client errors."""
+
+
+class ImmichAuthError(ImmichClientError):
+    """Authentication failed."""
+
+
+class ImmichNotFoundError(ImmichClientError):
+    """Resource not found."""
+
+
+class ImmichClient:
+    """Async client for Immich REST API.
+
+    Handles authentication, request/response serialization, and error handling.
+    Uses httpx for async HTTP with connection pooling.
+    """
+
+    def __init__(
+        self,
+        config: ImmichConnectionConfig,
+        logger: logging.Logger,
+    ) -> None:
+        """Initialize the Immich client.
+
+        Args:
+            config: Connection configuration (includes api_key)
+            logger: Logger instance
+        """
+        self.base_url = str(config.base_url).rstrip("/")
+        self.timeout = config.timeout_seconds
+        self.verify_ssl = config.verify_ssl
+        self.api_key = config.api_key
+        self.logger = logger
+        self._client: httpx.AsyncClient | None = None
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator["ImmichClient"]:
+        """Context manager for HTTP client lifecycle."""
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"x-api-key": self.api_key},
+            timeout=httpx.Timeout(self.timeout),
+            verify=self.verify_ssl,
+        )
+        try:
+            yield self
+        finally:
+            await self._client.aclose()
+            self._client = None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make an authenticated request to Immich API."""
+        if self._client is None:
+            raise RuntimeError("Client not connected. Use async with client.connect():")
+
+        response = await self._client.request(method, path, **kwargs)
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise ImmichAuthError("Invalid API key")
+        if response.status_code == HTTPStatus.NOT_FOUND:
+            raise ImmichNotFoundError(f"Resource not found: {path}")
+
+        response.raise_for_status()
+        return response
+
+    async def search_random(
+        self,
+        job: ImmichSyncJob,
+        count_override: int | None = None,
+    ) -> list[ImmichAsset]:
+        """Fetch random assets matching job criteria.
+
+        Args:
+            job: Sync job with filter configuration
+            count_override: Override job.count (for overfetching with client-side filters)
+
+        Returns:
+            List of matching assets
+        """
+        payload = self._build_random_payload(job, count_override)
+        body = payload.model_dump(by_alias=True, exclude_none=True)
+        self.logger.debug("Searching random assets with filters: %s", body)
+
+        response = await self._request("POST", "/api/search/random", json=body)
+        return RandomSearchResponse.model_validate(response.json()).root
+
+    async def search_smart(
+        self,
+        job: ImmichSyncJob,
+        count_override: int | None = None,
+        enrich_with_people: bool = True,
+    ) -> list[ImmichAsset]:
+        """Fetch assets matching semantic query with filters (CLIP-based).
+
+        Note: Smart search doesn't support withPeople parameter. If enrich_with_people
+        is True, we fetch full asset details for each result to include people data.
+
+        Args:
+            job: Sync job with filter configuration (must have query set)
+            count_override: Override job.count (for overfetching with client-side filters)
+            enrich_with_people: Fetch full details to include people data
+
+        Returns:
+            List of matching assets ranked by semantic similarity
+
+        Raises:
+            ValueError: If job.query is not set
+        """
+        if not job.query:
+            raise ValueError("Smart search requires a query string")
+
+        payload = self._build_smart_payload(job, count_override)
+        body = payload.model_dump(by_alias=True, exclude_none=True)
+        self.logger.debug("Searching smart assets with query '%s' and filters: %s", job.query, body)
+
+        response = await self._request("POST", "/api/search/smart", json=body)
+        result = SmartSearchResponse.model_validate(response.json())
+        assets = result.assets.items
+
+        # Smart search doesn't include people data - fetch full details if needed
+        if enrich_with_people and assets:
+            self.logger.debug("Enriching %d assets with full details (people data)", len(assets))
+            enriched = []
+            for asset in assets:
+                try:
+                    full_asset = await self.get_asset(asset.id)
+                    enriched.append(full_asset)
+                except Exception:
+                    self.logger.warning("Failed to enrich asset %s, using partial data", asset.id)
+                    enriched.append(asset)
+            return enriched
+
+        return assets
+
+    def _build_random_payload(
+        self,
+        job: ImmichSyncJob,
+        count_override: int | None = None,
+    ) -> RandomSearchPayload:
+        """Build payload for random search from job config."""
+        return RandomSearchPayload(
+            size=count_override or job.count,
+            album_ids=job.album_ids,
+            person_ids=job.person_ids,
+            tag_ids=job.tag_ids,
+            is_favorite=job.is_favorite,
+            city=job.city,
+            state=job.state,
+            country=job.country,
+            taken_after=job.taken_after.isoformat() if job.taken_after else None,
+            taken_before=job.taken_before.isoformat() if job.taken_before else None,
+            rating=job.rating,
+        )
+
+    def _build_smart_payload(
+        self,
+        job: ImmichSyncJob,
+        count_override: int | None = None,
+    ) -> SmartSearchPayload:
+        """Build payload for smart search from job config."""
+        if not job.query:
+            raise ValueError("Smart search requires a query string")
+
+        return SmartSearchPayload(
+            query=job.query,
+            size=count_override or job.count,
+            album_ids=job.album_ids,
+            person_ids=job.person_ids,
+            tag_ids=job.tag_ids,
+            is_favorite=job.is_favorite,
+            city=job.city,
+            state=job.state,
+            country=job.country,
+            taken_after=job.taken_after.isoformat() if job.taken_after else None,
+            taken_before=job.taken_before.isoformat() if job.taken_before else None,
+            rating=job.rating,
+        )
+
+    async def download_original(self, asset_id: str) -> AsyncIterator[bytes]:
+        """Stream download of asset's original file.
+
+        Args:
+            asset_id: Asset UUID
+
+        Yields:
+            Chunks of file data
+        """
+        if self._client is None:
+            raise RuntimeError("Client not connected")
+
+        async with self._client.stream(
+            "GET",
+            f"/api/assets/{asset_id}/original",
+        ) as response:
+            response.raise_for_status()
+            async for chunk in response.aiter_bytes(chunk_size=8192):
+                yield chunk
+
+    async def get_asset(self, asset_id: str) -> ImmichAsset:
+        """Get full asset details including people data.
+
+        Args:
+            asset_id: Asset UUID
+
+        Returns:
+            Asset with full details including people/faces
+        """
+        response = await self._request("GET", f"/api/assets/{asset_id}")
+        return ImmichAsset.model_validate(response.json())
+
+    async def get_asset_albums(self, asset_id: str) -> list[ImmichAlbum]:
+        """Get albums containing a specific asset.
+
+        Args:
+            asset_id: Asset UUID
+
+        Returns:
+            List of albums containing this asset
+        """
+        response = await self._request("GET", "/api/albums", params={"assetId": asset_id})
+        return AlbumsResponse.model_validate(response.json()).root

private_assistant_picture_display_skill/immich/config.py

@@ -0,0 +1,94 @@
+"""Configuration models for Immich sync operations.
+
+Connection settings are loaded from environment variables.
+Sync job configuration is stored in the database (ImmichSyncJob model).
+"""
+
+from pydantic import BaseModel, Field, HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ImmichConnectionConfig(BaseSettings):
+    """Immich server connection settings from environment variables.
+
+    Environment variables:
+        IMMICH_BASE_URL: Immich server URL
+        IMMICH_API_KEY: API key for authentication
+        IMMICH_TIMEOUT_SECONDS: Request timeout (default: 30)
+        IMMICH_VERIFY_SSL: Verify SSL certificates (default: True)
+    """
+
+    model_config = SettingsConfigDict(env_prefix="IMMICH_")
+
+    base_url: HttpUrl = Field(description="Immich server base URL")
+    api_key: str = Field(description="API key for x-api-key header")
+    timeout_seconds: int = Field(default=30, description="HTTP request timeout")
+    verify_ssl: bool = Field(default=True, description="Verify SSL certificates")
+
+
+class MinioWriterConfig(BaseSettings):
+    """MinIO configuration with write access for sync operations.
+
+    Separate from MinioConfig (reader) to use different credentials.
+
+    Environment variables:
+        MINIO_WRITER_ENDPOINT: MinIO server endpoint
+        MINIO_WRITER_BUCKET: Target bucket (default: inky-images)
+        MINIO_WRITER_SECURE: Use HTTPS (default: False)
+        MINIO_WRITER_ACCESS_KEY: Access key with write permissions
+        MINIO_WRITER_SECRET_KEY: Secret key with write permissions
+    """
+
+    model_config = SettingsConfigDict(env_prefix="MINIO_WRITER_")
+
+    endpoint: str = Field(description="MinIO server endpoint")
+    bucket: str = Field(default="inky-images", description="Bucket for image storage")
+    secure: bool = Field(default=False, description="Use HTTPS for MinIO connection")
+    access_key: str = Field(description="Access key with write permissions")
+    secret_key: str = Field(description="Secret key with write permissions")
+
+
+class ImmichSyncConfig(BaseSettings):
+    """Global sync settings from environment variables.
+
+    Per-job settings (filters, counts, etc.) are stored in ImmichSyncJob table.
+
+    Environment variables:
+        IMMICH_STORAGE_PREFIX: MinIO path prefix (default: immich)
+        IMMICH_SKIP_EXISTING: Skip already synced images (default: True)
+        IMMICH_TARGET_WIDTH: Process images to this width
+        IMMICH_TARGET_HEIGHT: Process images to this height
+    """
+
+    model_config = SettingsConfigDict(env_prefix="IMMICH_")
+
+    storage_prefix: str = Field(
+        default="immich",
+        description="MinIO path prefix for stored images",
+    )
+    skip_existing: bool = Field(
+        default=True,
+        description="Skip images already in database",
+    )
+    target_width: int | None = Field(
+        default=None,
+        description="Process images to this width (None = no processing)",
+    )
+    target_height: int | None = Field(
+        default=None,
+        description="Process images to this height (None = no processing)",
+    )
+
+
+class DeviceRequirements(BaseModel):
+    """Display requirements derived from target device.
+
+    These values come from the device's device_attributes JSON field
+    in the global_devices table. All fields are required - sync jobs
+    must have a valid target device with display specifications.
+    """
+
+    width: int
+    height: int
+    orientation: str  # "landscape" | "portrait" | "square"
+    display_model: str | None = None  # e.g., "inky_impression_spectra_6"

private_assistant_picture_display_skill/immich/models.py

@@ -0,0 +1,109 @@
+"""Pydantic models for Immich API responses.
+
+All models use extra="ignore" for forward compatibility with new API fields.
+"""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+
+class ImmichExifInfo(BaseModel):
+    """EXIF metadata from Immich asset."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    city: str | None = None
+    state: str | None = None
+    country: str | None = None
+    description: str | None = None
+    date_time_original: datetime | None = Field(default=None, alias="dateTimeOriginal")
+    make: str | None = None
+    model: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    rating: int | None = None
+    exif_image_width: int | None = Field(default=None, alias="exifImageWidth")
+    exif_image_height: int | None = Field(default=None, alias="exifImageHeight")
+
+
+class ImmichPerson(BaseModel):
+    """Person recognized in an Immich asset."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    name: str | None = None
+
+
+class ImmichAsset(BaseModel):
+    """Asset response from Immich API.
+
+    Maps to AssetResponseDto from Immich OpenAPI spec.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    id: str
+    type: Literal["IMAGE", "VIDEO"]
+    original_file_name: str = Field(alias="originalFileName")
+    original_mime_type: str = Field(alias="originalMimeType")
+    checksum: str  # Base64 SHA1 for deduplication
+
+    # Timestamps
+    file_created_at: datetime = Field(alias="fileCreatedAt")
+    local_date_time: datetime | None = Field(default=None, alias="localDateTime")
+
+    # Optional metadata
+    exif_info: ImmichExifInfo | None = Field(default=None, alias="exifInfo")
+    people: list[ImmichPerson] | None = None
+    is_favorite: bool = Field(default=False, alias="isFavorite")
+
+
+class ImmichAlbum(BaseModel):
+    """Album from Immich API."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    id: str
+    album_name: str = Field(alias="albumName")
+    description: str | None = None
+    asset_count: int = Field(alias="assetCount")
+
+
+# Response wrapper models for API endpoints
+
+
+class RandomSearchResponse(RootModel[list[ImmichAsset]]):
+    """Response from POST /search/random - returns list of assets directly."""
+
+    pass
+
+
+class AlbumsResponse(RootModel[list[ImmichAlbum]]):
+    """Response from GET /albums - returns list of albums."""
+
+    pass
+
+
+class SearchAssetResponseDto(BaseModel):
+    """Assets page in smart search response."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    total: int = 0
+    count: int = 0
+    items: list[ImmichAsset] = Field(default_factory=list)
+    next_page: str | None = Field(default=None, alias="nextPage")
+
+
+class SmartSearchResponse(BaseModel):
+    """Response from POST /search/smart (SearchResponseDto).
+
+    Only models the assets field - albums is not populated for smart search.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    assets: SearchAssetResponseDto

private_assistant_picture_display_skill/immich/payloads.py

@@ -0,0 +1,55 @@
+"""Pydantic models for Immich API request payloads.
+
+Uses alias_generator for automatic snake_case to camelCase conversion,
+matching the Immich API's expected format.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class BaseSearchPayload(BaseModel):
+    """Base payload for Immich search APIs.
+
+    All fields use snake_case internally but serialize to camelCase for the API.
+    Fields set to None are excluded from the payload.
+    """
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="ignore",
+    )
+
+    size: int = Field(default=10)
+    album_ids: list[str] | None = None
+    person_ids: list[str] | None = None
+    tag_ids: list[str] | None = None
+    is_favorite: bool | None = None
+    city: str | None = None
+    state: str | None = None
+    country: str | None = None
+    taken_after: str | None = None  # ISO format string
+    taken_before: str | None = None  # ISO format string
+    rating: int | None = None
+    type: str = "IMAGE"  # Always IMAGE for this skill
+
+
+class RandomSearchPayload(BaseSearchPayload):
+    """Payload for POST /search/random endpoint.
+
+    Includes withExif and withPeople flags to get complete asset data.
+    """
+
+    with_exif: bool = True
+    with_people: bool = True
+
+
+class SmartSearchPayload(BaseSearchPayload):
+    """Payload for POST /search/smart endpoint (CLIP semantic search).
+
+    Note: Smart search doesn't support withPeople/withExif parameters.
+    Use get_asset() to fetch full details after smart search.
+    """
+
+    query: str  # Required for smart search