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/api/v1/admin.py

@@ -168,6 +168,29 @@ async def enqueue_collection_ingestion(
     )
 
 
+class TrendingRefreshEnqueuedOut(BaseModel):
+    arq_job_id: str
+    status: str = "enqueued"
+
+
+@router.post("/refresh-trending", response_model=TrendingRefreshEnqueuedOut)
+async def enqueue_trending_refresh(
+    queue: ArqRedis = Depends(get_queue),
+) -> TrendingRefreshEnqueuedOut:
+    """Manually kick off the same refresh the twice-daily cron job runs
+    (see WorkerSettings.cron_jobs) -- useful right after a fresh deploy so
+    GET /movies/trending isn't empty until the next scheduled tick. Not
+    tracked via ingestion_jobs (see refresh_trending_task's docstring), so
+    there's no job_id to poll -- check GET /movies/trending directly."""
+
+    arq_job = await queue.enqueue_job("refresh_trending_task")
+    if arq_job is None:
+        raise HTTPException(
+            status.HTTP_503_SERVICE_UNAVAILABLE, "Could not enqueue trending refresh (queue busy)."
+        )
+    return TrendingRefreshEnqueuedOut(arq_job_id=arq_job.job_id)
+
+
 @router.get("/ingest/jobs/{job_id}", response_model=IngestionJobOut)
 async def get_ingestion_job_status(
     job_id: uuid.UUID, session: AsyncSession = Depends(get_db)

app/api/v1/movies.py

@@ -75,6 +75,21 @@ async def upcoming_movies(
     return await movie_service.list_upcoming(session, region=region, page=page, page_size=page_size)
 
 
+@router.get("/trending", response_model=MovieListOut)
+async def trending_movies(
+    time_window: Literal["day", "week"] = Query("day", alias="window"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    session: AsyncSession = Depends(get_db),
+) -> MovieListOut:
+    try:
+        return await movie_service.list_trending(
+            session, time_window=time_window, page=page, page_size=page_size
+        )
+    except movie_service.InvalidMovieFilterError as exc:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
+
+
 @router.get("/{aurora_id}", response_model=MovieDetailOut)
 async def get_movie(
     aurora_id: str,

app/api/v1/series.py

@@ -55,6 +55,21 @@ async def list_series(
         raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
 
 
+@router.get("/trending", response_model=SeriesListOut)
+async def trending_series(
+    time_window: Literal["day", "week"] = Query("day", alias="window"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    session: AsyncSession = Depends(get_db),
+) -> SeriesListOut:
+    try:
+        return await tv_service.list_trending(
+            session, time_window=time_window, page=page, page_size=page_size
+        )
+    except tv_service.InvalidSeriesFilterError as exc:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
+
+
 @router.get("/{aurora_id}", response_model=SeriesDetailOut)
 async def get_series(
     aurora_id: str,

app/models/__init__.py

@@ -24,6 +24,7 @@ from app.models.movie import (
 )
 from app.models.person import Person
 from app.models.provider import IngestionJob, Provider, ProviderRecord
+from app.models.trending import TrendingEntry
 from app.models.tv import (
     Episode,
     Season,
@@ -75,4 +76,5 @@ __all__ = [
     "Video",
     "WatchProvider",
     "WatchProviderOffering",
+    "TrendingEntry",
 ]

app/models/trending.py

@@ -0,0 +1,35 @@
+"""Aurora's mirror of TMDb's own trending lists (section 17, additive).
+
+TMDb already computes trending using signals Aurora has no access to
+(real view/search velocity across their whole audience) — reinventing
+that from Aurora's own popularity snapshots would require re-syncing the
+entire catalog on a schedule, which isn't feasible at any real scale.
+Instead Aurora asks TMDb what's trending right now and mirrors that
+ranked list (see app/services/ingestion/trending_ingestion.py)."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Index, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class TrendingEntry(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    """One row per (entity, time_window) currently on Aurora's trending
+    list -- replaced wholesale on each refresh, same as ReleaseDate/
+    WatchProviderOffering. `updated_at` doubles as "when this window was
+    last refreshed"."""
+
+    __tablename__ = "trending_entries"
+    __table_args__ = (Index("ix_trending_entries_window", "entity_type", "time_window"),)
+
+    entity_type: Mapped[str] = mapped_column(String(30), nullable=False)  # "movie" | "series"
+    entity_id: Mapped[uuid.UUID] = mapped_column(nullable=False, index=True)
+    time_window: Mapped[str] = mapped_column(String(10), nullable=False)  # "day" | "week"
+    rank: Mapped[int] = mapped_column(Integer, nullable=False)
+
+
+__all__ = ["TrendingEntry"]

app/providers/base.py

@@ -70,5 +70,16 @@ class MetadataProvider(ABC):
         """Search this provider's catalog for movies matching `query`. Used
         to seed ingestion, not exposed directly to API clients."""
 
+    async def get_trending(self, media_type: str, time_window: str) -> list[dict[str, Any]]:
+        """Fetch a ranked list of raw items (movies or series, per
+        `media_type`) currently trending over `time_window` ("day" |
+        "week"). Not every provider has a trending concept, so this is
+        concrete rather than abstract (like `aclose` below) — a provider
+        that doesn't support it simply doesn't override this, and callers
+        get an empty list rather than every other provider implementation
+        having to stub out a method that means nothing for them."""
+
+        return []
+
     async def aclose(self) -> None:
         """Release any held resources (HTTP clients, ...). Optional."""

app/providers/tmdb.py

@@ -124,6 +124,13 @@ class TMDbProvider(MetadataProvider):
         data = await self._get("/search/movie", {"query": query})
         return data.get("results", [])
 
+    async def get_trending(self, media_type: str, time_window: str) -> list[dict[str, Any]]:
+        # TMDb's own endpoint shape: /trending/{movie|tv}/{day|week} -- page
+        # 1 only (~20 results), enough for a trending rail without pulling
+        # in TMDb's full multi-page trending list.
+        data = await self._get(f"/trending/{media_type}/{time_window}")
+        return data.get("results", [])
+
     async def aclose(self) -> None:
         if self._owns_client:
             await self._client.aclose()

app/repositories/trending_repository.py

@@ -0,0 +1,40 @@
+"""Data access for TrendingEntry."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.trending import TrendingEntry
+
+
+async def get_trending_entity_ids(
+    session: AsyncSession, *, entity_type: str, time_window: str
+) -> list[uuid.UUID]:
+    stmt = (
+        select(TrendingEntry.entity_id)
+        .where(TrendingEntry.entity_type == entity_type, TrendingEntry.time_window == time_window)
+        .order_by(TrendingEntry.rank.asc())
+    )
+    result = await session.execute(stmt)
+    return list(result.scalars().all())
+
+
+async def replace_trending(
+    session: AsyncSession, *, entity_type: str, time_window: str, entity_ids: list[uuid.UUID]
+) -> None:
+    """Replace a window's trending snapshot wholesale, same delete-then-
+    recreate approach as ReleaseDate/WatchProviderOffering -- there is no
+    history to preserve, only the current ranking."""
+
+    await session.execute(
+        delete(TrendingEntry).where(
+            TrendingEntry.entity_type == entity_type, TrendingEntry.time_window == time_window
+        )
+    )
+    for rank, entity_id in enumerate(entity_ids):
+        session.add(
+            TrendingEntry(entity_type=entity_type, entity_id=entity_id, time_window=time_window, rank=rank)
+        )

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,
     *,

app/workers/tasks.py

@@ -19,6 +19,7 @@ from typing import Any
 
 from app.core.database import session_scope
 from app.core.logging import get_logger
+from app.providers.tmdb import TMDbProvider
 from app.services.artwork.download import download_artwork
 from app.services.artwork.storage import get_artwork_storage
 from app.services.ingestion.runner import (
@@ -34,6 +35,7 @@ from app.services.ingestion.runner import (
     run_season_ingestion,
     run_series_ingestion,
 )
+from app.services.ingestion.trending_ingestion import refresh_trending
 
 logger = get_logger(__name__)
 
@@ -112,3 +114,18 @@ async def ingest_collection_task(ctx: dict[str, Any], job_id: str, external_id:
 async def download_artwork_task(ctx: dict[str, Any], artwork_id: str) -> bool:
     async with session_scope() as session:
         return await download_artwork(session, get_artwork_storage(), uuid.UUID(artwork_id))
+
+
+async def refresh_trending_task(ctx: dict[str, Any]) -> None:
+    """Runs on a schedule (see WorkerSettings.cron_jobs in
+    app/workers/worker.py) -- not tracked in ingestion_jobs, same as
+    download_artwork_task, since there's no single external_id a client
+    would poll status for."""
+
+    provider = TMDbProvider()
+    try:
+        for media_type in ("movie", "tv"):
+            for time_window in ("day", "week"):
+                await refresh_trending(provider, media_type, time_window)
+    finally:
+        await provider.aclose()

app/workers/worker.py

@@ -10,6 +10,7 @@ each job is picked up by exactly one worker.
 from __future__ import annotations
 
 from arq.connections import RedisSettings
+from arq.cron import cron
 
 from app.core.config import get_settings
 from app.core.logging import configure_logging, get_logger
@@ -20,6 +21,7 @@ from app.workers.tasks import (
     ingest_person_task,
     ingest_season_task,
     ingest_series_task,
+    refresh_trending_task,
 )
 
 logger = get_logger(__name__)
@@ -43,6 +45,10 @@ class WorkerSettings:
         ingest_collection_task,
         download_artwork_task,
     ]
+    # Twice a day (UTC) rather than run_at_startup=True -- a worker
+    # container restart (common during deploys) must not hammer TMDb with
+    # a full trending refresh every time it comes up.
+    cron_jobs = [cron(refresh_trending_task, hour={3, 15}, minute=0)]
     on_startup = startup
     on_shutdown = shutdown
     redis_settings = RedisSettings.from_dsn(get_settings().REDIS_URL)