major refactor

core/schema/models/brand.py

@@ -0,0 +1,38 @@
+"""Brand schema — source of truth for brand discovery."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+
+class BrandSource(str, Enum):
+    OCR = "ocr"
+    VLM = "local_vlm"
+    CLOUD = "cloud_llm"
+    MANUAL = "manual"
+
+
+@dataclass
+class Brand:
+    """
+    A brand discovered or registered in the system.
+
+    Airings track where/when the brand appeared — each airing
+    references a timeline and a frame range.
+    """
+
+    id: UUID
+    canonical_name: str
+    aliases: List[str] = field(default_factory=list)
+    source: BrandSource = BrandSource.OCR  # how first discovered
+    confirmed: bool = False
+
+    # Airings — JSONB array of appearances
+    # [{timeline_id, frame_start, frame_end, confidence, source, timestamp}]
+    airings: List[Dict[str, Any]] = field(default_factory=list)
+    total_airings: int = 0
+
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None