feat: Minstrel stops acquiring music and drops Discover
release / go (push) Successful in 1m54s
release / web (push) Failing after 5s
release / integration (push) Failing after 3m44s
release / govulncheck (push) Successful in 20s
release / Attach APK to the Release (tag releases only) (push) Canceled after 0s
release / Build + push container image (push) Canceled after 0s
release / Verify release artifacts (tag releases only) (push) Canceled after 0s
release / Build signed APK (push) Canceled after 19s
release / android (push) Canceled after 2m37s

Minstrel is now a viewer of the library it is pointed at. Finding,
downloading and filing music moves out of it.

Removed from the server:
- the request flow (requests, approval, auto-approve) and the wanted list,
  follows, release profiles and release blocks;
- searching indexers, the download clients, the importer, the album
  lifecycle and missing-file re-acquisition;
- the catalogue's discography, search and art (the MusicBrainz release and
  track-list cache stays, for the duplicate resolver);
- Discover: its suggestions of artists not in the library, snoozes, the
  candidate-artist tag enrichment and its tuning scope;
- writes to acquisition tables from moving the library folder and from
  merging duplicates, the want-list join on Suspect sources, the sealing of
  acquisition credentials, and the release-group lookup only
  re-acquisition used.

Settling a wrong-slot duplicate no longer sets the release aside: the
copies go and their slots show as missing until a good copy is in the
library.

Removed from the web: Admin > Acquisition and Requests, /requests,
/discover, Follow on the artist page, the auto-approve toggle, and the
Collection's wanted-list tabs. The Collection is now the library's health:
an overview, Reports, Duplicates, Suspect sources and Missing files. The
README and docs no longer describe getting music.

The tables stay for now; a later migration drops them. The request
notification kinds and the Android screens are still to go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-21 20:51:14 -05:00
co-authored by Claude Opus 5.5
parent dabe1e052d
commit 55c7497ca7
277 changed files with 521 additions and 40021 deletions
@@ -1,455 +0,0 @@
package recommendation
import (
"context"
"testing"
"github.com/jackc/pgx/v5/pgtype"
"github.com/jackc/pgx/v5/pgxpool"
"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)
// The candidate-artist tag cache for out-of-library Discover candidates. These
// cover the SQL rather than the provider chain — the eligibility query is the
// piece with real risk in it (a GROUP BY over a many-rows-per-candidate table,
// a LEFT JOIN to bookkeeping, and two exclusion branches), and it feeds this
// package's taste-tag ranking.
//
// Fixtures live here because the harness and seedUnmatched do.
const (
tagVersionCurrent = 2
tagVersionOld = 1
)
// listEligible is the query under test, at the current provider version.
func listEligible(t *testing.T, pool *pgxpool.Pool, limit int32) []dbq.ListCandidateArtistsMissingTagsRow {
t.Helper()
rows, err := dbq.New(pool).ListCandidateArtistsMissingTags(context.Background(),
dbq.ListCandidateArtistsMissingTagsParams{
TagSourcesVersion: tagVersionCurrent,
Limit: limit,
})
if err != nil {
t.Fatalf("ListCandidateArtistsMissingTags: %v", err)
}
return rows
}
func setState(t *testing.T, pool *pgxpool.Pool, mbid, source string, version int32) {
t.Helper()
if err := dbq.New(pool).SetCandidateArtistTagState(context.Background(),
dbq.SetCandidateArtistTagStateParams{
CandidateMbid: mbid, TagSource: source, TagSourcesVersion: version,
}); err != nil {
t.Fatalf("SetCandidateArtistTagState: %v", err)
}
}
func mbidsOf(rows []dbq.ListCandidateArtistsMissingTagsRow) []string {
out := make([]string, 0, len(rows))
for _, r := range rows {
out = append(out, r.CandidateMbid)
}
return out
}
func TestCandidateTags_NeverProcessedIsEligible(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, user.ID, seed.ID)
seedUnmatched(t, pool, seed.ID, "cand-1", "Candidate One", 0.9)
rows := listEligible(t, pool, 10)
if len(rows) != 1 {
t.Fatalf("len = %d, want 1: %v", len(rows), mbidsOf(rows))
}
if rows[0].CandidateName != "Candidate One" {
t.Errorf("name = %q, want Candidate One", rows[0].CandidateName)
}
if rows[0].TotalScore != 0.9 {
t.Errorf("score = %v, want 0.9", rows[0].TotalScore)
}
}
// An in-library candidate's tags belong in track_tags, and the suggestion query
// filters it out anyway — enriching it would be wasted API budget.
func TestCandidateTags_InLibraryCandidateIsExcluded(t *testing.T) {
pool := newPool(t)
seed := seedArtist(t, pool, "Seed", "")
seedArtist(t, pool, "Already Here", "cand-in-lib")
seedUnmatched(t, pool, seed.ID, "cand-in-lib", "Already Here", 0.9)
if rows := listEligible(t, pool, 10); len(rows) != 0 {
t.Errorf("len = %d, want 0: %v", len(rows), mbidsOf(rows))
}
}
func TestCandidateTags_SettledWithTagsIsExcluded(t *testing.T) {
pool := newPool(t)
seed := seedArtist(t, pool, "Seed", "")
seedUnmatched(t, pool, seed.ID, "cand-1", "Candidate One", 0.9)
setState(t, pool, "cand-1", "musicbrainz", tagVersionCurrent)
if rows := listEligible(t, pool, 10); len(rows) != 0 {
t.Errorf("len = %d, want 0 (already enriched): %v", len(rows), mbidsOf(rows))
}
}
// A candidate that settled 'none' becomes eligible again when the provider set
// widens (version bump) — that's the whole point of the version column. It must
// NOT be eligible at the current version, or the worker re-fetches it forever.
func TestCandidateTags_SettledNoneReopensOnlyOnVersionBump(t *testing.T) {
pool := newPool(t)
seed := seedArtist(t, pool, "Seed", "")
seedUnmatched(t, pool, seed.ID, "cand-1", "Candidate One", 0.9)
setState(t, pool, "cand-1", "none", tagVersionCurrent)
if rows := listEligible(t, pool, 10); len(rows) != 0 {
t.Errorf("current version: len = %d, want 0 (settled)", len(rows))
}
setState(t, pool, "cand-1", "none", tagVersionOld)
if rows := listEligible(t, pool, 10); len(rows) != 1 {
t.Errorf("older version: len = %d, want 1 (eligible again)", len(rows))
}
}
// artist_similarity_unmatched holds one row per (seed, candidate, source).
// Without the GROUP BY, a candidate that five seeds point at would be fetched
// five times — five times the MusicBrainz budget for identical data.
func TestCandidateTags_ManySeedsCollapseToOneRowAndSumScores(t *testing.T) {
pool := newPool(t)
seedA := seedArtist(t, pool, "Seed A", "")
seedB := seedArtist(t, pool, "Seed B", "")
seedUnmatched(t, pool, seedA.ID, "cand-1", "Candidate One", 0.4)
seedUnmatched(t, pool, seedB.ID, "cand-1", "Candidate One", 0.3)
rows := listEligible(t, pool, 10)
if len(rows) != 1 {
t.Fatalf("len = %d, want 1 (grouped): %v", len(rows), mbidsOf(rows))
}
if got := rows[0].TotalScore; got < 0.69 || got > 0.71 {
t.Errorf("total_score = %v, want ~0.7 (summed across seeds)", got)
}
}
// The pool is far larger than one pass can drain at ~1 req/s, so the ordering
// IS the feature: the strongest candidates must be enriched first, or the ones
// that actually reach a user's deck starve behind the long tail.
func TestCandidateTags_StrongestCandidatesComeFirst(t *testing.T) {
pool := newPool(t)
seed := seedArtist(t, pool, "Seed", "")
seedUnmatched(t, pool, seed.ID, "weak", "Weak", 0.1)
seedUnmatched(t, pool, seed.ID, "strong", "Strong", 0.95)
seedUnmatched(t, pool, seed.ID, "middle", "Middle", 0.5)
rows := listEligible(t, pool, 10)
want := []string{"strong", "middle", "weak"}
got := mbidsOf(rows)
if len(got) != 3 {
t.Fatalf("len = %d, want 3: %v", len(got), got)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("order = %v, want %v", got, want)
}
}
// And the limit takes the strongest, not an arbitrary slice.
if top := mbidsOf(listEligible(t, pool, 1)); len(top) != 1 || top[0] != "strong" {
t.Errorf("limit 1 returned %v, want [strong]", top)
}
}
func TestCandidateTags_InsertKeepsTheStrongerWeight(t *testing.T) {
pool := newPool(t)
q := dbq.New(pool)
ctx := context.Background()
ins := func(w float64) {
if err := q.InsertCandidateArtistTag(ctx, dbq.InsertCandidateArtistTagParams{
CandidateMbid: "cand-1", Tag: "shoegaze", Weight: w,
}); err != nil {
t.Fatalf("InsertCandidateArtistTag: %v", err)
}
}
ins(0.8)
ins(0.3) // weaker second write must not clobber
rows, err := q.ListCandidateArtistTagsForMbids(ctx, []string{"cand-1"})
if err != nil {
t.Fatalf("ListCandidateArtistTagsForMbids: %v", err)
}
if len(rows) != 1 {
t.Fatalf("len = %d, want 1", len(rows))
}
if rows[0].Weight != 0.8 {
t.Errorf("weight = %v, want 0.8 (GREATEST)", rows[0].Weight)
}
}
func TestCandidateTags_ListForMbidsIgnoresUnaskedCandidates(t *testing.T) {
pool := newPool(t)
q := dbq.New(pool)
ctx := context.Background()
for _, mbid := range []string{"want-1", "want-2", "other"} {
if err := q.InsertCandidateArtistTag(ctx, dbq.InsertCandidateArtistTagParams{
CandidateMbid: mbid, Tag: "rock", Weight: 1,
}); err != nil {
t.Fatalf("insert %s: %v", mbid, err)
}
}
rows, err := q.ListCandidateArtistTagsForMbids(ctx, []string{"want-1", "want-2"})
if err != nil {
t.Fatalf("ListCandidateArtistTagsForMbids: %v", err)
}
if len(rows) != 2 {
t.Errorf("len = %d, want 2", len(rows))
}
for _, r := range rows {
if r.CandidateMbid == "other" {
t.Error("returned a candidate that wasn't asked for")
}
}
}
// The similarity feed is refetched and churns, so without the sweep the cache
// only grows. Both halves must survive/die together for the right candidates.
func TestCandidateTags_GcDropsOrphansAndKeepsLiveOnes(t *testing.T) {
pool := newPool(t)
q := dbq.New(pool)
ctx := context.Background()
seed := seedArtist(t, pool, "Seed", "")
seedUnmatched(t, pool, seed.ID, "live", "Live", 0.9)
// "gone" is cached but no longer in the feed; "adopted" got added to the
// library since, so its tags belong in track_tags now.
seedArtist(t, pool, "Adopted", "adopted")
seedUnmatched(t, pool, seed.ID, "adopted", "Adopted", 0.8)
for _, mbid := range []string{"live", "gone", "adopted"} {
if err := q.InsertCandidateArtistTag(ctx, dbq.InsertCandidateArtistTagParams{
CandidateMbid: mbid, Tag: "rock", Weight: 1,
}); err != nil {
t.Fatalf("insert %s: %v", mbid, err)
}
setState(t, pool, mbid, "musicbrainz", tagVersionCurrent)
}
deleted, err := q.GcDeleteOrphanedCandidateArtistTags(ctx)
if err != nil {
t.Fatalf("GcDeleteOrphanedCandidateArtistTags: %v", err)
}
if deleted != 2 {
t.Errorf("deleted %d tag rows, want 2 (gone + adopted)", deleted)
}
deletedState, err := q.GcDeleteOrphanedCandidateArtistTagState(ctx)
if err != nil {
t.Fatalf("GcDeleteOrphanedCandidateArtistTagState: %v", err)
}
if deletedState != 2 {
t.Errorf("deleted %d state rows, want 2", deletedState)
}
rows, err := q.ListCandidateArtistTagsForMbids(ctx, []string{"live", "gone", "adopted"})
if err != nil {
t.Fatalf("ListCandidateArtistTagsForMbids: %v", err)
}
if len(rows) != 1 || rows[0].CandidateMbid != "live" {
t.Errorf("survivors = %v, want [live] only", rows)
}
}
// Coverage is the admin's window onto the honest ceiling: processed vs
// actually-tagged. A big gap means thin upstream data, not a broken worker.
func TestCandidateTags_CoverageCountsProcessedAndTagged(t *testing.T) {
pool := newPool(t)
setState(t, pool, "has-tags", "musicbrainz", tagVersionCurrent)
setState(t, pool, "mixed-tags", "mixed", tagVersionCurrent)
setState(t, pool, "no-tags", "none", tagVersionCurrent)
got, err := dbq.New(pool).CountCandidateArtistTagCoverage(context.Background())
if err != nil {
t.Fatalf("CountCandidateArtistTagCoverage: %v", err)
}
if got.Processed != 3 {
t.Errorf("processed = %d, want 3", got.Processed)
}
if got.WithTags != 2 {
t.Errorf("with_tags = %d, want 2 ('none' excluded)", got.WithTags)
}
}
// --- The taste-tag blend, end to end ---
//
// The pure tests in tagoverlap_test.go cover the scoring maths. These cover the
// wiring the pure tests cannot reach: that loadTagInputs actually reads both
// sides from the DB and that the blend reaches the returned deck.
func seedTasteTag(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID, tag string, weight float64) {
t.Helper()
if _, err := pool.Exec(context.Background(),
`INSERT INTO taste_profile_tags (user_id, tag, weight) VALUES ($1, $2, $3)
ON CONFLICT (user_id, tag) DO UPDATE SET weight = EXCLUDED.weight`,
userID, tag, weight,
); err != nil {
t.Fatalf("seedTasteTag: %v", err)
}
}
func seedCandidateTag(t *testing.T, pool *pgxpool.Pool, mbid, tag string, weight float64) {
t.Helper()
if err := dbq.New(pool).InsertCandidateArtistTag(context.Background(),
dbq.InsertCandidateArtistTagParams{CandidateMbid: mbid, Tag: tag, Weight: weight},
); err != nil {
t.Fatalf("seedCandidateTag: %v", err)
}
}
// twoCandidatePool wires a liked seed with two unmatched neighbours: "loud"
// scores higher on similarity, "match" lower. Skewed on purpose — with equal
// similarity the reorder assertion below could not fail.
func twoCandidatePool(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID) {
t.Helper()
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, userID, seed.ID)
seedUnmatched(t, pool, seed.ID, "loud", "Loud Neighbour", 0.9)
seedUnmatched(t, pool, seed.ID, "match", "Taste Match", 0.6)
}
func TestSuggestArtists_TasteTagMatchOvertakesStrongerSimilarity(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
twoCandidatePool(t, pool, user.ID)
seedTasteTag(t, pool, user.ID, "shoegaze", 10)
seedCandidateTag(t, pool, "match", "shoegaze", 1.0)
seedCandidateTag(t, pool, "loud", "death metal", 1.0)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 1.0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 2 {
t.Fatalf("len = %d, want 2", len(out))
}
if out[0].MBID != "match" {
t.Errorf("first = %q, want match (0.6×2 beats 0.9×1)", out[0].MBID)
}
// And it explains itself.
if len(out[0].MatchedTags) != 1 || out[0].MatchedTags[0] != "shoegaze" {
t.Errorf("matched tags = %v, want [shoegaze]", out[0].MatchedTags)
}
if out[1].MatchedTags != nil {
t.Errorf("non-matching candidate got matched tags: %v", out[1].MatchedTags)
}
}
// The same fixture with the knob at 0 must return pure similarity order — the
// off switch, verified against a real DB rather than assumed.
func TestSuggestArtists_ZeroTagWeightKeepsSimilarityOrder(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
twoCandidatePool(t, pool, user.ID)
seedTasteTag(t, pool, user.ID, "shoegaze", 10)
seedCandidateTag(t, pool, "match", "shoegaze", 1.0)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if out[0].MBID != "loud" {
t.Errorf("first = %q, want loud (tag term disabled)", out[0].MBID)
}
}
// A user with no taste profile must still get a full deck in similarity order:
// the cold-start path, which is every user's first days.
func TestSuggestArtists_NoTasteTagsStillReturnsSimilarityOrder(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
twoCandidatePool(t, pool, user.ID)
// Candidate tags exist, but the user has no taste tags to match them.
seedCandidateTag(t, pool, "match", "shoegaze", 1.0)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 1.0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 2 {
t.Fatalf("len = %d, want 2 (nothing dropped)", len(out))
}
if out[0].MBID != "loud" {
t.Errorf("first = %q, want loud", out[0].MBID)
}
}
// An untagged candidate must never be dropped or sunk just because another
// candidate has tags — permanently-partial coverage must not become a
// permanent ranking penalty.
func TestSuggestArtists_UntaggedCandidateSurvivesAlongsideTagged(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
twoCandidatePool(t, pool, user.ID)
seedTasteTag(t, pool, user.ID, "shoegaze", 10)
seedCandidateTag(t, pool, "match", "shoegaze", 1.0)
// "loud" is deliberately left with NO cached tags at all.
// Compared against the same request with the term disabled, rather than
// against a literal. The pool score is signal-weighted by the seed query
// (ln(1+signal) x similarity), so hardcoding a number here would assert
// against the seeding maths — a different layer — and break whenever that
// changes. The property under test is only that the blend leaves an
// untagged candidate alone.
blended, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 1.0)
if err != nil {
t.Fatalf("SuggestArtists(blended): %v", err)
}
baseline, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists(baseline): %v", err)
}
if len(blended) != 2 {
t.Fatalf("len = %d, want 2 — the untagged candidate must still appear", len(blended))
}
scoreOf := func(out []ArtistSuggestion, mbid string) (float64, bool) {
for _, s := range out {
if s.MBID == mbid {
return s.Score, true
}
}
return 0, false
}
want, ok := scoreOf(baseline, "loud")
if !ok {
t.Fatal("untagged candidate missing from the baseline deck")
}
got, ok := scoreOf(blended, "loud")
if !ok {
t.Fatal("untagged candidate vanished once the tag term was enabled")
}
if got != want {
t.Errorf("untagged score = %v, want %v (identical to the term-disabled run)", got, want)
}
// Sanity: the tagged candidate DID move, so the comparison above is
// meaningful rather than both runs being trivially identical.
if tagged, _ := scoreOf(blended, "match"); tagged == mustScore(t, baseline, "match") {
t.Error("the tagged candidate's score did not change — the term did nothing")
}
}
func mustScore(t *testing.T, out []ArtistSuggestion, mbid string) float64 {
t.Helper()
for _, s := range out {
if s.MBID == mbid {
return s.Score
}
}
t.Fatalf("no candidate %q in %v", mbid, out)
return 0
}
@@ -0,0 +1,121 @@
package recommendation
// Shared fixtures for this package's integration tests.
import (
"context"
"io"
"log/slog"
"os"
"testing"
"time"
"github.com/jackc/pgx/v5/pgtype"
"github.com/jackc/pgx/v5/pgxpool"
"git.fabledsword.com/bvandeusen/minstrel/internal/db"
"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
"git.fabledsword.com/bvandeusen/minstrel/internal/dbtest"
)
func newPool(t *testing.T) *pgxpool.Pool {
t.Helper()
if testing.Short() {
t.Skip("skipping integration test in -short mode")
}
dsn := os.Getenv("MINSTREL_TEST_DATABASE_URL")
if dsn == "" {
t.Skip("MINSTREL_TEST_DATABASE_URL not set")
}
if err := db.Migrate(dsn, slog.New(slog.NewTextHandler(io.Discard, nil))); err != nil {
t.Fatalf("migrate: %v", err)
}
pool, err := pgxpool.New(context.Background(), dsn)
if err != nil {
t.Fatalf("pool: %v", err)
}
t.Cleanup(pool.Close)
dbtest.ResetDB(t, pool)
return pool
}
func seedUser(t *testing.T, pool *pgxpool.Pool, name string) dbq.User {
t.Helper()
u, err := dbq.New(pool).CreateUser(context.Background(), dbq.CreateUserParams{
Username: dbtest.TestUserPrefix + name, PasswordHash: "x",
ApiTokenHash: name + "-token", IsAdmin: false,
})
if err != nil {
t.Fatalf("seed user: %v", err)
}
return u
}
func seedArtist(t *testing.T, pool *pgxpool.Pool, name, mbid string) dbq.Artist {
t.Helper()
var mbidPtr *string
if mbid != "" {
mbidPtr = &mbid
}
a, err := dbq.New(pool).UpsertArtist(context.Background(), dbq.UpsertArtistParams{
Name: name, SortName: name, Mbid: mbidPtr,
})
if err != nil {
t.Fatalf("seed artist: %v", err)
}
return a
}
func seedAlbumForArtist(t *testing.T, pool *pgxpool.Pool, artistID pgtype.UUID, title string) dbq.Album {
t.Helper()
a, err := dbq.New(pool).UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
Title: title, SortTitle: title, ArtistID: artistID,
})
if err != nil {
t.Fatalf("seed album: %v", err)
}
return a
}
func seedTrackOnAlbum(t *testing.T, pool *pgxpool.Pool, albumID, artistID pgtype.UUID, title string) dbq.Track {
t.Helper()
tr, err := dbq.New(pool).UpsertTrack(context.Background(), dbq.UpsertTrackParams{
Title: title, AlbumID: albumID, ArtistID: artistID,
DurationMs: 1000, FilePath: "/tmp/m5c-" + title + ".mp3",
FileSize: 1, FileFormat: "mp3",
})
if err != nil {
t.Fatalf("seed track: %v", err)
}
return tr
}
func insertPlayEvent(t *testing.T, pool *pgxpool.Pool, userID, trackID pgtype.UUID, startedAt time.Time) {
t.Helper()
ctx := context.Background()
var sessionID pgtype.UUID
if err := pool.QueryRow(ctx,
`INSERT INTO play_sessions (user_id, started_at, last_event_at, client_id)
VALUES ($1, $2, $2, 'm5c-test') RETURNING id`,
userID, startedAt,
).Scan(&sessionID); err != nil {
t.Fatalf("insert play_session: %v", err)
}
if _, err := pool.Exec(ctx,
`INSERT INTO play_events (user_id, track_id, session_id, started_at, was_skipped)
VALUES ($1, $2, $3, $4, false)`,
userID, trackID, sessionID, startedAt,
); err != nil {
t.Fatalf("insert play_event: %v", err)
}
}
func likeArtist(t *testing.T, pool *pgxpool.Pool, userID, artistID pgtype.UUID) {
t.Helper()
if _, err := pool.Exec(context.Background(),
`INSERT INTO general_likes_artists (user_id, artist_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
userID, artistID,
); err != nil {
t.Fatalf("like artist: %v", err)
}
}
-322
View File
@@ -1,322 +0,0 @@
// suggestions.go is the per-user artist-suggestion service behind the
// Discover request surface. Seeds from the taste profile (falling back to
// likes + completed plays for a user who has none yet), projects those seeds
// through artist_similarity_unmatched via a single CTE, and returns top-N
// out-of-library candidates with top-3 attribution seeds resolved to names.
//
// Seeding from the taste profile rather than raw likes + plays matters: raw
// counts grow without bound and count skips as engagement, so a few
// heavily-played artists would monopolize every slot and entrench harder the
// more the user listened. See internal/db/queries/recommendation.sql for the
// tiering.
package recommendation
import (
"context"
"crypto/md5"
"encoding/hex"
"fmt"
"sort"
"time"
"github.com/jackc/pgx/v5/pgtype"
"github.com/jackc/pgx/v5/pgxpool"
"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
)
// ArtistSuggestion is one ranked candidate with its top-3 attribution seeds.
type ArtistSuggestion struct {
MBID string
Name string
Score float64
Attribution []SeedContribution
// MatchedTags are the candidate's own tags that overlap the user's taste
// profile, strongest first (max 3) — the "matches: shoegaze, melancholic"
// explanation. Empty when the candidate has no cached tags, which is
// common and not an error: coverage is permanently partial.
MatchedTags []string
// TagOverlap is the [0,1] share of the candidate's tag mass the user likes.
// Exposed for admin tuning — seeing the term's actual distribution is how
// a weight gets picked rather than guessed.
TagOverlap float64
}
// SeedContribution is one of the top-3 contributing seeds for a candidate.
type SeedContribution struct {
ArtistID pgtype.UUID
Name string
Contribution float64
IsLiked bool
PlayCount int64
}
// SuggestArtists returns top-N artist suggestions for the user. limit is
// capped at 50 (default 12 when out of range).
//
// halfLifeDays (default 30) is the recency-decay half-life for the TIER-2
// seed path only — the likes + completed-plays fallback used while the user
// has no taste-profile rows yet. Once the profile is populated it seeds
// instead, carrying its own decay, so this knob stops applying.
func SuggestArtists(
ctx context.Context, pool *pgxpool.Pool, userID pgtype.UUID,
halfLifeDays float64, limit int, tagOverlapWeight float64,
) ([]ArtistSuggestion, error) {
if limit <= 0 || limit > 50 {
limit = 12
}
if halfLifeDays <= 0 {
halfLifeDays = 30
}
q := dbq.New(pool)
// Over-fetch so there is something to rotate through. A deterministic
// top-N over a score ordering shows the same faces every day until one is
// requested away, leaving the tail of the ranking unreachable. Selection
// from this pool happens in selectSuggestions.
rows, err := q.SuggestArtistsForUser(ctx, dbq.SuggestArtistsForUserParams{
UserID: userID,
Column2: halfLifeDays,
Limit: int32(poolSizeFor(limit)),
})
if err != nil {
return nil, fmt.Errorf("suggest: query: %w", err)
}
if len(rows) == 0 {
return []ArtistSuggestion{}, nil
}
// Collect the union of top-3 seed IDs across all rows for one batched
// name lookup. pgtype.UUID is a comparable struct so it works as a map
// key directly.
seedSet := make(map[pgtype.UUID]struct{}, len(rows)*3)
for _, r := range rows {
for _, sid := range r.TopSeedIds {
seedSet[sid] = struct{}{}
}
}
seedIDs := make([]pgtype.UUID, 0, len(seedSet))
for id := range seedSet {
seedIDs = append(seedIDs, id)
}
artists, err := q.GetArtistsByIDs(ctx, seedIDs)
if err != nil {
return nil, fmt.Errorf("suggest: resolve seeds: %w", err)
}
nameByID := make(map[pgtype.UUID]string, len(artists))
for _, a := range artists {
nameByID[a.ID] = a.Name
}
out := make([]ArtistSuggestion, 0, len(rows))
for _, r := range rows {
attribution := make([]SeedContribution, 0, len(r.TopSeedIds))
for i, sid := range r.TopSeedIds {
if i >= len(r.TopContributions) || i >= len(r.TopIsLiked) || i >= len(r.TopPlayCounts) {
break
}
attribution = append(attribution, SeedContribution{
ArtistID: sid,
Name: nameByID[sid],
Contribution: r.TopContributions[i],
IsLiked: r.TopIsLiked[i],
PlayCount: r.TopPlayCounts[i],
})
}
out = append(out, ArtistSuggestion{
MBID: r.CandidateMbid,
Name: r.CandidateName,
Score: r.TotalScore,
Attribution: attribution,
})
}
// Taste-tag term. Applied to the whole over-fetched pool BEFORE
// selection, so the rotation and diversity rules in selectSuggestions
// operate on taste-blended scores — boosting only the twelve already
// chosen by similarity would leave the actual re-ranking undone.
//
// A query error here is returned, NOT degraded past. Graceful degradation
// is for expected absence — no taste profile yet, no cached tags for a
// candidate — and both of those are handled explicitly as empty inputs
// below. A failing query is neither: swallowing it would hide a broken DB
// behind a subtly worse ranking that nothing reports.
tasteTags, candTags, err := loadTagInputs(ctx, q, userID, out)
if err != nil {
return nil, err
}
out = applyTagOverlap(out, candTags, tasteTags, tagOverlapWeight)
return selectSuggestions(out, limit, rotationDay(time.Now())), nil
}
// tasteTagLimit caps how many of the user's taste tags participate. The
// profile's long tail is near-zero weight and contributes nothing after
// normalization, so this bounds the query rather than the meaning.
const tasteTagLimit = 50
// loadTagInputs fetches both sides of the overlap comparison: the user's taste
// tags and the cached tags for exactly the candidates in this pool.
func loadTagInputs(
ctx context.Context, q *dbq.Queries, userID pgtype.UUID, pool []ArtistSuggestion,
) (TagWeights, map[string]TagWeights, error) {
tasteRows, err := q.ListTasteProfileTagsForUser(ctx, dbq.ListTasteProfileTagsForUserParams{
UserID: userID,
Limit: tasteTagLimit,
})
if err != nil {
return nil, nil, fmt.Errorf("suggest: taste tags: %w", err)
}
// No taste tags is a cold start, not a failure — return early and skip the
// candidate-tag fetch entirely, since nothing could match.
if len(tasteRows) == 0 {
return nil, nil, nil
}
taste := make(TagWeights, len(tasteRows))
for _, r := range tasteRows {
taste[r.Tag] = r.Weight
}
mbids := make([]string, 0, len(pool))
for _, s := range pool {
mbids = append(mbids, s.MBID)
}
tagRows, err := q.ListCandidateArtistTagsForMbids(ctx, mbids)
if err != nil {
return nil, nil, fmt.Errorf("suggest: candidate tags: %w", err)
}
byCandidate := make(map[string]TagWeights, len(pool))
for _, r := range tagRows {
if byCandidate[r.CandidateMbid] == nil {
byCandidate[r.CandidateMbid] = TagWeights{}
}
byCandidate[r.CandidateMbid][r.Tag] = r.Weight
}
return taste, byCandidate, nil
}
// Pool multiplier: how many scored candidates to fetch per slot shown, so the
// rotation has somewhere to rotate. 4x keeps a day's deck genuinely different
// from yesterday's without pulling the whole long tail (whose scores are noise)
// into every request.
const suggestionPoolFactor = 4
// Hard ceiling on the fetched pool. The scored tail past this is low-signal, so
// paying for it would buy churn rather than better suggestions.
const suggestionPoolMax = 60
func poolSizeFor(limit int) int {
n := limit * suggestionPoolFactor
if n > suggestionPoolMax {
return suggestionPoolMax
}
return n
}
// rotationDay is the bucket the daily rotation hashes against. Server-local
// date, matching the `current_date` the Home rows already rotate on, so the
// whole product turns over at the same moment.
func rotationDay(now time.Time) string {
return now.Format("2006-01-02")
}
// selectSuggestions turns the scored pool into the response.
//
// Pure by design — no DB, no clock — so the rotation and diversity rules are
// unit-testable without Postgres. Callers pass the day bucket in.
//
// Three rules, in order:
//
// 1. Diversity cap. Walking in score order, a candidate is dropped once its
// dominant seed already owns maxPerSeed slots, so twelve slots cannot all
// be neighbours of one artist and read as a single narrow cluster.
// 2. Head. The best few by score always lead, so the strongest matches are
// never rotated out of sight. Mirrors For You's head/tail shape.
// 3. Tail. The rest of the slots are drawn from the remaining pool ordered by
// md5(mbid + day) — the same daily-stable idiom the Home rows use. Stable
// within a day, different tomorrow, and it needs no stored state.
func selectSuggestions(pool []ArtistSuggestion, limit int, day string) []ArtistSuggestion {
if len(pool) <= limit {
return pool
}
preferred, overflow := partitionPerSeed(pool, maxPerSeedFor(limit))
headCount := limit / 3
if headCount > len(preferred) {
headCount = len(preferred)
}
out := make([]ArtistSuggestion, 0, limit)
out = append(out, preferred[:headCount]...)
// Hash once per candidate, not once per comparison.
rest := preferred[headCount:]
tail := make([]rotatable, 0, len(rest))
for _, s := range rest {
tail = append(tail, rotatable{key: rotationKey(s.MBID, day), suggestion: s})
}
sort.SliceStable(tail, func(i, j int) bool { return tail[i].key < tail[j].key })
for _, r := range tail {
if len(out) >= limit {
break
}
out = append(out, r.suggestion)
}
// Diversity is a PREFERENCE, not a quota that may starve the deck. A user
// whose whole pool hangs off one or two seeds would otherwise get a
// three-card surface, which is worse than the monoculture it avoids.
// Top up
// in score order from what the cap set aside.
for _, s := range overflow {
if len(out) >= limit {
break
}
out = append(out, s)
}
return out
}
// rotatable pairs a candidate with its precomputed daily rotation key.
type rotatable struct {
key string
suggestion ArtistSuggestion
}
// maxPerSeedFor keeps roughly a quarter of the deck attributable to any single
// seed artist — enough for a strong affinity to be well represented, not enough
// for it to BE the deck. Floored at 1 so a small limit still returns something.
func maxPerSeedFor(limit int) int {
n := limit / 4
if n < 1 {
return 1
}
return n
}
// partitionPerSeed splits the pool by whether each candidate's dominant
// (highest-contributing) seed still has allowance left. Input must be in score
// order; both outputs preserve it.
//
// Candidates with no attribution are always preferred — there is no seed to
// attribute them to, so they cannot be the cause of a monoculture.
func partitionPerSeed(pool []ArtistSuggestion, maxPerSeed int) (preferred, overflow []ArtistSuggestion) {
perSeed := make(map[pgtype.UUID]int, len(pool))
preferred = make([]ArtistSuggestion, 0, len(pool))
for _, s := range pool {
if len(s.Attribution) == 0 {
preferred = append(preferred, s)
continue
}
dominant := s.Attribution[0].ArtistID
if perSeed[dominant] >= maxPerSeed {
overflow = append(overflow, s)
continue
}
perSeed[dominant]++
preferred = append(preferred, s)
}
return preferred, overflow
}
func rotationKey(mbid, day string) string {
sum := md5.Sum([]byte(mbid + day))
return hex.EncodeToString(sum[:])
}
@@ -1,687 +0,0 @@
package recommendation
import (
"context"
"fmt"
"io"
"log/slog"
"os"
"testing"
"time"
"github.com/jackc/pgx/v5/pgtype"
"github.com/jackc/pgx/v5/pgxpool"
"git.fabledsword.com/bvandeusen/minstrel/internal/db"
"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
"git.fabledsword.com/bvandeusen/minstrel/internal/dbtest"
)
func newPool(t *testing.T) *pgxpool.Pool {
t.Helper()
if testing.Short() {
t.Skip("skipping integration test in -short mode")
}
dsn := os.Getenv("MINSTREL_TEST_DATABASE_URL")
if dsn == "" {
t.Skip("MINSTREL_TEST_DATABASE_URL not set")
}
if err := db.Migrate(dsn, slog.New(slog.NewTextHandler(io.Discard, nil))); err != nil {
t.Fatalf("migrate: %v", err)
}
pool, err := pgxpool.New(context.Background(), dsn)
if err != nil {
t.Fatalf("pool: %v", err)
}
t.Cleanup(pool.Close)
dbtest.ResetDB(t, pool)
return pool
}
func seedUser(t *testing.T, pool *pgxpool.Pool, name string) dbq.User {
t.Helper()
u, err := dbq.New(pool).CreateUser(context.Background(), dbq.CreateUserParams{
Username: dbtest.TestUserPrefix + name, PasswordHash: "x",
ApiTokenHash: name + "-token", IsAdmin: false,
})
if err != nil {
t.Fatalf("seed user: %v", err)
}
return u
}
func seedArtist(t *testing.T, pool *pgxpool.Pool, name, mbid string) dbq.Artist {
t.Helper()
var mbidPtr *string
if mbid != "" {
mbidPtr = &mbid
}
a, err := dbq.New(pool).UpsertArtist(context.Background(), dbq.UpsertArtistParams{
Name: name, SortName: name, Mbid: mbidPtr,
})
if err != nil {
t.Fatalf("seed artist: %v", err)
}
return a
}
func seedAlbumForArtist(t *testing.T, pool *pgxpool.Pool, artistID pgtype.UUID, title string) dbq.Album {
t.Helper()
a, err := dbq.New(pool).UpsertAlbum(context.Background(), dbq.UpsertAlbumParams{
Title: title, SortTitle: title, ArtistID: artistID,
})
if err != nil {
t.Fatalf("seed album: %v", err)
}
return a
}
func seedTrackOnAlbum(t *testing.T, pool *pgxpool.Pool, albumID, artistID pgtype.UUID, title string) dbq.Track {
t.Helper()
tr, err := dbq.New(pool).UpsertTrack(context.Background(), dbq.UpsertTrackParams{
Title: title, AlbumID: albumID, ArtistID: artistID,
DurationMs: 1000, FilePath: "/tmp/m5c-" + title + ".mp3",
FileSize: 1, FileFormat: "mp3",
})
if err != nil {
t.Fatalf("seed track: %v", err)
}
return tr
}
func insertPlayEvent(t *testing.T, pool *pgxpool.Pool, userID, trackID pgtype.UUID, startedAt time.Time) {
t.Helper()
ctx := context.Background()
var sessionID pgtype.UUID
if err := pool.QueryRow(ctx,
`INSERT INTO play_sessions (user_id, started_at, last_event_at, client_id)
VALUES ($1, $2, $2, 'm5c-test') RETURNING id`,
userID, startedAt,
).Scan(&sessionID); err != nil {
t.Fatalf("insert play_session: %v", err)
}
if _, err := pool.Exec(ctx,
`INSERT INTO play_events (user_id, track_id, session_id, started_at, was_skipped)
VALUES ($1, $2, $3, $4, false)`,
userID, trackID, sessionID, startedAt,
); err != nil {
t.Fatalf("insert play_event: %v", err)
}
}
func likeArtist(t *testing.T, pool *pgxpool.Pool, userID, artistID pgtype.UUID) {
t.Helper()
if _, err := pool.Exec(context.Background(),
`INSERT INTO general_likes_artists (user_id, artist_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
userID, artistID,
); err != nil {
t.Fatalf("like artist: %v", err)
}
}
func seedUnmatched(t *testing.T, pool *pgxpool.Pool, seedID pgtype.UUID, candMBID, candName string, score float64) {
t.Helper()
if err := dbq.New(pool).UpsertArtistSimilarityUnmatched(context.Background(), dbq.UpsertArtistSimilarityUnmatchedParams{
SeedArtistID: seedID,
CandidateMbid: candMBID,
CandidateName: candName,
Score: score,
Source: "listenbrainz",
}); err != nil {
t.Fatalf("seed unmatched: %v", err)
}
}
func TestSuggestArtists_LikesAndPlaysContributeToScore(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seedA := seedArtist(t, pool, "Seed Liked", "")
seedB := seedArtist(t, pool, "Seed Played", "")
likeArtist(t, pool, user.ID, seedA.ID)
seedBAlbum := seedAlbumForArtist(t, pool, seedB.ID, "Album B")
seedBTrack := seedTrackOnAlbum(t, pool, seedBAlbum.ID, seedB.ID, "Track B")
insertPlayEvent(t, pool, user.ID, seedBTrack.ID, time.Now().Add(-1*time.Hour))
seedUnmatched(t, pool, seedA.ID, "out-mbid", "Outsider", 0.9)
seedUnmatched(t, pool, seedB.ID, "out-mbid", "Outsider", 0.5)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1", len(out))
}
s := out[0]
if s.MBID != "out-mbid" || s.Name != "Outsider" {
t.Errorf("got = %+v", s)
}
if s.Score <= 0 {
t.Errorf("score = %v, want > 0", s.Score)
}
if len(s.Attribution) != 2 {
t.Errorf("attribution len = %d, want 2", len(s.Attribution))
}
}
func TestSuggestArtists_Top12Cap(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, user.ID, seed.ID)
for i := 0; i < 30; i++ {
seedUnmatched(t, pool, seed.ID, fmt.Sprintf("mbid-%02d", i), fmt.Sprintf("Artist %02d", i), 0.99-float64(i)*0.01)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 12 {
t.Errorf("len = %d, want 12", len(out))
}
if out[0].MBID != "mbid-00" {
t.Errorf("first = %s, want mbid-00 (highest score)", out[0].MBID)
}
}
func TestSuggestArtists_AttributionTopThree(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seeds := make([]dbq.Artist, 5)
for i := 0; i < 5; i++ {
seeds[i] = seedArtist(t, pool, fmt.Sprintf("Seed %d", i), "")
likeArtist(t, pool, user.ID, seeds[i].ID)
seedUnmatched(t, pool, seeds[i].ID, "shared-mbid", "Shared", 0.9-float64(i)*0.1)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1 (shared candidate)", len(out))
}
if got := len(out[0].Attribution); got != 3 {
t.Errorf("attribution len = %d, want 3", got)
}
if out[0].Attribution[0].Name != "Seed 0" {
t.Errorf("top attribution = %q, want Seed 0", out[0].Attribution[0].Name)
}
}
func TestSuggestArtists_RecencyDecayDownweightsOldPlays(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
recentSeed := seedArtist(t, pool, "Recent", "")
oldSeed := seedArtist(t, pool, "Old", "")
rAlbum := seedAlbumForArtist(t, pool, recentSeed.ID, "Recent Album")
rTrack := seedTrackOnAlbum(t, pool, rAlbum.ID, recentSeed.ID, "Recent Track")
insertPlayEvent(t, pool, user.ID, rTrack.ID, time.Now().Add(-1*24*time.Hour))
oAlbum := seedAlbumForArtist(t, pool, oldSeed.ID, "Old Album")
oTrack := seedTrackOnAlbum(t, pool, oAlbum.ID, oldSeed.ID, "Old Track")
insertPlayEvent(t, pool, user.ID, oTrack.ID, time.Now().Add(-90*24*time.Hour))
seedUnmatched(t, pool, recentSeed.ID, "cand", "Cand", 0.5)
seedUnmatched(t, pool, oldSeed.ID, "cand", "Cand", 0.5)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1", len(out))
}
if len(out[0].Attribution) != 2 {
t.Fatalf("attribution len = %d, want 2", len(out[0].Attribution))
}
if out[0].Attribution[0].Name != "Recent" {
t.Errorf("top attribution = %q, want Recent", out[0].Attribution[0].Name)
}
if out[0].Attribution[0].Contribution <= out[0].Attribution[1].Contribution {
t.Errorf("recent contribution (%v) should exceed old (%v)",
out[0].Attribution[0].Contribution, out[0].Attribution[1].Contribution)
}
}
func TestSuggestArtists_FiltersInLibraryCandidates(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, user.ID, seed.ID)
inLibMBID := "in-lib-mbid"
seedArtist(t, pool, "InLib", inLibMBID)
seedUnmatched(t, pool, seed.ID, inLibMBID, "InLib", 0.9)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 0 {
t.Errorf("len = %d, want 0 (in-library candidate should be filtered)", len(out))
}
}
func TestSuggestArtists_FiltersAlreadyRequested(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, user.ID, seed.ID)
seedUnmatched(t, pool, seed.ID, "req-mbid", "Pending Request", 0.9)
if _, err := dbq.New(pool).CreateRequest(context.Background(), dbq.CreateRequestParams{
UserID: user.ID,
Kind: dbq.RequestKindArtist,
ArtistMbid: "req-mbid",
ArtistName: "Pending Request",
}); err != nil {
t.Fatalf("CreateRequest: %v", err)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 0 {
t.Errorf("len = %d, want 0 (pending request should hide candidate)", len(out))
}
}
func TestSuggestArtists_RejectedRequestStillShown(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, user.ID, seed.ID)
seedUnmatched(t, pool, seed.ID, "rej-mbid", "Rejected Once", 0.9)
req, err := dbq.New(pool).CreateRequest(context.Background(), dbq.CreateRequestParams{
UserID: user.ID,
Kind: dbq.RequestKindArtist,
ArtistMbid: "rej-mbid",
ArtistName: "Rejected Once",
})
if err != nil {
t.Fatalf("CreateRequest: %v", err)
}
rejNotes := "wrong artist"
if _, err := dbq.New(pool).RejectRequest(context.Background(), dbq.RejectRequestParams{
ID: req.ID, Notes: &rejNotes, DecidedBy: user.ID,
}); err != nil {
t.Fatalf("RejectRequest: %v", err)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Errorf("len = %d, want 1 (rejected requests don't hide the candidate)", len(out))
}
}
func TestSuggestArtists_EmptyForNewUser(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "newbie")
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 0 {
t.Errorf("len = %d, want 0 (new user has no signal)", len(out))
}
}
// --- Taste-profile seeding, tiering, and skipped plays ---
func setTasteWeight(t *testing.T, pool *pgxpool.Pool, userID, artistID pgtype.UUID, weight float64) {
t.Helper()
if _, err := pool.Exec(context.Background(),
`INSERT INTO taste_profile_artists (user_id, artist_id, weight) VALUES ($1, $2, $3)
ON CONFLICT (user_id, artist_id) DO UPDATE SET weight = EXCLUDED.weight`,
userID, artistID, weight,
); err != nil {
t.Fatalf("set taste weight: %v", err)
}
}
func insertSkippedPlayEvent(t *testing.T, pool *pgxpool.Pool, userID, trackID pgtype.UUID, startedAt time.Time) {
t.Helper()
ctx := context.Background()
var sessionID pgtype.UUID
if err := pool.QueryRow(ctx,
`INSERT INTO play_sessions (user_id, started_at, last_event_at, client_id)
VALUES ($1, $2, $2, 'skip-test') RETURNING id`,
userID, startedAt,
).Scan(&sessionID); err != nil {
t.Fatalf("insert play_session: %v", err)
}
if _, err := pool.Exec(ctx,
`INSERT INTO play_events (user_id, track_id, session_id, started_at, was_skipped)
VALUES ($1, $2, $3, $4, true)`,
userID, trackID, sessionID, startedAt,
); err != nil {
t.Fatalf("insert skipped play_event: %v", err)
}
}
// Tier 1: a taste-profile weight alone seeds a suggestion, with no like and no
// play on the seed artist.
func TestSuggestArtists_TasteProfileWeightSeedsTier1(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seed := seedArtist(t, pool, "Profile Seed", "")
setTasteWeight(t, pool, user.ID, seed.ID, 4.0)
seedUnmatched(t, pool, seed.ID, "out-mbid", "Outsider", 0.9)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1 (taste weight alone should seed)", len(out))
}
if out[0].MBID != "out-mbid" {
t.Errorf("mbid = %q, want out-mbid", out[0].MBID)
}
if out[0].Score <= 0 {
t.Errorf("score = %v, want > 0", out[0].Score)
}
}
// Once the profile has any positive row, tier 2 is not consulted — so an artist
// the user played but that the taste engine did not keep does NOT seed. That is
// the point of the rewrite: the taste engine decides what counts as affinity.
func TestSuggestArtists_TasteProfileSupersedesRawPlays(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
kept := seedArtist(t, pool, "Kept By Taste", "")
dropped := seedArtist(t, pool, "Dropped By Taste", "")
setTasteWeight(t, pool, user.ID, kept.ID, 3.0)
// `dropped` has real completed plays but no profile row.
album := seedAlbumForArtist(t, pool, dropped.ID, "Album")
track := seedTrackOnAlbum(t, pool, album.ID, dropped.ID, "Track")
insertPlayEvent(t, pool, user.ID, track.ID, time.Now().Add(-1*time.Hour))
seedUnmatched(t, pool, kept.ID, "kept-cand", "Kept Candidate", 0.9)
seedUnmatched(t, pool, dropped.ID, "dropped-cand", "Dropped Candidate", 0.9)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1 (tier 2 must not run alongside tier 1)", len(out))
}
if out[0].MBID != "kept-cand" {
t.Errorf("mbid = %q, want kept-cand", out[0].MBID)
}
}
// A non-positive taste weight is not affinity. Guarded by a second, positive
// row so tier 1 stays active — otherwise an empty tier 1 would fall through to
// tier 2 and the assertion would pass for the wrong reason.
func TestSuggestArtists_NonPositiveTasteWeightDoesNotSeed(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
positive := seedArtist(t, pool, "Still Liked", "")
abandoned := seedArtist(t, pool, "Abandoned", "")
setTasteWeight(t, pool, user.ID, positive.ID, 2.0)
setTasteWeight(t, pool, user.ID, abandoned.ID, -1.5)
seedUnmatched(t, pool, positive.ID, "pos-cand", "Positive Candidate", 0.9)
seedUnmatched(t, pool, abandoned.ID, "neg-cand", "Negative Candidate", 0.9)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
for _, s := range out {
if s.MBID == "neg-cand" {
t.Fatalf("negative-weight artist seeded a suggestion: %+v", s)
}
}
if len(out) != 1 || out[0].MBID != "pos-cand" {
t.Errorf("out = %+v, want only pos-cand", out)
}
}
// Tier 2 counts COMPLETED plays only. Counting every play_event would make
// skipping an artist repeatedly increase its signal and push more of its
// neighbours at the user.
func TestSuggestArtists_SkippedPlaysDoNotSeedTier2(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
skipped := seedArtist(t, pool, "Only Skipped", "")
album := seedAlbumForArtist(t, pool, skipped.ID, "Album")
track := seedTrackOnAlbum(t, pool, album.ID, skipped.ID, "Track")
for i := 0; i < 5; i++ {
insertSkippedPlayEvent(t, pool, user.ID, track.ID, time.Now().Add(-time.Duration(i+1)*time.Hour))
}
seedUnmatched(t, pool, skipped.ID, "skip-cand", "Skip Candidate", 0.9)
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 0 {
t.Errorf("len = %d, want 0 (skips are not affinity): %+v", len(out), out)
}
}
// --- Time-boxed suggestion snooze ---
//
// The defining property under test is that a snooze EXPIRES: suggestions have
// no permanent "never show" control. A permanent dismissal would pass most of
// these; only TestSuggestArtists_ExpiredSnooze distinguishes the two.
// snoozeUntil inserts a snooze row with an explicit absolute expiry, so a
// test can place it in the past without depending on the duration arithmetic
// in SnoozeSuggestion.
func snoozeUntil(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID, mbid, name string, until time.Time) {
t.Helper()
if _, err := pool.Exec(context.Background(),
`INSERT INTO suggestion_snoozes (user_id, candidate_mbid, candidate_name, snoozed_until)
VALUES ($1, $2, $3, $4)
ON CONFLICT (user_id, candidate_mbid) DO UPDATE SET snoozed_until = EXCLUDED.snoozed_until`,
userID, mbid, name, until,
); err != nil {
t.Fatalf("snoozeUntil: %v", err)
}
}
// seedOneCandidate wires the minimum that puts exactly one candidate in the
// deck: a liked seed artist with one unmatched neighbour.
func seedOneCandidate(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID, mbid, name string) {
t.Helper()
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, userID, seed.ID)
seedUnmatched(t, pool, seed.ID, mbid, name, 0.9)
}
func TestSuggestArtists_ActiveSnoozeHidesCandidate(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seedOneCandidate(t, pool, user.ID, "snoozed-mbid", "Parked Artist")
if err := dbq.New(pool).SnoozeSuggestion(context.Background(), dbq.SnoozeSuggestionParams{
UserID: user.ID,
CandidateMbid: "snoozed-mbid",
CandidateName: "Parked Artist",
Column4: 90,
}); err != nil {
t.Fatalf("SnoozeSuggestion: %v", err)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 0 {
t.Errorf("len = %d, want 0 (active snooze should hide the candidate): %+v", len(out), out)
}
}
// The whole point of a snooze over a dismissal: it comes back on its own.
func TestSuggestArtists_ExpiredSnoozeShowsCandidateAgain(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seedOneCandidate(t, pool, user.ID, "expired-mbid", "Returning Artist")
snoozeUntil(t, pool, user.ID, "expired-mbid", "Returning Artist", time.Now().Add(-time.Hour))
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Fatalf("len = %d, want 1 (an expired snooze must not hide anything): %+v", len(out), out)
}
if out[0].MBID != "expired-mbid" {
t.Errorf("mbid = %q, want expired-mbid", out[0].MBID)
}
}
// One household member parking a suggestion must not remove it
// from anyone else's deck.
func TestSuggestArtists_SnoozeIsPerUser(t *testing.T) {
pool := newPool(t)
alice := seedUser(t, pool, "alice")
bob := seedUser(t, pool, "bob")
seed := seedArtist(t, pool, "Seed", "")
likeArtist(t, pool, alice.ID, seed.ID)
likeArtist(t, pool, bob.ID, seed.ID)
seedUnmatched(t, pool, seed.ID, "shared-mbid", "Shared Candidate", 0.9)
snoozeUntil(t, pool, alice.ID, "shared-mbid", "Shared Candidate", time.Now().Add(24*time.Hour))
aliceOut, err := SuggestArtists(context.Background(), pool, alice.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists(alice): %v", err)
}
if len(aliceOut) != 0 {
t.Errorf("alice len = %d, want 0 (she snoozed it)", len(aliceOut))
}
bobOut, err := SuggestArtists(context.Background(), pool, bob.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists(bob): %v", err)
}
if len(bobOut) != 1 {
t.Errorf("bob len = %d, want 1 (alice's snooze is not his)", len(bobOut))
}
}
func TestUnsnoozeSuggestion_RestoresImmediately(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
seedOneCandidate(t, pool, user.ID, "undo-mbid", "Undo Artist")
snoozeUntil(t, pool, user.ID, "undo-mbid", "Undo Artist", time.Now().Add(90*24*time.Hour))
q := dbq.New(pool)
rows, err := q.UnsnoozeSuggestion(context.Background(), dbq.UnsnoozeSuggestionParams{
UserID: user.ID, CandidateMbid: "undo-mbid",
})
if err != nil {
t.Fatalf("UnsnoozeSuggestion: %v", err)
}
if rows != 1 {
t.Errorf("rows = %d, want 1", rows)
}
// A second delete affects nothing — the handler turns this into a 404
// rather than reporting success for a no-op.
rows, err = q.UnsnoozeSuggestion(context.Background(), dbq.UnsnoozeSuggestionParams{
UserID: user.ID, CandidateMbid: "undo-mbid",
})
if err != nil {
t.Fatalf("UnsnoozeSuggestion (repeat): %v", err)
}
if rows != 0 {
t.Errorf("repeat rows = %d, want 0", rows)
}
out, err := SuggestArtists(context.Background(), pool, user.ID, 30, 12, 0)
if err != nil {
t.Fatalf("SuggestArtists: %v", err)
}
if len(out) != 1 {
t.Errorf("len = %d, want 1 (unsnooze restores the candidate)", len(out))
}
}
// Re-snoozing must extend, not conflict on the PK.
func TestSnoozeSuggestion_UpsertExtends(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
q := dbq.New(pool)
snoozeUntil(t, pool, user.ID, "extend-mbid", "Old Name", time.Now().Add(time.Hour))
if err := q.SnoozeSuggestion(context.Background(), dbq.SnoozeSuggestionParams{
UserID: user.ID,
CandidateMbid: "extend-mbid",
CandidateName: "New Name",
Column4: 90,
}); err != nil {
t.Fatalf("SnoozeSuggestion (re-snooze): %v", err)
}
rows, err := q.ListActiveSuggestionSnoozes(context.Background(), user.ID)
if err != nil {
t.Fatalf("ListActiveSuggestionSnoozes: %v", err)
}
if len(rows) != 1 {
t.Fatalf("len = %d, want 1 (upsert, not a second row)", len(rows))
}
if rows[0].CandidateName != "New Name" {
t.Errorf("name = %q, want New Name (upsert refreshes it)", rows[0].CandidateName)
}
if got := time.Until(rows[0].SnoozedUntil.Time); got < 80*24*time.Hour {
t.Errorf("snoozed_until is %v away, want ~90d (re-snooze should extend)", got)
}
}
// ListActiveSuggestionSnoozes filters expired rows itself rather than
// trusting the hourly gc sweep to have run.
func TestListActiveSuggestionSnoozes_ExcludesExpired(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
snoozeUntil(t, pool, user.ID, "live-mbid", "Live", time.Now().Add(24*time.Hour))
snoozeUntil(t, pool, user.ID, "dead-mbid", "Dead", time.Now().Add(-24*time.Hour))
rows, err := dbq.New(pool).ListActiveSuggestionSnoozes(context.Background(), user.ID)
if err != nil {
t.Fatalf("ListActiveSuggestionSnoozes: %v", err)
}
if len(rows) != 1 {
t.Fatalf("len = %d, want 1 (expired row must not be listed)", len(rows))
}
if rows[0].CandidateMbid != "live-mbid" {
t.Errorf("mbid = %q, want live-mbid", rows[0].CandidateMbid)
}
}
func TestGcDeleteExpiredSuggestionSnoozes_KeepsActive(t *testing.T) {
pool := newPool(t)
user := seedUser(t, pool, "alice")
snoozeUntil(t, pool, user.ID, "live-mbid", "Live", time.Now().Add(24*time.Hour))
snoozeUntil(t, pool, user.ID, "dead-mbid", "Dead", time.Now().Add(-24*time.Hour))
q := dbq.New(pool)
deleted, err := q.GcDeleteExpiredSuggestionSnoozes(context.Background())
if err != nil {
t.Fatalf("GcDeleteExpiredSuggestionSnoozes: %v", err)
}
if deleted != 1 {
t.Errorf("deleted = %d, want 1 (only the expired row)", deleted)
}
rows, err := q.ListActiveSuggestionSnoozes(context.Background(), user.ID)
if err != nil {
t.Fatalf("ListActiveSuggestionSnoozes: %v", err)
}
if len(rows) != 1 {
t.Errorf("len = %d, want 1 (active snooze survives the sweep)", len(rows))
}
}
@@ -1,169 +0,0 @@
package recommendation
import (
"fmt"
"testing"
"github.com/jackc/pgx/v5/pgtype"
)
// selectSuggestions is deliberately pure (no DB, no clock), so the rotation and
// diversity rules are covered here in the fast lane rather
// than behind the integration gate.
func seedID(n byte) pgtype.UUID {
var u pgtype.UUID
u.Bytes[0] = n
u.Valid = true
return u
}
// candidate builds a pool entry attributed to the given dominant seed.
func candidate(mbid string, score float64, dominant byte) ArtistSuggestion {
return ArtistSuggestion{
MBID: mbid,
Name: mbid,
Score: score,
Attribution: []SeedContribution{
{ArtistID: seedID(dominant), Contribution: score},
},
}
}
// poolOf returns n candidates in descending score order, spread across
// `seeds` distinct dominant seeds.
func poolOf(n int, seeds int) []ArtistSuggestion {
out := make([]ArtistSuggestion, 0, n)
for i := 0; i < n; i++ {
out = append(out, candidate(fmt.Sprintf("mbid-%02d", i), 1.0-float64(i)*0.01, byte(i%seeds)))
}
return out
}
func mbids(in []ArtistSuggestion) []string {
out := make([]string, 0, len(in))
for _, s := range in {
out = append(out, s.MBID)
}
return out
}
func TestSelectSuggestions_ReturnsPoolUnchangedWhenNotOverfetched(t *testing.T) {
pool := poolOf(5, 5)
got := selectSuggestions(pool, 12, "2026-08-01")
if len(got) != 5 {
t.Fatalf("len = %d, want 5 (nothing to rotate)", len(got))
}
if got[0].MBID != "mbid-00" {
t.Errorf("first = %q, want mbid-00", got[0].MBID)
}
}
func TestSelectSuggestions_FillsTheRequestedLimit(t *testing.T) {
got := selectSuggestions(poolOf(48, 8), 12, "2026-08-01")
if len(got) != 12 {
t.Fatalf("len = %d, want 12", len(got))
}
}
// The reported symptom: the deck must change day to day without the user
// requesting anything.
func TestSelectSuggestions_RotatesAcrossDays(t *testing.T) {
pool := poolOf(48, 8)
day1 := mbids(selectSuggestions(pool, 12, "2026-08-01"))
day2 := mbids(selectSuggestions(pool, 12, "2026-08-02"))
if fmt.Sprint(day1) == fmt.Sprint(day2) {
t.Fatalf("deck identical across days: %v", day1)
}
// ...but stable WITHIN a day, or the surface would reshuffle on every
// pull-to-refresh, which reads as broken rather than fresh.
again := mbids(selectSuggestions(pool, 12, "2026-08-01"))
if fmt.Sprint(day1) != fmt.Sprint(again) {
t.Errorf("same day differed:\n %v\n %v", day1, again)
}
}
// The strongest matches should never rotate out of sight.
func TestSelectSuggestions_HeadIsStableTopScorers(t *testing.T) {
pool := poolOf(48, 8)
for _, day := range []string{"2026-08-01", "2026-08-02", "2026-09-15"} {
got := selectSuggestions(pool, 12, day)
if got[0].MBID != "mbid-00" {
t.Errorf("day %s: first = %q, want mbid-00 (top score leads)", day, got[0].MBID)
}
}
}
// Twelve slots must not all be neighbours of one artist.
//
// The pool is deliberately SKEWED — one seed owns the entire top of the score
// ranking — because that is the only shape where a cap can bite. With scores
// spread evenly across seeds the top-N is already diverse and the cap is
// untestable: an even pool cannot fail this test.
func TestSelectSuggestions_CapsOneDominantSeed(t *testing.T) {
const dominantRun = 20
pool := make([]ArtistSuggestion, 0, 48)
for i := 0; i < dominantRun; i++ { // seed 0 owns the 20 best scores
pool = append(pool, candidate(fmt.Sprintf("dom-%02d", i), 1.0-float64(i)*0.01, 0))
}
for i := 0; i < 28; i++ { // seeds 1..9 hold everything below
pool = append(pool, candidate(fmt.Sprintf("oth-%02d", i), 0.80-float64(i)*0.01, byte(1+i%9)))
}
got := selectSuggestions(pool, 12, "2026-08-01")
if len(got) != 12 {
t.Fatalf("len = %d, want 12", len(got))
}
perSeed := map[pgtype.UUID]int{}
for _, s := range got {
perSeed[s.Attribution[0].ArtistID]++
}
// Uncapped, the top 12 by score would be 12 of seed 0's neighbours.
if n := perSeed[seedID(0)]; n > maxPerSeedFor(12) {
t.Errorf("dominant seed owns %d of 12 slots, want <= %d: %v",
n, maxPerSeedFor(12), mbids(got))
}
if len(perSeed) < 4 {
t.Errorf("deck spans only %d seeds, want >= 4: %v", len(perSeed), mbids(got))
}
}
// Diversity must not starve the deck: a pool hanging off a single
// seed should still fill, not collapse to maxPerSeed entries.
func TestSelectSuggestions_SingleSeedPoolStillFills(t *testing.T) {
got := selectSuggestions(poolOf(30, 1), 12, "2026-08-01")
if len(got) != 12 {
t.Fatalf("len = %d, want 12 (cap must not starve the deck)", len(got))
}
if got[0].MBID != "mbid-00" {
t.Errorf("first = %q, want mbid-00", got[0].MBID)
}
}
// A candidate with no attribution has no seed to blame, so it must never be
// held back by the diversity cap.
func TestPartitionPerSeed_UnattributedNeverCapped(t *testing.T) {
pool := []ArtistSuggestion{
candidate("a", 0.9, 1),
candidate("b", 0.8, 1),
{MBID: "orphan", Score: 0.1},
}
preferred, overflow := partitionPerSeed(pool, 1)
if len(preferred) != 2 || preferred[1].MBID != "orphan" {
t.Errorf("preferred = %v, want [a orphan]", mbids(preferred))
}
if len(overflow) != 1 || overflow[0].MBID != "b" {
t.Errorf("overflow = %v, want [b]", mbids(overflow))
}
}
func TestPoolSizeFor_OverfetchesButIsBounded(t *testing.T) {
if got := poolSizeFor(12); got != 48 {
t.Errorf("poolSizeFor(12) = %d, want 48", got)
}
if got := poolSizeFor(50); got != suggestionPoolMax {
t.Errorf("poolSizeFor(50) = %d, want the %d ceiling", got, suggestionPoolMax)
}
}
-152
View File
@@ -1,152 +0,0 @@
// tagoverlap.go — the taste-tag term for the Discover request surface.
//
// Similarity alone says "some artist you play is similar to it", a
// graph-adjacency fact that says nothing about whether the music sounds like
// anything you actually like. Here the candidate's own folksonomy tags (from
// the candidate tag cache) are compared against the user's taste-profile
// tags, so the surface can rank on "matches the sound you like" and say WHY.
//
// Pure by design — no DB, no clock — so the scoring rules are unit-testable in
// the fast lane rather than behind the integration gate.
package recommendation
import "sort"
// maxMatchedTags caps the "matches: …" explanation. Three is what the existing
// seed attribution shows, and a longer list stops being a reason and becomes a
// tag dump.
const maxMatchedTags = 3
// TagWeights is a tag → weight map. Both sides of the comparison use it:
// candidate tags (normalized [0,1] by the enrichment providers) and the user's
// taste-profile tags (accumulated, unbounded — normalized here).
type TagWeights map[string]float64
// tagOverlap scores how much of a candidate's tag identity the user actually
// likes, in [0,1], and returns the matched tags ordered by contribution.
//
// The measure is: of this candidate's total tag mass, what share sits on tags
// the user likes — each weighted by how strongly they like it?
//
// overlap = Σ(shared) candWeight × normalizedTasteWeight ÷ Σ(all) candWeight
//
// Normalizing the taste side by the user's STRONGEST tag is what makes this
// comparable across users: taste weights accumulate with listening, so a
// heavy listener's raw numbers dwarf a new user's while meaning the same
// thing — "this is my favourite tag". Dividing by the candidate's own total
// mass makes it comparable across candidates, so a densely-tagged artist
// can't out-score a sparsely-tagged one just by having more tags.
//
// Returns (0, nil) when either side is empty. That is the load-bearing
// degradation path: tag coverage for out-of-library candidates is permanently
// partial, and a cold-start user has no taste tags at all. Both must leave
// the candidate's similarity score untouched rather than sink it.
func tagOverlap(candidate, taste TagWeights) (float64, []string) {
if len(candidate) == 0 || len(taste) == 0 {
return 0, nil
}
maxTaste := 0.0
for _, w := range taste {
if w > maxTaste {
maxTaste = w
}
}
// Every taste weight <= 0 carries no preference to match against. Guarding
// here also avoids dividing by zero below.
if maxTaste <= 0 {
return 0, nil
}
totalMass := 0.0
for _, w := range candidate {
// Negative or zero candidate weights would let a tag subtract from the
// denominator and inflate the ratio past 1.
if w > 0 {
totalMass += w
}
}
if totalMass <= 0 {
return 0, nil
}
type contribution struct {
tag string
score float64
}
var matched []contribution
sum := 0.0
for tag, candWeight := range candidate {
if candWeight <= 0 {
continue
}
tasteWeight, ok := taste[tag]
if !ok || tasteWeight <= 0 {
continue
}
c := candWeight * (tasteWeight / maxTaste)
sum += c
matched = append(matched, contribution{tag: tag, score: c})
}
if len(matched) == 0 {
return 0, nil
}
// Strongest contribution first; tag name breaks ties so the explanation is
// deterministic for a given input rather than map-iteration order.
sort.Slice(matched, func(i, j int) bool {
if matched[i].score != matched[j].score {
return matched[i].score > matched[j].score
}
return matched[i].tag < matched[j].tag
})
names := make([]string, 0, min(len(matched), maxMatchedTags))
for i := 0; i < len(matched) && i < maxMatchedTags; i++ {
names = append(names, matched[i].tag)
}
return sum / totalMass, names
}
// applyTagOverlap re-scores and re-orders a candidate pool by taste-tag
// overlap, stamping the matched tags onto each suggestion for the UI.
//
// The blend is MULTIPLICATIVE — score × (1 + weight × overlap) — not additive,
// and the difference is the whole safety argument:
//
// - A candidate with no tags has overlap 0, so its score is EXACTLY
// unchanged. Partial tag coverage costs a candidate nothing.
// - Nothing can leapfrog on tags alone. An additive term with a large
// weight would let a near-zero-similarity artist outrank a strong match
// just for sharing a popular tag, which reads as noise to the user.
// - weight 0 disables the feature completely and restores pure similarity
// order, so the knob has a real off position.
//
// Callers must pass the pool in similarity order; it is returned in blended
// order. Mutates the elements in place (they're the caller's own slice built
// per request), and re-sorts, because selectSuggestions downstream relies on
// score order for its head/tail split.
func applyTagOverlap(
pool []ArtistSuggestion, candidateTags map[string]TagWeights, taste TagWeights, weight float64,
) []ArtistSuggestion {
// A zero weight turns the feature off. Skip the work AND the re-sort so
// the ordering is bit-for-bit pure similarity order.
if weight == 0 || len(taste) == 0 {
return pool
}
for i := range pool {
overlap, matched := tagOverlap(candidateTags[pool[i].MBID], taste)
pool[i].MatchedTags = matched
pool[i].TagOverlap = overlap
pool[i].Score *= 1 + weight*overlap
}
sort.SliceStable(pool, func(i, j int) bool {
if pool[i].Score != pool[j].Score {
return pool[i].Score > pool[j].Score
}
// Stable tiebreak by MBID. Without it, two candidates on equal scores
// could swap between requests within the same day, which the daily
// rotation exists to prevent.
return pool[i].MBID < pool[j].MBID
})
return pool
}
-243
View File
@@ -1,243 +0,0 @@
package recommendation
import (
"fmt"
"testing"
)
// tagOverlap / applyTagOverlap are pure, so the taste-tag ranking rules are
// covered in the fast lane rather than behind the integration gate.
//
// Fixtures here are deliberately SKEWED — candidates that match the taste
// profile to clearly different degrees. An evenly-matching pool cannot exercise
// a re-ranking at all: every candidate gets the same multiplier and the order is
// unchanged whether the blend works or not.
func TestTagOverlap_FullMatchScoresOne(t *testing.T) {
// Every unit of the candidate's tag mass sits on the user's single
// strongest tag → the whole mass matches at full strength.
got, matched := tagOverlap(
TagWeights{"shoegaze": 1.0},
TagWeights{"shoegaze": 5.0},
)
if got != 1.0 {
t.Errorf("overlap = %v, want 1.0", got)
}
if len(matched) != 1 || matched[0] != "shoegaze" {
t.Errorf("matched = %v, want [shoegaze]", matched)
}
}
func TestTagOverlap_NoSharedTagsScoresZero(t *testing.T) {
got, matched := tagOverlap(
TagWeights{"death metal": 1.0},
TagWeights{"shoegaze": 5.0},
)
if got != 0 {
t.Errorf("overlap = %v, want 0", got)
}
if matched != nil {
t.Errorf("matched = %v, want nil", matched)
}
}
// Half the candidate's mass is on a matching tag, and that tag is the user's
// strongest → 0.5.
func TestTagOverlap_PartialMassMatchIsProportional(t *testing.T) {
got, _ := tagOverlap(
TagWeights{"shoegaze": 1.0, "death metal": 1.0},
TagWeights{"shoegaze": 5.0},
)
if got != 0.5 {
t.Errorf("overlap = %v, want 0.5", got)
}
}
// Matching a tag the user barely likes must score below matching one they love.
func TestTagOverlap_WeakTasteTagScoresLowerThanStrong(t *testing.T) {
taste := TagWeights{"shoegaze": 10.0, "polka": 1.0}
strong, _ := tagOverlap(TagWeights{"shoegaze": 1.0}, taste)
weak, _ := tagOverlap(TagWeights{"polka": 1.0}, taste)
if !(strong > weak) {
t.Errorf("strong=%v weak=%v — a favourite tag must outscore a marginal one", strong, weak)
}
if weak != 0.1 { // 1.0 * (1/10) / 1.0
t.Errorf("weak = %v, want 0.1", weak)
}
}
// THE degradation path. Tag coverage for out-of-library candidates is
// permanently partial and cold-start users have no taste tags, so both must be
// scored 0 — never negative, never dropped.
func TestTagOverlap_EmptyEitherSideIsZeroNotNegative(t *testing.T) {
cases := []struct {
name string
candidate, taste TagWeights
}{
{"no candidate tags", nil, TagWeights{"shoegaze": 5}},
{"no taste tags", TagWeights{"shoegaze": 1}, nil},
{"both empty", nil, nil},
{"taste weights all zero", TagWeights{"shoegaze": 1}, TagWeights{"shoegaze": 0}},
{"candidate weights all zero", TagWeights{"shoegaze": 0}, TagWeights{"shoegaze": 5}},
}
for _, c := range cases {
got, matched := tagOverlap(c.candidate, c.taste)
if got != 0 {
t.Errorf("%s: overlap = %v, want 0", c.name, got)
}
if matched != nil {
t.Errorf("%s: matched = %v, want nil", c.name, matched)
}
}
}
// A densely-tagged artist must not out-score a focused one merely by having
// more tags — that's what dividing by the candidate's own mass buys.
func TestTagOverlap_IsNotAPopularityContest(t *testing.T) {
taste := TagWeights{"shoegaze": 5.0}
focused, _ := tagOverlap(TagWeights{"shoegaze": 1.0}, taste)
sprawling, _ := tagOverlap(TagWeights{
"shoegaze": 1.0, "rock": 1.0, "alternative": 1.0, "90s": 1.0,
}, taste)
if !(focused > sprawling) {
t.Errorf("focused=%v sprawling=%v — extra unmatched tags must dilute, not add",
focused, sprawling)
}
}
// Taste weights accumulate with listening, so raw magnitudes differ wildly
// between a new user and a heavy one while meaning the same thing. Normalizing
// by the user's own strongest tag is what makes the score comparable.
func TestTagOverlap_IsInvariantToTasteMagnitude(t *testing.T) {
candidate := TagWeights{"shoegaze": 1.0, "dream pop": 1.0}
newUser, _ := tagOverlap(candidate, TagWeights{"shoegaze": 2.0, "polka": 1.0})
heavyUser, _ := tagOverlap(candidate, TagWeights{"shoegaze": 2000.0, "polka": 1000.0})
if newUser != heavyUser {
t.Errorf("newUser=%v heavyUser=%v — scaling all taste weights must not change the result",
newUser, heavyUser)
}
}
func TestTagOverlap_MatchedTagsAreOrderedAndCapped(t *testing.T) {
got, matched := tagOverlap(
TagWeights{"a": 0.2, "b": 0.9, "c": 0.5, "d": 0.7},
TagWeights{"a": 10, "b": 10, "c": 10, "d": 10},
)
if got <= 0 {
t.Fatalf("overlap = %v, want > 0", got)
}
// All taste weights equal, so candidate weight decides: b(.9) d(.7) c(.5).
want := []string{"b", "d", "c"}
if fmt.Sprint(matched) != fmt.Sprint(want) {
t.Errorf("matched = %v, want %v (strongest first, capped at %d)",
matched, want, maxMatchedTags)
}
}
// --- applyTagOverlap ---
func poolFor(specs ...struct {
mbid string
score float64
}) []ArtistSuggestion {
out := make([]ArtistSuggestion, 0, len(specs))
for _, s := range specs {
out = append(out, ArtistSuggestion{MBID: s.mbid, Name: s.mbid, Score: s.score})
}
return out
}
type spec = struct {
mbid string
score float64
}
// The payoff, and the reason the fixture is skewed: a taste-matching candidate
// that started BELOW another must be able to overtake it. With an evenly
// matching pool this assertion could not fail.
func TestApplyTagOverlap_TasteMatchOvertakesAStrongerNonMatch(t *testing.T) {
pool := poolFor(spec{"loud", 1.0}, spec{"match", 0.7})
candTags := map[string]TagWeights{
"loud": {"death metal": 1.0},
"match": {"shoegaze": 1.0},
}
taste := TagWeights{"shoegaze": 5.0}
got := applyTagOverlap(pool, candTags, taste, 1.0)
if got[0].MBID != "match" {
t.Errorf("first = %q, want match (0.7×2 = 1.4 beats 1.0×1)", got[0].MBID)
}
if got[0].MatchedTags == nil {
t.Error("matched tags not stamped onto the winner")
}
}
// An untagged candidate keeps its score EXACTLY. This is the multiplicative
// blend's whole safety argument: partial coverage costs a candidate nothing.
func TestApplyTagOverlap_UntaggedCandidateScoreIsUnchanged(t *testing.T) {
pool := poolFor(spec{"untagged", 0.9})
got := applyTagOverlap(pool, map[string]TagWeights{}, TagWeights{"shoegaze": 5}, 1.0)
if got[0].Score != 0.9 {
t.Errorf("score = %v, want 0.9 exactly (no tags must not penalise)", got[0].Score)
}
if got[0].MatchedTags != nil {
t.Errorf("matched = %v, want nil", got[0].MatchedTags)
}
}
// Weight 0 is the off switch: the ordering must be bit-for-bit pure similarity
// order, not merely similar.
func TestApplyTagOverlap_ZeroWeightIsAnExactNoOp(t *testing.T) {
pool := poolFor(spec{"a", 1.0}, spec{"b", 0.7})
candTags := map[string]TagWeights{"b": {"shoegaze": 1.0}}
got := applyTagOverlap(pool, candTags, TagWeights{"shoegaze": 5.0}, 0)
if got[0].MBID != "a" || got[0].Score != 1.0 || got[1].Score != 0.7 {
t.Errorf("weight 0 changed the pool: %+v", got)
}
// And it must not stamp matched tags either — the UI would otherwise
// explain a boost that never happened.
if got[1].MatchedTags != nil {
t.Errorf("matched tags stamped while the feature is off: %v", got[1].MatchedTags)
}
}
// A user with no taste profile is the cold-start case: every candidate scores
// the same multiplier of 1, so similarity order must survive intact.
func TestApplyTagOverlap_NoTasteProfileLeavesOrderIntact(t *testing.T) {
pool := poolFor(spec{"a", 1.0}, spec{"b", 0.7}, spec{"c", 0.4})
candTags := map[string]TagWeights{"c": {"shoegaze": 1.0}}
got := applyTagOverlap(pool, candTags, nil, 1.0)
for i, want := range []string{"a", "b", "c"} {
if got[i].MBID != want {
t.Fatalf("order = %v..., want a b c", got[i].MBID)
}
}
}
// Bounded boost: even a perfect match at the maximum weight can only multiply
// by (1 + w), so a candidate cannot be catapulted arbitrarily far.
func TestApplyTagOverlap_BoostIsBoundedByOnePlusWeight(t *testing.T) {
pool := poolFor(spec{"perfect", 1.0})
got := applyTagOverlap(pool,
map[string]TagWeights{"perfect": {"shoegaze": 1.0}},
TagWeights{"shoegaze": 5.0}, 2.0)
if got[0].Score != 3.0 {
t.Errorf("score = %v, want 3.0 (1.0 × (1 + 2×1))", got[0].Score)
}
if got[0].TagOverlap != 1.0 {
t.Errorf("TagOverlap = %v, want 1.0", got[0].TagOverlap)
}
}
// Equal blended scores must resolve deterministically, or two candidates could
// swap between requests inside one day — the exact churn the daily rotation
// exists to prevent.
func TestApplyTagOverlap_TiesBreakDeterministically(t *testing.T) {
first := applyTagOverlap(poolFor(spec{"zzz", 1.0}, spec{"aaa", 1.0}),
map[string]TagWeights{}, TagWeights{"x": 1}, 1.0)
second := applyTagOverlap(poolFor(spec{"aaa", 1.0}, spec{"zzz", 1.0}),
map[string]TagWeights{}, TagWeights{"x": 1}, 1.0)
if first[0].MBID != "aaa" || second[0].MBID != "aaa" {
t.Errorf("tie order not deterministic: %q then %q", first[0].MBID, second[0].MBID)
}
}