feat: add album grouping logic

Groups 2+ images or 2+ videos into albums
Mixed types or single items sent separately

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

nanobot/channels/telegram_media.py

@@ -244,3 +244,45 @@ def _optimize_png(img: Image.Image, max_bytes: int) -> bytes:
         return _optimize_jpeg(background, max_bytes)
 
     raise ValueError(f"Cannot optimize PNG under {max_bytes} bytes")
+
+
+def group_media_for_album(media_items: list[tuple[str, MediaKind]]) -> dict[str, list[str]]:
+    """
+    Group media items for album sending.
+
+    Logic:
+    - All images (2+) → album
+    - All videos (2+) → album
+    - Mixed types → separate
+    - Single item → separate
+
+    Args:
+        media_items: List of (path, MediaKind) tuples
+
+    Returns:
+        Dict with 'album' and 'separate' keys containing lists of paths
+    """
+    if len(media_items) <= 1:
+        return {
+            "album": [],
+            "separate": [path for path, _ in media_items]
+        }
+
+    # Count each kind
+    kinds = [kind for _, kind in media_items]
+    unique_kinds = set(kinds)
+
+    # All same type → album (if images or videos)
+    if len(unique_kinds) == 1:
+        kind = kinds[0]
+        if kind in (MediaKind.IMAGE, MediaKind.VIDEO):
+            return {
+                "album": [path for path, _ in media_items],
+                "separate": []
+            }
+
+    # Mixed types or non-album-able types → separate
+    return {
+        "album": [],
+        "separate": [path for path, _ in media_items]
+    }

tests/test_telegram_media.py

@@ -202,3 +202,62 @@ async def test_fetch_media_timeout():
 
         with pytest.raises(ValueError, match="timeout"):
             await fetch_media("https://example.com/image.jpg", max_bytes=10_000_000)
+
+
+def test_group_media_all_images():
+    """Test grouping all images into album."""
+    from nanobot.channels.telegram_media import MediaKind, group_media_for_album
+
+    media_items = [
+        ("image1.jpg", MediaKind.IMAGE),
+        ("image2.png", MediaKind.IMAGE),
+        ("image3.jpeg", MediaKind.IMAGE),
+    ]
+
+    result = group_media_for_album(media_items)
+
+    assert result["album"] == ["image1.jpg", "image2.png", "image3.jpeg"]
+    assert result["separate"] == []
+
+
+def test_group_media_all_videos():
+    """Test grouping all videos into album."""
+    from nanobot.channels.telegram_media import MediaKind, group_media_for_album
+
+    media_items = [
+        ("video1.mp4", MediaKind.VIDEO),
+        ("video2.mov", MediaKind.VIDEO),
+    ]
+
+    result = group_media_for_album(media_items)
+
+    assert result["album"] == ["video1.mp4", "video2.mov"]
+    assert result["separate"] == []
+
+
+def test_group_media_mixed_types():
+    """Test mixed media types sent separately."""
+    from nanobot.channels.telegram_media import MediaKind, group_media_for_album
+
+    media_items = [
+        ("image.jpg", MediaKind.IMAGE),
+        ("video.mp4", MediaKind.VIDEO),
+        ("audio.mp3", MediaKind.AUDIO),
+    ]
+
+    result = group_media_for_album(media_items)
+
+    assert result["album"] == []
+    assert result["separate"] == ["image.jpg", "video.mp4", "audio.mp3"]
+
+
+def test_group_media_single_item():
+    """Test single media item sent separately (not as album)."""
+    from nanobot.channels.telegram_media import MediaKind, group_media_for_album
+
+    media_items = [("image.jpg", MediaKind.IMAGE)]
+
+    result = group_media_for_album(media_items)
+
+    assert result["album"] == []
+    assert result["separate"] == ["image.jpg"]