Add trending movies/series, refreshed on a schedule

Mirrors TMDb's own /trending/{movie|tv}/{day|week} ranking rather than
Aurora computing trending itself from popularity deltas -- that would
require re-syncing the entire catalog on a schedule, infeasible at any
real scale, whereas TMDb already computes this well from signals (real
view/search velocity) Aurora has no access to.

New: TrendingEntry model + migration 0003, MetadataProvider.get_trending
(concrete/optional, like aclose(), so existing test fakes don't all need
updating), refresh_trending() which actually ingests each trending item
(only ~20 per window, cheap enough to fully ingest rather than apply the
never-fabricate-a-stub rule recommendations uses), a twice-daily arq cron
job (WorkerSettings.cron_jobs, new to this codebase), a manual admin
trigger for right after a deploy, and GET /movies/trending + GET
/series/trending.

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

app/services/ingestion/trending_ingestion.py

@@ -0,0 +1,53 @@
+"""Refreshes Aurora's mirror of TMDb's own trending lists (section 17,
+additive) -- see app/models/trending.py for why this mirrors TMDb's
+ranking rather than Aurora computing its own from popularity deltas.
+
+Unlike recommendations' never-fabricate-a-stub rule, this actually
+ingests/refreshes each trending item's own metadata as a side effect --
+there are only ~20 items per (media_type, time_window) window (TMDb's
+first page), cheap enough to fully ingest rather than silently drop
+anything Aurora hasn't seen yet.
+"""
+
+from __future__ import annotations
+
+from app.core.database import session_scope
+from app.core.logging import get_logger
+from app.providers.base import MetadataProvider
+from app.repositories.trending_repository import replace_trending
+from app.services.ingestion.movie_ingestion import ingest_movie
+from app.services.ingestion.series_ingestion import ingest_series
+
+logger = get_logger(__name__)
+
+# TMDb's own media_type values -> Aurora's entity_type values.
+_MEDIA_TYPE_TO_ENTITY_TYPE = {"movie": "movie", "tv": "series"}
+
+
+async def refresh_trending(provider: MetadataProvider, media_type: str, time_window: str) -> int:
+    """Fetch TMDb's current trending list for (media_type, time_window),
+    ingest/refresh each item, and replace Aurora's own ranked snapshot for
+    that window. Returns how many entries were written."""
+
+    entity_type = _MEDIA_TYPE_TO_ENTITY_TYPE[media_type]
+    raw_results = await provider.get_trending(media_type, time_window)
+
+    entity_ids = []
+    for item in raw_results:
+        external_id = str(item["id"])
+        async with session_scope() as session:
+            if media_type == "movie":
+                entity_id = await ingest_movie(session, provider, external_id)
+            else:
+                entity_id = await ingest_series(session, provider, external_id)
+        entity_ids.append(entity_id)
+
+    async with session_scope() as session:
+        await replace_trending(
+            session, entity_type=entity_type, time_window=time_window, entity_ids=entity_ids
+        )
+
+    logger.info(
+        "trending_refreshed", media_type=media_type, time_window=time_window, count=len(entity_ids)
+    )
+    return len(entity_ids)

app/services/movie_service.py

@@ -9,7 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.ids import aurora_id, parse_aurora_id
 from app.models.enums import ArtworkType, MovieStatus
 from app.models.movie import Movie
-from app.repositories import movie_repository, polymorphic
+from app.repositories import movie_repository, polymorphic, trending_repository
 from app.schemas.common import CollectionBriefOut, CompanyBriefOut, GenreOut, KeywordOut
 from app.schemas.movie import (
     MovieCreditsOut,
@@ -233,6 +233,30 @@ async def list_upcoming(session: AsyncSession, *, region: str, page: int, page_s
     )
 
 
+_TRENDING_WINDOWS = ("day", "week")
+
+
+async def list_trending(
+    session: AsyncSession, *, time_window: str, page: int, page_size: int
+) -> MovieListOut:
+    if time_window not in _TRENDING_WINDOWS:
+        raise InvalidMovieFilterError(f"unknown time_window: {time_window!r}")
+
+    all_ids = await trending_repository.get_trending_entity_ids(
+        session, entity_type="movie", time_window=time_window
+    )
+    total = len(all_ids)
+    start = (page - 1) * page_size
+    page_ids = all_ids[start : start + page_size]
+    movies = await movie_repository.get_movies_by_ids(session, page_ids)
+    results = [await _movie_summary_from_row(session, m) for m in movies]
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return MovieListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
 async def list_movies(
     session: AsyncSession,
     *,

app/services/tv_service.py

@@ -10,7 +10,7 @@ from app.core.ids import aurora_id, parse_aurora_id
 from app.models.credit import Credit
 from app.models.enums import ArtworkType, CompanyType, SeriesStatus
 from app.models.tv import Series
-from app.repositories import polymorphic, tv_repository
+from app.repositories import polymorphic, trending_repository, tv_repository
 from app.schemas.common import CastCreditOut, CompanyBriefOut, CrewCreditOut, GenreOut, KeywordOut
 from app.schemas.tv import (
     EpisodeBriefOut,
@@ -316,6 +316,30 @@ async def build_series_summaries(
     return out
 
 
+_TRENDING_WINDOWS = ("day", "week")
+
+
+async def list_trending(
+    session: AsyncSession, *, time_window: str, page: int, page_size: int
+) -> SeriesListOut:
+    if time_window not in _TRENDING_WINDOWS:
+        raise InvalidSeriesFilterError(f"unknown time_window: {time_window!r}")
+
+    all_ids = await trending_repository.get_trending_entity_ids(
+        session, entity_type="series", time_window=time_window
+    )
+    total = len(all_ids)
+    start = (page - 1) * page_size
+    page_ids = all_ids[start : start + page_size]
+    series_rows = await tv_repository.get_series_by_ids(session, page_ids)
+    results = [await _series_summary_from_row(session, s) for s in series_rows]
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return SeriesListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
 async def list_series(
     session: AsyncSession,
     *,