Spaces:

NLarchive
/

Emoji-AI-Avatar

Running

App Files Files Community

Emoji-AI-Avatar / README.md

Deminiko

Initial import: Emoji AI Avatar

25e624c 8 days ago

preview code

raw

history blame contribute delete

6.15 kB

A newer version of the Gradio SDK is available: 6.1.0

Upgrade

metadata

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

# 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

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

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

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

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

📝 How It Works

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

🚀 Deployment

Hugging Face Spaces

Create a new Space on Hugging Face
Select "Gradio" as the SDK
Push this repository to the Space
Add GEMINI_API_KEY to Space Secrets
The app will auto-deploy!

Docker

FROM python:3.10-slim

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

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