feat: add domain types and quality ranking

worker/lyra_worker/quality.py

@@ -0,0 +1,23 @@
+from lyra_worker.types import Candidate, Quality
+
+_SOURCE_TIERS = {"qobuz": 0, "soulseek": 1, "youtube": 2}
+
+
+def quality_class(q: Quality) -> int:
+    """3 = hi-res lossless, 2 = CD lossless, 1 = lossy."""
+    if q.lossless:
+        hires = (q.bit_depth is not None and q.bit_depth > 16) or (
+            q.sample_rate is not None and q.sample_rate > 44100
+        )
+        return 3 if hires else 2
+    return 1
+
+
+def source_tier(source: str) -> int:
+    """Lower is better. Unknown sources rank worst."""
+    return _SOURCE_TIERS.get(source, 99)
+
+
+def rank_key(c: Candidate) -> tuple[int, int]:
+    """Sort key; larger is better. Quality class first, then source tier."""
+    return (quality_class(c.quality), -source_tier(c.source))

worker/lyra_worker/types.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MBTarget:
+    artist: str
+    album: str
+    track_count: int | None = None
+    total_duration_s: int | None = None
+
+
+@dataclass(frozen=True)
+class Quality:
+    fmt: str
+    lossless: bool
+    bit_depth: int | None = None
+    sample_rate: int | None = None
+    bitrate_kbps: int | None = None
+
+
+@dataclass(frozen=True)
+class Candidate:
+    source: str
+    source_ref: str
+    matched_artist: str
+    matched_album: str
+    quality: Quality
+    track_count: int
+    confidence: float = 0.0
+
+
+@dataclass(frozen=True)
+class DownloadResult:
+    ok: bool
+    path: str | None = None
+    track_count: int = 0
+    error: str | None = None