README.md

---
title: EUMORA API
emoji: 🎵
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 8000
pinned: false
---

# 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}
}
```

---

## 🎯 **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.* 🎭