Surface series/episode credits in person filmography

/people/{id}/credits only ever looked at entity_type == "movie",
silently dropping the series-level cast/crew and episode-level
guest-star Credit rows that series_ingestion.py has been writing all
along -- a person ingested via a TV show would show an empty or
movie-only filmography no matter how much TV work was actually in the
database.

Regular series credits map straight to a filmography row, same shape
as movies. Guest-star episode credits are aggregated to one row per
(series, department/job/character) with an episode_count, rather than
one row per episode -- a prolific guest actor would otherwise flood
the list with dozens of near-identical entries. Added
tv_repository.get_series_by_ids/get_episodes_by_ids (bulk, mirroring
the existing movie_repository pattern) to support it.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

app/repositories/tv_repository.py

@@ -19,6 +19,24 @@ async def get_series_by_id(session: AsyncSession, series_id: uuid.UUID) -> Serie
     return result.scalar_one_or_none()
 
 
+async def get_series_by_ids(session: AsyncSession, series_ids: list[uuid.UUID]) -> list[Series]:
+    if not series_ids:
+        return []
+    stmt = select(Series).where(Series.id.in_(series_ids))
+    result = await session.execute(stmt)
+    by_id = {s.id: s for s in result.scalars().all()}
+    return [by_id[i] for i in series_ids if i in by_id]
+
+
+async def get_episodes_by_ids(session: AsyncSession, episode_ids: list[uuid.UUID]) -> list[Episode]:
+    if not episode_ids:
+        return []
+    stmt = select(Episode).where(Episode.id.in_(episode_ids))
+    result = await session.execute(stmt)
+    by_id = {e.id: e for e in result.scalars().all()}
+    return [by_id[i] for i in episode_ids if i in by_id]
+
+
 async def get_season_by_number(
     session: AsyncSession, series_id: uuid.UUID, season_number: int
 ) -> Season | None:

app/schemas/person.py

@@ -28,6 +28,11 @@ class FilmographyCreditOut(BaseModel):
     character: str | None = None
     release_date: date | None = None
     poster_path: str | None = None
+    # Set only for series filmography built from guest-star episode credits:
+    # how many distinct episodes this character/credit appeared in, since
+    # those are aggregated to one row per series rather than one per
+    # episode. None for movie credits and regular (non-guest) series roles.
+    episode_count: int | None = None
 
 
 class PersonDetailOut(BaseModel):

app/services/person_service.py

@@ -3,12 +3,15 @@
 from __future__ import annotations
 
 import uuid
+from collections import defaultdict
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.ids import aurora_id, parse_aurora_id
+from app.models.credit import Credit
 from app.models.enums import ArtworkType
-from app.repositories import movie_repository, person_repository, polymorphic
+from app.models.tv import Series
+from app.repositories import movie_repository, person_repository, polymorphic, tv_repository
 from app.schemas.person import (
     FilmographyCreditOut,
     PersonCreditsOut,
@@ -56,6 +59,11 @@ async def get_person_detail(session: AsyncSession, person_aurora_id: str) -> Per
     )
 
 
+async def _series_poster_path(session: AsyncSession, series_id: uuid.UUID) -> str | None:
+    posters = await polymorphic.get_artwork(session, "series", series_id, ArtworkType.POSTER)
+    return primary_artwork_path(posters, ArtworkType.POSTER)
+
+
 async def get_person_credits(session: AsyncSession, person_aurora_id: str) -> PersonCreditsOut:
     person_id = _resolve_person_id(person_aurora_id)
     person = await person_repository.get_person_by_id(session, person_id)
@@ -64,38 +72,104 @@ async def get_person_credits(session: AsyncSession, person_aurora_id: str) -> Pe
 
     credits_ = await person_repository.get_person_credits(session, person_id)
 
-    movie_ids = [c.entity_id for c in credits_ if c.entity_type == "movie"]
-    movies = {m.id: m for m in await movie_repository.get_movies_by_ids(session, movie_ids)}
+    movie_credits = [c for c in credits_ if c.entity_type == "movie"]
+    series_credits = [c for c in credits_ if c.entity_type == "series"]
+    episode_credits = [c for c in credits_ if c.entity_type == "episode"]
+
+    movies = {
+        m.id: m
+        for m in await movie_repository.get_movies_by_ids(
+            session, [c.entity_id for c in movie_credits]
+        )
+    }
+    episodes = {
+        e.id: e
+        for e in await tv_repository.get_episodes_by_ids(
+            session, [c.entity_id for c in episode_credits]
+        )
+    }
+
+    # Guest-star episode credits are aggregated to one filmography row per
+    # (series, department/job/character) rather than one row per episode —
+    # a prolific guest actor would otherwise flood the list with dozens of
+    # near-identical entries, one per episode they appeared in.
+    episode_groups: dict[tuple, list[Credit]] = defaultdict(list)
+    for credit in episode_credits:
+        episode = episodes.get(credit.entity_id)
+        if episode is None:
+            continue
+        key = (episode.series_id, credit.department, credit.job, credit.character)
+        episode_groups[key].append(credit)
+
+    series_ids = {c.entity_id for c in series_credits} | {
+        episode.series_id for episode in episodes.values()
+    }
+    series_by_id: dict[uuid.UUID, Series] = {
+        s.id: s for s in await tv_repository.get_series_by_ids(session, list(series_ids))
+    }
 
     cast: list[FilmographyCreditOut] = []
     crew: list[FilmographyCreditOut] = []
 
-    for credit in credits_:
-        if credit.entity_type != "movie":
-            # Series/episode filmography follows the same shape; movies are
-            # implemented first per the Core 0.1 milestone (section 34).
-            continue
+    def _bucket(department: str) -> list[FilmographyCreditOut]:
+        return cast if department == "Acting" else crew
+
+    for credit in movie_credits:
         movie = movies.get(credit.entity_id)
         if movie is None:
             continue
-        posters = await polymorphic.get_artwork(
-            session, "movie", movie.id, ArtworkType.POSTER
+        posters = await polymorphic.get_artwork(session, "movie", movie.id, ArtworkType.POSTER)
+        _bucket(credit.department).append(
+            FilmographyCreditOut(
+                id=aurora_id("credit", str(credit.id)),
+                media_id=aurora_id("movie", str(movie.id)),
+                media_type="movie",
+                title=movie.title,
+                department=credit.department,
+                job=credit.job,
+                character=credit.character,
+                release_date=movie.primary_release_date,
+                poster_path=primary_artwork_path(posters, ArtworkType.POSTER),
+            )
         )
-        item = FilmographyCreditOut(
-            id=aurora_id("credit", str(credit.id)),
-            media_id=aurora_id("movie", str(movie.id)),
-            media_type="movie",
-            title=movie.title,
-            department=credit.department,
-            job=credit.job,
-            character=credit.character,
-            release_date=movie.primary_release_date,
-            poster_path=primary_artwork_path(posters, ArtworkType.POSTER),
+
+    for credit in series_credits:
+        series = series_by_id.get(credit.entity_id)
+        if series is None:
+            continue
+        _bucket(credit.department).append(
+            FilmographyCreditOut(
+                id=aurora_id("credit", str(credit.id)),
+                media_id=aurora_id("series", str(series.id)),
+                media_type="series",
+                title=series.title,
+                department=credit.department,
+                job=credit.job,
+                character=credit.character,
+                release_date=series.first_air_date,
+                poster_path=await _series_poster_path(session, series.id),
+            )
+        )
+
+    for (series_id, department, job, character), group in episode_groups.items():
+        series = series_by_id.get(series_id)
+        if series is None:
+            continue
+        representative = group[0]
+        _bucket(department).append(
+            FilmographyCreditOut(
+                id=aurora_id("credit", str(representative.id)),
+                media_id=aurora_id("series", str(series.id)),
+                media_type="series",
+                title=series.title,
+                department=department,
+                job=job,
+                character=character,
+                release_date=series.first_air_date,
+                poster_path=await _series_poster_path(session, series.id),
+                episode_count=len(group),
+            )
         )
-        if credit.department == "Acting":
-            cast.append(item)
-        else:
-            crew.append(item)
 
     return PersonCreditsOut(id=aurora_id("person", str(person.id)), cast=cast, crew=crew)