Add GET /people browse/discover endpoint

Extends the browse/discover pattern already built for movies/series
to the fourth major entity type. No genre/year/status equivalent for
people -- known_for_department is the one categorical filter that
actually means something for a cast/crew list, and sort_by is just
popularity (default) or name. No invalid-filter case either: unlike
genre/status, known_for_department is a plain string compared
directly, nothing to parse or validate.

build_person_summary refactored to share row-to-summary logic with
the new list path, same pattern used for movies/series/companies.

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

app/api/v1/people.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends
+from typing import Literal
+
+from fastapi import APIRouter, Depends, Query
 from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -10,13 +12,34 @@ from app.api.deps import cached_response, not_found
 from app.core.database import get_db
 from app.core.redis import get_redis
 from app.core.security import enforce_rate_limit
-from app.schemas.person import PersonCreditsOut, PersonDetailOut
+from app.schemas.person import PersonCreditsOut, PersonDetailOut, PersonListOut
 from app.services import person_service
 from app.services.cache import build_key
 
 router = APIRouter(prefix="/people", tags=["people"], dependencies=[Depends(enforce_rate_limit)])
 
 
+@router.get("", response_model=PersonListOut)
+async def list_people(
+    known_for_department: str | None = Query(
+        None, description="Exact match, e.g. Acting, Directing, Writing"
+    ),
+    sort_by: Literal["popularity", "name"] = Query("popularity"),
+    sort_dir: Literal["asc", "desc"] = Query("desc"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    session: AsyncSession = Depends(get_db),
+) -> PersonListOut:
+    return await person_service.list_people(
+        session,
+        known_for_department=known_for_department,
+        sort_by=sort_by,
+        sort_dir=sort_dir,
+        page=page,
+        page_size=page_size,
+    )
+
+
 @router.get("/{aurora_id}", response_model=PersonDetailOut)
 async def get_person(
     aurora_id: str,

app/repositories/person_repository.py

@@ -4,12 +4,17 @@ from __future__ import annotations
 
 import uuid
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.credit import Credit
 from app.models.person import Person
 
+_PERSON_SORT_COLUMNS = {
+    "popularity": Person.popularity,
+    "name": Person.name,
+}
+
 
 async def get_person_by_id(session: AsyncSession, person_id: uuid.UUID) -> Person | None:
     result = await session.execute(select(Person).where(Person.id == person_id))
@@ -24,3 +29,33 @@ async def get_person_credits(session: AsyncSession, person_id: uuid.UUID) -> lis
     )
     result = await session.execute(stmt)
     return list(result.scalars().all())
+
+
+async def list_people(
+    session: AsyncSession,
+    *,
+    known_for_department: str | None,
+    sort_by: str,
+    sort_dir: str,
+    limit: int,
+    offset: int,
+) -> tuple[list[Person], int]:
+    """Browse people with an optional known_for_department filter -- see
+    movie_repository.list_movies for the window-function total-count
+    approach this mirrors. No genre/year/status equivalent for people:
+    department is the one categorical grouping that actually means
+    something when browsing a cast/crew list."""
+
+    column = _PERSON_SORT_COLUMNS[sort_by]
+    order = column.desc() if sort_dir == "desc" else column.asc()
+
+    stmt = select(Person, func.count().over().label("total_count"))
+    if known_for_department is not None:
+        stmt = stmt.where(Person.known_for_department == known_for_department)
+
+    stmt = stmt.order_by(order.nulls_last(), Person.id.asc()).limit(limit).offset(offset)
+
+    rows = (await session.execute(stmt)).all()
+    if not rows:
+        return [], 0
+    return [row[0] for row in rows], rows[0].total_count

app/schemas/person.py

@@ -70,3 +70,11 @@ class PersonCreditsOut(BaseModel):
     id: str
     cast: list[FilmographyCreditOut] = []
     crew: list[FilmographyCreditOut] = []
+
+
+class PersonListOut(BaseModel):
+    page: int
+    page_size: int
+    total_results: int
+    total_pages: int
+    results: list[PersonSummaryOut] = []

app/services/person_service.py

@@ -10,6 +10,7 @@ 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.models.person import Person
 from app.models.tv import Series
 from app.repositories import movie_repository, person_repository, polymorphic, tv_repository
 from app.schemas.person import (
@@ -17,6 +18,7 @@ from app.schemas.person import (
     GuestEpisodeOut,
     PersonCreditsOut,
     PersonDetailOut,
+    PersonListOut,
     PersonSummaryOut,
 )
 from app.services.common import primary_artwork_path, to_artwork_out
@@ -189,13 +191,8 @@ async def get_person_credits(session: AsyncSession, person_aurora_id: str) -> Pe
     return PersonCreditsOut(id=aurora_id("person", str(person.id)), cast=cast, crew=crew)
 
 
-async def build_person_summary(
-    session: AsyncSession, person_id: uuid.UUID
-) -> PersonSummaryOut | None:
-    person = await person_repository.get_person_by_id(session, person_id)
-    if person is None:
-        return None
-    profiles = await polymorphic.get_artwork(session, "person", person_id, ArtworkType.PROFILE)
+async def _person_summary_from_row(session: AsyncSession, person: Person) -> PersonSummaryOut:
+    profiles = await polymorphic.get_artwork(session, "person", person.id, ArtworkType.PROFILE)
     return PersonSummaryOut(
         id=aurora_id("person", str(person.id)),
         name=person.name,
@@ -205,6 +202,15 @@ async def build_person_summary(
     )
 
 
+async def build_person_summary(
+    session: AsyncSession, person_id: uuid.UUID
+) -> PersonSummaryOut | None:
+    person = await person_repository.get_person_by_id(session, person_id)
+    if person is None:
+        return None
+    return await _person_summary_from_row(session, person)
+
+
 async def build_person_summaries(
     session: AsyncSession, person_ids: list[uuid.UUID]
 ) -> list[PersonSummaryOut]:
@@ -214,3 +220,28 @@ async def build_person_summaries(
         if summary is not None:
             out.append(summary)
     return out
+
+
+async def list_people(
+    session: AsyncSession,
+    *,
+    known_for_department: str | None,
+    sort_by: str,
+    sort_dir: str,
+    page: int,
+    page_size: int,
+) -> PersonListOut:
+    people, total = await person_repository.list_people(
+        session,
+        known_for_department=known_for_department,
+        sort_by=sort_by,
+        sort_dir=sort_dir,
+        limit=page_size,
+        offset=(page - 1) * page_size,
+    )
+    results = [await _person_summary_from_row(session, p) for p in people]
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return PersonListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )