From 544ec67dd10a9c950f040d24bb3a8d6becb2b9db Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 18:46:58 +0100 Subject: [PATCH] feat(taste): learn what I like from what I listen to - taste package: each listening event has a value (complete +1, a play that counts +0.5, a skip that does not count -1, a short play 0), older events weigh less (half-life 90 days, taste.half_life_days), and the values of an artist become a preference in (-1, 1) with tanh. - Tag profile built from the artists I like: genres of my files plus the tags already stored from providers, each source scaled to its own best tag. - GET /me/taste shows the liked artists and the tags. It reads local data only and never asks a provider. - TasteRepo reads events, names and tags; tests on SQLite and PostgreSQL. - OpenAPI spec, contract test, README and example config updated. Closes #27 --- README.md | 6 +- cmd/sondad/main.go | 2 + internal/api/http/api_test.go | 2 + internal/api/http/contract_test.go | 9 ++ internal/api/http/handlers_taste.go | 61 +++++++++ internal/api/http/router.go | 9 ++ internal/api/http/taste_test.go | 144 +++++++++++++++++++++ internal/api/openapi/openapi.yaml | 70 ++++++++++ internal/config/config.go | 16 +++ internal/config/config_test.go | 16 +++ internal/storage/taste.go | 192 ++++++++++++++++++++++++++++ internal/storage/taste_test.go | 150 ++++++++++++++++++++++ internal/taste/service.go | 143 +++++++++++++++++++++ internal/taste/service_test.go | 166 ++++++++++++++++++++++++ internal/taste/taste.go | 136 ++++++++++++++++++++ internal/taste/taste_test.go | 147 +++++++++++++++++++++ sonda.example.toml | 3 + 17 files changed, 1271 insertions(+), 1 deletion(-) create mode 100644 internal/api/http/handlers_taste.go create mode 100644 internal/api/http/taste_test.go create mode 100644 internal/storage/taste.go create mode 100644 internal/storage/taste_test.go create mode 100644 internal/taste/service.go create mode 100644 internal/taste/service_test.go create mode 100644 internal/taste/taste.go create mode 100644 internal/taste/taste_test.go diff --git a/README.md b/README.md index 572fbf1..f990b5b 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,13 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr - **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen. - **API documentation.** The full API is described in OpenAPI and browsable with Swagger UI, served by Sonda itself. The UI is embedded in the binary, so opening it contacts no other server. - **Listening history.** Clients report explicit `play`, `complete` and `skip` events. An event counts as a listen when it is `complete`, or when it was played for at least 20 seconds (`listening.min_listen_seconds`); the rule is applied when the history is read, so changing it re-reads the past. You can read your own history, with a `counted` flag on every event. It stays in your database and is never sent anywhere. +- **Your taste.** `GET /me/taste` shows what Sonda has learned from your own listening: the artists you like and the kinds of music (tags) they have in common. A complete listen counts for more than a short one, a skip counts against the artist, and older listens weigh less (they halve every 90 days, `taste.half_life_days`). It is worked out on every request from data already in your database; nothing is sent to any provider. - **Tags.** `GET /artists/{id}/tags` shows what Last.fm and MusicBrainz say kind of music an artist plays, each with its own weights, and the genres of the artist's own files, read offline. See [External providers](#external-providers). - **Similar artists.** With Last.fm switched on, `GET /artists/{id}/similar` lists artists similar to an artist, and says which of them you already have. See [External providers](#external-providers). Without it, Sonda makes no outbound network requests at all. ## What is not there yet -Recommendations and radio queues, a web client, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. Recommendations from all this data (scoring) are next. +Recommendations and radio queues, a web client, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. Recommendations from all this data (scoring) are next: your taste is already learned, the scoring of what to discover is what is left. ## Requirements @@ -60,6 +61,7 @@ Precedence is: built-in defaults, then the file, then environment variables. An | `auth.access_ttl_minutes` | | `15` | Lifetime of an access token. | | `auth.refresh_ttl_hours` | | `720` | Lifetime of a refresh token (30 days). | | `listening.min_listen_seconds` | | `20` | A play counts as a listen after this long (1 to 3600), or when it is `complete`. | +| `taste.half_life_days` | | `90` | After this many days a listen weighs half as much when learning your taste (1 to 3650). | Libraries and the external providers are not in the config: you set them up through the API (see the demo and [External providers](#external-providers)). @@ -226,6 +228,7 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er | signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. | | signed in | `POST /listens` | Record a `play`, `complete` or `skip`; the answer says whether it counts as a listen. | | signed in | `GET /listens` | Your own history, newest first, with `counted` per event. Query: `limit`, `offset`, `counted=true`. | +| signed in | `GET /me/taste` | The artists and tags Sonda learned you like, from your own listening. Query: `limit` (default 20, max 50). | | signed in | `GET /library/scan` | Scan status and the last result. | | admin | `GET`, `POST /libraries`; `PATCH`, `DELETE /libraries/{id}` | Manage libraries. Deleting one removes its index entries, never your files. | | admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. `?full=true` reads every file again. | @@ -279,6 +282,7 @@ internal/library/ libraries, the scanner, the event hub, the tag reader internal/discovery/ similar artists: what the providers said, kept and refreshed internal/providers/ external providers: settings, the outbound HTTP client, the Last.fm and MusicBrainz clients internal/listening/ listen events +internal/taste/ what the listener likes, learned from the listening history internal/storage/ SQLite and PostgreSQL through bun, the repositories internal/streaming/ opening a track's file safely migrations/ SQL migrations, one folder per database diff --git a/cmd/sondad/main.go b/cmd/sondad/main.go index be6cd1b..2f6a8d2 100644 --- a/cmd/sondad/main.go +++ b/cmd/sondad/main.go @@ -27,6 +27,7 @@ import ( "codeberg.org/squidd/sonda/internal/providers/outbound" "codeberg.org/squidd/sonda/internal/storage" "codeberg.org/squidd/sonda/internal/streaming" + "codeberg.org/squidd/sonda/internal/taste" "codeberg.org/squidd/sonda/migrations" ) @@ -148,6 +149,7 @@ func run() error { Providers: providerSettings, Discovery: discoveries, Tags: tags, + Taste: taste.NewService(storage.NewTasteRepo(db), taste.Options{MinListen: cfg.Listening.MinListen(), HalfLife: cfg.Taste.HalfLife()}), Streams: streaming.NewService(libraryRepo), }) diff --git a/internal/api/http/api_test.go b/internal/api/http/api_test.go index cfce655..1e2f5b1 100644 --- a/internal/api/http/api_test.go +++ b/internal/api/http/api_test.go @@ -22,6 +22,7 @@ import ( "codeberg.org/squidd/sonda/internal/providers" "codeberg.org/squidd/sonda/internal/storage" "codeberg.org/squidd/sonda/internal/streaming" + "codeberg.org/squidd/sonda/internal/taste" "codeberg.org/squidd/sonda/migrations" ) @@ -86,6 +87,7 @@ func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun Providers: prov, Discovery: discovery.NewService(storage.NewDiscoveryRepo(db), &fakeLastfm{}, prov, zap.NewNop()), Tags: discovery.NewTagService(storage.NewDiscoveryRepo(db), map[string]discovery.TagSource{}, prov, zap.NewNop()), + Taste: taste.NewService(storage.NewTasteRepo(db), taste.Options{MinListen: 20 * time.Second, HalfLife: 90 * 24 * time.Hour}), Streams: streaming.NewService(noFiles{}), } mutate(&deps, db) diff --git a/internal/api/http/contract_test.go b/internal/api/http/contract_test.go index 81a9616..01b49ec 100644 --- a/internal/api/http/contract_test.go +++ b/internal/api/http/contract_test.go @@ -517,6 +517,15 @@ func TestResponsesMatchTheSpec(t *testing.T) { c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": 999, "event_type": "play", "idempotency_key": "k2"}), 404, "listen unknown track", "track_not_found") c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": tid, "event_type": "dance", "idempotency_key": "k3"}), 400, "listen invalid", "invalid_input") + // ---- taste ---- + learned := c.expect(c.call("GET", "/me/taste?limit=5", token, nil), 200, "taste") + if arts := learned["artists"].([]any); len(arts) != 1 || arts[0].(map[string]any)["name"] != "Artist X" || arts[0].(map[string]any)["listens"] != float64(1) { + t.Fatalf("taste = %v, want Artist X, listened once", learned) + } + c.expect(c.call("GET", "/me/taste", "", nil), 401, "taste without a token", "unauthorized") + c.expect(c.call("GET", "/me/taste?limit=-1", token, nil), 400, "taste with a bad limit", "invalid_input") + c.expect(c.call("GET", "/me/taste?limit=abc", token, nil), 400, "taste with a limit that is not a number", "invalid_input") + // ---- every operation in the spec was exercised ---- var missing []string for _, op := range specOperations(loadSpec(t)) { diff --git a/internal/api/http/handlers_taste.go b/internal/api/http/handlers_taste.go new file mode 100644 index 0000000..efc2319 --- /dev/null +++ b/internal/api/http/handlers_taste.go @@ -0,0 +1,61 @@ +package httpapi + +import ( + "errors" + "net/http" + "time" + + "github.com/gin-gonic/gin" + + "codeberg.org/squidd/sonda/internal/taste" +) + +type tasteHandlers struct{ svc tasteService } + +type tasteArtistJSON struct { + ID int64 `json:"id"` + Name string `json:"name"` + Preference float64 `json:"preference"` + Listens int `json:"listens"` + LastListenedAt string `json:"last_listened_at"` +} + +type tasteTagJSON struct { + Tag string `json:"tag"` + Weight float64 `json:"weight"` +} + +type tasteJSON struct { + Artists []tasteArtistJSON `json:"artists"` + Tags []tasteTagJSON `json:"tags"` +} + +// taste shows what Sonda has learned about the signed-in user's taste. It reads +// local data only and contacts nobody. +func (h *tasteHandlers) taste(c *gin.Context) { + limit, ok := queryInt(c, "limit") + if !ok { + return + } + p, err := h.svc.Taste(c.Request.Context(), currentUserID(c), clampInt(limit)) + switch { + case errors.Is(err, taste.ErrInvalidQuery): + writeError(c, http.StatusBadRequest, "invalid_input", err.Error()) + return + case err != nil: + _ = c.Error(err) + writeError(c, http.StatusInternalServerError, "internal", "internal error") + return + } + out := tasteJSON{Artists: make([]tasteArtistJSON, len(p.Artists)), Tags: make([]tasteTagJSON, len(p.Tags))} + for i, a := range p.Artists { + out.Artists[i] = tasteArtistJSON{ + ID: a.ID, Name: a.Name, Preference: a.Preference, Listens: a.Listens, + LastListenedAt: a.LastListened.UTC().Format(time.RFC3339), + } + } + for i, t := range p.Tags { + out.Tags[i] = tasteTagJSON{Tag: t.Tag, Weight: t.Weight} + } + c.JSON(http.StatusOK, out) +} diff --git a/internal/api/http/router.go b/internal/api/http/router.go index b3ec744..5263dc1 100644 --- a/internal/api/http/router.go +++ b/internal/api/http/router.go @@ -17,6 +17,7 @@ import ( "codeberg.org/squidd/sonda/internal/listening" "codeberg.org/squidd/sonda/internal/providers" "codeberg.org/squidd/sonda/internal/streaming" + "codeberg.org/squidd/sonda/internal/taste" ) // maxBodyBytes bounds every request body. @@ -70,6 +71,10 @@ type discoveryService interface { Similar(ctx context.Context, artistID int64, limit int) (discovery.Result, error) } +type tasteService interface { + Taste(ctx context.Context, userID int64, limit int) (taste.Profile, error) +} + type catalogService interface { Artists(ctx context.Context, f catalog.Filter) (catalog.Page[catalog.Artist], error) Albums(ctx context.Context, f catalog.Filter) (catalog.Page[catalog.Album], error) @@ -98,6 +103,7 @@ type Deps struct { Providers providerService Discovery discoveryService Tags tagService + Taste tasteService Streams streamService } @@ -126,6 +132,9 @@ func NewRouter(d Deps) *gin.Engine { protected.POST("/listens", l.record) protected.GET("/listens", l.list) + ts := &tasteHandlers{svc: d.Taste} + protected.GET("/me/taste", ts.taste) + lib := &libraryHandlers{scan: d.Scan} protected.GET("/library/scan", lib.scanStatus) diff --git a/internal/api/http/taste_test.go b/internal/api/http/taste_test.go new file mode 100644 index 0000000..aac8f5c --- /dev/null +++ b/internal/api/http/taste_test.go @@ -0,0 +1,144 @@ +package httpapi + +import ( + "math" + "net/http" + "strconv" + "testing" + "time" + + "github.com/uptrace/bun" + + "codeberg.org/squidd/sonda/internal/providers" + "codeberg.org/squidd/sonda/internal/storage" + "codeberg.org/squidd/sonda/internal/taste" +) + +func newTasteEnv(t *testing.T) *similarEnv { + t.Helper() + return newSimilarEnvWith(t, func(d *Deps, db *bun.DB, _ *providers.Service) { + d.Taste = taste.NewService(storage.NewTasteRepo(db), taste.Options{MinListen: 20 * time.Second, HalfLife: 90 * 24 * time.Hour}) + }) +} + +func (e *similarEnv) trackOf(t *testing.T, artist string) int64 { + t.Helper() + var id int64 + if err := e.db.QueryRow(`SELECT t.id FROM tracks t JOIN track_artists ta ON ta.track_id = t.id + JOIN artists a ON a.id = ta.artist_id WHERE a.name = ?`, artist).Scan(&id); err != nil { + t.Fatalf("track of %q: %v", artist, err) + } + return id +} + +func (e *similarEnv) listen(t *testing.T, token string, track int64, typ string, ms int64, key string) { + t.Helper() + body := map[string]any{"track_id": track, "event_type": typ, "duration_played_ms": ms, "idempotency_key": key} + if r := do(t, e.h, "POST", "/api/v1/listens", token, body); r.Code != http.StatusCreated { + t.Fatalf("listen %s: %d %v", key, r.Code, r.Body) + } +} + +func TestTasteNeedsASignedInUser(t *testing.T) { + e := newTasteEnv(t) + if r := do(t, e.h, "GET", "/api/v1/me/taste", "", nil); r.Code != http.StatusUnauthorized { + t.Errorf("no token: %d", r.Code) + } +} + +func TestTasteOfANewListenerIsEmptyLists(t *testing.T) { + e := newTasteEnv(t) + r := do(t, e.h, "GET", "/api/v1/me/taste", e.admin, nil) + if r.Code != http.StatusOK { + t.Fatalf("%d %v", r.Code, r.Body) + } + sameKeys(t, "taste", r.Body, "artists", "tags") + artists, ok1 := r.Body["artists"].([]any) + tags, ok2 := r.Body["tags"].([]any) + if !ok1 || !ok2 || len(artists) != 0 || len(tags) != 0 { + t.Errorf("taste = %v, want two empty lists", r.Body) + } +} + +func TestTasteFollowsWhatIListenTo(t *testing.T) { + e := newTasteEnv(t) + alpha, beta := e.trackOf(t, "Alpha"), e.trackOf(t, "Beta") + for i := 0; i < 3; i++ { + e.listen(t, e.admin, alpha, "complete", 1000, "a"+strconv.Itoa(i)) + } + e.listen(t, e.admin, beta, "skip", 1000, "b1") // too soon: against Beta + if _, err := e.db.Exec("INSERT INTO track_genres (track_id, genre) VALUES (?, 'shoegaze')", alpha); err != nil { + t.Fatal(err) + } + + r := do(t, e.h, "GET", "/api/v1/me/taste", e.admin, nil) + if r.Code != http.StatusOK { + t.Fatalf("%d %v", r.Code, r.Body) + } + artists := r.Body["artists"].([]any) + if len(artists) != 1 { + t.Fatalf("artists = %v, want only the one I like", artists) + } + a := artists[0].(map[string]any) + sameKeys(t, "artist", a, "id", "name", "preference", "listens", "last_listened_at") + if a["name"] != "Alpha" || a["id"] != float64(e.alpha) || a["listens"] != float64(3) { + t.Errorf("artist = %v", a) + } + if p, _ := a["preference"].(float64); math.Abs(p-math.Tanh(1)) > 0.001 { // three listens, just now + t.Errorf("preference = %v, want about %v", p, math.Tanh(1)) + } + if _, err := time.Parse(time.RFC3339, a["last_listened_at"].(string)); err != nil { + t.Errorf("last_listened_at = %v", a["last_listened_at"]) + } + tags := r.Body["tags"].([]any) + if len(tags) != 1 { + t.Fatalf("tags = %v", tags) + } + tg := tags[0].(map[string]any) + sameKeys(t, "tag", tg, "tag", "weight") + if tg["tag"] != "shoegaze" || tg["weight"] != float64(1) { + t.Errorf("tag = %v", tg) + } +} + +func TestTasteIsPrivate(t *testing.T) { + e := newTasteEnv(t) + e.listen(t, e.admin, e.trackOf(t, "Alpha"), "complete", 1000, "a1") + + body := map[string]any{"username": "bob", "password": "longenough"} + if r := do(t, e.h, "POST", "/api/v1/users", e.admin, body); r.Code != http.StatusCreated { + t.Fatalf("create bob: %d %v", r.Code, r.Body) + } + login := do(t, e.h, "POST", "/api/v1/auth/login", "", body) + bob, _ := login.Body["access_token"].(string) + r := do(t, e.h, "GET", "/api/v1/me/taste", bob, nil) + if r.Code != http.StatusOK || len(r.Body["artists"].([]any)) != 0 { + t.Errorf("bob sees %d %v, want nothing of alice's listening", r.Code, r.Body) + } +} + +func TestTasteLimit(t *testing.T) { + e := newTasteEnv(t) + e.listen(t, e.admin, e.trackOf(t, "Alpha"), "complete", 1000, "a1") + e.listen(t, e.admin, e.trackOf(t, "Beta"), "complete", 1000, "b1") + for _, tt := range []struct { + query string + code int + n int + }{ + {"", 200, 2}, {"?limit=1", 200, 1}, {"?limit=0", 200, 2}, {"?limit=1000", 200, 2}, + {"?limit=abc", 400, 0}, {"?limit=-1", 400, 0}, + } { + r := do(t, e.h, "GET", "/api/v1/me/taste"+tt.query, e.admin, nil) + if r.Code != tt.code { + t.Errorf("%q: %d %v, want %d", tt.query, r.Code, r.Body, tt.code) + continue + } + if tt.code == 200 && len(r.Body["artists"].([]any)) != tt.n { + t.Errorf("%q: %d artists, want %d", tt.query, len(r.Body["artists"].([]any)), tt.n) + } + if tt.code == 400 && errCode(r) != "invalid_input" { + t.Errorf("%q: error %v", tt.query, r.Body) + } + } +} diff --git a/internal/api/openapi/openapi.yaml b/internal/api/openapi/openapi.yaml index 81b2617..2809085 100644 --- a/internal/api/openapi/openapi.yaml +++ b/internal/api/openapi/openapi.yaml @@ -33,6 +33,8 @@ tags: description: Browsing and searching what can be played. - name: Playback description: Streaming and listening history. + - name: Taste + description: What Sonda has learned from your listening. - name: Discovery description: Music outside the library, from external providers an admin switched on. - name: Providers @@ -648,6 +650,43 @@ paths: application/json: schema: {$ref: '#/components/schemas/Error'} + /me/taste: + get: + tags: [Taste] + operationId: getMyTaste + summary: What Sonda has learned about your taste + description: | + Your taste, worked out from your own listening history every time you ask. It uses local + data only: nothing is sent to any provider, and nobody else's history is read. + + Each event has a value: a `complete` listen +1, any other listen that counts +0.5 (see + `POST /listens`), a `skip` before that -1, and a play too short to mean anything 0. An + event weighs half as much for every 90 days (`taste.half_life_days`) that has passed. For + each artist the values add up, and `preference` is `tanh(sum / 3)`: from -1 to 1, never + reaching either, so one skip does not sink an artist and no amount of listening makes + one perfect. A track with several artists credits each of them. + + `artists` are the ones you like (a `preference` above 0), the most liked first, ties going + to the most recent listen. `tags` are the kinds of music you like: the tags of those + artists (the genres of your files, and what Last.fm and MusicBrainz said earlier, if + they were ever asked) added up, each artist weighing as much as its `preference`, and + scaled so the best tag is 1. Tags are read from what is already stored; this request never + asks a provider. The tag profile is built from your 200 most liked artists. + security: [{bearerAuth: []}] + parameters: + - name: limit + in: query + description: How many artists to return. 20 when absent or 0; values above 50 are lowered to 50. Tags are not limited by it. + schema: {type: integer, minimum: 0, default: 20} + responses: + '200': + description: Your taste. Both lists are empty until you have listened to something. + content: + application/json: + schema: {$ref: '#/components/schemas/Taste'} + '400': {$ref: '#/components/responses/InvalidInput'} + '401': {$ref: '#/components/responses/Unauthorized'} + /albums: get: tags: [Catalog] @@ -1560,6 +1599,37 @@ components: duration_played_ms: {type: integer, format: int64} counted: {type: boolean, description: Whether the event counts as a listen under the current rule.} + Taste: + type: object + additionalProperties: false + required: [artists, tags] + properties: + artists: + type: array + items: {$ref: '#/components/schemas/TasteArtist'} + tags: + type: array + items: {$ref: '#/components/schemas/TasteTag'} + + TasteArtist: + type: object + additionalProperties: false + required: [id, name, preference, listens, last_listened_at] + properties: + id: {type: integer, format: int64} + name: {type: string} + preference: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: How much you like the artist. Only artists above 0 are listed.} + listens: {type: integer, description: "Events that count as a listen, with no decay."} + last_listened_at: {type: string, format: date-time, description: The most recent listen that counted.} + + TasteTag: + type: object + additionalProperties: false + required: [tag, weight] + properties: + tag: {type: string, description: Lower case.} + weight: {type: number, minimum: 0, exclusiveMinimum: true, maximum: 1, description: "How much the tag matters to you; the best one is 1."} + ListenPage: type: object additionalProperties: false diff --git a/internal/config/config.go b/internal/config/config.go index 624beeb..3a5db8b 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -23,6 +23,7 @@ type Config struct { Log Log `toml:"log"` Auth Auth `toml:"auth"` Listening Listening `toml:"listening"` + Taste Taste `toml:"taste"` } // Server holds HTTP listener settings. @@ -80,6 +81,17 @@ func (l Listening) MinListen() time.Duration { return time.Duration(l.MinListenSeconds) * time.Second } +// Taste holds the knobs of the model that learns from listening. +type Taste struct { + // HalfLifeDays is how long it takes for an old listen to weigh half as much. + HalfLifeDays int `toml:"half_life_days"` +} + +// HalfLife returns the half-life of a listening event. +func (t Taste) HalfLife() time.Duration { + return time.Duration(t.HalfLifeDays) * 24 * time.Hour +} + // Default returns the configuration used when nothing else is set. func Default() Config { return Config{ @@ -89,6 +101,7 @@ func Default() Config { Log: Log{Env: "production"}, Auth: Auth{AccessTTLMinutes: 15, RefreshTTLHours: 720}, // 15 minutes, 30 days Listening: Listening{MinListenSeconds: 20}, + Taste: Taste{HalfLifeDays: 90}, } } @@ -174,6 +187,9 @@ func (c Config) Validate() error { if c.Listening.MinListenSeconds < 1 || c.Listening.MinListenSeconds > 3600 { errs = append(errs, errors.New("listening.min_listen_seconds must be between 1 and 3600")) } + if c.Taste.HalfLifeDays < 1 || c.Taste.HalfLifeDays > 3650 { + errs = append(errs, errors.New("taste.half_life_days must be between 1 and 3650")) + } if c.Library.ScanWorkers < 1 { errs = append(errs, errors.New("library.scan_workers must be at least 1")) } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 2c9169e..b8fc240 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -131,6 +131,9 @@ func TestValidate(t *testing.T) { {"zero min listen", func(c *Config) { c.Listening.MinListenSeconds = 0 }, "listening.min_listen_seconds"}, {"negative min listen", func(c *Config) { c.Listening.MinListenSeconds = -5 }, "listening.min_listen_seconds"}, {"absurd min listen", func(c *Config) { c.Listening.MinListenSeconds = 3601 }, "listening.min_listen_seconds"}, + {"zero half life", func(c *Config) { c.Taste.HalfLifeDays = 0 }, "taste.half_life_days"}, + {"negative half life", func(c *Config) { c.Taste.HalfLifeDays = -1 }, "taste.half_life_days"}, + {"absurd half life", func(c *Config) { c.Taste.HalfLifeDays = 3651 }, "taste.half_life_days"}, {"bad workers", func(c *Config) { c.Library.ScanWorkers = 0 }, "library.scan_workers"}, {"bad access ttl", func(c *Config) { c.Auth.AccessTTLMinutes = 0 }, "auth.access_ttl_minutes"}, {"bad refresh ttl", func(c *Config) { c.Auth.RefreshTTLHours = 0 }, "auth.refresh_ttl_hours"}, @@ -181,6 +184,19 @@ func TestListeningSettingIsReadFromTheFile(t *testing.T) { } } +func TestTasteSettingIsReadFromTheFile(t *testing.T) { + cfg, err := Load(writeFile(t, t.TempDir(), "[taste]\nhalf_life_days = 30\n")) + if err != nil { + t.Fatal(err) + } + if cfg.Taste.HalfLife() != 30*24*time.Hour { + t.Errorf("half life = %v", cfg.Taste.HalfLife()) + } + if def := Default().Taste.HalfLife(); def != 90*24*time.Hour { + t.Errorf("default half life = %v, want 90 days", def) + } +} + // Provider settings moved into the database. An old config must fail with a // hint, never be ignored in silence. func TestLoadExplainsRemovedProviderSettings(t *testing.T) { diff --git a/internal/storage/taste.go b/internal/storage/taste.go new file mode 100644 index 0000000..8834ce6 --- /dev/null +++ b/internal/storage/taste.go @@ -0,0 +1,192 @@ +package storage + +import ( + "context" + "fmt" + "time" + + "github.com/uptrace/bun" + + "codeberg.org/squidd/sonda/internal/listening" + "codeberg.org/squidd/sonda/internal/providers" + "codeberg.org/squidd/sonda/internal/taste" +) + +// TasteRepo reads what the taste model needs. It implements taste.Store and +// never writes. +type TasteRepo struct{ db *bun.DB } + +// NewTasteRepo builds a TasteRepo. +func NewTasteRepo(db *bun.DB) *TasteRepo { return &TasteRepo{db: db} } + +// ArtistEvents returns the user's events since the given time, one per credited +// artist of the track. Tracks whose files are gone still count: the history is +// the listener's own. +func (r *TasteRepo) ArtistEvents(ctx context.Context, userID int64, since time.Time) ([]taste.Event, error) { + rows, err := r.db.QueryContext(ctx, + `SELECT ta.artist_id, e.event_type, e.duration_played_ms, e.occurred_at + FROM listening_events e JOIN track_artists ta ON ta.track_id = e.track_id + WHERE e.user_id = ? AND e.occurred_at >= ? AND ta.role = 'main' + ORDER BY e.occurred_at, e.id, ta.artist_id`, + userID, since.Unix()) + if err != nil { + return nil, fmt.Errorf("read listening events: %w", err) + } + defer rows.Close() + var out []taste.Event + for rows.Next() { + var ( + e taste.Event + typ string + at int64 + ) + if err := rows.Scan(&e.ArtistID, &typ, &e.PlayedMs, &at); err != nil { + return nil, err + } + e.Type, e.At = listening.EventType(typ), time.Unix(at, 0) + out = append(out, e) + } + return out, rows.Err() +} + +// ArtistNames returns the names of the artists that exist. +func (r *TasteRepo) ArtistNames(ctx context.Context, ids []int64) (map[int64]string, error) { + out := map[int64]string{} + if len(ids) == 0 { + return out, nil + } + rows, err := r.db.QueryContext(ctx, "SELECT id, name FROM artists WHERE id IN (?)", bun.In(ids)) + if err != nil { + return nil, fmt.Errorf("read artist names: %w", err) + } + defer rows.Close() + for rows.Next() { + var ( + id int64 + name string + ) + if err := rows.Scan(&id, &name); err != nil { + return nil, err + } + out[id] = name + } + return out, rows.Err() +} + +// ArtistTags returns the stored tags of the artists with weights from 0 to 1, +// from the genres of the user's files and from what the providers once said. It +// asks nobody. Each source is scaled to its own best tag (Last.fm's weights are +// already a percentage, MusicBrainz's are votes, the files' are track counts) and +// a tag several sources know keeps the largest weight. +func (r *TasteRepo) ArtistTags(ctx context.Context, ids []int64) (map[int64]map[string]float64, error) { + out := map[int64]map[string]float64{} + if len(ids) == 0 { + return out, nil + } + put := func(artist int64, tag string, w float64) { + if w > 1 { + w = 1 + } + if out[artist] == nil { + out[artist] = map[string]float64{} + } + if w > out[artist][tag] { + out[artist][tag] = w + } + } + + // Files: track counts, scaled to the artist's most common genre. + files, err := r.db.QueryContext(ctx, + `SELECT ta.artist_id, g.genre, COUNT(DISTINCT ta.track_id) + FROM track_artists ta JOIN track_genres g ON g.track_id = ta.track_id + WHERE ta.artist_id IN (?) AND ta.role = 'main' GROUP BY ta.artist_id, g.genre`, + bun.In(ids)) + if err != nil { + return nil, fmt.Errorf("read genres: %w", err) + } + if err := scaleToBest(files, put); err != nil { + return nil, err + } + + // Providers. + stored, err := r.db.QueryContext(ctx, + "SELECT artist_id, provider, tag, weight FROM artist_tags WHERE artist_id IN (?)", bun.In(ids)) + if err != nil { + return nil, fmt.Errorf("read tags: %w", err) + } + defer stored.Close() + type key struct { + artist int64 + provider string + } + type row struct { + artist int64 + tag string + weight float64 + } + byProvider := map[key][]row{} + best := map[key]float64{} + for stored.Next() { + var ( + rw row + provider string + ) + if err := stored.Scan(&rw.artist, &provider, &rw.tag, &rw.weight); err != nil { + return nil, err + } + k := key{rw.artist, provider} + byProvider[k] = append(byProvider[k], rw) + if rw.weight > best[k] { + best[k] = rw.weight + } + } + if err := stored.Err(); err != nil { + return nil, err + } + for k, rows := range byProvider { + for _, rw := range rows { + switch { + case k.provider == providers.LastFM: + put(rw.artist, rw.tag, rw.weight/100) + case best[k] > 0: + put(rw.artist, rw.tag, rw.weight/best[k]) + } + } + } + return out, nil +} + +// scaleToBest reads (artist, tag, count) rows and hands each one over scaled to +// the largest count of its artist. +func scaleToBest(rows interface { + Next() bool + Scan(...any) error + Err() error + Close() error +}, put func(int64, string, float64)) error { + defer rows.Close() + type row struct { + artist int64 + tag string + n float64 + } + var all []row + best := map[int64]float64{} + for rows.Next() { + var rw row + if err := rows.Scan(&rw.artist, &rw.tag, &rw.n); err != nil { + return err + } + all = append(all, rw) + if rw.n > best[rw.artist] { + best[rw.artist] = rw.n + } + } + if err := rows.Err(); err != nil { + return err + } + for _, rw := range all { + put(rw.artist, rw.tag, rw.n/best[rw.artist]) + } + return nil +} diff --git a/internal/storage/taste_test.go b/internal/storage/taste_test.go new file mode 100644 index 0000000..7349bf9 --- /dev/null +++ b/internal/storage/taste_test.go @@ -0,0 +1,150 @@ +package storage + +import ( + "context" + "testing" + "time" + + "github.com/uptrace/bun" + + "codeberg.org/squidd/sonda/internal/listening" + "codeberg.org/squidd/sonda/internal/taste" +) + +func trackByTitle(t *testing.T, db *bun.DB, title string) int64 { + t.Helper() + var id int64 + if err := db.QueryRow("SELECT id FROM tracks WHERE title = ?", title).Scan(&id); err != nil { + t.Fatalf("track %q: %v", title, err) + } + return id +} + +func TestTasteArtistEvents(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + s := seedCatalog(t, db) + ctx := context.Background() + users := NewUserRepo(db) + alice, _ := users.CreateUser(ctx, "alice", "h", false) + bob, _ := users.CreateUser(ctx, "bob", "h", false) + repo := NewListeningRepo(db) + record := func(user int64, track, key string, typ listening.EventType, ms int64, when time.Time) { + t.Helper() + if _, err := repo.Record(ctx, listening.Event{UserID: user, TrackID: s.track[track], Type: typ, + OccurredAt: when, DurationPlayedMs: ms, IdempotencyKey: key}); err != nil { + t.Fatal(err) + } + } + old, recent := time.Unix(1_000_000, 0), time.Unix(1_700_000_000, 0) + record(alice.ID, "Airbag", "a1", listening.Complete, 200_000, recent) + record(alice.ID, "Airbag", "a2", listening.Skip, 3_000, old) // before the cut: not read + record(alice.ID, "Army of Me", "a3", listening.Play, 30_000, recent) + record(bob.ID, "Airbag", "b1", listening.Complete, 1, recent) // somebody else's + // Two artists credited on one track: both are credited with the event. + record(alice.ID, "Song A", "a4", listening.Complete, 100_000, recent) + + got, err := NewTasteRepo(db).ArtistEvents(ctx, alice.ID, time.Unix(1_600_000_000, 0)) + if err != nil { + t.Fatal(err) + } + by := map[int64][]taste.Event{} + for _, e := range got { + by[e.ArtistID] = append(by[e.ArtistID], e) + } + radiohead, bjork := artistID(t, db, "Radiohead"), artistID(t, db, "Björk") + if len(by[radiohead]) != 1 || by[radiohead][0].Type != listening.Complete || by[radiohead][0].PlayedMs != 200_000 || + !by[radiohead][0].At.Equal(recent) { + t.Errorf("Radiohead events = %+v", by[radiohead]) + } + if len(by[bjork]) != 1 || by[bjork][0].Type != listening.Play { + t.Errorf("Björk events = %+v", by[bjork]) + } + if len(by[artistID(t, db, "Artist A")]) != 1 { + t.Errorf("the artist credited on Song A has %d events, want 1", len(by[artistID(t, db, "Artist A")])) + } + if len(got) != 3 { + t.Errorf("got %d events, want 3: %+v", len(got), got) + } + + // A track whose files are gone still counts: the history is the listener's own. + record(alice.ID, "Ghost", "a5", listening.Complete, 100_000, recent) + got, _ = NewTasteRepo(db).ArtistEvents(ctx, alice.ID, time.Unix(1_600_000_000, 0)) + if len(got) != 4 { + t.Errorf("with a track that has no file: %d events, want 4", len(got)) + } + }) +} + +func TestTasteArtistNames(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + seedCatalog(t, db) + repo := NewTasteRepo(db) + radiohead := artistID(t, db, "Radiohead") + got, err := repo.ArtistNames(context.Background(), []int64{radiohead, 99999}) + if err != nil || len(got) != 1 || got[radiohead] != "Radiohead" { + t.Errorf("names = %v err=%v", got, err) + } + if got, err := repo.ArtistNames(context.Background(), nil); err != nil || len(got) != 0 { + t.Errorf("no ids: %v err=%v", got, err) + } + }) +} + +func TestTasteArtistTags(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + s := seedCatalog(t, db) + ctx := context.Background() + radiohead, bjork := artistID(t, db, "Radiohead"), artistID(t, db, "Björk") + + // Genres of the files: Radiohead has 4 tracks, 4 rock and 2 art rock. + for _, g := range []struct{ track, genre string }{ + {"Airbag", "rock"}, {"Paranoid Android", "rock"}, {"Karma Police", "rock"}, {"Ghost", "rock"}, + {"Airbag", "art rock"}, {"Karma Police", "art rock"}, + } { + if _, err := db.Exec("INSERT INTO track_genres (track_id, genre) VALUES (?, ?)", s.track[g.track], g.genre); err != nil { + t.Fatal(err) + } + } + // Provider tags: Last.fm is 0-100, MusicBrainz is votes. + for _, row := range []struct { + artist int64 + provider string + tag string + weight float64 + }{ + {radiohead, "lastfm", "alternative", 100}, + {radiohead, "lastfm", "rock", 40}, // the files say 1: the larger weight wins + {radiohead, "musicbrainz", "electronic", 4}, + {radiohead, "musicbrainz", "alternative", 8}, // 8 of 8 votes: 1 + {bjork, "lastfm", "icelandic", 50}, + } { + if _, err := db.Exec("INSERT INTO artist_tags (artist_id, provider, tag, weight) VALUES (?, ?, ?, ?)", + row.artist, row.provider, row.tag, row.weight); err != nil { + t.Fatal(err) + } + } + + got, err := NewTasteRepo(db).ArtistTags(ctx, []int64{radiohead, bjork, artistID(t, db, "Miles Davis")}) + if err != nil { + t.Fatal(err) + } + want := map[string]float64{"rock": 1, "art rock": 0.5, "alternative": 1, "electronic": 0.5} + if len(got[radiohead]) != len(want) { + t.Errorf("Radiohead tags = %v, want %v", got[radiohead], want) + } + for tag, w := range want { + if got[radiohead][tag] != w { + t.Errorf("Radiohead %q = %v, want %v", tag, got[radiohead][tag], w) + } + } + if got[bjork]["icelandic"] != 0.5 || len(got[bjork]) != 1 { + t.Errorf("Björk tags = %v", got[bjork]) + } + if len(got[artistID(t, db, "Miles Davis")]) != 0 { + t.Errorf("an artist with no tags has %v", got[artistID(t, db, "Miles Davis")]) + } + if got, err := NewTasteRepo(db).ArtistTags(ctx, nil); err != nil || len(got) != 0 { + t.Errorf("no ids: %v err=%v", got, err) + } + }) +} diff --git a/internal/taste/service.go b/internal/taste/service.go new file mode 100644 index 0000000..5fa01d6 --- /dev/null +++ b/internal/taste/service.go @@ -0,0 +1,143 @@ +package taste + +import ( + "context" + "errors" + "fmt" + "sort" + "time" +) + +// ErrInvalidQuery is returned for a limit that makes no sense. +var ErrInvalidQuery = errors.New("invalid query") + +// Limits of the artist list. +const ( + DefaultLimit = 20 + MaxLimit = 50 + + // MaxProfileArtists is how many of the liked artists, the most liked first, + // shape the tag profile. The rest weigh too little to change it and cost a read each. + MaxProfileArtists = 200 + + // lookbackHalfLives is how far back the history is read: an event ten + // half-lives old weighs less than a thousandth of a new one. + lookbackHalfLives = 10 +) + +// Store reads what the model needs. It never writes. +type Store interface { + // ArtistEvents returns the listener's events since the given time, one per + // credited artist of the track. Events of deleted tracks are gone with them. + ArtistEvents(ctx context.Context, userID int64, since time.Time) ([]Event, error) + // ArtistTags returns, per artist, the tags already stored for it with weights + // from 0 to 1 (genres of the files and tags that providers gave). It reads + // the database only. + ArtistTags(ctx context.Context, artistIDs []int64) (map[int64]map[string]float64, error) + // ArtistNames returns the names of the given artists. + ArtistNames(ctx context.Context, artistIDs []int64) (map[int64]string, error) +} + +// ArtistTaste is an artist the listener likes. +type ArtistTaste struct { + ID int64 + Name string + Preference float64 // above 0, at most 1 + Listens int + LastListened time.Time +} + +// Profile is what Sonda has learned about a listener. +type Profile struct { + Artists []ArtistTaste // liked artists, the most liked first + Tags []TagWeight // best first, the top one is 1 +} + +// Service works out profiles. +type Service struct { + store Store + opts Options + now func() time.Time +} + +// NewService builds a Service. +func NewService(store Store, o Options) *Service { + return &Service{store: store, opts: o, now: time.Now} +} + +// Taste returns the listener's profile: up to limit liked artists (zero means +// DefaultLimit) and the tag profile built from the liked artists. +func (s *Service) Taste(ctx context.Context, userID int64, limit int) (Profile, error) { + if limit < 0 { + return Profile{}, fmt.Errorf("%w: limit cannot be negative", ErrInvalidQuery) + } + switch { + case limit == 0: + limit = DefaultLimit + case limit > MaxLimit: + limit = MaxLimit + } + + now := s.now() + events, err := s.store.ArtistEvents(ctx, userID, now.Add(-lookbackHalfLives*s.opts.HalfLife)) + if err != nil { + return Profile{}, fmt.Errorf("read events: %w", err) + } + var liked []ArtistPref + for _, p := range Preferences(events, now, s.opts) { + if p.Preference > 0 { + liked = append(liked, p) + } + } + sort.Slice(liked, func(i, j int) bool { + a, b := liked[i], liked[j] + switch { + case a.Preference != b.Preference: + return a.Preference > b.Preference + case !a.LastListened.Equal(b.LastListened): + return a.LastListened.After(b.LastListened) + default: + return a.ArtistID < b.ArtistID + } + }) + + profile := Profile{Artists: []ArtistTaste{}, Tags: []TagWeight{}} + if len(liked) == 0 { + return profile, nil + } + + top := liked + if len(top) > MaxProfileArtists { + top = top[:MaxProfileArtists] + } + ids := make([]int64, len(top)) + prefs := make(map[int64]ArtistPref, len(top)) + for i, p := range top { + ids[i], prefs[p.ArtistID] = p.ArtistID, p + } + tags, err := s.store.ArtistTags(ctx, ids) + if err != nil { + return Profile{}, fmt.Errorf("read tags: %w", err) + } + profile.Tags = TagProfile(prefs, tags) + + shown := liked + if len(shown) > limit { + shown = shown[:limit] + } + shownIDs := make([]int64, len(shown)) + for i, p := range shown { + shownIDs[i] = p.ArtistID + } + names, err := s.store.ArtistNames(ctx, shownIDs) + if err != nil { + return Profile{}, fmt.Errorf("read names: %w", err) + } + for _, p := range shown { + profile.Artists = append(profile.Artists, ArtistTaste{ + ID: p.ArtistID, Name: names[p.ArtistID], Preference: p.Preference, + Listens: p.Listens, LastListened: p.LastListened, + }) + } + return profile, nil +} diff --git a/internal/taste/service_test.go b/internal/taste/service_test.go new file mode 100644 index 0000000..fcc0308 --- /dev/null +++ b/internal/taste/service_test.go @@ -0,0 +1,166 @@ +package taste + +import ( + "context" + "errors" + "testing" + "time" + + "codeberg.org/squidd/sonda/internal/listening" +) + +type fakeStore struct { + events []Event + tags map[int64]map[string]float64 + names map[int64]string + since time.Time + user int64 + tagCalls [][]int64 + nameCalls [][]int64 + err error +} + +func (f *fakeStore) ArtistEvents(_ context.Context, userID int64, since time.Time) ([]Event, error) { + f.user, f.since = userID, since + return f.events, f.err +} + +func (f *fakeStore) ArtistTags(_ context.Context, ids []int64) (map[int64]map[string]float64, error) { + f.tagCalls = append(f.tagCalls, ids) + return f.tags, f.err +} + +func (f *fakeStore) ArtistNames(_ context.Context, ids []int64) (map[int64]string, error) { + f.nameCalls = append(f.nameCalls, ids) + return f.names, f.err +} + +func newService(f *fakeStore) *Service { + s := NewService(f, options) + s.now = func() time.Time { return now } + return s +} + +func complete(artist int64, n int) []Event { + var out []Event + for i := 0; i < n; i++ { + out = append(out, Event{ArtistID: artist, Type: listening.Complete, At: now}) + } + return out +} + +func TestTasteRanksTheArtistsILikeAndLeavesOutTheOthers(t *testing.T) { + f := &fakeStore{ + events: append(append(complete(1, 5), complete(2, 1)...), + Event{ArtistID: 3, Type: listening.Skip, PlayedMs: 1_000, At: now}, + Event{ArtistID: 4, Type: listening.Play, PlayedMs: 2_000, At: now}), // too short: neutral + tags: map[int64]map[string]float64{1: {"rock": 1}, 2: {"pop": 1}}, + names: map[int64]string{1: "One", 2: "Two"}, + } + p, err := newService(f).Taste(context.Background(), 7, 0) + if err != nil { + t.Fatal(err) + } + if f.user != 7 { + t.Errorf("asked for user %d", f.user) + } + if len(p.Artists) != 2 || p.Artists[0].ID != 1 || p.Artists[1].ID != 2 { + t.Fatalf("artists = %+v, want 1 then 2 only", p.Artists) + } + if p.Artists[0].Name != "One" || p.Artists[0].Listens != 5 || p.Artists[0].Preference <= p.Artists[1].Preference { + t.Errorf("first artist = %+v", p.Artists[0]) + } + if len(p.Tags) != 2 || p.Tags[0].Tag != "rock" || p.Tags[0].Weight != 1 { + t.Errorf("tags = %+v, want rock first at 1", p.Tags) + } + // Only the artists that are shown or liked are looked up, never the skipped ones. + for _, ids := range append(f.tagCalls, f.nameCalls...) { + for _, id := range ids { + if id == 3 || id == 4 { + t.Errorf("looked up artist %d, who is not liked", id) + } + } + } +} + +func TestTasteLooksOnlyAsFarBackAsItMatters(t *testing.T) { + f := &fakeStore{} + if _, err := newService(f).Taste(context.Background(), 1, 0); err != nil { + t.Fatal(err) + } + if want := now.Add(-10 * options.HalfLife); !f.since.Equal(want) { + t.Errorf("since = %v, want ten half-lives back: %v", f.since, want) + } +} + +func TestTasteOfSomeoneWhoHasListenedToNothing(t *testing.T) { + p, err := newService(&fakeStore{}).Taste(context.Background(), 1, 0) + if err != nil { + t.Fatal(err) + } + if p.Artists == nil || p.Tags == nil || len(p.Artists) != 0 || len(p.Tags) != 0 { + t.Errorf("profile = %+v, want empty lists that are not nil", p) + } +} + +func TestTasteLimit(t *testing.T) { + var events []Event + names := map[int64]string{} + for id := int64(1); id <= 60; id++ { + events = append(events, complete(id, 1)...) + names[id] = "a" + } + f := &fakeStore{events: events, names: names} + s := newService(f) + + p, _ := s.Taste(context.Background(), 1, 0) + if len(p.Artists) != DefaultLimit { + t.Errorf("default limit: %d artists, want %d", len(p.Artists), DefaultLimit) + } + if p, _ = s.Taste(context.Background(), 1, 1000); len(p.Artists) != MaxLimit { + t.Errorf("large limit: %d artists, want %d", len(p.Artists), MaxLimit) + } + if p, _ = s.Taste(context.Background(), 1, 3); len(p.Artists) != 3 { + t.Errorf("limit 3: %d artists", len(p.Artists)) + } + if _, err := s.Taste(context.Background(), 1, -1); !errors.Is(err, ErrInvalidQuery) { + t.Errorf("negative limit: err = %v", err) + } +} + +func TestTasteTiesAreStable(t *testing.T) { + // Same preference, so the one heard more recently goes first, then the lower id. + f := &fakeStore{ + events: []Event{ + {ArtistID: 5, Type: listening.Complete, At: now.Add(-time.Hour)}, + {ArtistID: 4, Type: listening.Complete, At: now.Add(-time.Hour)}, + {ArtistID: 6, Type: listening.Complete, At: now.Add(-time.Hour)}, + }, + names: map[int64]string{}, + } + p, _ := newService(f).Taste(context.Background(), 1, 0) + if len(p.Artists) != 3 || p.Artists[0].ID != 4 || p.Artists[1].ID != 5 || p.Artists[2].ID != 6 { + t.Errorf("order = %+v", p.Artists) + } +} + +func TestTasteBoundsTheArtistsBehindTheTagProfile(t *testing.T) { + var events []Event + for id := int64(1); id <= MaxProfileArtists+50; id++ { + events = append(events, complete(id, 1)...) + } + f := &fakeStore{events: events, names: map[int64]string{}} + if _, err := newService(f).Taste(context.Background(), 1, 0); err != nil { + t.Fatal(err) + } + if len(f.tagCalls) != 1 || len(f.tagCalls[0]) != MaxProfileArtists { + t.Errorf("tags were read for %d artists in %d calls, want %d in one", len(f.tagCalls[len(f.tagCalls)-1]), len(f.tagCalls), MaxProfileArtists) + } +} + +func TestTasteReturnsStoreErrors(t *testing.T) { + boom := errors.New("boom") + if _, err := newService(&fakeStore{err: boom}).Taste(context.Background(), 1, 0); !errors.Is(err, boom) { + t.Errorf("err = %v", err) + } +} diff --git a/internal/taste/taste.go b/internal/taste/taste.go new file mode 100644 index 0000000..587aa3a --- /dev/null +++ b/internal/taste/taste.go @@ -0,0 +1,136 @@ +// Package taste learns what a listener likes from what they listen to. +// +// Everything here is computed from the listener's own history and from tags that +// are already stored. Nothing is sent to any provider, and nothing is kept: the +// profile is worked out again on every request, so a change to the listening +// rule or to the half-life applies to the whole past at once. +// +// Each listening event has a value (see EventValue). Older events weigh less +// (the weight halves every Options.HalfLife). The values of one artist add up +// and are squeezed into (-1, 1) by tanh, so a few listens already say something +// but no amount of them reaches 1, and one skip does not sink an artist. +package taste + +import ( + "math" + "sort" + "time" + + "codeberg.org/squidd/sonda/internal/listening" +) + +// sumScale is the sum of weighted values that gives tanh(1), about 0.76: three +// full recent listens. +const sumScale = 3.0 + +// Options are the knobs of the model. +type Options struct { + MinListen time.Duration // how long a play must last to count as a listen + HalfLife time.Duration // after this long an event weighs half as much +} + +// Event is one thing the listener did with a track, credited to one of its artists. +type Event struct { + ArtistID int64 + Type listening.EventType + PlayedMs int64 + At time.Time +} + +// ArtistPref is what the history says about one artist. +type ArtistPref struct { + ArtistID int64 + Preference float64 // from -1 (avoided) to 1 (loved); 0 is neutral + Listens int // events that count as a listen, with no decay + LastListened time.Time // the latest counted event; zero when there is none +} + +// TagWeight is how much a tag matters to the listener, from 0 to 1. +type TagWeight struct { + Tag string + Weight float64 +} + +// EventValue says how much one event tells in favour (positive) or against +// (negative) the artist: a complete listen +1, any other listen +0.5, a skip +// before the listener had heard enough -1, and a play too short to mean anything 0. +func EventValue(t listening.EventType, playedMs int64, minListen time.Duration) float64 { + switch { + case t == listening.Complete: + return 1 + case playedMs >= minListen.Milliseconds(): + return 0.5 + case t == listening.Skip: + return -1 + default: + return 0 + } +} + +func counted(t listening.EventType, playedMs int64, minListen time.Duration) bool { + return t == listening.Complete || playedMs >= minListen.Milliseconds() +} + +// Preferences works out the preference of every artist that has events. +func Preferences(events []Event, now time.Time, o Options) map[int64]ArtistPref { + sums := map[int64]float64{} + out := map[int64]ArtistPref{} + for _, e := range events { + age := now.Sub(e.At) + if age < 0 { + age = 0 // a fast clock does not make an event more than new + } + weight := math.Exp2(-float64(age) / float64(o.HalfLife)) + sums[e.ArtistID] += weight * EventValue(e.Type, e.PlayedMs, o.MinListen) + + p := out[e.ArtistID] + p.ArtistID = e.ArtistID + if counted(e.Type, e.PlayedMs, o.MinListen) { + p.Listens++ + if e.At.After(p.LastListened) { + p.LastListened = e.At + } + } + out[e.ArtistID] = p + } + for id, p := range out { + p.Preference = math.Tanh(sums[id] / sumScale) + out[id] = p + } + return out +} + +// TagProfile adds up the tags of the artists the listener likes, each weighed by +// how much, and scales the result so the best tag is 1. Artists with a preference +// of zero or less add nothing. tags holds, per artist, tag weights from 0 to 1. +// The result is best first, ties in name order. +func TagProfile(prefs map[int64]ArtistPref, tags map[int64]map[string]float64) []TagWeight { + sums := map[string]float64{} + for id, p := range prefs { + if p.Preference <= 0 { + continue + } + for tag, w := range tags[id] { + sums[tag] += p.Preference * w + } + } + out := make([]TagWeight, 0, len(sums)) + best := 0.0 + for tag, w := range sums { + if w <= 0 { + continue + } + out = append(out, TagWeight{Tag: tag, Weight: w}) + best = math.Max(best, w) + } + for i := range out { + out[i].Weight /= best + } + sort.Slice(out, func(i, j int) bool { + if out[i].Weight != out[j].Weight { + return out[i].Weight > out[j].Weight + } + return out[i].Tag < out[j].Tag + }) + return out +} diff --git a/internal/taste/taste_test.go b/internal/taste/taste_test.go new file mode 100644 index 0000000..d90c343 --- /dev/null +++ b/internal/taste/taste_test.go @@ -0,0 +1,147 @@ +package taste + +import ( + "math" + "testing" + "time" + + "codeberg.org/squidd/sonda/internal/listening" +) + +var ( + now = time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC) + options = Options{MinListen: 20 * time.Second, HalfLife: 90 * 24 * time.Hour} +) + +func near(a, b float64) bool { return math.Abs(a-b) < 1e-9 } + +func TestEventValue(t *testing.T) { + min := 20 * time.Second + for _, c := range []struct { + name string + typ listening.EventType + played int64 + want float64 + }{ + {"complete", listening.Complete, 200_000, 1}, + {"complete played little", listening.Complete, 1_000, 1}, + {"play that counts", listening.Play, 20_000, 0.5}, + {"skip after the minimum still was a listen", listening.Skip, 45_000, 0.5}, + {"skip before the minimum", listening.Skip, 4_000, -1}, + {"skip with no time", listening.Skip, 0, -1}, + {"short play says nothing", listening.Play, 5_000, 0}, + } { + if got := EventValue(c.typ, c.played, min); got != c.want { + t.Errorf("%s: value = %v, want %v", c.name, got, c.want) + } + } +} + +func TestPreferenceGrowsWithListensAndStaysBelowOne(t *testing.T) { + events := []Event{ + {ArtistID: 1, Type: listening.Complete, At: now}, + {ArtistID: 1, Type: listening.Complete, At: now}, + {ArtistID: 1, Type: listening.Complete, At: now}, + } + got := Preferences(events, now, options)[1] + if want := math.Tanh(1); !near(got.Preference, want) { // three full listens: sum 3 + t.Errorf("preference = %v, want %v", got.Preference, want) + } + if got.Listens != 3 { + t.Errorf("listens = %d, want 3", got.Listens) + } + for i := 0; i < 10; i++ { + events = append(events, Event{ArtistID: 1, Type: listening.Complete, At: now}) + } + if p := Preferences(events, now, options)[1].Preference; p >= 1 || p < 0.99 { + t.Errorf("many listens: preference = %v, want just under 1", p) + } +} + +func TestOneSkipDoesNotSinkAnArtist(t *testing.T) { + got := Preferences([]Event{{ArtistID: 1, Type: listening.Skip, PlayedMs: 2_000, At: now}}, now, options)[1] + if want := math.Tanh(-1.0 / 3); !near(got.Preference, want) { + t.Errorf("preference = %v, want %v", got.Preference, want) + } + if got.Preference < -0.4 { + t.Errorf("one skip weighs too much: %v", got.Preference) + } + if got.Listens != 0 { + t.Errorf("a skip is not a listen: %d", got.Listens) + } +} + +func TestOldEventsWeighLess(t *testing.T) { + events := []Event{{ArtistID: 1, Type: listening.Complete, At: now.Add(-90 * 24 * time.Hour)}} + if got := Preferences(events, now, options)[1].Preference; !near(got, math.Tanh(0.5/3)) { + t.Errorf("after one half-life: preference = %v, want %v", got, math.Tanh(0.5/3)) + } + // An event in the future (a client with a fast clock) counts as new, not more than new. + future := []Event{{ArtistID: 1, Type: listening.Complete, At: now.Add(48 * time.Hour)}} + if got := Preferences(future, now, options)[1].Preference; !near(got, math.Tanh(1.0/3)) { + t.Errorf("future event: preference = %v, want %v", got, math.Tanh(1.0/3)) + } +} + +func TestPreferenceKeepsArtistsApartAndRemembersTheLastListen(t *testing.T) { + earlier := now.Add(-time.Hour) + events := []Event{ + {ArtistID: 1, Type: listening.Complete, At: earlier}, + {ArtistID: 1, Type: listening.Play, PlayedMs: 30_000, At: now}, + {ArtistID: 2, Type: listening.Skip, PlayedMs: 1_000, At: now}, + } + got := Preferences(events, now, options) + if len(got) != 2 { + t.Fatalf("got %d artists, want 2", len(got)) + } + if got[1].Preference <= 0 || got[2].Preference >= 0 { + t.Errorf("preferences = %v and %v", got[1].Preference, got[2].Preference) + } + if !got[1].LastListened.Equal(now) { + t.Errorf("last listened = %v, want %v", got[1].LastListened, now) + } + if !got[2].LastListened.IsZero() { + t.Errorf("an artist that was only skipped has no last listen: %v", got[2].LastListened) + } +} + +func TestPreferencesWithoutEventsIsEmpty(t *testing.T) { + if got := Preferences(nil, now, options); len(got) != 0 { + t.Errorf("got %v", got) + } +} + +func TestTagProfileFollowsTheArtistsILike(t *testing.T) { + prefs := map[int64]ArtistPref{ + 1: {ArtistID: 1, Preference: 0.8}, + 2: {ArtistID: 2, Preference: 0.4}, + 3: {ArtistID: 3, Preference: -0.9}, // disliked: must not pull its tags in + } + tags := map[int64]map[string]float64{ + 1: {"rock": 1, "grunge": 0.5}, + 2: {"rock": 0.5, "pop": 1}, + 3: {"jazz": 1}, + } + got := TagProfile(prefs, tags) + // rock 0.8*1 + 0.4*0.5 = 1.0 ; grunge 0.4 ; pop 0.4 ; jazz absent. Best first, scaled to 1. + if len(got) != 3 { + t.Fatalf("got %v", got) + } + if got[0].Tag != "rock" || !near(got[0].Weight, 1) { + t.Errorf("first = %+v, want rock at 1", got[0]) + } + if !near(got[1].Weight, 0.4) || !near(got[2].Weight, 0.4) { + t.Errorf("weights = %v and %v, want 0.4 and 0.4", got[1].Weight, got[2].Weight) + } + if got[1].Tag != "grunge" || got[2].Tag != "pop" { // ties in name order + t.Errorf("tie order = %s, %s", got[1].Tag, got[2].Tag) + } +} + +func TestTagProfileIsEmptyWithoutLikedArtists(t *testing.T) { + prefs := map[int64]ArtistPref{1: {ArtistID: 1, Preference: -0.5}, 2: {ArtistID: 2, Preference: 0}} + tags := map[int64]map[string]float64{1: {"rock": 1}, 2: {"rock": 1}} + if got := TagProfile(prefs, tags); len(got) != 0 { + t.Errorf("got %v", got) + } +} diff --git a/sonda.example.toml b/sonda.example.toml index b4f0b76..7dfbceb 100644 --- a/sonda.example.toml +++ b/sonda.example.toml @@ -26,4 +26,7 @@ refresh_ttl_hours = 720 # lifetime of a refresh token (30 days) [listening] min_listen_seconds = 20 # a play counts as a listen after this long, or when it completes +[taste] +half_life_days = 90 # an old listen weighs half as much after this many days + # Last.fm and MusicBrainz are set up through the API, not here: PUT /api/v1/providers/{name}.