Recommend new songs similar to a seed song.

Seed the search either with a known video_id, or with song (a free-text title, optionally narrowed with artist) to have the seed resolved via search internally -- e.g. "10 songs that relate to Kryptonite by 3 Doors Down" needs no separate lookup first. Exactly one of video_id or song must be given.

Combines YouTube Music's radio, its separate "related" signal, and the seed artist's own catalog plus related artists' catalogs, then ranks by how many independent signals agreed on each candidate. Never returns the seed song itself, and never returns a song already in Liked Music or in ANY of the user's playlists.

By default candidates can come from OTHER artists too (radio/related signals surface stylistically similar tracks, not just the seed artist's own catalog) -- pass same_artist_only=True to keep only songs credited to the seed's own artist(s), e.g. for "recommend songs BY artist X similar to song Y" requests.

language / exclude_languages filter the RESULTS independently of the seed, which is the point: seeding from a Punjabi song with language=["english"] returns English songs similar to it. Strict by default -- candidates with no language label are dropped, since a Punjabi-seeded pool is mostly Punjabi and keeping unlabelled ones would hand back exactly what was excluded. Pass allow_unlabelled_language=True to relax that; the response always reports what was dropped.

When a language filter leaves too few results -- seeding from a Punjabi song and asking for English usually does -- the surviving songs are used as fresh seeds to reach more of that language in the same neighbourhood, since filtering alone can only return what happened to be in the seed's own pool. Set expand_across_language=False to skip that and get the short list.

match_seed_tempo=True biases results toward the seed's own BPM (half- and double-time count as close). bpm sets a tempo target directly, and bpm_min/bpm_max bound it. Songs with no known BPM are kept and simply not scored on tempo.

Returns {"songs": [...], "notes": [...], "filters": {...}} -- notes carry anything the user should hear about, such as results dropped for having no language label.

The library exclusion set is cached for speed; newly liked songs are always honoured, but call refresh_library() after adding songs to a playlist by other means.

Recommend new songs based on an entire playlist.

Randomly samples up to seed_sample_size tracks from the playlist as seeds (the whole playlist if it's smaller), runs the same multi-signal candidate generation as recommend_from_song for each, and pools/ranks the results. Never returns a song already in Liked Music, already in the source playlist, or already in ANY other of the user's playlists.

The library exclusion set is cached for speed; newly liked songs are always honoured, but call refresh_library() after adding songs to a playlist by other means.

Return actual songs by a specific artist -- a direct catalog pull, not a similarity recommendation like recommend_from_song/recommend_from_playlist.

Resolves artist (a name) to its YouTube Music channel and pulls its real song catalog, excluding anything already in Liked Music OR in ANY of the user's playlists (not just one, unlike recommend_from_playlist's single-seed-playlist exclusion). Read-only: never adds results anywhere.

This is a hard requirement, not best-effort -- if fewer than limit qualifying songs exist after exclusion, this returns however many were actually found rather than padding the list. Check found vs requested in the result to see whether it fell short.

Remix/feature variants of the same underlying song (e.g. a track and its "(feat. ...)" credit under a different videoId) count once, not once per variant -- see variants_collapsed in the result.

The library exclusion set is cached for speed; newly liked songs are always honoured, but call refresh_library() after adding songs to a playlist by other means.

Rebuild the cached library exclusion set from scratch, right now.

Every recommendation tool excludes songs already in Liked Music or any of your playlists. That set is expensive to build (~20s), so it's cached and reused. Liking a song is picked up immediately regardless, but adding a song to some other playlist is only seen once the cache is rebuilt.

Call this after adding songs to a playlist by other means (e.g. a playlist-management tool) if you want the next recommendation to account for them without waiting out the cache TTL.

Recommend new songs that match how the listener actually feels right now.

Unlike recommend_from_song, the mood decides where candidates come from: seeds are drawn from the listener's OWN library nearest the target mood, then expanded through radio/related/artist signals and songs from YouTube's mood playlists. Results are still guaranteed absent from their library.

Describing the mood -- in priority order: vector The precise path, and the one to prefer. A dict with valence (-1..1, despairing->euphoric), energy (0..1, still->frantic), tension (0..1, resolved->anxious; this is what separates angry from excited) and depth (0..1, background ->lyric-forward). YOU should read the user's words and set these -- you understand "wistful but still wants to get things done" far better than any keyword list. feeling Their words verbatim, as a fallback when you'd rather not commit to numbers. Matched against a mood-word lexicon. context One of: Chill, Sleep, Focus, Commute, Feel good, Romance, Energize, Workout, Party, Gaming, Sad. If none are given, the mood is inferred from recent listening history.

arc shapes the sequence rather than returning a flat mood-matched set: mirror stay where they are and validate it (default) lift start where they are, rise gradually -- never jump straight to upbeat when someone is low, it reads as being told to cheer up settle descend to calm; an evening wind-down deepen go further in; sometimes you want to sit in it properly hold stay in a band with energy as a curve (workout: warmup/peak/cooldown)

genres optionally restricts the seeds to the listener's own genre playlists, e.g. ["Punjabi", "Hip-Hop & Rap"].

language / exclude_languages filter the RESULTS, e.g. language=["english"]. Strict by default: a candidate with no language label is dropped, because someone asking for English only wants a guarantee. The response says how many were dropped and why; pass allow_unlabelled_language=True to keep them.

bpm biases ranking toward a tempo (half- and double-time count as close). bpm_min/bpm_max bound it instead. Songs with no known BPM are KEPT and simply not scored on tempo -- Deezer has no tempo for much of the non-English catalogue, so dropping them would delete whole languages.

limit is a ceiling, not a guarantee. If fewer than limit songs genuinely fit the mood (rated, with a real fit -- not just an unrated placeholder score), the shortfall is NOT padded with weak filler to hit the number. Filler is capped at 25% of limit: asking for 100 with 7 genuine matches returns 32 (7 + 25), not 100. See match_quality in the result for the genuine/filler breakdown, and notes for the human-readable version.

If they also point at a specific playlist ("look at this playlist and recommend me songs for how I feel"), use recommend_from_playlist_for_mood instead -- it seeds from that playlist's own fitting tracks rather than from the whole library.

This is READ-ONLY. If they asked for a PLAYLIST rather than a list, this tool is step one of three: get the songs here, create the playlist from the returned videoIds with a playlist-management tool, then call refresh_library() so those tracks are excluded from later recommendations.

The result carries target (the mood aimed at), target_origin (where it came from), seeds (which of their songs it grew from), notes (caveats worth repeating to the user), match_quality (genuine vs. filler counts) and songs, each with its slot, mood fit and which signals surfaced it.

Recommend new songs from ONE playlist, shaped by how the listener feels.

For "I feel like this -- look at this playlist and find me songs". Use this over recommend_from_playlist whenever a mood is part of the ask, and over recommend_for_mood whenever a specific playlist is.

Unlike recommend_from_playlist, which samples a few tracks at random and ignores mood entirely: EVERY track in the playlist is read and scored for mood fit, and only genuine matches -- tracks whose own mood resolves and actually fits the target -- are used as seeds. An off-mood playlist therefore yields few seeds or none, which is reported rather than papered over by seeding from tracks that don't fit.

Seeding costs ~4 API calls per seed, so the best-fitting seeds are capped (default 20, override with seed_cap). seed_report in the result says how many tracks were considered, how many were genuine, and how many were capped away.

Mood arguments behave exactly as in recommend_for_mood (vector preferred, then feeling, then context; falls back to inferred mood). arc shapes the sequence the same way. Results are guaranteed absent from Liked Music, from this playlist, and from every other playlist -- and limit is a ceiling, not a guarantee: filler is capped at 25% of it, same as recommend_for_mood.

This is READ-ONLY -- it never creates a playlist or adds anything anywhere. To turn the result into a real playlist, pass the returned videoIds to a playlist-management tool, then call refresh_library() so the new tracks are excluded from later recommendations.

Infer the listener's current mood from recent listening, with evidence.

Returns the inferred vector, a plain-language described, a confidence, and evidence -- the specific observations behind it (a song on repeat, one artist dominating, valence drifting across the session).

Lead with the evidence, not the verdict. "You've had these three on loop since yesterday -- want something that sits there with you, or something that lifts?" is the point of this tool; asserting "you are sad" is not. Mood inference is often wrong, so offer it as a read the user can correct.

Explain why a song was recommended, in mood terms.

Reports the song's mood vector, which layer produced it (Claude reading the lyrics, YouTube mood-playlist membership, or the artist's own average), the named moods it sits closest to, and the mood it was last served against.

Record what the listener thought of a recommendation.

reaction is one of: loved, saved, skipped, wrong_mood.

wrong_mood is the valuable one -- it says the song was fine but the mood read was off, which is a different failure from simply not liking it. Anything marked skipped or wrong_mood is never recommended again.

Report how much of the mood index exists, so gaps are visible not silent.

Covers the mood-playlist crawl, how much of the listener's library carries a mood label and from which layer, and whether Claude-based labelling is configured. Low coverage means recommendations are ranking mostly on signal agreement rather than on mood -- worth saying out loud.