feat(recommendation): SuggestArtists service for M5c

Add per-user artist-suggestion service ranking out-of-library MBIDs by signal x similarity. Single-CTE SQL collects user likes (5x weight) and recency-decayed plays, joins against artist_similarity_unmatched, and filters in-library candidates plus non-terminal lidarr_requests. The service resolves top-3 attribution seeds to artist names in a batched GetArtistsByIDs call so the UI can render "because you liked X" reasons. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 06:20:02 -04:00
parent 5e73f590a9
commit 277898a49a
6 changed files with 619 additions and 0 deletions
@@ -294,3 +294,99 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
 	}
 	return items, nil
 }
+
+const suggestArtistsForUser = `-- name: SuggestArtistsForUser :many
+WITH seeds AS (
+    SELECT a.id AS artist_id,
+           5.0 * (CASE WHEN gla.artist_id IS NOT NULL THEN 1 ELSE 0 END)
+           + COALESCE(SUM(EXP(- EXTRACT(epoch FROM now() - pe.started_at) / ($2::float8 * 86400.0))), 0)
+           AS signal,
+           (gla.artist_id IS NOT NULL) AS is_liked,
+           COUNT(pe.id)::bigint AS play_count
+    FROM artists a
+    LEFT JOIN general_likes_artists gla ON gla.artist_id = a.id AND gla.user_id = $1
+    LEFT JOIN tracks t ON t.artist_id = a.id
+    LEFT JOIN play_events pe ON pe.track_id = t.id AND pe.user_id = $1
+    WHERE gla.artist_id IS NOT NULL OR pe.id IS NOT NULL
+    GROUP BY a.id, gla.artist_id
+),
+contributions AS (
+    SELECT u.candidate_mbid,
+           u.candidate_name,
+           seeds.artist_id AS seed_id,
+           seeds.is_liked,
+           seeds.play_count,
+           seeds.signal * u.score AS contribution
+    FROM artist_similarity_unmatched u
+    JOIN seeds ON seeds.artist_id = u.seed_artist_id
+    WHERE NOT EXISTS (SELECT 1 FROM artists WHERE mbid = u.candidate_mbid)
+      AND NOT EXISTS (
+          SELECT 1 FROM lidarr_requests r
+           WHERE r.user_id = $1
+             AND r.lidarr_artist_mbid = u.candidate_mbid
+             AND r.status NOT IN ('rejected', 'failed')
+      )
+)
+SELECT candidate_mbid,
+       candidate_name,
+       SUM(contribution)::float8 AS total_score,
+       ((array_agg(seed_id      ORDER BY contribution DESC))[1:3])::uuid[]    AS top_seed_ids,
+       ((array_agg(contribution ORDER BY contribution DESC))[1:3])::float8[]  AS top_contributions,
+       ((array_agg(is_liked     ORDER BY contribution DESC))[1:3])::boolean[] AS top_is_liked,
+       ((array_agg(play_count   ORDER BY contribution DESC))[1:3])::bigint[]  AS top_play_counts
+FROM contributions
+GROUP BY candidate_mbid, candidate_name
+ORDER BY total_score DESC
+LIMIT $3
+`
+
+type SuggestArtistsForUserParams struct {
+	UserID  pgtype.UUID
+	Column2 float64
+	Limit   int32
+}
+
+type SuggestArtistsForUserRow struct {
+	CandidateMbid    string
+	CandidateName    string
+	TotalScore       float64
+	TopSeedIds       []pgtype.UUID
+	TopContributions []float64
+	TopIsLiked       []bool
+	TopPlayCounts    []int64
+}
+
+// M5c: per-user artist suggestions ranked by signal x similarity. The
+// seeds CTE collects the user's likes (x5) plus recency-decayed plays
+// (exp(-age_days / $2)). The contributions CTE joins those seeds against
+// artist_similarity_unmatched and filters out candidates already in
+// library or already in a non-terminal lidarr_request. The outer SELECT
+// aggregates per candidate, returning the top-3 contributing seeds for
+// attribution. $1=user_id, $2=half_life_days, $3=limit.
+func (q *Queries) SuggestArtistsForUser(ctx context.Context, arg SuggestArtistsForUserParams) ([]SuggestArtistsForUserRow, error) {
+	rows, err := q.db.Query(ctx, suggestArtistsForUser, arg.UserID, arg.Column2, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []SuggestArtistsForUserRow
+	for rows.Next() {
+		var i SuggestArtistsForUserRow
+		if err := rows.Scan(
+			&i.CandidateMbid,
+			&i.CandidateName,
+			&i.TotalScore,
+			&i.TopSeedIds,
+			&i.TopContributions,
+			&i.TopIsLiked,
+			&i.TopPlayCounts,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}