sonda/internal/discover/score.go
tgiachi f548423f73 fix(discover): ask permission first, stable order, honest docs
- Check the discover_from_listening setting before reading the listening
  history, so a refused request does no work and a database failure cannot turn
  it into a 500.
- Cosine adds up in tag order: the sum in map order changed in the last digit
  between runs, and equal artists could swap places between requests.
- A seed that could not be read is no longer listed as a seed.
- README and spec: Discover exists now; "disabled" means something had to be
  asked and Last.fm is off; the stored lookups are shared, so another local user
  can see from retrieved_at that an artist was looked up, but not who.
- Tests: the history is not read for a refused request, a stable cosine, tags
  fetched only for the pool and four at a time, a cancelled request stops,
  MusicBrainz is never asked, the setting is per user.
2026-11-11 19:48:51 +01:00

146 lines
4.2 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// Package discover scores artists the listener may like.
//
// The score is S = wA·A + wG·G + wP·P + wD·D, each part from 0 to 1:
//
// A affinity: how close the artist is to the artists the listener likes
// G genre: how close its tags are to the tags of those artists
// P preference: what the listening history says about the artist
// D discovery: a bonus for what the listener has not played yet
//
// A part with no data (an artist whose tags are unknown) is left out and the
// others are rescaled, so a missing part never counts as a bad one. The parts are
// returned with the score, so every number can be explained.
package discover
import (
"errors"
"math"
"sort"
)
// Weights say how much each part counts. Only their proportions matter.
type Weights struct {
Affinity, Genre, Preference, Discovery float64
}
// maxWeight bounds one weight; they are only proportions, so large ones mean nothing.
const maxWeight = 10
// DefaultWeights are the weights used when the config does not set any.
func DefaultWeights() Weights {
return Weights{Affinity: 0.40, Genre: 0.25, Preference: 0.25, Discovery: 0.10}
}
// Validate refuses weights that cannot score: negative, not a number, too big, or all zero.
func (w Weights) Validate() error {
sum := 0.0
for _, v := range []float64{w.Affinity, w.Genre, w.Preference, w.Discovery} {
if math.IsNaN(v) || v < 0 || v > maxWeight {
return errors.New("each weight must be a number from 0 to 10")
}
sum += v
}
if sum == 0 {
return errors.New("at least one weight must be above 0")
}
return nil
}
// Link says one seed artist considers the candidate similar. Weight is how much the
// listener cares about the seed (1 for a seed they named). Match is the provider's
// similarity from 0 to 1; it is relative to the seed's own list, which is why the
// absolute scale comes from the weight.
type Link struct {
Seed int64
Weight float64
Match float64
}
func clamp01(v float64) float64 {
switch {
case math.IsNaN(v) || v < 0:
return 0
case v > 1:
return 1
default:
return v
}
}
// Affinity is 1 − Π(1 − weight·match) over the links: each seed that points at the
// candidate adds to the others, and the result stays below 1.
func Affinity(links []Link) float64 {
miss := 1.0
for _, l := range links {
miss *= 1 - clamp01(l.Weight)*clamp01(l.Match)
}
return clamp01(1 - miss)
}
// Cosine compares two tag vectors. ok is false when either has nothing to compare
// (no tags, or all weights zero), which is different from "nothing in common".
func Cosine(a, b map[string]float64) (float64, bool) {
// Added up in tag order: a sum in map order changes in the last digit from one
// run to the next, and two equal artists could swap places between requests.
var dot, na, nb float64
for _, tag := range sortedKeys(a) {
na += a[tag] * a[tag]
dot += a[tag] * b[tag]
}
for _, tag := range sortedKeys(b) {
nb += b[tag] * b[tag]
}
if na <= 0 || nb <= 0 {
return 0, false
}
return clamp01(dot / (math.Sqrt(na) * math.Sqrt(nb))), true
}
func sortedKeys(m map[string]float64) []string {
keys := make([]string, 0, len(m))
for k := range m {
keys = append(keys, k)
}
sort.Strings(keys)
return keys
}
// PreferenceScore maps the preference from -1..1 to 0..1. An artist the listener
// never played (known is false) is neutral: 0.5.
func PreferenceScore(pref float64, known bool) float64 {
if !known {
return 0.5
}
return clamp01((pref + 1) / 2)
}
// DiscoveryBonus is 1 for what has never been listened to and falls with every listen.
func DiscoveryBonus(listens int) float64 {
if listens < 0 {
listens = 0
}
return 1 / float64(1+listens)
}
// Components are the parts of a score. G is nil when it is not known.
type Components struct {
A float64
G *float64
P float64
D float64
}
// Combine adds the parts up with the weights, leaving out G when it is nil and
// rescaling the others. It returns 0 when no weight is left to score with.
func Combine(c Components, w Weights) float64 {
sum := w.Affinity*clamp01(c.A) + w.Preference*clamp01(c.P) + w.Discovery*clamp01(c.D)
total := w.Affinity + w.Preference + w.Discovery
if c.G != nil {
sum += w.Genre * clamp01(*c.G)
total += w.Genre
}
if total <= 0 {
return 0
}
return clamp01(sum / total)
}