README.md

metadata

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

# 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

# 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

# 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:

# 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

# 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

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

# 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

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

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

# 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)

# 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

# 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)

# 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

# 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

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

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

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

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

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

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

# 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:

{
    "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)

# 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

@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. 🎭