fix(taste): order by the score, clamp future events, keep tags short

- Order the liked artists by the weighted sum, not by tanh, which rounds to
  exactly 1 after about 58 listens and made heavy artists tie.
- An event dated after now counts as happening now, also for the last listen.
- Genres of files that are gone no longer shape the tag profile, as in
  /artists/{id}/tags.
- The tag list is capped at 50.
- A zero half-life falls back to 90 days instead of producing NaN.
- Document the 10 half-lives window and the new rules in the spec and README.
- Tests: heavy artists keep their order, tracks with two artists credit both,
  genres of a missing file are left out, the tag cap, a zero half-life.
This commit is contained in:
tgiachi 2026-11-11 18:52:08 +01:00
commit d251cc4f39

View file

@ -661,22 +661,26 @@ paths:
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.
event weighs half as much for every 90 days (`taste.half_life_days`) that has passed, and
one dated after the moment of the request weighs as if it happened then. Only the last
ten half-lives are read (900 days by default); older events weigh less than a thousandth
and are left out, also from `listens`. For each artist the values add up, and `preference`
is `tanh(sum / 3)`: from -1 to 1, approaching both (a large sum rounds to exactly 1), so
one skip does not sink an artist and listening makes one loved at most. 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.
`artists` are the ones you like (a `preference` above 0), the most played first. They are
ordered by the sum itself, so artists whose `preference` rounds to 1 keep their order;
ties go to the lower id. `tags` are the kinds of music you like, at most 50: the tags of
those artists (the genres of your files that still exist, 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, best first. 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.
description: How many artists to return. 20 when absent or 0; values above 50 are lowered to 50. It does not limit `tags`.
schema: {type: integer, minimum: 0, default: 20}
responses:
'200':
@ -1619,7 +1623,7 @@ components:
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."}
listens: {type: integer, description: "Events that count as a listen, with no decay, within the period that is read (ten half-lives)."}
last_listened_at: {type: string, format: date-time, description: The most recent listen that counted.}
TasteTag: