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]>
2026-09-04 17:34:03 -05:00
commit c20df1c503
111 changed files with 10041 additions and 0 deletions
@@ -0,0 +1,37 @@
+"""Entity matching (section 14): decides whether an incoming provider
+record corresponds to an existing Aurora entity.
+
+Core 0.1 policy — deliberately conservative:
+
+- An exact external-ID match (this provider has already been linked to an
+  Aurora entity of this type) is the only case treated as MatchConfidence
+  EXACT and reused.
+- Anything else creates a *new* Aurora entity (MatchConfidence NEW) rather
+  than guessing via fuzzy title matching. Silently merging two providers'
+  differing descriptions of "the same" title is exactly what section 14
+  prohibits.
+
+Fuzzy candidate matching (title + year similarity, surfaced for human
+review) is genuinely deferred — see docs/architecture.md — until Core has
+an admin review workflow to act on AMBIGUOUS matches.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import MatchConfidence
+from app.repositories.reference_repository import find_entity_by_external_id
+
+
+async def match_entity(
+    session: AsyncSession, *, provider_id: uuid.UUID, entity_type: str, external_id: str
+) -> tuple[uuid.UUID | None, MatchConfidence]:
+    """Return (existing_aurora_id_or_None, confidence)."""
+
+    existing = await find_entity_by_external_id(session, provider_id, entity_type, external_id)
+    if existing is not None:
+        return existing, MatchConfidence.EXACT
+    return None, MatchConfidence.NEW