Add opt-in season cascade to series ingestion

Ingesting a series only ever produced season stubs -- getting actual
episodes meant calling POST /admin/ingest/season once per season by
hand, which is exactly what manual end-to-end testing kept requiring
for every multi-season show.

POST /api/v1/admin/ingest/series now takes include_seasons (default
false, since a show can have dozens of seasons and that's dozens of
TMDb calls fired from one request). When true, ingest_series_task
fans out one ingest_season job per season once the series succeeds,
using arq's own ctx['redis'] connection for the job (the same pattern
arq's docs recommend for job chaining) rather than a second unrelated
connection. Each fanned-out season job still goes through
get_or_create_ingestion_job, so re-running a cascaded series ingestion
reuses the same season job rows instead of creating duplicates.

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

app/api/v1/admin.py

@@ -36,6 +36,12 @@ class IngestPersonRequest(BaseModel):
 
 class IngestSeriesRequest(BaseModel):
     tmdb_id: str
+    # When true, ingest_series_task also enqueues an ingest_season job for
+    # every season the series has, once the series itself finishes.
+    # Defaults to false: a show can have dozens of seasons, and cascading
+    # automatically means dozens of TMDb calls fired off from one request —
+    # opt in rather than surprise the caller with that.
+    include_seasons: bool = False
 
 
 class IngestSeasonRequest(BaseModel):
@@ -120,7 +126,7 @@ async def enqueue_series_ingestion(
         entity_type="series",
         external_id=body.tmdb_id,
         task_name="ingest_series_task",
-        task_args=(body.tmdb_id,),
+        task_args=(body.tmdb_id, body.include_seasons),
     )
 
 

app/services/ingestion/runner.py

@@ -25,6 +25,7 @@ from app.repositories.provider_repository import (
     mark_job_running,
     mark_job_succeeded,
 )
+from app.repositories.tv_repository import get_seasons_for_series
 from app.services.ingestion.movie_ingestion import ingest_movie
 from app.services.ingestion.person_ingestion import ingest_person
 from app.services.ingestion.series_ingestion import ingest_season, ingest_series
@@ -138,3 +139,14 @@ async def run_season_ingestion(
             session, provider, series_external_id, season_number, ingestion_job_id=job_id
         ),
     )
+
+
+async def get_series_season_numbers(series_id: uuid.UUID) -> list[int]:
+    """All season numbers a just-ingested series has, for cascading into
+    per-season ingestion jobs (see `app/workers/tasks.py:ingest_series_task`,
+    `include_seasons`). A short-lived session of its own since this runs
+    after `run_series_ingestion`'s own session has already closed."""
+
+    async with session_scope() as session:
+        seasons = await get_seasons_for_series(session, series_id)
+        return [season.season_number for season in seasons]

app/workers/tasks.py

@@ -14,6 +14,8 @@ from typing import Any
 
 from app.core.logging import get_logger
 from app.services.ingestion.runner import (
+    get_or_create_ingestion_job,
+    get_series_season_numbers,
     run_movie_ingestion,
     run_person_ingestion,
     run_season_ingestion,
@@ -33,8 +35,28 @@ async def ingest_person_task(ctx: dict[str, Any], job_id: str, external_id: str)
     return str(person_id)
 
 
-async def ingest_series_task(ctx: dict[str, Any], job_id: str, external_id: str) -> str:
+async def ingest_series_task(
+    ctx: dict[str, Any], job_id: str, external_id: str, include_seasons: bool = False
+) -> str:
     series_id = await run_series_ingestion(uuid.UUID(job_id), external_id)
+
+    if include_seasons:
+        # Fan out one ingest_season job per season this series has, using
+        # the same arq connection this task is running on (arq hands every
+        # job's ctx a "redis" entry precisely for chaining/fan-out like
+        # this) — not a second, unrelated connection.
+        redis = ctx["redis"]
+        for season_number in await get_series_season_numbers(series_id):
+            season_job_id = await get_or_create_ingestion_job(
+                "season_sync", "season", f"{external_id}:{season_number}"
+            )
+            await redis.enqueue_job(
+                "ingest_season_task", str(season_job_id), external_id, season_number
+            )
+        logger.info(
+            "series_seasons_cascaded", series_id=str(series_id), external_id=external_id
+        )
+
     return str(series_id)