feat(about): artist descriptions from Wikipedia

- GET /artists/{id}/description shows what Wikipedia says about an artist: a short
  text with its page, a link and the licence (CC BY-SA 4.0).
- New provider "wikipedia" (off by default, no key, contact in the User-Agent, which
  Wikimedia requires). The way to the text is a chain of ids, never a name: the
  artist's MusicBrainz id, the Wikidata item MusicBrainz links to it, the Wikipedia
  page Wikidata names in the first configured language that has one. A page is used
  only if it is an article about that same item.
- [wikipedia] languages in the config (one to five codes of two or three lower case
  letters, checked before they are sent: an unknown site makes Wikidata answer with
  every language).
- Stored 30 days (a day when there was nothing to find), served stale if Wikipedia
  fails, removed with the provider's data (the purge now reports descriptions).
- MusicBrainz client: WikidataID. Wikipedia client for Wikidata and the summary,
  which also reads Wikidata's errors that come with HTTP 200.
- artist_descriptions table (migration 0014, SQLite and PostgreSQL).
- Spec, contract test, README and example config updated.

Closes #39
This commit is contained in:
tgiachi 2026-11-11 21:36:27 +01:00
commit 48cb903115

View file

@ -928,6 +928,46 @@ paths:
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
/artists/{id}/description:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Discovery]
operationId: getArtistDescription
summary: What Wikipedia says about an artist
description: |
A short text about the artist from Wikipedia, with the page it comes from. The way to it
is a chain of identifiers, never a search by name: the artist's MusicBrainz id, then the
Wikidata item that MusicBrainz links to it, then the Wikipedia page that Wikidata names in
the first of the server's languages (`[wikipedia] languages`) that has one. A page is used
only if it is an article about that same item (not a page of disambiguation). An artist
with no MusicBrainz id answers `no_id`: Sonda does not look an id up by name.
It needs the `wikipedia` provider, which an admin switches on; nothing is sent while it is
off (`disabled`). What is sent: the MusicBrainz id to MusicBrainz, the Wikidata item to
Wikidata, the title of the page to Wikipedia, and your server's IP address and a
`User-Agent` with the contact of the admin to all three. The answer is stored: 30 days, or a
day when there was nothing to find, and an old one is returned as `stale` if Wikipedia
fails. When there is nothing to show, `description` is `null` and `provider_status` is
`ok`.
The text is CC BY-SA 4.0. Where you show it, name the page (`title`), link to it (`url`) and
give the licence (`license`, `license_url`), and say if you changed it.
security: [{bearerAuth: []}]
responses:
'200':
description: The description, or `null` with the status that says why.
content:
application/json:
schema: {$ref: '#/components/schemas/ArtistDescription'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such artist (`artist_not_found`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/albums:
get:
tags: [Catalog]
@ -1265,7 +1305,7 @@ paths:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz]}
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
put:
tags: [Providers]
operationId: updateProvider
@ -1303,7 +1343,7 @@ paths:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz]}
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
post:
tags: [Providers]
operationId: testProvider
@ -1338,7 +1378,7 @@ paths:
- name: name
in: path
required: true
schema: {type: string, enum: [lastfm, musicbrainz]}
schema: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
delete:
tags: [Providers]
operationId: purgeProviderData
@ -1799,7 +1839,7 @@ components:
additionalProperties: false
required: [name, enabled, needs_api_key, has_api_key, contact, sends, notes, updated_at]
properties:
name: {type: string, enum: [lastfm, musicbrainz]}
name: {type: string, enum: [lastfm, musicbrainz, wikipedia]}
enabled: {type: boolean, description: Whether Sonda may contact this provider.}
needs_api_key: {type: boolean}
has_api_key: {type: boolean, description: Whether a key is stored. The key itself is never returned.}
@ -1829,12 +1869,47 @@ components:
maxLength: 200
description: A URL or e-mail address, without parentheses. Empty restores the default.
ArtistDescription:
type: object
additionalProperties: false
required: [provider, provider_status, stale, retrieved_at, attribution, description]
properties:
provider: {type: string, enum: [wikipedia]}
provider_status:
type: string
enum: [ok, disabled, error, no_id]
description: |
`ok` when the stored answer is as fresh as it needs to be (which can be "nothing found");
`disabled` when the provider is off; `error` when Wikipedia could not be asked; `no_id`
when the artist has no MusicBrainz id.
stale: {type: boolean, description: True when the description is older than it should be because Wikipedia could not be asked.}
retrieved_at: {type: string, format: date-time, nullable: true, description: When it was read; null when nothing is known.}
attribution: {type: string, description: What to show where the text is shown.}
description:
nullable: true
allOf:
- {$ref: '#/components/schemas/Description'}
Description:
type: object
additionalProperties: false
required: [text, short, language, title, url, license, license_url]
properties:
text: {type: string, description: "The first paragraph of the article, plain text, at most 4000 characters."}
short: {type: string, description: "One line, like \"gruppo musicale inglese\". May be empty."}
language: {type: string, description: "The language of the page, like `it`."}
title: {type: string, description: "The title of the page."}
url: {type: string, format: uri, description: "The page, on Wikipedia."}
license: {type: string, description: "The licence of the text."}
license_url: {type: string, format: uri}
ProviderPurge:
type: object
additionalProperties: false
required: [similar_artists, tags, artists]
required: [similar_artists, tags, descriptions, artists]
properties:
similar_artists: {type: integer, description: Similar-artist links removed.}
descriptions: {type: integer, description: Artist descriptions removed (only the data of Wikipedia has any).}
tags: {type: integer, description: Tags removed.}
artists: {type: integer, description: "Artists removed because only the removed data named them and nobody has files for them."}