Repository navigation
feat: LLM-guided discovery mode for AI auto-playlist #96
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
c9df953
e8f1267
5cd17e8
336e872
3c40f75
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,283 @@ | ||
| /******************************************************************** | ||
| * aiMixGenerator.ts — LLM-guided discovery mix (issue #49, discovery mode) | ||
| * | ||
| * The on-device mix (aiMixPlaylist.ts) only reshuffles what the user | ||
| * already has. This generator asks a keyless LLM for SEARCH QUERIES | ||
| * only — it never picks tracks. The queries run through the app's own | ||
| * search API, results are scored by the same buildSmartQueue weights, | ||
| * and a failure at any stage falls back to the on-device mix. | ||
| * | ||
| * Endpoint: Pollinations text API, OpenAI-compatible, anonymous. | ||
| * The free lane accepts no credentials — an API token in the request | ||
| * would be rejected, so none is ever attached. | ||
| * | ||
| * Privacy: the prompt carries artist/track NAMES only. No ids, no | ||
| * accounts, no play counts beyond rank order. Same tradeoff class as | ||
| * streaming the songs themselves. | ||
| ******************************************************************/ | ||
| import type { Track } from "../contexts/PlayerContext"; | ||
| import { StorageService, type Playlist } from "../utils/storage"; | ||
| import { loadReplaySummary } from "../utils/listeningStats"; | ||
| import { searchAPI } from "./searchAPI"; | ||
| import { buildSmartQueue, loadPlayCounts } from "./aiPlaylistService"; | ||
| import { | ||
| generateAiMixPlaylist, | ||
| persistAiMix, | ||
| pickSeed, | ||
| } from "./aiMixPlaylist"; | ||
|
|
||
| /** | ||
| * The keyless lane is rate-limited and returns HTTP 402 once an IP has used | ||
| * its anonymous quota. Try the canonical model id after the alias before | ||
| * giving up: an alias can be retired (404) while the id it points at lives on. | ||
| * Anonymous only — no credentials are ever attached. | ||
| */ | ||
| const ENDPOINTS = [ | ||
| { url: "https://text.pollinations.ai/openai", model: "openai" }, | ||
| { url: "https://text.pollinations.ai/openai", model: "openai-fast" }, | ||
| ]; | ||
| const REQUEST_TIMEOUT_MS = 15000; | ||
| const MAX_QUERIES = 6; | ||
| const QUERIES_PER_REQUEST = 8; | ||
| const MIN_DISCOVERY_TRACKS = 8; | ||
| const SEARCH_LIMIT = 10; | ||
|
|
||
| /** | ||
| * The prompt carries names only — top artists and top tracks, ranked. | ||
| * Fenced to a JSON array so parsing is mechanical, not hopeful. | ||
| */ | ||
| export function buildHistoryPrompt(language: "en" | "fa"): string { | ||
| const ask = | ||
| language === "fa" | ||
| ? "لطفا فقط یک آرایه JSON از رشتهها برگردان، بدون هیچ متن دیگری." | ||
| : "Reply with ONLY a JSON array of strings, no other text."; | ||
| return [ | ||
| "You suggest music search queries.", | ||
| `Give me exactly ${QUERIES_PER_REQUEST} YouTube Music search queries for finding songs I have NOT heard yet but will like.`, | ||
| `Make them general discovery queries (genres, eras, moods, scenes) - do NOT include these exact artist or track names in the queries.`, | ||
| `Rules: 3-6 words each, in ${language === "fa" ? "Persian/Farsi" : "English"}.`, | ||
| ask, | ||
| ].join("\n"); | ||
| } | ||
|
|
||
| export function buildHistoryContext( | ||
| artists: string[], | ||
| tracks: string[], | ||
| language: "en" | "fa", | ||
| ): string { | ||
| const head = | ||
| language === "fa" | ||
| ? "من به این آهنگها گوش میدهم:" | ||
| : "These are what I listen to most:"; | ||
| return [ | ||
| head, | ||
| `Top artists: ${artists.slice(0, 10).join(", ")}`, | ||
| `Top tracks: ${tracks.slice(0, 15).join("; ")}`, | ||
| buildHistoryPrompt(language), | ||
| ].join("\n"); | ||
| } | ||
|
|
||
| /** | ||
| * Strict parser: finds the first JSON array of strings in model output, | ||
| * tolerates markdown fences and chatter around it. Anything else (an | ||
| * object, nested arrays, garbage) returns []. The caller treats [] as | ||
| * "LLM failed" and falls back — never as "empty playlist". | ||
| */ | ||
| export function parseQueryList(raw: unknown): string[] { | ||
| if (typeof raw !== "string") return []; | ||
| // Strip code fences first: they are the common wrapping, and their | ||
| // brackets would otherwise win the scan. | ||
| const unfenced = raw.replace(/```[a-z]*\n?/gi, "").replace(/```/g, ""); | ||
| const match = unfenced.match(/\[[\s\S]*\]/); | ||
| if (!match) return []; | ||
| let parsed: unknown; | ||
| try { | ||
| parsed = JSON.parse(match[0]); | ||
| } catch { | ||
| return []; | ||
| } | ||
| if (!Array.isArray(parsed)) return []; | ||
| const out: string[] = []; | ||
| for (const item of parsed) { | ||
| if (typeof item !== "string") continue; | ||
| const clean = item.trim().slice(0, 80); | ||
| // A query must be words: reject JSON fragments that slipped through. | ||
| if (clean.length < 3 || !/[a-z\u0600-\u06FF]/i.test(clean)) continue; | ||
| out.push(clean); | ||
| if (out.length >= MAX_QUERIES) break; | ||
| } | ||
| return out; | ||
| } | ||
|
|
||
| /** One attempt against one endpoint. Returns [] on any failure. */ | ||
| async function fetchFrom( | ||
| endpoint: { url: string; model: string }, | ||
| prompt: string, | ||
| fetchImpl: typeof fetch, | ||
| ): Promise<string[]> { | ||
| const controller = new AbortController(); | ||
| const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS); | ||
| try { | ||
| const res = await fetchImpl(endpoint.url, { | ||
| method: "POST", | ||
| headers: { "Content-Type": "application/json" }, | ||
| // Anonymous is the free lane: no auth token of any kind. | ||
| body: JSON.stringify({ | ||
| model: endpoint.model, | ||
| stream: false, | ||
| messages: [{ role: "user", content: prompt }], | ||
| }), | ||
| signal: controller.signal, | ||
| }); | ||
| if (!res.ok) { | ||
| console.log(`[aiMix] ${endpoint.model} HTTP ${res.status}`); | ||
| return []; | ||
| } | ||
| const data = (await res.json()) as { | ||
| choices?: Array<{ message?: { content?: string } }>; | ||
| }; | ||
| return parseQueryList(data?.choices?.[0]?.message?.content); | ||
| } catch (error) { | ||
| console.log( | ||
| `[aiMix] ${endpoint.model} failed:`, | ||
| error instanceof Error ? error.message : error, | ||
| ); | ||
| return []; | ||
| } finally { | ||
| clearTimeout(timer); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Walk the keyless endpoint chain until one returns usable queries. | ||
| * The last resort is not here — it is the on-device mix, in the caller. | ||
| */ | ||
| export async function fetchSearchQueries( | ||
| prompt: string, | ||
| fetchImpl: typeof fetch = fetch, | ||
| ): Promise<string[]> { | ||
| for (const endpoint of ENDPOINTS) { | ||
| const queries = await fetchFrom(endpoint, prompt, fetchImpl); | ||
| if (queries.length) return queries; | ||
| } | ||
| return []; | ||
| } | ||
|
|
||
| /** Load ranked artist/track names from local listening stats. */ | ||
| async function loadHistoryNames(): Promise<{ | ||
| artists: string[]; | ||
| tracks: string[]; | ||
| }> { | ||
| try { | ||
| const summary = await loadReplaySummary("alltime"); | ||
| const artists = (summary.topArtists || []) | ||
| .map((a) => a.name) | ||
| .filter(Boolean); | ||
| const tracks = (summary.topTracks || []) | ||
| .map((t) => (t.artist ? `${t.title} — ${t.artist}` : t.title)) | ||
| .filter(Boolean); | ||
| return { artists, tracks }; | ||
| } catch { | ||
| return { artists: [], tracks: [] }; | ||
| } | ||
| } | ||
|
|
||
| /** Run discovery queries through the app's own search. Dedupes by id. */ | ||
| export async function resolveQueries( | ||
| queries: string[], | ||
| search: (query: string) => Promise<Track[]> = defaultSearch, | ||
| ): Promise<Track[]> { | ||
| const seen = new Set<string>(); | ||
| const found: Track[] = []; | ||
| for (const query of queries.slice(0, MAX_QUERIES)) { | ||
| let results: Track[] = []; | ||
| try { | ||
| results = await search(query); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · A hanging search stalls generation When a search request remains pending instead of resolving or rejecting, Give search requests a deadline so a stalled request can be skipped and generation can continue. Prompt for AI agentsIn `modules/aiMixGenerator.ts` at line 195:
**A hanging search stalls generation**
When a search request remains pending instead of resolving or rejecting, `resolveQueries` awaits each search without a deadline, so it never reaches the remaining queries or on-device fallback and the generating indicator stays active indefinitely.
Give search requests a deadline so a stalled request can be skipped and generation can continue. |
||
| } catch { | ||
| // one dead query source must not sink the batch | ||
| continue; | ||
| } | ||
| for (const t of results) { | ||
| if (!t?.id || !t.title || seen.has(String(t.id))) continue; | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟠 High · Known tracks enter discovery mix When a search query returns a track the user has liked or previously played, Exclude liked and previously played track IDs from discovery candidates before scoring them. Also at Prompt for AI agentsIn `modules/aiMixGenerator.ts` at line 201:
**Known tracks enter discovery mix**
When a search query returns a track the user has liked or previously played, `resolveQueries` passes the track to `buildSmartQueue`, which excludes only the seed and can include the already-known track in the discovery mix.
Exclude liked and previously played track IDs from discovery candidates before scoring them.
Also at `modules/aiMixGenerator.ts:258`, `modules/aiMixGenerator.ts:268-273`. |
||
| seen.add(String(t.id)); | ||
| found.push(t); | ||
| } | ||
| } | ||
| return found; | ||
| } | ||
|
|
||
| /** Default resolver: YouTube Music via the existing search surface. */ | ||
| async function defaultSearch(query: string): Promise<Track[]> { | ||
| const result = await searchAPI.searchWithYouTubeMusic(query, "all", 1, SEARCH_LIMIT); | ||
| const items = result?.items || []; | ||
| return items.map((item: any) => ({ | ||
| id: String(item.id), | ||
| title: item.title || "", | ||
| artist: item.author || item.artist || "", | ||
| thumbnail: item.img || item.thumbnailUrl || item.thumbnail, | ||
| url: item.href, | ||
| source: "youtubemusic", | ||
| })) as Track[]; | ||
|
Comment on lines
+210
to
+220
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Discovery searches only one catalog When a discovery track is available from another supported search catalog but not YouTube Music, Use the app's mixed search providers to resolve discovery queries. Prompt for AI agentsIn `modules/aiMixGenerator.ts` at lines 210-220:
**Discovery searches only one catalog**
When a discovery track is available from another supported search catalog but not YouTube Music, `defaultSearch` calls only `searchWithYouTubeMusic`, so tracks from the other mixed-search providers never enter the candidate pool.
Use the app's mixed search providers to resolve discovery queries. |
||
| } | ||
|
|
||
| /** | ||
| * Discovery-first generator. Stages: | ||
| * 1. history names -> prompt -> LLM queries (fail => on-device) | ||
| * 2. queries -> search -> candidate pool (< MIN => on-device) | ||
| * 3. score with buildSmartQueue against seed (empty => on-device) | ||
| * 4. persist under the stable @ai_mix id | ||
| */ | ||
| export async function generateAiMixWithDiscovery( | ||
| language: "en" | "fa", | ||
| deps?: { | ||
| fetchImpl?: typeof fetch; | ||
| search?: (query: string) => Promise<Track[]>; | ||
| }, | ||
| ): Promise<Playlist | null> { | ||
| const [{ artists, tracks: trackNames }, liked, recent, playCounts] = | ||
| await Promise.all([ | ||
| loadHistoryNames(), | ||
| StorageService.loadLikedSongs(), | ||
| StorageService.loadPreviouslyPlayedSongs(), | ||
|
Comment on lines
+240
to
+241
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · History read failures look like no history When reading liked songs or previously played songs fails while the user has history, Propagate history read errors or distinguish them from valid empty lists before deciding there is no seed. Also at Prompt for AI agentsIn `modules/aiMixGenerator.ts` at lines 240-241:
**History read failures look like no history**
When reading liked songs or previously played songs fails while the user has history, `StorageService` returns empty arrays, so `pickSeed` returns `null` and generation reports an empty-history outcome instead of a read failure.
Propagate history read errors or distinguish them from valid empty lists before deciding there is no seed.
Also at `modules/aiMixGenerator.ts:248`. |
||
| loadPlayCounts(), | ||
| ]); | ||
|
|
||
| const seed = await pickSeed(liked, recent); | ||
| if (!seed) { | ||
| // Same contract as the on-device path: honest null, no fake playlist. | ||
| return null; | ||
| } | ||
|
|
||
| const prompt = buildHistoryContext(artists, trackNames, language); | ||
| const queries = await fetchSearchQueries(prompt, deps?.fetchImpl); | ||
| if (!queries.length) { | ||
| console.log("[aiMix] no queries from LLM, falling back to on-device mix"); | ||
| return generateAiMixPlaylist(language); | ||
| } | ||
|
|
||
| const candidates = await resolveQueries(queries, deps?.search); | ||
| if (candidates.length < MIN_DISCOVERY_TRACKS) { | ||
| console.log( | ||
| `[aiMix] only ${candidates.length} discovery tracks, falling back to on-device mix`, | ||
| ); | ||
| return generateAiMixPlaylist(language); | ||
| } | ||
|
|
||
| // Seed scoring gives the discovery pool taste; new tracks have no play | ||
| // history, so playCounts only discriminates tracks the user already has. | ||
| const discovered = buildSmartQueue({ | ||
| seed, | ||
| library: candidates, | ||
| size: 30, | ||
| playCounts, | ||
| }); | ||
|
Comment on lines
+268
to
+273
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Unrelated tracks enter discovery mix When discovery queries return enough candidates with no meaningful artist or title overlap with the seed, Require meaningful similarity to the seed before accepting discovery candidates, and fall back when too few qualify. Prompt for AI agentsIn `modules/aiMixGenerator.ts` at lines 268-273:
**Unrelated tracks enter discovery mix**
When discovery queries return enough candidates with no meaningful artist or title overlap with the seed, `buildSmartQueue` gives every candidate a positive liked-track baseline, so unrelated search results remain eligible and can be included instead of triggering fallback.
Require meaningful similarity to the seed before accepting discovery candidates, and fall back when too few qualify. |
||
| if (discovered.length < MIN_DISCOVERY_TRACKS) { | ||
| console.log("[aiMix] scoring kept too little, falling back to on-device mix"); | ||
| return generateAiMixPlaylist(language); | ||
| } | ||
|
|
||
| console.log( | ||
| `[aiMix] discovery: ${queries.length} queries -> ${candidates.length} candidates -> ${discovered.length} tracks`, | ||
| ); | ||
| return persistAiMix(discovered, language); | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,6 +7,39 @@ export const AI_MIX_ID = "@ai_mix"; | |
|
|
||
| const MIX_SIZE = 30; | ||
|
|
||
| /** | ||
| * Persist an already-built track list as the pinned AI Mix. | ||
| * Shared by the on-device generator and the discovery generator so | ||
| * both write through one write path and one stable id. | ||
| */ | ||
| export async function persistAiMix( | ||
| tracks: Track[], | ||
| language: "en" | "fa", | ||
| ): Promise<Playlist> { | ||
| const now = new Date().toISOString(); | ||
| // Read once, write once. addPlaylist re-reads the list internally, so | ||
| // going through it here would race another writer's change; and reading | ||
| // twice (once for `existing`, once for `rest`) lets the two disagree. | ||
| const stored = await StorageService.loadPlaylists(); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔴 Critical · Existing playlists can be erased When Distinguish a failed playlist read from a valid empty list and do not save a replacement after a failed read. Prompt for AI agentsIn `modules/aiMixPlaylist.ts` at line 23:
**Existing playlists can be erased**
When `StorageService.loadPlaylists()` encounters a read or parse error, `persistAiMix` treats the returned empty array as a successful read and saves only the AI Mix, overwriting the user's other playlists.
Distinguish a failed playlist read from a valid empty list and do not save a replacement after a failed read. |
||
| const existing = stored.find((p) => p.id === AI_MIX_ID); | ||
| const playlist: Playlist = { | ||
| id: AI_MIX_ID, | ||
| name: aiMixName(language), | ||
| description: language === "fa" ? "از تاریخچه پخش شما" : "Built from your listening history", | ||
| tracks, | ||
| createdAt: existing?.createdAt ?? now, | ||
| updatedAt: now, | ||
| // The top track's art doubles as the cover: a real image beats a | ||
| // placeholder glyph, and it changes as the mix does. | ||
| thumbnail: tracks[0]?.thumbnail, | ||
| }; | ||
| // Replace in place, keep every other playlist, and put the mix first so | ||
| // it stays where the user expects it. | ||
| const rest = stored.filter((p) => p.id !== AI_MIX_ID); | ||
| await StorageService.savePlaylists([playlist, ...rest]); | ||
|
Comment on lines
+23
to
+39
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟠 High · Concurrent playlist changes disappear When another playlist writer or AI Mix generation saves between Serialize playlist read-modify-write operations or use an atomic update that preserves concurrent changes. Prompt for AI agentsIn `modules/aiMixPlaylist.ts` at lines 23-39:
**Concurrent playlist changes disappear**
When another playlist writer or AI Mix generation saves between `persistAiMix` loading and saving the list, `persistAiMix` saves its earlier snapshot over the concurrent change, so the user's playlist edit or newer mix disappears.
Serialize playlist read-modify-write operations or use an atomic update that preserves concurrent changes.There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Medium · Saved mix may not refresh the library When the metadata-cache update fails after the playlist write succeeds, Keep the metadata cache and library event consistent when a playlist write succeeds, even if the cache update initially fails. Also at Prompt for AI agentsIn `modules/aiMixPlaylist.ts` at line 39:
**Saved mix may not refresh the library**
When the metadata-cache update fails after the playlist write succeeds, `savePlaylists` rejects after storing the mix but before updating the metadata cache and emitting the library event, so the library may not refresh and the player shows no result alert.
Keep the metadata cache and library event consistent when a playlist write succeeds, even if the cache update initially fails.
Also at `components/FullPlayerModal.tsx:1693-1695`. |
||
| return playlist; | ||
| } | ||
|
|
||
| /** Playlist name in both languages; the id is what the code keys on. */ | ||
| export function aiMixName(language: "en" | "fa"): string { | ||
| return language === "fa" ? "میکس هوش مصنوعی" : "AI Mix"; | ||
|
|
@@ -16,7 +49,7 @@ export function aiMixName(language: "en" | "fa"): string { | |
| * The seed: what the user actually listens to, not just what they liked. | ||
| * Falls back to the most recent track when nothing has been played yet. | ||
| */ | ||
| async function pickSeed(liked: Track[], recent: Track[]): Promise<Track | null> { | ||
| export async function pickSeed(liked: Track[], recent: Track[]): Promise<Track | null> { | ||
| if (recent.length) { | ||
| return recent[0]; | ||
| } | ||
|
|
@@ -79,27 +112,5 @@ export async function generateAiMixPlaylist( | |
| return null; | ||
| } | ||
|
|
||
| const now = new Date().toISOString(); | ||
| // Read once, write once. addPlaylist re-reads the list internally, so | ||
| // going through it here would race another writer's change; and reading | ||
| // twice (once for `existing`, once for `rest`) lets the two disagree. | ||
| const stored = await StorageService.loadPlaylists(); | ||
| const existing = stored.find((p) => p.id === AI_MIX_ID); | ||
| const playlist: Playlist = { | ||
| id: AI_MIX_ID, | ||
| name: aiMixName(language), | ||
| description: language === "fa" ? "از تاریخچه پخش شما" : "Built from your listening history", | ||
| tracks, | ||
| createdAt: existing?.createdAt ?? now, | ||
| updatedAt: now, | ||
| // The top track's art doubles as the cover: a real image beats a | ||
| // placeholder glyph, and it changes as the mix does. | ||
| thumbnail: tracks[0]?.thumbnail, | ||
| }; | ||
|
|
||
| // Replace in place, keep every other playlist, and put the mix first so | ||
| // it stays where the user expects it. | ||
| const rest = stored.filter((p) => p.id !== AI_MIX_ID); | ||
| await StorageService.savePlaylists([playlist, ...rest]); | ||
| return playlist; | ||
| } | ||
| return persistAiMix(tracks, language); | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 Medium · Listening history sent to third party
When the user taps the AI Mix button with listening history available,
loadHistoryNamesputs ranked artist and track names into the prompt, andfetchFromposts it to Pollinations. The player tells the user only that an AI Mix is being generated, so they are not informed that personal listening preferences leave the device and are sent to an external service.Disclose the third-party transfer and obtain informed opt-in before sending history names, or keep the history-based generation on-device.
Also at
modules/aiMixGenerator.ts:128.Prompt for AI agents