A kind of initial commit

app/types.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class TrackCandidate:
+    id: str
+    uri: str
+    name: str
+    artist_names: list[str]
+    artist_ids: list[str]
+    popularity: int | None = None
+    source: str = "unknown"
+    score: float = 0.0
+    seed_reasons: list[str] = field(default_factory=list)
+    added_at: datetime | None = None
+
+
+@dataclass
+class PlaylistBuildResult:
+    tracks: list[TrackCandidate]
+    target_size: int
+    new_count: int
+    reused_count: int
+    min_new_required: int
+    notes: str | None = None