Osele1/sonic-clusters

1# Music Clustering Demo - Local Setup Guide2 3A FastAPI backend with React frontend for real-time music clustering and recommendations using your trained Phase 3 models.4 5## Architecture6 7```8Frontend (React)          Backend (FastAPI)          Data/Models9┌────────────────┐       ┌──────────────────┐      ┌─────────────────┐10│  React App     │◄─────►│  /api/songs      │      │  songs.csv      │11│  - Search      │:3000   │  /api/search     │:8000 │  - 10,000 songs │12│  - Visualize   │       │  /api/cluster    │      │                 │13│  - Compare     │       │  /api/predict    │      │  Trained Models │14└────────────────┘       │                  │      │  - kmeans.pkl   │15                         └──────────────────┘      │  - hierarchical.pkl16                                                    │  - dbscan.pkl17                                                    └─────────────────┘18```19 20## Quick Start (Automated)21 22### macOS/Linux:23```bash24cd "/Users/trieule/School/DATA480/modelling and testing/website-demo"25./start.sh26```27 28### Windows:29```cmd30cd "website-demo"31start.bat32```33 34Then open:35- **Frontend**: http://localhost:300036- **API Docs**: http://localhost:8000/docs37 38## Manual Setup (Step-by-Step)39 40### 1. Backend Setup41 42```bash43cd backend44 45# Install Python dependencies46pip3 install -r requirements.txt47 48# Start the backend server49python3 main.py50```51 52Backend runs at: **http://localhost:8000**53 54**API Endpoints:**55- `GET /api/songs` - Get all songs with cluster assignments56- `GET /api/search?query=...` - Search songs57- `GET /api/recommendations/{song_id}?algorithm=kmeans` - Get recommendations58- `POST /api/predict-cluster` - Predict cluster for new song59- `GET /api/algorithms` - Get algorithm metrics60- `GET /api/distributions` - Get cluster distributions61 62**Interactive API Docs**: http://localhost:8000/docs63 64### 2. Frontend Setup (New Terminal)65 66```bash67# In the website-demo directory (not backend)68npm install69 70# Start the frontend71npm run dev72```73 74Frontend runs at: **http://localhost:3000**75 76### 3. Verify Everything Works77 781. Open http://localhost:3000 in your browser792. You should see the "Backend: Connected" status at the top803. Try the **Recommendations** tab - search for a song and see live API calls81 82## What's Different from Static Site?83 84| Feature | Static JSON | FastAPI Backend |85|---------|-------------|-----------------|86| **Recommendations** | Pre-computed in JSON | Computed live using scikit-learn |87| **Search** | Fuse.js fuzzy search | Backend SQL-like string matching |88| **Cluster Prediction** | Not possible | Live prediction for new songs |89| **Data** | 800 songs subset | All 10,000 songs |90| **Speed** | Instant | ~100-500ms per query |91 92## File Structure93 94```95website-demo/96├── backend/97│   ├── main.py                    # FastAPI app98│   ├── requirements.txt           # Python deps99│   ├── models/100│   │   ├── preprocessor.pkl       # Trained preprocessor101│   │   ├── kmeans_model.pkl      # Trained K-Means102│   │   ├── hierarchical_model.pkl # Trained Hierarchical103│   │   └── dbscan_model.pkl       # Trained DBSCAN104│   ├── data/105│   │   ├── songs_with_clusters.csv # 10K songs + clusters106│   │   ├── feature_matrix.npy     # Pre-computed features107│   │   ├── kmeans_centroids.npy  # K-Means centroids108│   │   ├── metadata.json          # Dataset metadata109│   │   └── feature_info.json     # Feature schema110│   └── services/111│       ├── clustering.py          # Clustering service112│       └── recommendations.py     # Recommendation service113├── src/114│   ├── services/api.ts           # Frontend API client115│   ├── hooks/useData.ts          # React hooks for API116│   └── components/               # React components117├── start.sh                       # macOS/Linux startup118├── start.bat                      # Windows startup119└── export_models.py              # Script to export models from Phase 3120```121 122## How the Live Model Works123 124### 1. Loading Trained Models125```python126# In backend/services/clustering.py127self.kmeans = joblib.load('models/kmeans_model.pkl')128self.preprocessor = joblib.load('models/preprocessor.pkl')129```130 131### 2. Real-time Recommendations132When you select a song:133 134```python135# 1. Get the song's cluster136cluster_id = kmeans.predict(song_features)137 138# 2. Find all songs in same cluster139cluster_songs = songs[songs.cluster == cluster_id]140 141# 3. Calculate Euclidean distances142distances = [euclidean_distance(song_features, other_features) 143             for other in cluster_songs]144 145# 4. Return closest 5 songs146return sorted(distances)[:5]147```148 149### 3. Predicting New Song Cluster150If you send song features to `/api/predict-cluster`:151 152```python153# 1. Preprocess features154X = preprocessor.transform(features)155 156# 2. Predict cluster157cluster = kmeans.predict(X)158 159# 3. Return result160return {"predicted_cluster": int(cluster[0])}161```162 163## Testing the API164 165You can test the backend API directly:166 167```bash168# Get all songs (first 1000)169curl http://localhost:8000/api/songs?limit=10170 171# Search for a song172curl "http://localhost:8000/api/search?query=Casual&limit=5"173 174# Get recommendations for song ID 0175curl "http://localhost:8000/api/recommendations/0?algorithm=kmeans&n=5"176 177# Get algorithm info178curl http://localhost:8000/api/algorithms179 180# Predict cluster for new song181curl -X POST "http://localhost:8000/api/predict-cluster?algorithm=kmeans" \182  -H "Content-Type: application/json" \183  -d '{184    "tempo": 120.0,185    "loudness": -10.0,186    "duration": 180.0,187    "artist_hotttnesss": 0.5,188    "artist_familiarity": 0.7,189    "key_confidence": 0.8,190    "mode_confidence": 0.9,191    "time_signature_confidence": 0.8,192    "danceability": 0.6,193    "energy": 0.7,194    "key": 5,195    "mode": 1,196    "time_signature": 4197  }'198```199 200Or use the interactive docs at http://localhost:8000/docs201 202## Troubleshooting203 204### Backend won't start205```bash206# Check if Python packages are installed207cd backend208pip3 install -r requirements.txt209 210# Try running with verbose errors211python3 -u main.py212```213 214### Frontend can't connect to backend215- Check if backend is running: `curl http://localhost:8000/health`216- Check browser console for CORS errors217- Make sure you're using `http://localhost:3000` not `127.0.0.1:3000`218 219### Models not found220- Make sure you ran `python3 export_models.py` in the `website-demo` directory221- Check that `backend/models/` contains `.pkl` files222 223### Port already in use224```bash225# Find and kill process on port 8000226lsof -ti:8000 | xargs kill227 228# Or use different port229python3 main.py --port 8001230# Then update frontend src/services/api.ts API_BASE_URL231```232 233## Re-exporting Models from Phase 3234 235If you modified the Phase 3 notebook and want to update the backend:236 237```bash238cd "/Users/trieule/School/DATA480/modelling and testing/website-demo"239python3 export_models.py240```241 242This will:2431. Load `phase2_cleaned_dataset.csv`2442. Retrain all three models2453. Save them to `backend/models/`2464. Update all data files247 248## Next Steps249 250Your local setup is complete! The app demonstrates:251- ✅ Real-time K-Means clustering252- ✅ Live Euclidean distance calculations253- ✅ 10,000 song dataset from Phase 3254- ✅ All three algorithms (K-Means, Hierarchical, DBSCAN)255- ✅ RESTful API with FastAPI256- ✅ Interactive React frontend257 258Enjoy your live music clustering demo! 🎵259