README.md

---
title: Emoji AI Avatar
emoji: 😊
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "6.0.0"
python_version: "3.10"
app_file: app.py
pinned: false
suggested_hardware: "cpu-basic"
short_description: Real-time emoji sentiment avatars for chat
tags:
  - mcp-in-action-track-enterprise
  - mcp-in-action-track-consumer
  - mcp-in-action-track-creative
  - Google-Gemini-API
  - sentiment-analysis
  - emoji
  - chatbot
  - gradio
  - transformer
  - distilbert
---

# 😊 Emoji AI Avatar 🤖

**Real-time emoji avatars that reflect the sentiment of your conversation!**

Watch as both your emoji and the AI's emoji change dynamically based on the emotional tone of messages.

## ✨ Features

- **Transformer-Based Sentiment Analysis**: Uses DistilBERT (91%+ accuracy) for precise emotion detection
- **Real-time Updates**: Analyzes messages as you type and as AI responds
- **Dual Emoji Avatars**: Separate emoji displays for user and AI
- **Streaming Support**: AI emoji updates during response generation
- **100+ Emotion States**: Comprehensive sentiment coverage from joy to despair
- **Beautiful UI**: Modern, responsive Gradio interface
- **Evaluation Framework**: CI/CD-ready testing with accuracy benchmarks

## 🚀 Quick Start

### Local Development

```bash
# Clone the repository
git clone https://github.com/NLarchive/Emoji-AI-Avatar.git
cd emoji-ai-avatar

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the app (uses mock AI by default)
python app.py

# Or with hot reload
gradio app.py
```

### With Gemini API

```bash
# Set your API key
export GEMINI_API_KEY='your-api-key-here'

# Run the app
python app.py
```

## 🎭 Emoji Palette

### User Emotions (Based on Transformer Classification)
| Emoji | Sentiment | Accuracy |
|-------|-----------|----------|
| 😢 | Sadness/Negative | 100% |
| 😊 | Happiness/Positive | 100% |
| 😐 | Neutral | ~50% |

The system detects **100+ specific emotions** (both transformer and multi-emotion models) including:
- **Positive**: joy, happiness, excitement, enthusiasm, love, gratitude, etc.
- **Negative**: sadness, anger, fear, anxiety, frustration, disgust, etc.
- **Neutral**: thinking, uncertain, confused, etc.

## 🏗️ Project Structure

```
emoji-ai-avatar/
├── app.py                      # Main Gradio application
├── avatar/                     # Sentiment analysis + utils
│   ├── __init__.py
│   ├── sentiment_transformer.py  # DistilBERT-based binary analyzer
│   ├── sentiment_multi_emotion.py # Multi-emotion (RoBERTa) analyzer
│   ├── sentiment_emoji_map.py   # Sentiment → Emoji mapping
│   ├── sentiment_keyword_map.py # Keyword→emotion mapping used by analyzer
├── llm-inference/              # LLM client module
│   ├── __init__.py
│   └── gemini_client.py        # Gemini API wrapper
├── mcp-client/                 # MCP protocol client
│   ├── __init__.py
│   └── mcp_client.py           # MCP client implementation
├── evaluation/                 # Testing & benchmarking + reports
│   ├── __init__.py
│   ├── emotion_test_suite.py   # 100+ emotion test cases
│   ├── accuracy_benchmark.py   # Speed/accuracy measurement
│   ├── live_stream_test.py     # Transition testing
│   ├── report_generator.py     # Markdown/JSON reports
│   ├── run_evaluation.py       # Full evaluation runner
│   └── reports/                # Generated reports
├── tests/                      # Unit tests
├── requirements.txt            # Python dependencies
└── README.md
```

## 📊 Evaluation Results

Run the evaluation framework:

```bash
python -m evaluation.run_evaluation
```

**Latest Results (approx):**
- Weighted accuracy and wheel-aware evaluation results are recorded in evaluation/reports
- Full test suites (V1, V2, V3) are available — expected overall accuracy ~90% depending on model and suite

| Category | Count | Accuracy |
|----------|-------|----------|
| Positive Emotions | 40+ | 100% |
| Negative Emotions | 50+ | 100% |
| Neutral/Edge Cases | 10+ | ~40% |

## 🧪 Testing

```bash
# Run all tests
python -m pytest avatar/tests/ -v

# Run evaluation benchmark
python -m evaluation.run_evaluation
```

## 🔧 Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `GEMINI_API_KEY` | Google Gemini API key | No (uses mock if not set) |

### Customization

Edit `avatar/emoji_mapper.py` to customize emoji mappings:

```python
mapper = EmojiMapper(
    custom_mappings={"excitement": "🎉", "love": "❤️"}
)
```

## 📝 How It Works

1. **User Input**: When you type a message, it's analyzed by DistilBERT
2. **Sentiment Classification**: Model outputs positive/negative with confidence
3. **User Emoji Update**: Your avatar emoji changes to reflect your mood
4. **AI Processing**: The message is sent to Gemini (or mock)
5. **Streaming Response**: As AI generates a response, its emoji updates
6. **Final Analysis**: Both emojis settle on their final states

## 🚀 Deployment

### Hugging Face Spaces

1. Create a new Space on Hugging Face
2. Select "Gradio" as the SDK
3. Push this repository to the Space
4. Add `GEMINI_API_KEY` to Space Secrets
5. The app will auto-deploy!

### Docker

```dockerfile
FROM python:3.10-slim

WORKDIR /app
COPY . .
RUN pip install -r requirements.txt

EXPOSE 7860
CMD ["python", "app.py"]
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License — see LICENSE file. (Copyright © 2025 Nicolas Larenas)

## 🙏 Acknowledgments

- [Gradio](https://gradio.app/) - For the amazing UI framework
- [Google Gemini](https://ai.google.dev/) - For the AI capabilities
- [Hugging Face](https://huggingface.co/) - For hosting, deployment, and transformers
- [DistilBERT](https://huggingface.co/distilbert-base-uncased-finetuned-sst-2-english) - For sentiment analysis