PRODUCT_SPEC.md

EUMORA — Product Feature Specification

Version 1.0 | May 2026 | Status: In Development

---

1. What EUMORA Does

EUMORA is a lyric-to-song recommendation engine. A user provides a piece of text — song lyrics, a mood description, a sentence — and EUMORA:

1. Classifies the emotional content of the text using a fine-tuned DeBERTa-v3-Base transformer model
2. Maps that emotion to a set of Spotify audio feature targets (valence, energy, danceability, tempo, mode)
3. Queries the Spotify Recommendations API with those targets to find real songs matching the emotional fingerprint
4. Returns a ranked list of track recommendations with per-feature match justification

---

2. Spotify Audio Features — What We Can and Can't Map

Spotify's /v1/audio-features and /v1/recommendations use the following fields. Our emotion classifier operates on text only, so mappability depends on whether emotion correlates with that feature:

Spotify Field	Type	Range	Can We Map?	Reasoning
valence	float	0.0 – 1.0	✅ Yes	Directly correlates with positive/negative emotion
energy	float	0.0 – 1.0	✅ Yes	High for joy/anger/surprise, low for sadness/neutral
danceability	float	0.0 – 1.0	✅ Yes	High for joy/love/surprise, low for sadness/fear
tempo	float (BPM)	~50 – 200	✅ Yes	Fast for joy/anger, slow for sadness/fear
mode	int	0 (minor) / 1 (major)	✅ Yes	Joy/love → major; sadness/anger/fear → minor
loudness	float (dB)	-60 – 0	⚠️ Partial	Anger/joy → louder; sadness/neutral → quieter
speechiness	float	0.0 – 1.0	⚠️ Partial	Sarcasm/anger skew slightly higher; not strongly correlated
acousticness	float	0.0 – 1.0	❌ No	Depends on instrumentation, not text emotion
instrumentalness	float	0.0 – 1.0	❌ No	Depends on vocal presence, not text content
liveness	float	0.0 – 1.0	❌ No	Live vs. studio recording — unrelated to emotion
key	int	0 – 11 (Pitch)	❌ No	Musical key — no emotion mapping
time_signature	int	3 – 7	❌ No	Rhythmic metre — no emotion mapping
duration_ms	int	ms	❌ No	Song length — unrelated

Summary: We can confidently map 5 features (valence, energy, danceability, tempo, mode), partially use 2 more (loudness, speechiness), and skip the remaining 6.

---

3. Emotion → Spotify Feature Targets

These are the numeric ranges passed as target_* parameters to /v1/recommendations. Where the classifier returns a full probability distribution, the top-2 emotions are blended by their probabilities (weighted average) for a more nuanced query.

Emotion	target_valence	target_energy	target_danceability	target_tempo (BPM)	target_mode	seed_genres
joy	0.85	0.82	0.80	128	1 (major)	pop, dance
love	0.75	0.52	0.62	96	1 (major)	romance, r-n-b
sadness	0.18	0.28	0.32	72	0 (minor)	sad, indie, acoustic
anger	0.18	0.88	0.58	148	0 (minor)	metal, hard-rock
fear	0.22	0.52	0.38	88	0 (minor)	ambient, dark
surprise	0.62	0.80	0.70	138	1 (major)	pop, electronic
neutral	0.50	0.38	0.50	100	1 (major)	chill, study
sarcasm	0.45	0.60	0.55	110	0 (minor)	alternative, indie

Blended Query Example

Input: "I'm excited but kind of scared" → Classifier: 52% surprise + 35% fear → Blended targets:

• target_valence = (0.52 × 0.62) + (0.35 × 0.22) = 0.40
• target_energy = (0.52 × 0.80) + (0.35 × 0.52) = 0.60
• target_tempo = (0.52 × 138) + (0.35 × 88) = 103 BPM

---

4. Core System Components

4.1 Emotion Classifier (src/predict.py)

• Model: DeBERTa-v3-Base fine-tuned on ~59k samples (GoEmotions + dair-ai/emotion)
• Output: 8 emotion classes — sadness, joy, love, anger, fear, surprise, neutral, sarcasm
• Sarcasm handling: Bayesian prior adjustment (target_sarcasm_prior) corrects training-domain bias
• Output format: Primary emotion + full probability distribution + confidence score + music context
• Current accuracy: ~65.6% weighted F1 on validation; 95%+ on unambiguous direct expressions

4.2 Emotion → Feature Mapper (src/spotify.py — to be built)

• Converts classifier output to numeric Spotify target_* parameters
• Implements probability-weighted blending across top-2 emotions
• Expands confidence score into min_*/max_* constraint windows:
  • High confidence (>0.75) → tight window (±0.08 around target)
  • Medium confidence (0.45–0.75) → medium window (±0.15)
  • Low confidence (<0.45) → wide window (±0.25), broader genre seeds

4.3 Spotify Integration (src/spotify.py — to be built)

Endpoints used:

• GET /v1/recommendations — Core call with target_valence, target_energy, target_danceability, target_tempo, target_mode, seed_genres, limit
• GET /v1/audio-features/{id} — Fetch actual features of returned tracks for match scoring
• GET /v1/search — Optional seed track lookup by title/artist

Authentication: OAuth 2.0 Client Credentials flow (no user login needed for recommendations)

4.4 Recommendation Ranker (src/spotify.py — to be built)

After Spotify returns candidates, EUMORA re-ranks using:

• Feature distance score: Euclidean distance across [valence, energy, danceability, tempo_norm] between the emotion target vector and each track's actual audio features
• Diversity filter: Max 2 tracks per artist in top-10
• Output: Ordered list of tracks with per-track match score (0–100)

---

5. Data Flow (End-to-End)

User Input: "City lights blur as I'm driving through the night"
        ↓
[ EmotionPredictor — src/predict.py ]
  DeBERTa-v3-Base → 8-class softmax → sarcasm calibration
        ↓
  { emotion: "fear", confidence: 0.54, probabilities: {fear: 0.54, anger: 0.23, ...} }
        ↓
[ Feature Mapper — src/spotify.py ]
  Blend top-2 emotions (fear × 0.54 + anger × 0.23, normalised)
  → { target_valence: 0.19, target_energy: 0.73, target_danceability: 0.46,
      target_tempo: 122, target_mode: 0, seed_genres: ["dark", "hard-rock"] }
        ↓
[ Spotify Recommendations API ]
  GET /v1/recommendations?target_valence=0.19&target_energy=0.73&limit=20&seed_genres=dark,hard-rock
        ↓
  20 raw candidate tracks (with audio_features fetched per track)
        ↓
[ Ranker — src/spotify.py ]
  Euclidean distance scoring + artist diversity filter
        ↓
  Top 10 tracks with match scores + Spotify links
        ↓
User Output (CLI / future: UI)

---

6. CLI Interface

Command	What it does
python main.py predict "text"	Emotion only (existing)
python main.py recommend "text"	Full pipeline → Spotify tracks (to be added)
python main.py recommend "text" --limit 5	Top 5 recommendations
python main.py recommend "text" --genre rock	Override seed genre
python main.py recommend "text" --no-blend	Use top-1 emotion only, no blending

---

7. What It Does NOT Do (Phase 1 Scope)

• Does not map acousticness, instrumentalness, liveness, key, time_signature — no text-to-audio model for these
• Does not personalize based on user listening history (no user OAuth)
• Does not analyze audio files or waveforms (text-only)
• Does not stream or play music directly
• Does not guarantee sarcasm accuracy — calibration mitigates it

---

8. Planned Extensions (Phase 2+)

Feature	Phase	Description
User preference learning	2	OAuth login; bias toward user's top genres/artists
Audio file analysis	3	Upload a recording; extract features via librosa
Acousticness/instrumentalness mapping	3	Infer from audio+lyrics combined model
Multimodal fusion	4	Combine lyrics emotion + audio features
Web UI	5	Browser interface with Spotify 30s clip previews
Playlist generation	5	Multi-text input → coherent 10-track playlist

---

9. New Dependencies

Library	Version	Role
spotipy	>=2.23.0	Spotify Web API client — handles OAuth + all endpoint calls

Add to requirements.txt:

spotipy>=2.23.0