/
/
/
1"""Constants for Last.fm Recommendations Provider."""
2
3from __future__ import annotations
4
5from typing import Final
6
7CONF_API_KEY: Final[str] = "api_key"
8CONF_ENABLE_PERSONALIZED: Final[str] = "enable_personalized"
9CONF_ENABLE_GLOBAL_CHARTS: Final[str] = "enable_global_charts"
10CONF_ENABLE_GENRE: Final[str] = "enable_genre"
11CONF_ENABLE_GEO: Final[str] = "enable_geo"
12CONF_GEO_COUNTRY: Final[str] = "geo_country"
13CONF_ACTION_CLEAR_CACHE: Final[str] = "clear_cache"
14REFRESH_TASK_ID: Final[str] = "lastfm_recommendations_refresh"
15
16# Cache settings
17# Cache category for resolved Artist/Album/Track objects
18CACHE_CATEGORY_RESOLVED_ITEMS = 1
19
20# Cache category for the user's derived top genres
21CACHE_CATEGORY_TOP_GENRES = 2
22
23# Expiration time for cached resolved items (in seconds)
24CACHE_EXPIRATION_SECONDS = 60 * 60 * 24 * 90 # 90 days
25
26# Expiration for the derived top genres; genre identity is stable and the genre rows only
27# rotate daily, so a daily recompute is plenty and keeps the per-artist tag fan-out cheap.
28TOP_GENRES_CACHE_EXPIRATION_SECONDS = 60 * 60 * 24 # 1 day
29
30# Concurrency limits
31# Maximum number of concurrent provider searches to prevent overwhelming APIs
32SEARCH_CONCURRENCY_LIMIT = 5
33
34# Item counts and limits
35# Target number of items to return in recommendation folders
36TARGET_ITEM_COUNT = 10
37
38# Number of items to fetch when we expect some resolution failures (small buffer)
39RESOLUTION_BUFFER_SMALL = 15
40
41# Genre chart pool (single fetch); sized so the hourly rotation surfaces more of the genre per day
42RESOLUTION_BUFFER_LARGE = 60
43
44# Number of top items to always include when sampling (before random selection)
45TOP_ITEMS_TO_TAKE = 3
46
47# Number of library search hits scanned when verifying an item is already in the library.
48# A small window so a genuine match ranked behind a fuzzier one is still caught.
49LIBRARY_MATCH_SCAN_LIMIT = 5
50
51# Number of similar artists to resolve before filtering to target count. Over-fetched above the
52# target to absorb resolution misses and artists excluded because already in the library.
53SIMILAR_ITEMS_BUFFER = 18
54
55# Number of similar tracks to resolve before filtering to target count. Larger than the
56# artist buffer to absorb this row's extra attrition: artist+title verification and the
57# exclusion of tracks that resolve to the user's own library copy.
58SIMILAR_TRACKS_BUFFER = 15
59
60# Number of similar items to fetch for each seed artist/track
61SIMILAR_ITEMS_PER_SEED = 5
62
63# Number of top artists to use as seeds for personalized recommendations
64TOP_ARTISTS_LIMIT = 5
65
66# Number of recent tracks used as similar-track seeds; kept high so a single album playthrough
67# doesn't fill the whole seed set, and so enough seeds are recognised by Last.fm
68TOP_TRACKS_LIMIT = 20
69
70# Recent-listening window (days) for personalized seeds. Seeds are drawn from plays in this
71# window so they track current listening; the playlog is pruned at 90 days.
72RECENT_PLAYS_WINDOW_DAYS = 30
73
74# Maximum number of recent play events to scan when ranking seeds.
75RECENT_PLAYS_SCAN_LIMIT = 200
76
77# Number of derived genres; the genre rows cycle through them daily
78TOP_GENRES_LIMIT = 3
79
80# Genres are derived from the community tags of the user's most played artists. Last.fm has no
81# genre data of its own, so an artist's top tags stand in for its genre.
82# Number of the user's top artists to analyse, and the time span to rank them over.
83GENRE_ARTISTS_LIMIT = 25
84GENRE_ARTISTS_PERIOD = "overall"
85
86# Number of top tags to take from each artist. Kept small because an artist's leading tags are
87# almost always its genre; folksonomy noise ("seen live", "favourites") sits further down.
88TAGS_PER_ARTIST = 5
89
90# API search settings
91# Search limit for provider API calls (workaround for Spotify API bug with limit=1)
92PROVIDER_SEARCH_LIMIT = 2
93
94# Curated list of popular countries for Last.fm geo charts.
95# Last.fm API expects full country names (not ISO codes).
96# Covers major music markets and can be expanded based on user requests.
97GEO_COUNTRIES = [
98 "Argentina",
99 "Australia",
100 "Austria",
101 "Belgium",
102 "Brazil",
103 "Canada",
104 "China",
105 "Czech Republic",
106 "Denmark",
107 "Finland",
108 "France",
109 "Germany",
110 "Greece",
111 "Hungary",
112 "Iceland",
113 "India",
114 "Ireland",
115 "Israel",
116 "Italy",
117 "Japan",
118 "Lithuania",
119 "Mexico",
120 "Netherlands",
121 "New Zealand",
122 "Norway",
123 "Philippines",
124 "Poland",
125 "Portugal",
126 "Serbia",
127 "Singapore",
128 "Slovenia",
129 "South Africa",
130 "South Korea",
131 "Spain",
132 "Sweden",
133 "Switzerland",
134 "Thailand",
135 "Turkey",
136 "Ukraine",
137 "United Arab Emirates",
138 "United Kingdom",
139 "United States",
140]
141