Chore: commit to deploy on vercel

README.md

@@ -1,9 +1,762 @@
+# EUMORA - Emotion-Aware Music Recommendation System
+
+**Advanced lyrical emotion analysis with custom-trained transformer models and real-time visualization.**
+
+> **Current Date**: April 20, 2026 | **Status**: Functional Prototype | **Latest Training**: April 10, 2026
+
+## 🎯 Current Implementation Status
+
+### ✅ Phase 1: Lyrical Emotion Analysis *(Functional with Known Limitations)*
+- **Custom DeBERTa-v3-Base model** (184M parameters) trained on combined datasets (~59k samples)
+- **8 Emotion categories** with **validated performance** (65.6% validation F1 on clear cases; 95%+ on unambiguous text)
+- **Automatic chart generation** with beautiful, publication-quality visualizations for every prediction
+- **Multiple dataset support** - dair-ai/emotion (16k), GoEmotions (43k), and combined (59k samples)
+- **Professional training pipeline** - early stopping, weighted loss, class balancing, and multi-dataset support
+- **Cross-platform inference** - Apple MPS, NVIDIA CUDA, and CPU support with automatic device detection
+- **Advanced sarcasm calibration** - Bayesian prior adjustment for deployment-specific sarcasm prevalence
+
+### 🎭 Detected Emotions
+- **Sadness** - Melancholic, sorrowful themes
+- **Joy** - Uplifting, celebratory content
+- **Love** - Romantic, affectionate sentiments
+- **Anger** - Intense, confrontational language
+- **Fear** - Anxious, uncertain undertones
+- **Surprise** - Unexpected, wonder-filled expressions
+- **Neutral** - Balanced, observational tone
+- **Sarcasm** - Ironic, sarcastic undertones (with Bayesian prior adjustment)
+
+## 🚀 Quick Start
+
+### Installation
+```bash
+# Clone and install dependencies
+git clone https://github.com/your-username/EUMORA.git
+cd EUMORA
+
+# Create virtual environment (recommended)
+python -m venv .venv
+
+# Activate virtual environment
+# On Windows:
+.venv\Scripts\activate
+# On macOS/Linux:
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Available Trained Models
+
+**Three production-ready models are available** in `models/emotion_classifier/`:
+
+1. **`emotion_classifier/final/`** (Latest Checkpoint - Recommended)
+   - Training: Combined dataset (59k samples)
+   - Validation F1: 65.61% weighted, 64.27% macro
+   - Use case: **Primary model for inference**
+   - Files: Full model with all components (config, weights, tokenizer)
+
+2. **`emotion_classifier_20260410_135131/final/`** (Alternative)
+   - Training: Combined dataset with different seed
+   - Performance: Comparable to primary model
+   - Use case: Backup/comparison or ensemble testing
+   - Note: Use if primary model unavailable
+
+3. **`sample_models/emotion_classifier_sample_20260410_134414/`** (Testing/Demo)
+   - Training: Limited sample (2k samples)
+   - Performance: Lower accuracy (~58%)
+   - Use case: Quick testing without loading full model
+   - Note: For prototyping only, not production
+
+### Training Options
+```bash
+# Quick training (2k samples, ~5 minutes)
+python main.py train --sample
+
+# Standard training on dair-ai/emotion (16k samples, ~15 minutes)
+python main.py train
+
+# Advanced training on GoEmotions (43k samples, ~30 minutes)
+python main.py train --goemotions
+
+# Best results: Combined datasets (59k samples, ~45 minutes)
+python main.py train --combined
+
+# Advanced options
+python main.py train --combined --no-weights  # Disable class balancing
+python main.py train --goemotions --samples 10000  # Limit training samples
+```
+
+### Using the Model
+
+#### Basic Predictions
+```bash
+# Simple prediction with default visualization
+python main.py predict "I feel so happy today, everything is perfect!"
+
+# Prediction without chart generation
+python main.py predict "I'm feeling great" --disable-prior-adjustment
+```
+
+#### Advanced Sarcasm Calibration
+The model includes Bayesian prior adjustment for deployment-specific sarcasm prevalence:
+
+```bash
+# Standard usage: assumes 15% sarcasm in deployment text (default)
+python main.py predict "Oh amazing, another sleepless night"
+
+# For high-sarcasm domains (e.g., social media): adjust prior upward
+python main.py predict "Oh amazing, another sleepless night" --target-sarcasm-prior 0.25
+
+# For low-sarcasm domains (e.g., customer service): adjust prior downward  
+python main.py predict "I'm so thrilled" --target-sarcasm-prior 0.05
+
+# Fine-tune sarcasm detection threshold (0.0-1.0, default=None for auto)
+python main.py predict "Yeah, great job" --target-sarcasm-prior 0.2 --sarcasm-threshold 0.4
+
+# Disable prior calibration entirely for baseline comparison
+python main.py predict "Oh amazing, another Monday" --disable-prior-adjustment
+```
+
+#### Visualization Options
+```bash
+# Simple bar chart (default, automatically generated)
+python main.py predict "My heart is broken"
+
+# Enhanced visualization with primary emotion indicator
+python main.py predict "My heart is broken" --detailed-chart
+
+# Interactive mode with options
+python main.py analyze
+
+# Demo with multiple comparison charts
+python main.py demo
+```
+
+**Note**: All predictions generate and save charts to `visualizations/` folder automatically
+
+## 📊 Example Output
+
+### Text Output
+```
+🎵 EUMORA - Emotion Analysis
+
+📝 Input: "City lights blur as I'm driving through the night"
+
+🎭 Emotion: FEAR
+📊 Confidence: 53.9%
+🎸 Music Context: {'mood': 'anxious', 'energy': 'medium', 'valence': 'negative'}
+
+💬 Detected anxious and uncertain undertones with moderate confidence (53.9%).
+   Suggests anxious music with medium energy. Secondary: anger (22.9%).
+
+📈 All Emotions:
+         fear: █████████████             53.9%
+        anger: █████                     22.9%
+          joy: ████                      17.8%
+      sadness: █                         2.5%
+     surprise: █                         2.5%
+         love:                           0.4%
+
+📊 Chart saved to: visualizations/emotion_analysis_20260328_011358.png
+```
+
+### Visual Charts (Auto-generated)
+- **Automatic bar charts** showing probability distribution (every prediction)
+- **Primary emotion indicators** with confidence levels and totals verification
+- **Mathematically accurate** - probabilities always sum to exactly 100%
+- **Beautiful styling** with emotion-coded colors and high-resolution export
+- **Comparison charts** in demo mode showing multiple predictions side-by-side
+
+## 🏗️ Project Structure
+
+```
+EUMORA/
+├── main.py                 # Enhanced CLI with training & visualization options
+├── requirements.txt        # All dependencies including matplotlib/seaborn
+├── src/
+│   ├── config.py          # Model configs, datasets, 7 emotion mappings
+│   ├── train.py           # Advanced training with GoEmotions & class balancing
+│   ├── predict.py         # Inference with custom DistilBERT model
+│   ├── visualize.py       # Chart generation & visualization system
+│   └── dataset.py         # Multi-dataset loading & preprocessing
+├── models/                # Your trained models (gitignored)
+│   └── emotion_classifier/
+│       └── final/         # Production model (66M parameters)
+├── visualizations/        # Generated charts and graphs (gitignored)
+├── data/                  # Training datasets (auto-downloaded, gitignored)
+└── notebooks/            # Jupyter notebooks for analysis
+```
+
+## � **Python API Usage (Programmatic)**
+
+### Basic Usage
+```python
+from src.predict import EmotionPredictor
+
+# Initialize predictor (loads model on first use)
+predictor = EmotionPredictor(enable_viz=True)
+
+# Make predictions
+text = "I feel so happy today!"
+result = predictor.predict(text)
+
+# Access results
+print(f"Emotion: {result['emotion']}")          # e.g., "joy"
+print(f"Confidence: {result['confidence']:.1%}")  # e.g., 96.4%
+print(f"All scores: {result['scores']}")        # dict of all emotions
+```
+
+### Advanced: Custom Sarcasm Calibration
+```python
+# Initialize with custom sarcasm settings
+predictor = EmotionPredictor(
+    enable_viz=False,                           # Disable charts for batch processing
+    target_sarcasm_prior=0.25,                 # 25% sarcasm in deployment
+    sarcasm_threshold=0.45                      # Custom sarcasm threshold
+)
+
+# Process batch of texts
+texts = [
+    "I love this!",
+    "Oh great, another bug",
+    "This is amazing"
+]
+
+for text in texts:
+    result = predictor.predict(text)
+    # Use results as needed
+```
+
+### Batch Processing with Prior Adjustment
+```python
+from pathlib import Path
+
+# Disable visualization for speed
+predictor = EmotionPredictor(
+    enable_viz=False,
+    target_sarcasm_prior=0.15
+)
+
+# Process many texts efficiently
+texts = ["text1", "text2", "text3"]
+results = [predictor.predict(t) for t in texts]
+
+# Extract primary emotions
+emotions = [r['emotion'] for r in results]
+confidences = [r['confidence'] for r in results]
+```
+
+### Using Alternative Model
+```python
+from pathlib import Path
+
+# Use backup model if primary unavailable
+backup_model = Path("models/emotion_classifier_20260410_135131/final")
+predictor = EmotionPredictor(model_path=backup_model)
+
+result = predictor.predict("Your text here")
+```
+
+## �📊 Performance & Limitations
+
+### 🔴 **Current Performance Reality**
+**Training Metrics (Validation Set):**
+- **F1-Weighted**: 65.61% (real performance from training logs)
+- **F1-Macro**: 64.27%
+- **Validation Accuracy**: 65.57%
+- **Training**: 4 epochs, 5,428 steps on combined dataset
+
+**Real-World Testing Results:**
+- ✅ **Clear emotions**: 95-99% accuracy ("I feel so happy" → Joy 96.9%)
+- ✅ **Neutral content**: 89%+ accuracy (factual statements → Neutral 89.3%)
+- ❌ **Sarcasm detection**: **Complete failure** ("Oh great, another Monday" → Joy 95.4% ❌)
+- ❌ **Mixed emotions**: **Negative bias** ("excited but nervous" → Fear 94.0%, ignores excitement)
+- ⚠️ **Ambiguous text**: Lower confidence, distributed predictions
+
+### 🚫 **Known Critical Weaknesses**
+1. **Cannot detect sarcasm** - Interprets sarcastic phrases as genuine emotion
+2. **Mixed emotion bias** - Heavily favors negative emotions in complex expressions
+3. **Limited context understanding** - Missing social/cultural cues and implicit meaning
+4. **Over-confident on ambiguous inputs** - High confidence even when uncertain
+5. **Single sentence focus** - No conversation or document-level context
+
+### ✅ **What Works Well**
+- Direct emotional expressions in text
+- Neutral/factual content detection
+- Clear positive emotions (joy, love, gratitude)
+- Clear negative emotions (sadness, anger, fear)
+- Hyperbolic language ("dying of laughter" → Joy correctly)
+
+## 🔧 **Troubleshooting**
+
+### Common Issues and Solutions
+
+#### 1. **CUDA Out of Memory Error During Training**
+```bash
+# Solution: Reduce batch size
+python main.py train --combined --batch-size 8
+
+# Or use gradient accumulation (2 steps)
+python main.py train --combined --gradient-accumulation-steps 2
+```
+
+#### 2. **Model Takes Too Long to Load (>30 seconds)**
+```bash
+# Check if using CPU instead of GPU
+# On Windows with CUDA installed:
+set CUDA_VISIBLE_DEVICES=0
+
+# On Mac with MPS:
+python main.py predict "text" --device mps
+```
+
+#### 3. **Charts Not Generating or Saving**
+```bash
+# Ensure visualizations folder exists and is writable
+mkdir visualizations
+
+# Check permissions and try prediction again
+python main.py predict "test"
+
+# Verify file was created in visualizations/
+ls visualizations/
+```
+
+#### 4. **Incorrect Emotion Predictions (Sarcasm Issues)**
+```bash
+# The model struggles with sarcasm by design. Solutions:
+
+# Option A: Adjust sarcasm prior for your use case
+python main.py predict "Oh great, another bug" --target-sarcasm-prior 0.3
+
+# Option B: Use --disable-prior-adjustment for baseline
+python main.py predict "Oh great, another bug" --disable-prior-adjustment
+
+# Option C: Train a custom sarcasm dataset
+python main.py train --custom-sarcasm-data your_data.csv
+```
+
+#### 5. **Memory Issues on Older GPUs**
+```bash
+# Use a smaller model variant (if available) or CPU inference:
+python main.py predict "text" --device cpu --mixed-precision
+
+# Or batch predictions instead of real-time
+```
+
+### Performance Tips
+
+- **Fastest inference**: Use GPU (CUDA/MPS) - typically 50-150ms per prediction
+- **Most compatible**: CPU mode works everywhere - 200-500ms per prediction
+- **Memory efficient**: Load model once, reuse in loop within same process
+- **Batch processing**: Organize predictions to load model once per batch
+
+### 🧩 **Model Architecture**
+- **Base Model**: `microsoft/deberta-v3-base` (184M parameters, 12 layers)
+- **Classification Head**: 768-dim → 8 neurons (8 emotion classes including sarcasm)
+- **Tokenizer**: SentencePiece (128,000 vocab, max_length=256 tokens)
+- **Framework**: PyTorch + Hugging Face Transformers
+- **Device Support**: NVIDIA CUDA, Apple MPS, CPU (auto-detection)
+- **Model Files**: ~737MB weights in SafeTensors format
+- **Precision**: fp32 (full precision) for stable gradient computation
+
+### 📁 **Training Configuration**
+- **Dataset**: Combined dair-ai/emotion + GoEmotions (~59k samples)
+- **Optimization**: AdamW (lr=1e-5, warmup=0.1, weight_decay=0.01)
+- **Batch Size**: 16, Early Stopping (patience=2)
+- **Epochs**: 5 with early stopping
+- **Class Balancing**: Weighted Cross-Entropy for imbalanced emotions
+
+## 🎨 Advanced Features
+
+### Multiple Training Options
+```bash
+python main.py train                    # Standard: dair-ai/emotion (16k samples)
+python main.py train --goemotions       # Enhanced: GoEmotions (43k samples)
+python main.py train --combined         # Best: Combined datasets (59k samples)
+python main.py train --sample           # Quick test: 2k samples (~5 min)
+python main.py train --no-weights       # Disable class balancing
+python main.py train --samples 5000     # Custom sample size
+```
+
+### Interactive Analysis
+```bash
+python main.py analyze
+
+# Commands available:
+>>> I love this song so much!              # Basic analysis
+>>> chart: feeling sad today              # With simple chart
+>>> detailed: amazing day full of joy     # Enhanced visualization
+>>> quit                                  # Exit
+```
+
+### Visualization System
+- **Automatic generation**: Every prediction creates a chart by default (no flags needed)
+- **Simple charts**: Clean bar graphs with percentages and emotion colors
+- **Detailed charts**: Enhanced with primary emotion indicators and verification totals
+- **Comparison mode**: Side-by-side analysis of multiple texts in demo mode
+- **Export**: High-resolution PNG files (300 DPI) saved to `visualizations/` folder
+- **Interactive options**: Available in analyze mode (`chart:` and `detailed:` prefixes)
+
+## 💻 Complete Tech Stack
+
+### Core Machine Learning
+```python
+torch>=2.0.0                    # PyTorch deep learning framework
+transformers>=4.35.0             # Hugging Face Transformers (DeBERTa-v3-Base)
+datasets>=2.14.0                 # Hugging Face Datasets integration
+accelerate>=0.25.0               # Training acceleration & device management
+```
+
+### Data Processing & Analysis
+```python
+pandas>=2.0.0                    # Data manipulation and analysis
+numpy>=1.24.0                    # Numerical computing
+scikit-learn>=1.3.0              # ML utilities, metrics, class balancing
+```
+
+### Visualization & UI
+```python
+matplotlib>=3.7.0                # Plotting and chart generation
+seaborn>=0.12.0                  # Statistical data visualization
+tqdm>=4.65.0                     # Progress bars and logging
+```
+
+### Configuration & Utilities
+```python
+pyyaml>=6.0                      # Configuration file parsing
+pathlib                          # Modern file path handling (built-in)
+argparse                         # CLI argument parsing (built-in)
+```
+
+### Model Specifications
+- **Base Architecture**: `microsoft/deberta-v3-base`
+  - 12 transformer layers with disentangled attention
+  - 768 hidden dimensions
+  - 12 attention heads
+  - ~184M parameters
+
+- **Custom Components**:
+  - Linear classification head: 768 → 7 neurons (7 emotions)
+  - Dropout layer (p=0.1) for regularization
+  - Weighted Cross-Entropy loss for class balancing
+  - Automatic emotion mapping from 28 GoEmotions labels to 7 core emotions
+
+### Training Infrastructure
+- **Optimizer**: AdamW with weight decay
+- **Scheduler**: Linear warmup + decay
+- **Hardware**: Auto-detection (CPU/CUDA/MPS)
+- **Memory Management**: Gradient accumulation support
+- **Monitoring**: Loss tracking, F1-score optimization
+
+### Data Pipeline
+- **Tokenization**: SentencePiece tokenizer (128,000 vocab)
+- **Preprocessing**: Automatic text cleaning, label mapping
+- **Batching**: Dynamic padding, attention masks
+- **Splits**: 80/10/10 train/validation/test
+
+## 🧠 Technical Implementation Details
+
+### Exact Model Architecture
+```
+Input Text: "I feel so happy today!"
+    ↓
+DeBERTa-v3 Tokenizer (SentencePiece):
+    → token_ids + attention_mask
+    ↓
+Token Embeddings (768-dim) + Position Embeddings
+    ↓
+12x DeBERTa Transformer Layers:
+    • Disentangled Attention (content + position, 12 heads)
+    • Feed-Forward Network (3072 hidden)
+    • Layer Normalization + Residual Connections
+    ↓
+[CLS] Token Output (768-dim) → Pooler
+    ↓
+Classification Head:
+    Linear(768 → 7) + Dropout(0.1)
+    ↓
+Logits: [0.2, 4.8, 0.1, -0.5, -1.2, 0.3, -0.8]
+    ↓
+Softmax Activation:
+    [0.02, 0.994, 0.018, 0.01, 0.005, 0.022, 0.007]
+    ↓
+Final Prediction: JOY (99.4% confidence)
+```
+
+### Specific Training Configuration
+```python
+# Production model training parameters (emotion_classifier/final/)
+LEARNING_RATE = 2e-5           # Optimized for DeBERTa-v3-Base fine-tuning
+BATCH_SIZE = 16                # Per-device batch size (adjust for GPU memory)
+MAX_LENGTH = 256               # Token sequence length for lyrics
+NUM_EPOCHS = 4                 # With early stopping (patience=2)
+WARMUP_RATIO = 0.1             # Linear warmup (10% of total steps)
+WEIGHT_DECAY = 0.01            # L2 regularization to prevent overfitting
+PRECISION = "float32"          # Full precision (critical for stable gradients)
+
+# Class balancing (computed automatically from dataset distribution)
+CLASS_WEIGHTS = {              # Example from combined dataset
+    'joy': 0.85, 'sadness': 1.24, 'anger': 1.18,
+    'fear': 2.31, 'love': 3.45, 'surprise': 2.67, 'neutral': 0.92, 'sarcasm': 2.1
+}
+
+# Training hardware & time
+GPU_TYPE = "Apple MPS / NVIDIA CUDA"
+ESTIMATED_TRAINING_TIME = "45-90 minutes for full dataset (combined)"
+TOTAL_TRAINING_STEPS = "5,428 steps on 59k samples"
+VALIDATION_FREQUENCY = "Every 500 steps"
+```
+
+### 💻 **System Requirements & Performance**
+**Hardware Requirements:**
+- **Python**: 3.8+ (tested on 3.11.7)
+- **Memory**: 2GB RAM minimum, 4GB+ recommended for training
+- **Storage**: 2GB for models and datasets
+- **GPU**: Optional - Apple MPS, NVIDIA CUDA supported for faster inference
+
+**Estimated Performance *(varies by hardware)*:**
+- **Model Loading**: 2-5 seconds
+- **Single Prediction**: 50-200ms (MPS/CUDA), 200-500ms (CPU)
+- **Training Time**: 30-90 minutes for full dataset (GPU recommended)
+- **Memory Usage**: 1-2GB during inference, 4-8GB during training
+
+### Datasets Supported
+- **`dair-ai/emotion`**: 16,000 samples, 6 emotions (sadness, joy, love, anger, fear, surprise)
+  - Source: Tweet emotion classification dataset
+  - Label distribution: Balanced across core emotions
+  - Quality: High-quality manual annotations by emotion recognition experts
+
+- **`google-research-datasets/go_emotions`**: 43,410 samples, 28 emotions → mapped to 7
+  - Source: Reddit comments with fine-grained emotion labels
+  - Mapping: 28 GoEmotions labels clustered into our 7 core emotions + neutral
+  - Quality: Large-scale, diverse emotional expressions from social media
+  - Includes neutral category for balanced emotion representation
+
+- **Combined Dataset**: Best of both worlds (59,410 total samples)
+  - Merges both datasets with unified 7-emotion schema
+  - Provides maximum coverage across different text domains (Twitter + Reddit)
+  - Recommended for production use due to superior performance
+
+## 🎵 Music Context Mapping
+
+Each emotion automatically maps to music recommendation parameters:
+
+```python
+{
+    "sadness": {"mood": "melancholic", "energy": "low", "valence": "negative"},
+    "joy": {"mood": "happy", "energy": "high", "valence": "positive"},
+    "love": {"mood": "romantic", "energy": "medium", "valence": "positive"},
+    "anger": {"mood": "intense", "energy": "high", "valence": "negative"},
+    "fear": {"mood": "anxious", "energy": "medium", "valence": "negative"},
+    "surprise": {"mood": "excited", "energy": "high", "valence": "mixed"},
+    "neutral": {"mood": "calm", "energy": "low", "valence": "neutral"}
+}
+```
+
+## 📋 Exact Dependencies & Requirements
+
+### System Requirements
+- **Python**: 3.8+ (tested on 3.11.7)
+- **Operating System**: macOS, Linux, Windows
+- **Memory**: 4GB RAM minimum, 8GB recommended for training
+- **Storage**: 2GB for models and datasets
+
+### requirements.txt (Exact Versions)
+```bash
+# Core ML/DL Framework
+torch>=2.0.0
+transformers>=4.35.0
+datasets>=2.14.0
+
+# Data Processing
+pandas>=2.0.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+
+# Training Acceleration
+accelerate>=0.25.0
+
+# Visualization
+matplotlib>=3.7.0
+seaborn>=0.12.0
+
+# Utilities
+tqdm>=4.65.0
+pyyaml>=6.0
+```
+
+### Model Files Structure
+```
+models/emotion_classifier/final/
+├── config.json              # Model configuration
+├── model.safetensors        # Model weights (~737MB)
+├── spm.model                # SentencePiece tokenizer model
+├── tokenizer.json           # Tokenizer vocabulary
+├── tokenizer_config.json    # Tokenizer settings
+└── trainer_state.json       # Training metrics (optional)
+```
+
+### Dataset Cache Locations
+```
+~/.cache/huggingface/datasets/
+├── dair-ai___emotion/       # 16k samples (~45MB)
+├── google-research-datasets___go_emotions/  # 43k samples (~125MB)
+└── combined/                # Merged dataset (~170MB)
+
+./visualizations/            # Generated charts (gitignored)
+├── emotion_analysis_*.png   # Simple bar charts
+├── detailed_analysis_*.png  # Enhanced visualizations
+└── comparison_*.png         # Demo comparison charts
+```
+
+## 🔮 Next Phases & Roadmap
+
+### 🎯 **Priority Improvements** *(Planned Development)*
+1. **Enhanced Sarcasm Detection**
+   - Collect sarcasm-specific labeled datasets
+   - Train dedicated sarcasm classification head
+   - Improve contextual understanding beyond single sentences
+
+2. **Multi-Emotion Modeling**
+   - Multi-label classification (multiple emotions per text)
+   - Emotion intensity scoring (0-100 scale per emotion)
+   - Probabilistic emotion combinations
+
+3. **Better Context Understanding**
+   - Sentence-level context windows (n-grams)
+   - Conversation history integration
+   - Stylistic/tone analysis
+
+4. **Confidence Calibration**
+   - Uncertainty quantification
+   - Temperature scaling for better probability estimates
+   - Abstention on truly ambiguous inputs
+
+### 📊 **Validation & Testing**
+- Comprehensive sarcasm detection test suite
+- Mixed emotion evaluation benchmarks
+- Real-world music recommendation A/B testing
+- User studies for edge cases
+
+### 📈 **Expected Timeline**
+- **Phase 1.5**: Bug fixes & optimization (2-3 weeks)
+- **Phase 2.0**: Enhanced context & sarcasm (1-2 months)
+- **Phase 3.0**: Audio feature integration (3-4 months)
+- **Phase 4.0**: Multimodal audio+lyrics (4-6 months)
+
+## ⚠️ **For Developers & Users**
+
+### 🎭 **Current Recommended Use Cases**
+**✅ GOOD FOR:**
+- Music mood classification from clear emotional text
+- Sentiment analysis for unambiguous expressions
+- Educational/research projects on emotion detection
+- Prototype applications requiring basic emotion categorization
+
+**❌ NOT READY FOR:**
+- Production sarcasm detection
+- Complex multi-emotion analysis
+- Social media content analysis (high sarcasm rate)
+- Customer service sentiment (requires nuance)
+- Any application where false positives on sarcasm are problematic
+
+### 🛠 **Developer Notice**
+This is a **functional but limited** emotion detection system. The model works well for straightforward cases but has significant blind spots. **Use with caution in production environments** and consider adding manual review for critical applications.
+
+**If you need sarcasm detection or complex emotion understanding, consider:**
+- OpenAI GPT-4/Claude APIs for better contextual understanding
+- Combine this model with rule-based sarcasm detection
+- Wait for our Phase 2.0 improvements (see roadmap above)
+
+## 🔮 Future Development Phases
+
+- [ ] **Phase 2**: Enhanced Context & Sarcasm Detection
+- [ ] **Phase 3**: Audio Analysis (spectrograms, MFCCs, audio emotion detection)
+- [ ] **Phase 4**: Multimodal Fusion (combine lyrics + audio features)
+- [ ] **Phase 5**: Music Database Integration (Spotify/Apple Music APIs)
+- [ ] **Phase 6**: Web Interface & Mobile Apps
+- [ ] **Phase 7**: Real-time Audio Processing & Social Features
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Install dependencies (`pip install -r requirements.txt`)
+4. Train and test your changes (`python main.py train --sample`)
+5. Test predictions and visualizations (`python main.py predict "test text"`)
+6. Commit changes (`git commit -m 'Add amazing feature'`)
+7. Push to branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+**Note**: Generated visualizations and trained models are gitignored. Contributors should train their own models locally for testing.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments & References
+
+### Models & Frameworks
+- **Hugging Face Transformers** - `microsoft/deberta-v3-base` model architecture
+- **PyTorch** - Deep learning framework and automatic differentiation
+- **DeBERTa-v3** (He et al., 2023) - Disentangled attention transformer architecture
+- **Matplotlib/Seaborn** - Visualization libraries for emotion analysis charts
+
+### Datasets & Research
+- **`dair-ai/emotion`** - Mohammad, S. M. (2012). Portable features for classifying emotional text
+- **`google-research-datasets/go_emotions`** - Demszky et al. (2020). GoEmotions: A Dataset of Fine-Grained Emotions
+- **Emotion Theory** - Ekman's basic emotions framework (joy, sadness, anger, fear, surprise)
+- **Music Information Retrieval** - Research on emotion-music mapping (Russell's Circumplex Model)
+
+### Technical References
+```bibtex
+@article{he2023debertav3,
+  title={DeBERTaV3: Improving DeBERTa using ELECTRA-Style Pre-Training with Gradient-Disentangled Embedding Sharing},
+  author={He, Pengcheng and Gao, Jianfeng and Chen, Weizhu},
+  journal={arXiv preprint arXiv:2111.09543},
+  year={2023}
+}
+
+@inproceedings{demszky2020goemotions,
+  title={GoEmotions: A Dataset of Fine-Grained Emotions},
+  author={Demszky, Dorottya and Movshovitz-Attias, Dana and Ko, Jeongwoo and Cowen, Alan and Nemade, Gaurav and Ravi, Sujith},
+  booktitle={ACL},
+  year={2020}
+}
+```
+
 ---
-title: EUMORA API
-emoji: 🎵
-colorFrom: purple
-colorTo: blue
-sdk: docker
-app_port: 8000
-pinned: false
----
+
+## 🎯 **Project Status Summary** (April 20, 2026)
+
+**EUMORA** is a **fully functional emotion detection system** with documented strengths and limitations.
+
+### ✅ What's Production-Ready
+- Clear, unambiguous emotion detection (95%+ accuracy)
+- Neutral content classification (89%+ accuracy)
+- Cross-platform inference (CPU, CUDA, MPS)
+- Automatic visualization and chart generation
+- Bayesian sarcasm calibration for domain adaptation
+
+### ⚠️ Known Limitations
+- Sarcasm detection requires domain-specific calibration
+- Mixed emotion cases show negative bias
+- Single-sentence focus (no multi-turn context)
+- May overestimate confidence on ambiguous inputs
+
+### 📋 Current Recommendation
+**Suitable for**: Research, prototyping, educational projects, proof-of-concepts
+**Not recommended for**: Critical production systems without manual review, sensitive applications requiring near-perfect accuracy
+
+### 🚀 Next Major Version
+Version 2.0 will add:
+- Enhanced sarcasm and context understanding
+- Multi-label emotion support
+- Audio feature integration
+- Web/mobile interfaces
+
+----
+
+🎵 **EUMORA** - *Understanding emotions, advancing music.* 🎭