sonda/internal/affinity/service.go
tgiachi a880b87a9e chore: move the module path to git.kmalloc.org/squid/sonda
Migrating hosting from Codeberg to git.kmalloc.org. Renames the
module path in go.mod, every internal import, and the OCI image
source label in the Dockerfile. Build and full test suite verified
green after the rename.
2026-11-15 17:30:29 +01:00

414 lines
11 KiB
Go

package affinity
import (
"context"
"errors"
"fmt"
"math"
"sort"
"strings"
"sync"
"time"
"golang.org/x/sync/singleflight"
"git.kmalloc.org/squid/sonda/internal/feedback"
"git.kmalloc.org/squid/sonda/internal/usersettings"
)
// Limits and rules.
const (
DefaultLimit = 20
MaxLimit = 50
// seedCount is how many of the most played artists the suggestions start from.
seedCount = 40
// poolCount is how many of the most played artists are considered at all, besides the ones linked to a seed.
poolCount = 300
// recentDays: an artist of the library played in this many days is not "forgotten", so it is not suggested.
recentDays = 60
// minPlays is how many times an artist that is not in the library must have been played to be worth getting.
minPlays = 3
// staleAfter and bigChange say when the model is built again: when plays were added and the last build is older
// than staleAfter, or at once when as many as bigChange were added (an import).
staleAfter = 10 * time.Minute
bigChange = 100
)
// Errors of the service.
var (
// ErrNotAllowed means the listener did not allow Discover to start from their listening.
ErrNotAllowed = errors.New("allow Discover to start from your listening to get suggestions")
// ErrInvalidLimit means a negative limit.
ErrInvalidLimit = errors.New("the limit cannot be negative")
// ErrUnknownArtist means the name is not an artist the listener has played.
ErrUnknownArtist = errors.New("that is not an artist you have played")
)
// Built says when and from what the model was built.
type Built struct {
BuiltAt time.Time
Plays int
Sessions int
Artists int
Links int
}
// LibraryArtist is an artist that exists on this server.
type LibraryArtist struct {
ID int64
Name string
Playable bool // there is music of it to play
}
// Store reads the plays of a person and keeps what was learned from them.
type Store interface {
Plays(ctx context.Context, userID int64, minPlayed time.Duration) ([]Play, error)
PlayCount(ctx context.Context, userID int64, minPlayed time.Duration) (int, error)
Save(ctx context.Context, userID int64, at time.Time, m Model) error
Build(ctx context.Context, userID int64) (Built, bool, error)
Seeds(ctx context.Context, userID int64, limit int) ([]Artist, error)
Artists(ctx context.Context, userID int64, keys []string) (map[string]Artist, error)
Neighbours(ctx context.Context, userID int64, keys []string) ([]Link, error)
}
// Library says which of the artists exist on this server, by search key.
type Library interface {
LibraryArtists(ctx context.Context, keys []string) (map[string]LibraryArtist, error)
}
// Marks reads what the listener decided about artists.
type Marks interface {
Marks(ctx context.Context, userID int64) (map[int64]feedback.Kind, error)
}
// Wishes puts an artist on the wishlist by name and gives its id.
type Wishes interface {
Wishlist(ctx context.Context, userID int64, name string, at time.Time) (int64, error)
}
// Settings reads the listener's own settings.
type Settings interface {
Get(ctx context.Context, userID int64) (usersettings.Settings, error)
}
// Reason is an artist the listener plays, because of which another is suggested.
type Reason struct {
Name string
Score float64
}
// Suggestion is an artist put forward.
type Suggestion struct {
key string
Name string
ArtistID int64 // 0 when no artist of this name exists on this server yet
Score float64
Plays int
LastPlayed time.Time
Wishlisted bool
Because []Reason
}
// Suggestions is the answer.
type Suggestions struct {
// Library are artists the listener has, linked to what they play now, not played for a while.
Library []Suggestion
// Missing are artists the listener plays that they have no music of, the ones they play most and that go with
// what they play now first.
Missing []Suggestion
Built Built
}
// Service learns from the listening of a person and makes suggestions.
type Service struct {
store Store
library Library
marks Marks
wishes Wishes
settings Settings
minListen time.Duration
opts Options
now func() time.Time
flight singleflight.Group
mu sync.Mutex
}
// NewService builds a Service. minListen is how long a play must last to count as a listen.
func NewService(store Store, lib Library, marks Marks, wishes Wishes, settings Settings, minListen time.Duration) *Service {
return &Service{store: store, library: lib, marks: marks, wishes: wishes, settings: settings, minListen: minListen, opts: DefaultOptions(), now: time.Now}
}
// Rebuild learns again from every play of the person, and keeps it.
func (s *Service) Rebuild(ctx context.Context, userID int64) (Built, error) {
v, err, _ := s.flight.Do(fmt.Sprint(userID), func() (any, error) { return s.rebuild(ctx, userID) })
if err != nil {
return Built{}, err
}
return v.(Built), nil
}
func (s *Service) rebuild(ctx context.Context, userID int64) (Built, error) {
plays, err := s.store.Plays(ctx, userID, s.minListen)
if err != nil {
return Built{}, err
}
at := s.now()
m := Build(plays, at, s.opts)
if err := s.store.Save(ctx, userID, at, m); err != nil {
return Built{}, err
}
return Built{BuiltAt: at, Plays: m.Plays, Sessions: m.Sessions, Artists: len(m.Artists), Links: len(m.Links)}, nil
}
// ensure builds the model when there is none or when plays were added since.
func (s *Service) ensure(ctx context.Context, userID int64) (Built, error) {
have, ok, err := s.store.Build(ctx, userID)
if err != nil {
return Built{}, err
}
if !ok {
return s.Rebuild(ctx, userID)
}
n, err := s.store.PlayCount(ctx, userID, s.minListen)
if err != nil {
return Built{}, err
}
changed := n - have.Plays
if changed < 0 {
changed = -changed
}
if changed >= bigChange || (changed > 0 && s.now().Sub(have.BuiltAt) > staleAfter) {
return s.Rebuild(ctx, userID)
}
return have, nil
}
// Suggest makes the suggestions for a person. It needs them to have allowed Discover to start from their listening.
func (s *Service) Suggest(ctx context.Context, userID int64, limit int) (Suggestions, error) {
switch {
case limit < 0:
return Suggestions{}, ErrInvalidLimit
case limit == 0:
limit = DefaultLimit
case limit > MaxLimit:
limit = MaxLimit
}
set, err := s.settings.Get(ctx, userID)
if err != nil {
return Suggestions{}, err
}
if !set.DiscoverFromListening {
return Suggestions{}, ErrNotAllowed
}
build, err := s.ensure(ctx, userID)
if err != nil {
return Suggestions{}, err
}
out := Suggestions{Library: []Suggestion{}, Missing: []Suggestion{}, Built: build}
pool, err := s.store.Seeds(ctx, userID, poolCount)
if err != nil {
return Suggestions{}, err
}
if len(pool) == 0 {
return out, nil
}
seeds := pool[:min(seedCount, len(pool))]
weight := map[string]float64{}
keys := make([]string, 0, len(seeds))
for _, a := range seeds {
weight[a.Key] = math.Log1p(a.Weight)
keys = append(keys, a.Key)
}
links, err := s.store.Neighbours(ctx, userID, keys)
if err != nil {
return Suggestions{}, err
}
type reason struct {
key string
score float64
}
affinity := map[string]float64{}
because := map[string][]reason{}
link := func(seed, other string, score float64) {
w, ok := weight[seed]
if !ok || seed == other {
return
}
affinity[other] += w * score
because[other] = append(because[other], reason{seed, w * score})
}
for _, l := range links {
link(l.A, l.B, l.Score)
link(l.B, l.A, l.Score)
}
stats := map[string]Artist{}
for _, a := range pool {
stats[a.Key] = a
}
var unknown []string
for k := range affinity {
if _, ok := stats[k]; !ok {
unknown = append(unknown, k)
}
}
extra, err := s.store.Artists(ctx, userID, unknown)
if err != nil {
return Suggestions{}, err
}
for k, a := range extra {
stats[k] = a
}
all := make([]string, 0, len(stats))
for k := range stats {
all = append(all, k)
}
sort.Strings(all)
inLibrary, err := s.library.LibraryArtists(ctx, all)
if err != nil {
return Suggestions{}, err
}
marks, err := s.marks.Marks(ctx, userID)
if err != nil {
return Suggestions{}, err
}
names := func(key string) string {
if a, ok := stats[key]; ok {
return a.Name
}
return key
}
make1 := func(key string) Suggestion {
a := stats[key]
sg := Suggestion{key: key, Name: a.Name, Plays: a.Plays, LastPlayed: a.Last}
if la, ok := inLibrary[key]; ok {
sg.ArtistID = la.ID
sg.Name = la.Name
sg.Wishlisted = marks[la.ID] == feedback.Wishlist
}
rs := because[key]
sort.Slice(rs, func(i, j int) bool {
if rs[i].score != rs[j].score {
return rs[i].score > rs[j].score
}
return rs[i].key < rs[j].key
})
for _, r := range rs[:min(3, len(rs))] {
sg.Because = append(sg.Because, Reason{Name: names(r.key), Score: r.score})
}
return sg
}
dismissed := func(key string) bool {
la, ok := inLibrary[key]
return ok && marks[la.ID] == feedback.Dismissed
}
// The artists of the library that go with what is played now and have not been played for a while.
recent := s.now().AddDate(0, 0, -recentDays)
var lib []Suggestion
maxAff := 0.0
for _, key := range all {
la, ok := inLibrary[key]
if !ok || !la.Playable || affinity[key] <= 0 || dismissed(key) || stats[key].Last.After(recent) {
continue
}
maxAff = math.Max(maxAff, affinity[key])
sg := make1(key)
sg.Score = affinity[key]
lib = append(lib, sg)
}
for i := range lib {
lib[i].Score /= maxAff
}
out.Library = top(lib, limit)
// The artists that are played and are not in the library: how much they are played and how well they go with
// what is played now, half and half.
var away []Suggestion
maxOwn, maxAway := 0.0, 0.0
for _, key := range all {
if la, ok := inLibrary[key]; ok && la.Playable {
continue
}
if stats[key].Plays < minPlays || dismissed(key) {
continue
}
maxOwn = math.Max(maxOwn, math.Log1p(stats[key].Weight))
maxAway = math.Max(maxAway, affinity[key])
away = append(away, make1(key))
}
for i := range away {
key := away[i].key
own := math.Log1p(stats[key].Weight) / maxOwn
with := 0.0
if maxAway > 0 {
with = affinity[key] / maxAway
}
away[i].Score = 0.5*own + 0.5*with
}
out.Missing = top(away, limit)
return out, nil
}
// top keeps the best of the suggestions, the highest score first, then the most played, then by name.
func top(in []Suggestion, limit int) []Suggestion {
sort.SliceStable(in, func(i, j int) bool {
a, b := in[i], in[j]
switch {
case a.Score != b.Score:
return a.Score > b.Score
case a.Plays != b.Plays:
return a.Plays > b.Plays
default:
return a.Name < b.Name
}
})
if len(in) > limit {
in = in[:limit]
}
if in == nil {
in = []Suggestion{}
}
return in
}
// AddToWishlist puts an artist the listener has played on their wishlist, by name, and gives its id.
func (s *Service) AddToWishlist(ctx context.Context, userID int64, name string) (int64, error) {
name = strings.TrimSpace(name)
if name == "" {
return 0, ErrUnknownArtist
}
set, err := s.settings.Get(ctx, userID)
if err != nil {
return 0, err
}
if !set.DiscoverFromListening {
return 0, ErrNotAllowed
}
if _, err := s.ensure(ctx, userID); err != nil {
return 0, err
}
found := false
seeds, err := s.store.Seeds(ctx, userID, math.MaxInt32)
if err != nil {
return 0, err
}
for _, a := range seeds {
if a.Name == name {
found = true
name = a.Name
break
}
}
if !found {
return 0, ErrUnknownArtist
}
return s.wishes.Wishlist(ctx, userID, name, s.now())
}