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

private_assistant_picture_display_skill/immich/storage.py

@@ -0,0 +1,127 @@
+"""MinIO storage utilities for Immich sync."""
+
+import logging
+from collections.abc import AsyncIterator
+from io import BytesIO
+
+from minio import Minio
+from minio.error import S3Error
+
+from private_assistant_picture_display_skill.immich.config import MinioWriterConfig
+
+
+class MinioStorageClient:
+    """MinIO client for uploading images.
+
+    Wraps the synchronous minio-py library.
+    AIDEV-NOTE: minio-py is synchronous; consider running in executor for large uploads.
+    """
+
+    def __init__(
+        self,
+        config: MinioWriterConfig,
+        logger: logging.Logger,
+    ) -> None:
+        """Initialize MinIO client.
+
+        Args:
+            config: MinIO configuration with write credentials
+            logger: Logger instance
+        """
+        self.config = config
+        self.logger = logger
+        self._client = Minio(
+            endpoint=config.endpoint,
+            access_key=config.access_key,
+            secret_key=config.secret_key,
+            secure=config.secure,
+        )
+
+    def ensure_bucket_exists(self) -> None:
+        """Create bucket if it doesn't exist."""
+        if not self._client.bucket_exists(self.config.bucket):
+            self._client.make_bucket(self.config.bucket)
+            self.logger.info("Created bucket: %s", self.config.bucket)
+
+    def object_exists(self, object_path: str) -> bool:
+        """Check if an object already exists in MinIO.
+
+        Args:
+            object_path: Full path within bucket
+
+        Returns:
+            True if object exists
+        """
+        try:
+            self._client.stat_object(self.config.bucket, object_path)
+            return True
+        except S3Error:
+            return False
+
+    async def upload_from_stream(
+        self,
+        object_path: str,
+        data_stream: AsyncIterator[bytes],
+        content_type: str,
+    ) -> str:
+        """Upload file from async byte stream.
+
+        Collects stream into memory then uploads.
+        AIDEV-NOTE: For very large files, consider chunked upload or temp file.
+
+        Args:
+            object_path: Destination path in bucket
+            data_stream: Async iterator of bytes
+            content_type: MIME type
+
+        Returns:
+            Full storage path (bucket/object_path)
+        """
+        # Collect stream into buffer
+        buffer = BytesIO()
+        async for chunk in data_stream:
+            buffer.write(chunk)
+
+        buffer.seek(0)
+        size = buffer.getbuffer().nbytes
+
+        self._client.put_object(
+            bucket_name=self.config.bucket,
+            object_name=object_path,
+            data=buffer,
+            length=size,
+            content_type=content_type,
+        )
+
+        self.logger.debug("Uploaded %s (%d bytes)", object_path, size)
+        return object_path
+
+    def upload_from_bytes(
+        self,
+        object_path: str,
+        data: bytes,
+        content_type: str,
+    ) -> str:
+        """Upload file from bytes.
+
+        Args:
+            object_path: Destination path in bucket
+            data: File content as bytes
+            content_type: MIME type
+
+        Returns:
+            Full storage path (bucket/object_path)
+        """
+        buffer = BytesIO(data)
+        size = len(data)
+
+        self._client.put_object(
+            bucket_name=self.config.bucket,
+            object_name=object_path,
+            data=buffer,
+            length=size,
+            content_type=content_type,
+        )
+
+        self.logger.debug("Uploaded %s (%d bytes)", object_path, size)
+        return object_path

private_assistant_picture_display_skill/immich/sync_service.py

@@ -0,0 +1,501 @@
+"""Immich sync service - orchestrates fetch, download, store, record workflow."""
+
+import logging
+import random
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+from uuid import UUID
+
+import sqlalchemy
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+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.models import ImmichAsset
+from private_assistant_picture_display_skill.immich.storage import MinioStorageClient
+from private_assistant_picture_display_skill.models.image import Image
+from private_assistant_picture_display_skill.models.immich_sync_job import ImmichSyncJob, SyncStrategy
+from private_assistant_picture_display_skill.utils.color_analysis import ColorProfileAnalyzer
+from private_assistant_picture_display_skill.utils.image_processing import ImageProcessor
+from private_assistant_picture_display_skill.utils.metadata_builder import MetadataBuilder
+
+
+class ProcessResult(Enum):
+    """Result of processing a single asset."""
+
+    DOWNLOADED = auto()
+    SKIPPED_EXISTING = auto()
+    SKIPPED_UNDERSIZED = auto()
+    SKIPPED_COLOR_MISMATCH = auto()
+
+
+@dataclass
+class SyncResult:
+    """Result of a sync operation."""
+
+    fetched: int = 0
+    filtered: int = 0  # After client-side filters
+    downloaded: int = 0
+    skipped_existing: int = 0
+    skipped_undersized: int = 0  # Too small for target dimensions
+    skipped_color_mismatch: int = 0  # Color profile incompatible
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def success(self) -> bool:
+        """Return True if no errors occurred."""
+        return len(self.errors) == 0
+
+    def __str__(self) -> str:
+        """Return human-readable summary."""
+        return (
+            f"SyncResult(fetched={self.fetched}, filtered={self.filtered}, "
+            f"downloaded={self.downloaded}, skipped_existing={self.skipped_existing}, "
+            f"skipped_undersized={self.skipped_undersized}, "
+            f"skipped_color={self.skipped_color_mismatch}, errors={len(self.errors)})"
+        )
+
+
+class ImmichSyncService:
+    """Orchestrates syncing images from Immich to local storage.
+
+    Workflow:
+    1. Load active sync jobs from database
+    2. For each job, fetch assets from Immich matching filters
+    3. Apply client-side filters (orientation, dimensions, color)
+    4. Download original file from Immich
+    5. Upload to MinIO with path: {prefix}/{asset_id}.{ext}
+    6. Create/update Image record in PostgreSQL
+    """
+
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        logger: logging.Logger,
+        connection_config: ImmichConnectionConfig | None = None,
+        sync_config: ImmichSyncConfig | None = None,
+        minio_config: MinioWriterConfig | None = None,
+    ) -> None:
+        """Initialize sync service.
+
+        Args:
+            engine: Async database engine
+            logger: Logger instance
+            connection_config: Immich connection settings (defaults to env vars)
+            sync_config: Global sync settings (defaults to env vars)
+            minio_config: MinIO writer config (defaults to env vars)
+        """
+        self.engine = engine
+        self.logger = logger
+
+        # Load configs from environment if not provided
+        self.connection_config = connection_config or ImmichConnectionConfig()
+        self.sync_config = sync_config or ImmichSyncConfig()
+        self.minio_config = minio_config or MinioWriterConfig()
+
+        # Initialize clients
+        self.immich = ImmichClient(
+            config=self.connection_config,
+            logger=logger,
+        )
+        self.storage = MinioStorageClient(
+            config=self.minio_config,
+            logger=logger,
+        )
+
+    async def sync_all_active_jobs(self) -> dict[str, SyncResult]:
+        """Execute all active sync jobs from database.
+
+        Returns:
+            Dict mapping job name to SyncResult
+        """
+        results: dict[str, SyncResult] = {}
+
+        async with AsyncSession(self.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:
+            self.logger.warning("No active sync jobs found in database")
+            return results
+
+        self.logger.info("Found %d active sync jobs", len(jobs))
+        self.storage.ensure_bucket_exists()
+
+        async with self.immich.connect():
+            for job in jobs:
+                self.logger.info("Processing sync job: %s", job.name)
+                try:
+                    result = await self._sync_job(job)
+                    results[job.name] = result
+                    self.logger.info("Job '%s' completed: %s", job.name, result)
+                except Exception as e:
+                    error_result = SyncResult()
+                    error_result.errors.append(f"Job failed: {e}")
+                    results[job.name] = error_result
+                    self.logger.exception("Job '%s' failed", job.name)
+
+        return results
+
+    async def _sync_job(self, job: ImmichSyncJob) -> SyncResult:
+        """Execute a single sync job.
+
+        Args:
+            job: Sync job configuration
+
+        Returns:
+            SyncResult with counts and any errors
+        """
+        result = SyncResult()
+
+        # Get device requirements (always required)
+        device_reqs = await self._get_device_requirements(job.target_device_id)
+
+        # Calculate fetch count (overfetch for client-side orientation/dimension filters)
+        fetch_count = job.count * job.overfetch_multiplier
+
+        strategy_desc = f"smart search (query='{job.query}')" if job.strategy == SyncStrategy.SMART else "random"
+        self.logger.info(
+            "Fetching %d images via %s for job '%s' (overfetch x%d for client-side filters)",
+            fetch_count,
+            strategy_desc,
+            job.name,
+            job.overfetch_multiplier,
+        )
+
+        try:
+            # Route to appropriate search method based on strategy
+            if job.strategy == SyncStrategy.SMART:
+                assets = await self.immich.search_smart(job, count_override=fetch_count)
+                # Optionally random-pick from smart search results
+                if job.random_pick and len(assets) > job.count:
+                    assets = random.sample(assets, job.count)
+                    self.logger.info("Randomly picked %d assets from smart search results", len(assets))
+            else:
+                assets = await self.immich.search_random(job, count_override=fetch_count)
+
+            result.fetched = len(assets)
+            self.logger.info("Fetched %d assets from Immich", result.fetched)
+        except Exception as e:
+            result.errors.append(f"Failed to fetch assets: {e}")
+            self.logger.exception("Failed to fetch assets from Immich")
+            return result
+
+        # Apply client-side filters (orientation, dimensions)
+        assets = self._filter_assets(assets, job, device_reqs)
+        result.filtered = len(assets)
+        if len(assets) < job.count:
+            self.logger.warning(
+                "Only %d images matched client-side filters (requested %d). "
+                "Consider increasing overfetch_multiplier or relaxing filters.",
+                len(assets),
+                job.count,
+            )
+        else:
+            self.logger.info("Filtered to %d assets matching criteria", len(assets))
+
+        # Process each asset
+        for asset in assets:
+            try:
+                process_result = await self._process_asset(asset, job, device_reqs)
+                if process_result == ProcessResult.DOWNLOADED:
+                    result.downloaded += 1
+                elif process_result == ProcessResult.SKIPPED_EXISTING:
+                    result.skipped_existing += 1
+                elif process_result == ProcessResult.SKIPPED_UNDERSIZED:
+                    result.skipped_undersized += 1
+                elif process_result == ProcessResult.SKIPPED_COLOR_MISMATCH:
+                    result.skipped_color_mismatch += 1
+            except Exception as e:
+                error_msg = f"Failed to process asset {asset.id}: {e}"
+                result.errors.append(error_msg)
+                self.logger.exception("Failed to process asset %s", asset.id)
+
+        return result
+
+    async def _get_device_requirements(self, device_id: UUID) -> DeviceRequirements:
+        """Get display requirements from global device table.
+
+        Args:
+            device_id: UUID of target device
+
+        Returns:
+            DeviceRequirements with width, height, and orientation
+
+        Raises:
+            ValueError: If device not found or missing required display attributes
+        """
+        async with AsyncSession(self.engine) as session:
+            # Query global_devices table (from private-assistant-commons)
+            # AIDEV-NOTE: global_devices uses device_attributes JSON for display specs
+            result = await session.exec(
+                select("*").select_from("global_devices").where(device_id == "id")  # type: ignore[arg-type]
+            )
+            row = result.first()
+
+        if not row:
+            raise ValueError(f"Target device not found: {device_id}")
+
+        # Extract device_attributes JSON
+        attrs: dict[str, Any] = row.device_attributes or {}  # type: ignore[attr-defined]
+
+        width = attrs.get("display_width")
+        height = attrs.get("display_height")
+        orientation = attrs.get("orientation")
+
+        if not width or not height or not orientation:
+            raise ValueError(
+                f"Device {device_id} missing required display attributes. "
+                f"Got: width={width}, height={height}, orientation={orientation}"
+            )
+
+        return DeviceRequirements(
+            width=width,
+            height=height,
+            orientation=orientation,
+            display_model=attrs.get("model"),
+        )
+
+    async def _process_asset(
+        self,
+        asset: ImmichAsset,
+        job: ImmichSyncJob,
+        device_reqs: DeviceRequirements,
+    ) -> ProcessResult:
+        """Process a single asset: download, store, record.
+
+        Args:
+            asset: Immich asset to process
+            job: Sync job configuration
+            device_reqs: Target device display requirements
+
+        Returns:
+            ProcessResult indicating what happened
+        """
+        source_url = self._build_source_url(asset.id)
+
+        # Check for existing record
+        if self.sync_config.skip_existing:
+            existing = await self._find_existing_image(source_url)
+            if existing:
+                self.logger.debug("Skipping existing asset: %s", asset.id)
+                return ProcessResult.SKIPPED_EXISTING
+
+        # Target dimensions from device requirements (always processed to jpg)
+        target_width = device_reqs.width
+        target_height = device_reqs.height
+        storage_path = f"{self.sync_config.storage_prefix}/{asset.id}.jpg"
+
+        # Check if already in MinIO (in case DB record was lost)
+        if self.storage.object_exists(storage_path):
+            self.logger.debug("Object already in MinIO: %s", storage_path)
+        else:
+            # Download original
+            self.logger.info("Downloading asset: %s", asset.id)
+            image_bytes = await self._collect_stream(self.immich.download_original(asset.id))
+
+            # Check color compatibility (before resize/crop for accurate scoring)
+            min_score = job.min_color_score
+            if min_score > 0:
+                score = ColorProfileAnalyzer.calculate_compatibility_score(image_bytes)
+                if score < min_score:
+                    self.logger.info("Skipping asset %s: color score %.2f < %.2f", asset.id, score, min_score)
+                    return ProcessResult.SKIPPED_COLOR_MISMATCH
+                self.logger.debug("Asset %s color score: %.2f", asset.id, score)
+
+            # Process to target dimensions
+            self.logger.debug("Processing image to %dx%d", target_width, target_height)
+            processed = ImageProcessor.process_for_display(
+                image_bytes,
+                target_width,
+                target_height,
+            )
+            if processed is None:
+                self.logger.info("Skipping asset %s: too small for target dimensions", asset.id)
+                return ProcessResult.SKIPPED_UNDERSIZED
+            image_bytes = processed
+
+            # Upload to MinIO
+            self.storage.upload_from_bytes(
+                object_path=storage_path,
+                data=image_bytes,
+                content_type="image/jpeg",
+            )
+
+        # Create database record
+        await self._upsert_image_record(asset, storage_path, source_url, job.name)
+
+        return ProcessResult.DOWNLOADED
+
+    async def _find_existing_image(self, source_url: str) -> Image | None:
+        """Find existing image by source URL."""
+        async with AsyncSession(self.engine) as session:
+            result = await session.exec(select(Image).where(Image.source_url == source_url))
+            return result.first()
+
+    async def _upsert_image_record(
+        self,
+        asset: ImmichAsset,
+        storage_path: str,
+        source_url: str,
+        source_name: str,
+    ) -> None:
+        """Create or update Image record in database."""
+        async with AsyncSession(self.engine) as session:
+            # Check for existing record
+            result = await session.exec(select(Image).where(Image.source_url == source_url))
+            existing = result.first()
+
+            if existing:
+                image = existing
+            else:
+                image = Image(
+                    source_name=source_name,
+                    storage_path=storage_path,
+                    source_url=source_url,
+                )
+                session.add(image)
+
+            # Set/update metadata with natural language descriptions
+            await self._populate_image_from_asset(image, asset)
+
+            await session.commit()
+            await session.refresh(image)
+            self.logger.debug("Saved image record: %s", image.id)
+
+    async def _populate_image_from_asset(self, image: Image, asset: ImmichAsset) -> None:
+        """Populate Image fields from Immich asset with natural language metadata."""
+        people_names = [p.name for p in (asset.people or []) if p.name]
+
+        city = state = country = None
+        date = asset.file_created_at
+        if asset.exif_info:
+            city = asset.exif_info.city
+            state = asset.exif_info.state
+            country = asset.exif_info.country
+            date = asset.exif_info.date_time_original or date
+            image.original_width = asset.exif_info.exif_image_width
+            image.original_height = asset.exif_info.exif_image_height
+
+        album_names = await self._get_asset_album_names(asset.id)
+
+        image.title = MetadataBuilder.build_title(
+            people=people_names if people_names else None,
+            city=city,
+            country=country,
+            date=date,
+        )
+        image.description = MetadataBuilder.build_description(
+            people=people_names if people_names else None,
+            city=city,
+            state=state,
+            country=country,
+            date=date,
+            album_names=album_names if album_names else None,
+        )
+        image.tags = self._build_tags(city, country, asset.is_favorite, asset.people)
+
+    async def _get_asset_album_names(self, asset_id: str) -> list[str]:
+        """Fetch album names for an asset."""
+        try:
+            albums = await self.immich.get_asset_albums(asset_id)
+            return [a.album_name for a in albums]
+        except Exception:
+            self.logger.debug("Could not fetch albums for asset %s", asset_id)
+            return []
+
+    @staticmethod
+    def _build_tags(
+        city: str | None,
+        country: str | None,
+        is_favorite: bool,
+        people: list | None,
+    ) -> str | None:
+        """Build comma-separated tags from metadata."""
+        tags: list[str] = []
+        if city:
+            tags.append(city)
+        if country:
+            tags.append(country)
+        if is_favorite:
+            tags.append("favorite")
+        if people:
+            tags.extend(person.name for person in people if person.name)
+        return ",".join(tags) if tags else None
+
+    def _filter_assets(
+        self,
+        assets: list[ImmichAsset],
+        job: ImmichSyncJob,
+        device_reqs: DeviceRequirements,
+    ) -> list[ImmichAsset]:
+        """Filter assets by orientation and dimensions (client-side).
+
+        Args:
+            assets: List of assets from Immich
+            job: Sync job configuration
+            device_reqs: Target device display requirements
+
+        Returns:
+            Filtered list limited to job.count
+        """
+        filtered: list[ImmichAsset] = []
+
+        for asset in assets:
+            if not asset.exif_info:
+                self.logger.debug("Skipping asset %s: no EXIF data", asset.id)
+                continue
+
+            width = asset.exif_info.exif_image_width
+            height = asset.exif_info.exif_image_height
+            if not width or not height:
+                self.logger.debug("Skipping asset %s: missing dimensions in EXIF", asset.id)
+                continue
+
+            # Orientation check from device requirements
+            if not self._matches_orientation(width, height, device_reqs.orientation):
+                continue
+
+            # Dimension checks from device requirements
+            if width < device_reqs.width or height < device_reqs.height:
+                continue
+
+            filtered.append(asset)
+
+            if len(filtered) >= job.count:
+                break
+
+        return filtered
+
+    @staticmethod
+    def _matches_orientation(width: int, height: int, orientation: str) -> bool:
+        """Check if dimensions match the requested orientation."""
+        if orientation == "landscape":
+            return width > height
+        if orientation == "portrait":
+            return height > width
+        if orientation == "square":
+            return width == height
+        return True
+
+    @staticmethod
+    async def _collect_stream(stream: AsyncIterator[bytes]) -> bytes:
+        """Collect async byte stream into a single bytes object."""
+        chunks: list[bytes] = []
+        async for chunk in stream:
+            chunks.append(chunk)
+        return b"".join(chunks)
+
+    def _build_source_url(self, asset_id: str) -> str:
+        """Build unique source URL for deduplication."""
+        return f"immich://{asset_id}"