feat(taste): phase 1 — persistent per-user taste profile from graded engagement (#796)

Build a persistent, decaying model of each user's taste, recomputed daily, that later phases consume across every recommendation surface. Phase 1 only BUILDS the object — no behaviour change to what's surfaced yet. Core mechanic — graded engagement (replaces binary was_skipped for learning; was_skipped stays for History): a play's completion ratio maps to a signal in [-1,+1] via two linear ramps (instant-skip → -1, ~0.30 neutral, ≥0.90 → +1). Time-decayed (half-life ~75d) so recent behaviour dominates and the profile tracks drift. Per operator constraints: - No explicit dislike button — negatives come only from passive behaviour (early skips). Nothing recorded to regret or opt out of. - Negatives are track-scoped; artist/tag weight is the decayed SUM of their tracks' engagement, so one skip nets out against many good plays (a DB test asserts a liked artist stays positive despite an early-skipped track). A floor clamp bounds how negative any single entity can get. - migration 0035: taste_profile_artists / taste_profile_tags (signed weight, indexed by (user, weight DESC)). - internal/taste: engagement.go (pure curve + decay) + profile.go (accumulate plays + like bonuses, floor damping, size caps, atomic-replace). - scheduler: rebuildUserDaily recomputes the profile before the playlist build (so phase 2 can read it), best-effort — a taste failure never blocks playlist building. Wired into the daily job + startup catch-up only (not manual/lazy rebuilds). - tests: pure (engagement curve, decay, ranking, floor, genre split) + DB-backed (positive/negative weights, aggregation-protects-artist, like bonus, atomic replace). All green vs real Postgres. Config knobs live in taste.DefaultConfig() for now; wiring them into the server RecommendationConfig is a later follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 20:55:14 -04:00
parent 752906b054
commit 6e0d0e5723
11 changed files with 1156 additions and 8 deletions
@@ -497,6 +497,20 @@ type SystemPlaylistRun struct {
 	LastError   *string
 }

+type TasteProfileArtist struct {
+	UserID    pgtype.UUID
+	ArtistID  pgtype.UUID
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
+type TasteProfileTag struct {
+	UserID    pgtype.UUID
+	Tag       string
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
 type Track struct {
 	ID          pgtype.UUID
 	Title       string
@@ -0,0 +1,262 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: taste_profile.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const deleteTasteProfileArtistsForUser = `-- name: DeleteTasteProfileArtistsForUser :exec
+DELETE FROM taste_profile_artists WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileArtistsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileArtistsForUser, userID)
+	return err
+}
+
+const deleteTasteProfileTagsForUser = `-- name: DeleteTasteProfileTagsForUser :exec
+DELETE FROM taste_profile_tags WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileTagsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileTagsForUser, userID)
+	return err
+}
+
+const insertTasteProfileArtist = `-- name: InsertTasteProfileArtist :exec
+INSERT INTO taste_profile_artists (user_id, artist_id, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileArtistParams struct {
+	UserID   pgtype.UUID
+	ArtistID pgtype.UUID
+	Weight   float64
+}
+
+func (q *Queries) InsertTasteProfileArtist(ctx context.Context, arg InsertTasteProfileArtistParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileArtist, arg.UserID, arg.ArtistID, arg.Weight)
+	return err
+}
+
+const insertTasteProfileTag = `-- name: InsertTasteProfileTag :exec
+INSERT INTO taste_profile_tags (user_id, tag, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileTagParams struct {
+	UserID pgtype.UUID
+	Tag    string
+	Weight float64
+}
+
+func (q *Queries) InsertTasteProfileTag(ctx context.Context, arg InsertTasteProfileTagParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileTag, arg.UserID, arg.Tag, arg.Weight)
+	return err
+}
+
+const listLikedArtistIDsForUser = `-- name: ListLikedArtistIDsForUser :many
+SELECT artist_id FROM general_likes_artists WHERE user_id = $1
+`
+
+// Artists the user has explicitly liked; feeds the artist-like bonus.
+func (q *Queries) ListLikedArtistIDsForUser(ctx context.Context, userID pgtype.UUID) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, listLikedArtistIDsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var artist_id pgtype.UUID
+		if err := rows.Scan(&artist_id); err != nil {
+			return nil, err
+		}
+		items = append(items, artist_id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listLikedTrackTasteInputsForUser = `-- name: ListLikedTrackTasteInputsForUser :many
+SELECT t.artist_id, t.genre
+FROM general_likes gl
+JOIN tracks t ON t.id = gl.track_id
+WHERE gl.user_id = $1
+`
+
+type ListLikedTrackTasteInputsForUserRow struct {
+	ArtistID pgtype.UUID
+	Genre    *string
+}
+
+// (artist_id, genre) for each track the user has explicitly liked. Feeds the
+// track-like bonus into the liked track's artist and tags.
+func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID pgtype.UUID) ([]ListLikedTrackTasteInputsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listLikedTrackTasteInputsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListLikedTrackTasteInputsForUserRow
+	for rows.Next() {
+		var i ListLikedTrackTasteInputsForUserRow
+		if err := rows.Scan(&i.ArtistID, &i.Genre); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listPlayEngagementInputsForUser = `-- name: ListPlayEngagementInputsForUser :many
+
+SELECT
+    t.artist_id,
+    t.genre,
+    LEAST(GREATEST(
+        COALESCE(pe.completion_ratio,
+                 pe.duration_played_ms::float8 / NULLIF(t.duration_ms, 0),
+                 0), 0), 1)::float8 AS completion,
+    (EXTRACT(epoch FROM now() - pe.started_at) / 86400.0)::float8 AS age_days
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1
+  AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = $1 AND q.track_id = t.id
+  )
+`
+
+type ListPlayEngagementInputsForUserParams struct {
+	UserID  pgtype.UUID
+	Column2 float64
+}
+
+type ListPlayEngagementInputsForUserRow struct {
+	ArtistID   pgtype.UUID
+	Genre      *string
+	Completion float64
+	AgeDays    float64
+}
+
+// Taste profile (#796 phase 1). The daily build computes signed artist/tag
+// weights in Go (graded engagement + decay + like bonus) and atomic-replaces
+// them here. Read queries serve "top taste" lookups (used in phase 2).
+// One row per play in the decay-relevant window. completion is the play's
+// completion ratio (precomputed column when present, else duration_played /
+// track duration, clamped to [0,1]); age_days drives the time-decay. Genre
+// is split into tags in Go. Quarantined tracks are excluded.
+func (q *Queries) ListPlayEngagementInputsForUser(ctx context.Context, arg ListPlayEngagementInputsForUserParams) ([]ListPlayEngagementInputsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listPlayEngagementInputsForUser, arg.UserID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListPlayEngagementInputsForUserRow
+	for rows.Next() {
+		var i ListPlayEngagementInputsForUserRow
+		if err := rows.Scan(
+			&i.ArtistID,
+			&i.Genre,
+			&i.Completion,
+			&i.AgeDays,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTasteProfileArtistsForUser = `-- name: ListTasteProfileArtistsForUser :many
+SELECT artist_id, weight
+FROM taste_profile_artists
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileArtistsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileArtistsForUserRow struct {
+	ArtistID pgtype.UUID
+	Weight   float64
+}
+
+// Top-weighted taste artists (phase-2 consumption + tests).
+func (q *Queries) ListTasteProfileArtistsForUser(ctx context.Context, arg ListTasteProfileArtistsForUserParams) ([]ListTasteProfileArtistsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileArtistsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileArtistsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileArtistsForUserRow
+		if err := rows.Scan(&i.ArtistID, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTasteProfileTagsForUser = `-- name: ListTasteProfileTagsForUser :many
+SELECT tag, weight
+FROM taste_profile_tags
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileTagsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileTagsForUserRow struct {
+	Tag    string
+	Weight float64
+}
+
+func (q *Queries) ListTasteProfileTagsForUser(ctx context.Context, arg ListTasteProfileTagsForUserParams) ([]ListTasteProfileTagsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileTagsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileTagsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileTagsForUserRow
+		if err := rows.Scan(&i.Tag, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
@@ -0,0 +1,3 @@
+-- Reverse 0035_taste_profile.up.sql.
+DROP TABLE IF EXISTS taste_profile_tags;
+DROP TABLE IF EXISTS taste_profile_artists;
@@ -0,0 +1,33 @@
+-- 0035_taste_profile.up.sql — per-user taste profile (#796 phase 1).
+--
+-- A persistent, decaying model of each user's taste, rebuilt daily from
+-- graded play engagement (completion + skip position) plus explicit
+-- likes. Two facet tables: weighted artists and weighted genre tags.
+-- Weight is a signed float — positive = drawn to, negative = (passively)
+-- avoided; magnitude reflects decayed engagement. Phase 1 only BUILDS
+-- these; consumption (candidate sourcing + scoring) lands in phase 2.
+--
+-- CASCADE on user/artist deletes keeps them clean. Indexed by
+-- (user_id, weight DESC) to serve "top taste artists/tags" reads cheaply.
+
+CREATE TABLE taste_profile_artists (
+    user_id    uuid             NOT NULL REFERENCES users(id)   ON DELETE CASCADE,
+    artist_id  uuid             NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
+    weight     double precision NOT NULL,
+    updated_at timestamptz      NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, artist_id)
+);
+
+CREATE INDEX taste_profile_artists_user_weight_idx
+    ON taste_profile_artists (user_id, weight DESC);
+
+CREATE TABLE taste_profile_tags (
+    user_id    uuid             NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    tag        text             NOT NULL,
+    weight     double precision NOT NULL,
+    updated_at timestamptz      NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, tag)
+);
+
+CREATE INDEX taste_profile_tags_user_weight_idx
+    ON taste_profile_tags (user_id, weight DESC);
@@ -0,0 +1,66 @@
+-- Taste profile (#796 phase 1). The daily build computes signed artist/tag
+-- weights in Go (graded engagement + decay + like bonus) and atomic-replaces
+-- them here. Read queries serve "top taste" lookups (used in phase 2).
+
+-- name: ListPlayEngagementInputsForUser :many
+-- One row per play in the decay-relevant window. completion is the play's
+-- completion ratio (precomputed column when present, else duration_played /
+-- track duration, clamped to [0,1]); age_days drives the time-decay. Genre
+-- is split into tags in Go. Quarantined tracks are excluded.
+SELECT
+    t.artist_id,
+    t.genre,
+    LEAST(GREATEST(
+        COALESCE(pe.completion_ratio,
+                 pe.duration_played_ms::float8 / NULLIF(t.duration_ms, 0),
+                 0), 0), 1)::float8 AS completion,
+    (EXTRACT(epoch FROM now() - pe.started_at) / 86400.0)::float8 AS age_days
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1
+  AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = $1 AND q.track_id = t.id
+  );
+
+-- name: ListLikedTrackTasteInputsForUser :many
+-- (artist_id, genre) for each track the user has explicitly liked. Feeds the
+-- track-like bonus into the liked track's artist and tags.
+SELECT t.artist_id, t.genre
+FROM general_likes gl
+JOIN tracks t ON t.id = gl.track_id
+WHERE gl.user_id = $1;
+
+-- name: ListLikedArtistIDsForUser :many
+-- Artists the user has explicitly liked; feeds the artist-like bonus.
+SELECT artist_id FROM general_likes_artists WHERE user_id = $1;
+
+-- name: DeleteTasteProfileArtistsForUser :exec
+DELETE FROM taste_profile_artists WHERE user_id = $1;
+
+-- name: InsertTasteProfileArtist :exec
+INSERT INTO taste_profile_artists (user_id, artist_id, weight)
+VALUES ($1, $2, $3);
+
+-- name: DeleteTasteProfileTagsForUser :exec
+DELETE FROM taste_profile_tags WHERE user_id = $1;
+
+-- name: InsertTasteProfileTag :exec
+INSERT INTO taste_profile_tags (user_id, tag, weight)
+VALUES ($1, $2, $3);
+
+-- name: ListTasteProfileArtistsForUser :many
+-- Top-weighted taste artists (phase-2 consumption + tests).
+SELECT artist_id, weight
+FROM taste_profile_artists
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2;
+
+-- name: ListTasteProfileTagsForUser :many
+SELECT tag, weight
+FROM taste_profile_tags
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2;