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/services/search/base.py

@@ -0,0 +1,40 @@
+"""Search provider abstraction (section 16).
+
+API clients and the rest of the service layer talk to `SearchProvider`, not
+to PostgreSQL directly, so the underlying engine can be swapped later (e.g.
+for an `OpenSearchProvider`) without touching callers.
+"""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@dataclass
+class SearchMatch:
+    entity_id: uuid.UUID
+    score: float
+
+
+@dataclass
+class SearchResultIDs:
+    movies: list[SearchMatch] = field(default_factory=list)
+    series: list[SearchMatch] = field(default_factory=list)
+    people: list[SearchMatch] = field(default_factory=list)
+    collections: list[SearchMatch] = field(default_factory=list)
+    companies: list[SearchMatch] = field(default_factory=list)
+
+
+class SearchProvider(ABC):
+    """Returns ranked Aurora entity IDs matching a query. Never returns
+    fully-hydrated entities — that's the SearchService's job, so the
+    provider stays a thin, swappable ranking layer."""
+
+    @abstractmethod
+    async def search(
+        self, session: AsyncSession, query: str, *, limit_per_type: int = 10
+    ) -> SearchResultIDs: ...

app/services/search/postgresql_provider.py

@@ -0,0 +1,121 @@
+"""PostgreSQL-backed search: full-text search ranking blended with trigram
+similarity for typo tolerance, over primary titles/names and alternate
+titles. Requires the `pg_trgm` extension and the functional GIN indexes
+created in the initial migration.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.search.base import SearchMatch, SearchProvider, SearchResultIDs
+
+_MOVIE_SQL = text(
+    """
+    WITH scored AS (
+        SELECT m.id AS entity_id,
+               GREATEST(
+                   ts_rank_cd(to_tsvector('simple', coalesce(m.title, '') || ' ' || coalesce(m.original_title, '')), plainto_tsquery('simple', :q)),
+                   similarity(m.title, :q)
+               ) AS score
+        FROM movies m
+        WHERE to_tsvector('simple', coalesce(m.title, '') || ' ' || coalesce(m.original_title, '')) @@ plainto_tsquery('simple', :q)
+           OR m.title % :q
+        UNION ALL
+        SELECT mat.movie_id AS entity_id, similarity(mat.title, :q) AS score
+        FROM movie_alternate_titles mat
+        WHERE mat.title % :q
+    )
+    SELECT entity_id, MAX(score) AS score
+    FROM scored
+    GROUP BY entity_id
+    ORDER BY score DESC
+    LIMIT :limit
+    """
+)
+
+_SERIES_SQL = text(
+    """
+    WITH scored AS (
+        SELECT s.id AS entity_id,
+               GREATEST(
+                   ts_rank_cd(to_tsvector('simple', coalesce(s.title, '') || ' ' || coalesce(s.original_title, '')), plainto_tsquery('simple', :q)),
+                   similarity(s.title, :q)
+               ) AS score
+        FROM series s
+        WHERE to_tsvector('simple', coalesce(s.title, '') || ' ' || coalesce(s.original_title, '')) @@ plainto_tsquery('simple', :q)
+           OR s.title % :q
+        UNION ALL
+        SELECT sat.series_id AS entity_id, similarity(sat.title, :q) AS score
+        FROM series_alternate_titles sat
+        WHERE sat.title % :q
+    )
+    SELECT entity_id, MAX(score) AS score
+    FROM scored
+    GROUP BY entity_id
+    ORDER BY score DESC
+    LIMIT :limit
+    """
+)
+
+_PEOPLE_SQL = text(
+    """
+    SELECT p.id AS entity_id,
+           GREATEST(
+               ts_rank_cd(to_tsvector('simple', p.name), plainto_tsquery('simple', :q)),
+               similarity(p.name, :q)
+           ) AS score
+    FROM people p
+    WHERE to_tsvector('simple', p.name) @@ plainto_tsquery('simple', :q)
+       OR p.name % :q
+    ORDER BY score DESC
+    LIMIT :limit
+    """
+)
+
+_COLLECTIONS_SQL = text(
+    """
+    SELECT c.id AS entity_id, similarity(c.name, :q) AS score
+    FROM collections c
+    WHERE c.name % :q OR to_tsvector('simple', c.name) @@ plainto_tsquery('simple', :q)
+    ORDER BY score DESC
+    LIMIT :limit
+    """
+)
+
+_COMPANIES_SQL = text(
+    """
+    SELECT co.id AS entity_id, similarity(co.name, :q) AS score
+    FROM companies co
+    WHERE co.name % :q OR to_tsvector('simple', co.name) @@ plainto_tsquery('simple', :q)
+    ORDER BY score DESC
+    LIMIT :limit
+    """
+)
+
+
+class PostgreSQLSearchProvider(SearchProvider):
+    async def search(
+        self, session: AsyncSession, query: str, *, limit_per_type: int = 10
+    ) -> SearchResultIDs:
+        params = {"q": query, "limit": limit_per_type}
+        movies = await session.execute(_MOVIE_SQL, params)
+        series = await session.execute(_SERIES_SQL, params)
+        people = await session.execute(_PEOPLE_SQL, params)
+        collections = await session.execute(_COLLECTIONS_SQL, params)
+        companies = await session.execute(_COMPANIES_SQL, params)
+
+        def to_matches(rows) -> list[SearchMatch]:
+            return [
+                SearchMatch(entity_id=row.entity_id, score=float(row.score or 0.0))
+                for row in rows
+            ]
+
+        return SearchResultIDs(
+            movies=to_matches(movies),
+            series=to_matches(series),
+            people=to_matches(people),
+            collections=to_matches(collections),
+            companies=to_matches(companies),
+        )

app/services/search/service.py

@@ -0,0 +1,49 @@
+"""Search service: runs a `SearchProvider` and hydrates matches into full
+response summaries via the entity services. API clients never see the
+underlying search engine (section 16)."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.schemas.search import SearchResultsOut
+from app.services.collection_service import build_collection_summaries
+from app.services.company_service import build_company_summaries
+from app.services.movie_service import build_movie_summaries
+from app.services.person_service import build_person_summaries
+from app.services.search.base import SearchProvider
+from app.services.tv_service import build_series_summaries
+
+
+class SearchService:
+    def __init__(self, provider: SearchProvider) -> None:
+        self._provider = provider
+
+    async def search(
+        self, session: AsyncSession, query: str, *, limit_per_type: int = 10
+    ) -> SearchResultsOut:
+        query = query.strip()
+        if not query:
+            return SearchResultsOut(query=query)
+
+        results = await self._provider.search(session, query, limit_per_type=limit_per_type)
+
+        movies = await build_movie_summaries(session, [m.entity_id for m in results.movies])
+        series = await build_series_summaries(session, [s.entity_id for s in results.series])
+        people = await build_person_summaries(session, [p.entity_id for p in results.people])
+        collections = await build_collection_summaries(
+            session, [c.entity_id for c in results.collections]
+        )
+        companies = await build_company_summaries(
+            session, [c.entity_id for c in results.companies]
+        )
+
+        return SearchResultsOut(
+            query=query,
+            movies=movies,
+            series=series,
+            people=people,
+            collections=collections,
+            companies=companies,
+            total_results=len(movies) + len(series) + len(people) + len(collections) + len(companies),
+        )