Initial Aurora Core 0.1 implementation

Production-grade media metadata backend per docs/aurora-core-spec.md:
Aurora-owned UUIDv7 identity system, normalized movie/TV/people/credits
schema, provider abstraction with a TMDb adapter, an idempotent async
ingestion pipeline (normalize -> match -> upsert -> provenance), a
Postgres FTS/trigram search layer, a stateless FastAPI v1 API with
Redis caching/rate-limiting, arq workers, dev/prod Docker Compose
topologies, unit + integration + load tests, CI, and architecture/
database/API/ERD documentation.

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

app/providers/base.py

@@ -0,0 +1,58 @@
+"""Provider abstraction (section 13).
+
+A `MetadataProvider` fetches **raw**, unnormalized data from one external
+source. It never writes to the database and never returns Aurora entities —
+that's the normalizer/matcher/ingestion pipeline's job (see
+`app/services/metadata/` and `app/services/ingestion/`). This keeps adapters
+replaceable: swapping TMDb for another provider means writing a new class
+here, not touching ingestion logic.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ProviderError(Exception):
+    """Raised for any provider-side failure (auth, not-found, rate limit,
+    network). Ingestion jobs catch this and record it, they don't crash."""
+
+
+class ProviderNotConfiguredError(ProviderError):
+    """Raised when a required credential (e.g. TMDB_API_KEY) is missing."""
+
+
+class ProviderNotFoundError(ProviderError):
+    """Raised when the provider has no record for the given external ID."""
+
+
+class MetadataProvider(ABC):
+    slug: str
+    name: str
+
+    @abstractmethod
+    async def get_movie(self, external_id: str) -> dict[str, Any]:
+        """Fetch raw movie data, including credits/images/videos/keywords/
+        alternate titles/external IDs/release dates where the provider
+        supports fetching them in one call."""
+
+    @abstractmethod
+    async def get_series(self, external_id: str) -> dict[str, Any]:
+        """Fetch raw series data (without season/episode bodies)."""
+
+    @abstractmethod
+    async def get_season(self, series_external_id: str, season_number: int) -> dict[str, Any]:
+        """Fetch raw season data, including its episodes."""
+
+    @abstractmethod
+    async def get_person(self, external_id: str) -> dict[str, Any]:
+        """Fetch raw person data, including external IDs and images."""
+
+    @abstractmethod
+    async def search_movie(self, query: str) -> list[dict[str, Any]]:
+        """Search this provider's catalog for movies matching `query`. Used
+        to seed ingestion, not exposed directly to API clients."""
+
+    async def aclose(self) -> None:
+        """Release any held resources (HTTP clients, ...). Optional."""

app/providers/tmdb.py

@@ -0,0 +1,89 @@
+"""TMDb metadata provider adapter.
+
+Requires the `TMDB_API_KEY` environment variable (a TMDb v3 API key —
+https://www.themoviedb.org/settings/api). If it is not configured, every
+method raises `ProviderNotConfiguredError` rather than returning fake data.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from app.core.config import get_settings
+from app.providers.base import (
+    MetadataProvider,
+    ProviderError,
+    ProviderNotConfiguredError,
+    ProviderNotFoundError,
+)
+
+_MOVIE_APPEND = "credits,images,videos,keywords,alternative_titles,external_ids,release_dates,recommendations"
+_SERIES_APPEND = "credits,images,videos,keywords,alternative_titles,external_ids,content_ratings"
+_PERSON_APPEND = "external_ids,images,combined_credits"
+
+
+class TMDbProvider(MetadataProvider):
+    slug = "tmdb"
+    name = "The Movie Database (TMDb)"
+    base_url = "https://api.themoviedb.org/3"
+
+    def __init__(self, api_key: str | None = None, client: httpx.AsyncClient | None = None) -> None:
+        settings = get_settings()
+        self._api_key = api_key if api_key is not None else settings.TMDB_API_KEY
+        self._client = client or httpx.AsyncClient(base_url=self.base_url, timeout=15.0)
+        self._owns_client = client is None
+
+    def _require_api_key(self) -> None:
+        if not self._api_key:
+            raise ProviderNotConfiguredError(
+                "TMDB_API_KEY is not set. Configure it in the environment to use the TMDb "
+                "provider — see .env.example."
+            )
+
+    @retry(
+        reraise=True,
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=0.5, max=5),
+        retry=retry_if_exception_type(httpx.TransportError),
+    )
+    async def _get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._require_api_key()
+        query = {"api_key": self._api_key, **(params or {})}
+        try:
+            response = await self._client.get(path, params=query)
+        except httpx.TransportError as exc:
+            raise ProviderError(f"TMDb request failed: {exc}") from exc
+
+        if response.status_code == 404:
+            raise ProviderNotFoundError(f"TMDb has no record at {path}")
+        if response.status_code == 401:
+            raise ProviderNotConfiguredError("TMDb rejected the configured TMDB_API_KEY.")
+        if response.status_code >= 400:
+            raise ProviderError(f"TMDb error {response.status_code} at {path}: {response.text[:300]}")
+        return response.json()
+
+    async def get_movie(self, external_id: str) -> dict[str, Any]:
+        return await self._get(f"/movie/{external_id}", {"append_to_response": _MOVIE_APPEND})
+
+    async def get_series(self, external_id: str) -> dict[str, Any]:
+        return await self._get(f"/tv/{external_id}", {"append_to_response": _SERIES_APPEND})
+
+    async def get_season(self, series_external_id: str, season_number: int) -> dict[str, Any]:
+        return await self._get(
+            f"/tv/{series_external_id}/season/{season_number}",
+            {"append_to_response": "credits,images,external_ids"},
+        )
+
+    async def get_person(self, external_id: str) -> dict[str, Any]:
+        return await self._get(f"/person/{external_id}", {"append_to_response": _PERSON_APPEND})
+
+    async def search_movie(self, query: str) -> list[dict[str, Any]]:
+        data = await self._get("/search/movie", {"query": query})
+        return data.get("results", [])
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()