mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
93e7c13f3d
- Added hierarchical AGENTS.md knowledge base - Implemented PlaylistService with 6h themed and 24h devotion mix logic - Integrated AI theme generation for 6h playlists via Gemini/OpenAI - Added /playlists/refresh and metadata endpoints to API - Updated background worker with scheduled playlist curation - Created frontend PlaylistsSection, Tooltip components and integrated into Dashboard - Added Alembic migration for playlist tracking columns - Fixed Docker healthcheck with curl installation
41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
# SERVICES KNOWLEDGE BASE
|
|
|
|
**Target:** `backend/app/services/`
|
|
**Context:** Central business logic, 7+ specialized services, LLM integration.
|
|
|
|
## OVERVIEW
|
|
|
|
Core logic hub transforming raw music data into metrics, playlists, and AI narratives.
|
|
|
|
- **Data Ingress/Egress**: `SpotifyClient` (OAuth/Player), `GeniusClient` (Lyrics), `ReccoBeatsClient` (Audio Features).
|
|
- **Analytics**: `StatsService` (HHI, Gini, clustering, heatmaps, skip detection).
|
|
- **AI/Narrative**: `NarrativeService` (LLM prompt engineering, multi-provider support), `AIService` (Simple Gemini analysis).
|
|
- **Orchestration**: `PlaylistService` (AI-curated dynamic playlist generation).
|
|
|
|
## WHERE TO LOOK
|
|
|
|
| Service | File | Key Responsibilities |
|
|
|---------|------|----------------------|
|
|
| **Analytics** | `stats_service.py` | Metrics (Volume, Vibe, Time, Taste, LifeCycle). |
|
|
| **Spotify** | `spotify_client.py` | Auth, Player API, Playlist CRUD. |
|
|
| **Narrative** | `narrative_service.py` | LLM payload shaping, system prompts, JSON parsing. |
|
|
| **Playlists** | `playlist_service.py` | Periodic curation logic (6h/24h cycles). |
|
|
| **Enrichment** | `reccobeats_client.py` | External audio features (energy, valence). |
|
|
| **Lyrics** | `genius_client.py` | Song/Artist metadata & lyrics search. |
|
|
|
|
## CONVENTIONS
|
|
|
|
- **Async Everywhere**: All external API clients (`Spotify`, `ReccoBeats`) use `httpx.AsyncClient`.
|
|
- **Stat Modularization**: `StatsService` splits logic into `compute_X_stats` methods; returns serializable dicts.
|
|
- **Provider Agnostic AI**: `NarrativeService` detects `OPENAI_API_KEY` vs `GEMINI_API_KEY` automatically.
|
|
- **Payload Shaping**: AI services aggressively prune stats JSON before sending to LLM to save tokens.
|
|
- **Fallbacks**: All AI/External calls have explicit fallback/empty return states.
|
|
|
|
## ANTI-PATTERNS
|
|
|
|
- **Blocking I/O**: `GeniusClient` is synchronous; avoid calling in hot async paths.
|
|
- **Service Circularity**: `PlaylistService` depends on `StatsService`. Avoid reversing this.
|
|
- **N+1 DB Hits**: Aggregations in `StatsService` should use `joinedload` or batch queries.
|
|
- **Missing Checksums**: Audio features assume presence; always check for `None` before math.
|
|
- **Token Waste**: Never pass raw DB models to `NarrativeService`; use shaped dicts.
|