feat: Music Recommender Simulation — complete implementation with evaluation, model card, and tests

[jupitersnow1]

Summary

• Implemented load_songs, score_song, recommend_songs, and Recommender class in src/recommender.py
• Expanded song catalog from 10 to 18 songs with diverse genres and moods
• Tested six user profiles (3 core, 3 edge cases) to evaluate scoring behavior
• Ran weight shift experiment to validate original weights (genre 0.40, mood 0.35, energy 0.25)
• Documented findings in model_card.md, reflection.md, and README.md
• All 11 tests passing

Tests (Newly Implemented)

• test_score_song_genre_match_adds_correct_weight — genre match adds exactly 0.40
• test_score_song_no_genre_or_mood_match_returns_energy_only — only energy contributes when no genre/mood match
• test_recommend_returns_k_results — k parameter is respected
• test_load_songs_returns_correct_count — CSV loads all 18 songs
• test_score_song_conflicting_profile — genre + mood match beats pure energy match
• test_recommend_empty_catalog — empty catalog returns empty list without crashing
• test_score_song_perfect_match — perfect match scores exactly 1.0
• test_score_song_energy_boundary — energy at opposite extremes contributes 0.0
• test_recommend_scores_are_descending — results are always sorted highest to lowest

Test plan

• Run python -m src.main and verify recommendations print for all 6 user profiles
• Run pytest and confirm 11/11 tests pass
• Review model_card.md for completeness
• Check README renders correctly on GitHub (flowchart image, screenshots)

Future Work

Planning to return and expand this project with improvements including mood-as-hard-filter logic, genre grouping fallbacks, and broader catalog coverage.