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/schemas/collection.py

@@ -0,0 +1,24 @@
+"""Collection/franchise response schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from app.schemas.movie import MovieSummaryOut
+from app.schemas.tv import SeriesSummaryOut
+
+
+class CollectionDetailOut(BaseModel):
+    id: str
+    type: str = "collection"
+    name: str
+    overview: str | None = None
+    poster_path: str | None = None
+    backdrop_path: str | None = None
+    movies: list[MovieSummaryOut] = []
+    series: list[SeriesSummaryOut] = []
+
+    created_at: datetime
+    updated_at: datetime

app/schemas/common.py

@@ -0,0 +1,119 @@
+"""Shared response building blocks used across entity schemas.
+
+These are hand-written Pydantic models, never SQLAlchemy models serialized
+directly — see section 18 of the build spec.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ORMModel(BaseModel):
+    """Base for schemas built from ORM rows via `model_validate(obj)`."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class GenreOut(ORMModel):
+    id: str
+    name: str
+
+
+class KeywordOut(ORMModel):
+    id: str
+    name: str
+
+
+class ArtworkOut(BaseModel):
+    id: str
+    type: str
+    language: str | None = None
+    width: int | None = None
+    height: int | None = None
+    aspect_ratio: float | None = None
+    url: str
+    provider: str | None = None
+    is_primary: bool = False
+    vote_average: float | None = None
+
+
+class ImagesOut(BaseModel):
+    posters: list[ArtworkOut] = []
+    backdrops: list[ArtworkOut] = []
+    logos: list[ArtworkOut] = []
+
+
+class VideoOut(BaseModel):
+    id: str
+    type: str
+    site: str | None = None
+    url: str
+    language: str | None = None
+    country: str | None = None
+    is_official: bool = False
+    published_at: date | None = None
+    provider: str | None = None
+
+
+class ExternalIDsOut(BaseModel):
+    """Provider slug -> native ID, e.g. {"tmdb": "550", "imdb": "tt0137523"}."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class PersonBriefOut(BaseModel):
+    id: str
+    name: str
+    profile_path: str | None = None
+
+
+class CastCreditOut(BaseModel):
+    id: str
+    person: PersonBriefOut
+    character: str | None = None
+    billing_order: int | None = None
+    episode_count: int | None = None
+
+
+class CrewCreditOut(BaseModel):
+    id: str
+    person: PersonBriefOut
+    department: str
+    job: str | None = None
+    episode_count: int | None = None
+
+
+class CreditsOut(BaseModel):
+    cast: list[CastCreditOut] = []
+    crew: list[CrewCreditOut] = []
+
+
+class CompanyBriefOut(BaseModel):
+    id: str
+    name: str
+    company_type: str
+    logo_path: str | None = None
+
+
+class CollectionBriefOut(BaseModel):
+    id: str
+    name: str
+
+
+class PageMeta(BaseModel):
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+
+
+class ErrorDetail(BaseModel):
+    code: str
+    message: str
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetail

app/schemas/company.py

@@ -0,0 +1,24 @@
+"""Company response schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class CompanyDetailOut(BaseModel):
+    id: str
+    type: str = "company"
+    name: str
+    company_type: str
+    description: str | None = None
+    country: str | None = None
+    headquarters: str | None = None
+    homepage: str | None = None
+    logo_path: str | None = None
+    parent_company_id: str | None = None
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime

app/schemas/health.py

@@ -0,0 +1,20 @@
+"""Health/readiness response schemas."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthOut(BaseModel):
+    status: str = "ok"
+
+
+class DependencyStatus(BaseModel):
+    name: str
+    ok: bool
+    required: bool
+
+
+class ReadyOut(BaseModel):
+    status: str
+    dependencies: list[DependencyStatus]

app/schemas/movie.py

@@ -0,0 +1,80 @@
+"""Movie response schemas."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pydantic import BaseModel
+
+from app.schemas.common import (
+    CastCreditOut,
+    CollectionBriefOut,
+    CompanyBriefOut,
+    CrewCreditOut,
+    GenreOut,
+    ImagesOut,
+    KeywordOut,
+    VideoOut,
+)
+
+
+class MovieSummaryOut(BaseModel):
+    """Compact movie representation used in lists and search results."""
+
+    id: str
+    type: str = "movie"
+    title: str
+    original_title: str | None = None
+    overview: str | None = None
+    release_date: date | None = None
+    poster_path: str | None = None
+    popularity: float | None = None
+    vote_average: float | None = None
+
+
+class MovieDetailOut(BaseModel):
+    id: str
+    type: str = "movie"
+    title: str
+    original_title: str | None = None
+    overview: str | None = None
+    tagline: str | None = None
+    status: str
+    original_language: str | None = None
+    release_date: date | None = None
+    runtime: int | None = None
+    budget: int | None = None
+    revenue: int | None = None
+    popularity: float | None = None
+    vote_average: float | None = None
+    vote_count: int | None = None
+    adult: bool = False
+
+    genres: list[GenreOut] = []
+    keywords: list[KeywordOut] = []
+    cast: list[CastCreditOut] = []
+    crew: list[CrewCreditOut] = []
+    companies: list[CompanyBriefOut] = []
+    collection: CollectionBriefOut | None = None
+    images: ImagesOut = ImagesOut()
+    videos: list[VideoOut] = []
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime
+
+
+class MovieCreditsOut(BaseModel):
+    id: str
+    cast: list[CastCreditOut] = []
+    crew: list[CrewCreditOut] = []
+
+
+class MovieImagesOut(BaseModel):
+    id: str
+    images: ImagesOut = ImagesOut()
+
+
+class MovieVideosOut(BaseModel):
+    id: str
+    videos: list[VideoOut] = []

app/schemas/person.py

@@ -0,0 +1,55 @@
+"""Person response schemas."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pydantic import BaseModel
+
+from app.schemas.common import ArtworkOut
+
+
+class PersonSummaryOut(BaseModel):
+    id: str
+    type: str = "person"
+    name: str
+    known_for_department: str | None = None
+    profile_path: str | None = None
+    popularity: float | None = None
+
+
+class FilmographyCreditOut(BaseModel):
+    id: str
+    media_id: str
+    media_type: str
+    title: str
+    department: str
+    job: str | None = None
+    character: str | None = None
+    release_date: date | None = None
+    poster_path: str | None = None
+
+
+class PersonDetailOut(BaseModel):
+    id: str
+    type: str = "person"
+    name: str
+    aliases: list[str] = []
+    biography: str | None = None
+    birthday: date | None = None
+    deathday: date | None = None
+    birthplace: str | None = None
+    gender: str | None = None
+    known_for_department: str | None = None
+    popularity: float | None = None
+    profile_images: list[ArtworkOut] = []
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime
+
+
+class PersonCreditsOut(BaseModel):
+    id: str
+    cast: list[FilmographyCreditOut] = []
+    crew: list[FilmographyCreditOut] = []

app/schemas/search.py

@@ -0,0 +1,20 @@
+"""Search response schemas."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from app.schemas.common import CollectionBriefOut, CompanyBriefOut
+from app.schemas.movie import MovieSummaryOut
+from app.schemas.person import PersonSummaryOut
+from app.schemas.tv import SeriesSummaryOut
+
+
+class SearchResultsOut(BaseModel):
+    query: str
+    movies: list[MovieSummaryOut] = []
+    series: list[SeriesSummaryOut] = []
+    people: list[PersonSummaryOut] = []
+    collections: list[CollectionBriefOut] = []
+    companies: list[CompanyBriefOut] = []
+    total_results: int = 0

app/schemas/tv.py

@@ -0,0 +1,123 @@
+"""Series/season/episode response schemas."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pydantic import BaseModel
+
+from app.schemas.common import (
+    CastCreditOut,
+    CompanyBriefOut,
+    CrewCreditOut,
+    GenreOut,
+    ImagesOut,
+    KeywordOut,
+    VideoOut,
+)
+
+
+class SeriesSummaryOut(BaseModel):
+    id: str
+    type: str = "series"
+    title: str
+    original_title: str | None = None
+    overview: str | None = None
+    first_air_date: date | None = None
+    poster_path: str | None = None
+    popularity: float | None = None
+    vote_average: float | None = None
+
+
+class SeasonBriefOut(BaseModel):
+    id: str
+    season_number: int
+    title: str | None = None
+    episode_count: int | None = None
+    air_date: date | None = None
+    poster_path: str | None = None
+
+
+class SeriesDetailOut(BaseModel):
+    id: str
+    type: str = "series"
+    title: str
+    original_title: str | None = None
+    overview: str | None = None
+    tagline: str | None = None
+    status: str
+    original_language: str | None = None
+    first_air_date: date | None = None
+    last_air_date: date | None = None
+    number_of_seasons: int | None = None
+    number_of_episodes: int | None = None
+    popularity: float | None = None
+    vote_average: float | None = None
+    vote_count: int | None = None
+
+    genres: list[GenreOut] = []
+    keywords: list[KeywordOut] = []
+    creators: list[CrewCreditOut] = []
+    cast: list[CastCreditOut] = []
+    crew: list[CrewCreditOut] = []
+    networks: list[CompanyBriefOut] = []
+    companies: list[CompanyBriefOut] = []
+    seasons: list[SeasonBriefOut] = []
+    images: ImagesOut = ImagesOut()
+    videos: list[VideoOut] = []
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime
+
+
+class SeriesSeasonsOut(BaseModel):
+    id: str
+    seasons: list[SeasonBriefOut] = []
+
+
+class EpisodeBriefOut(BaseModel):
+    id: str
+    episode_number: int
+    title: str | None = None
+    air_date: date | None = None
+    still_path: str | None = None
+
+
+class SeasonDetailOut(BaseModel):
+    id: str
+    type: str = "season"
+    series_id: str
+    season_number: int
+    title: str | None = None
+    overview: str | None = None
+    air_date: date | None = None
+    episode_count: int | None = None
+    episodes: list[EpisodeBriefOut] = []
+    images: ImagesOut = ImagesOut()
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime
+
+
+class EpisodeDetailOut(BaseModel):
+    id: str
+    type: str = "episode"
+    series_id: str
+    season_id: str
+    season_number: int
+    episode_number: int
+    title: str | None = None
+    overview: str | None = None
+    air_date: date | None = None
+    runtime: int | None = None
+
+    cast: list[CastCreditOut] = []
+    guest_stars: list[CastCreditOut] = []
+    crew: list[CrewCreditOut] = []
+    images: ImagesOut = ImagesOut()
+    external_ids: dict[str, str] = {}
+
+    created_at: datetime
+    updated_at: datetime