An intelligent emotional support companion that uses voice, facial expression, and text analysis to detect emotions and provide personalized empathetic responses powered by Llama 3.2. Built for mental wellness with real-time AI-driven coping strategies.

• 🎤 Voice Emotion Detection - Speak naturally and get instant emotion analysis
• 📸 Facial Expression Analysis - Upload photos or use webcam for emotion recognition
• 💬 Text-based Chat - Type your feelings and receive empathetic AI responses
• 🤖 Llama 3.2 Integration - Dynamic, personalized responses (not pre-written templates!)
• 📊 Emotion Tracking - Monitor your emotional journey with analytics
• 🧘 Smart Coping Strategies - AI-generated wellness techniques tailored to your emotion

User: "I'm feeling really stressed about my presentation tomorrow"

AI: I can sense the pressure you're under. Presenting can be nerve-wracking, 
    but remember that feeling anxious shows you care about doing well. 
    You've got this! 💙

Detected: fear (87% confidence)

Coping Strategy: Try the 5-4-3-2-1 grounding technique:
                 Notice 5 things you see, 4 you touch, 3 you hear,
                 2 you smell, and 1 you taste.

• 🎤 Click record → Speak your feelings
• 🧠 AI detects emotion from your words
• 💬 Receive empathetic response
• 🔊 Hear AI speak back to you (optional)

• 📸 Upload photo or use webcam
• 👁️ AI analyzes facial expression
• 😊 Detects: happy, sad, angry, fear, surprise, disgust, neutral
• 🎯 Provides emotion-specific support

• Python 3.8+
• Ollama (for Llama 3.2)
• Microphone (for voice input)
• Webcam (optional, for facial capture)

# 1. Clone repository
git clone https://github.com/yourusername/ai-emotion-companion.git
cd ai-emotion-companion

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

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install Llama 3.2
# Download Ollama from https://ollama.ai
ollama pull llama3.2

# 5. Run the app
streamlit run app.py

brew install portaudio
pip install pyaudio

sudo apt-get install python3-pyaudio portaudio19-dev
pip install pyaudio

pip install pyaudio

# Terminal 1: Start Ollama server
ollama serve

# Terminal 2: Run Streamlit app
streamlit run app.py

Open your browser at http://localhost:8501

1. Navigate to 🎤 Voice Input tab
2. Click "Start Recording"
3. Speak for 3-10 seconds
4. View emotion analysis and AI response
5. (Optional) Enable voice response to hear AI speak

1. Navigate to 📸 Facial Analysis tab
2. Choose "Upload Image" or "Use Webcam"
3. Upload/capture your photo
4. View detected emotion and personalized support

1. Navigate to 💬 Text Chat tab
2. Type your message in the chat input
3. Receive emotion analysis and empathetic response
4. Continue the conversation naturally

1. Navigate to 📊 Your Stats tab
2. See emotion distribution charts
3. Track your emotional journey over time

emotion-ai-companion/
│
├── app.py                          # Main Streamlit application
├── emotion_detector.py             # Emotion detection (text/voice/facial)
├── llm_response_generator.py      # Llama 3.2 integration
├── utils.py                        # Helper utilities
├── requirements.txt                # Python dependencies
└── README.md                       # Documentation

┌─────────────────────────────────────────────────────────┐
│                      USER INTERFACE                      │
│                     (Streamlit - app.py)                 │
└────────────┬────────────────────────────┬────────────────┘
             │                            │
             v                            v
┌────────────────────────┐    ┌──────────────────────────┐
│  EMOTION DETECTION     │    │  LLM RESPONSE GENERATOR  │
│  emotion_detector.py   │    │  llm_response_generator  │
│                        │    │                          │
│  • Text Analysis       │───→│  • Empathy Generation    │
│  • Voice Recognition   │    │  • Coping Strategies     │
│  • Facial Detection    │    │  • Llama 3.2 API         │
└────────────┬───────────┘    └──────────┬───────────────┘
             │                           │
             v                           v
┌────────────────────────────────────────────────────────┐
│                    UTILITIES                           │
│                   (utils.py)                           │
│                                                        │
│  • Voice Output (TTS)                                 │
│  • Webcam Capture                                     │
│  • Session Management                                 │
│  • Data Formatting                                    │
└────────────────────────────────────────────────────────┘

User Input (Voice/Text/Image)
         ↓
Emotion Detection (DistilRoBERTa / DeepFace)
         ↓
Emotion Classification (angry/sad/happy/etc.)
         ↓
LLM Processing (Llama 3.2)
         ↓
Personalized Response + Coping Strategy
         ↓
Display to User + Save to History

# Uses DistilRoBERTa fine-tuned on emotion classification
text = "I'm feeling anxious"
emotion, confidence = detector.detect_text_emotion(text)
# Output: ('fear', 0.89)

# Uses DeepFace CNN model
image = load_image("photo.jpg")
emotion, confidence = detector.detect_facial_emotion(image)
# Output: ('sad', 0.76)

# Sends context-aware prompt to Llama
prompt = f"""
User said: "{user_message}"
Detected emotion: {emotion} (confidence: {confidence})

Provide a compassionate, supportive response.
"""

response = llama.generate(prompt)
# Output: Personalized empathetic message

Edit llm_response_generator.py:

# Adjust temperature for response creativity
"options": {
    "temperature": 0.7,  # 0.0 = deterministic, 1.0 = creative
    "max_tokens": 150    # Response length
}

Edit emotion_detector.py:

EMOTION_MAPPING = {
    'angry': 'angry',
    'happy': 'happy',
}

docker build -t emotion-companion .
docker run -p 8501:8501 emotion-companion

# Test emotion detection
python -c "from emotion_detector import EmotionDetector; d = EmotionDetector(); print(d.detect_text_emotion('I am happy'))"

# Test LLM connection
python -c "from llm_response_generator import LLMResponseGenerator; l = LLMResponseGenerator(); print(l.check_llm_available())"

# Test microphone
python -c "import speech_recognition as sr; print(sr.Microphone.list_microphone_names())"

# Test webcam
python -c "import cv2; cap = cv2.VideoCapture(0); print('OK' if cap.isOpened() else 'Failed')"

# Check Ollama is running
curl http://localhost:11434/api/tags

# Restart Ollama
ollama serve

# Verify model is installed
ollama list

# List available microphones
python -c "import speech_recognition as sr; print(sr.Microphone.list_microphone_names())"

# Grant microphone permissions in system settings

# Reinstall with specific backend
pip uninstall deepface tf-keras tensorflow
pip install deepface tf-keras tensorflow

# Force reinstall all dependencies
pip install --force-reinstall -r requirements.txt

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

# Install dev dependencies
pip install black flake8 pytest

# Run formatter
black *.py

# Run linter
flake8 *.py

# Run tests
pytest tests/

This AI is NOT a substitute for professional mental health care.

If you're experiencing:

• 🚨 Thoughts of self-harm or suicide
• 🚨 Severe depression or anxiety
• 🚨 Mental health crisis
• 🚨 Trauma or abuse

• 🌍 International Association for Suicide Prevention: iasp.info
• 🌐 Befrienders Worldwide: befrienders.org
• 🏥 Emergency Services: Call your local emergency number

This tool is designed for emotional wellness support only, not medical diagnosis or treatment.

• Hugging Face - DistilRoBERTa emotion model
• Meta AI - Llama 3.2 language model
• DeepFace - Facial emotion recognition
• Streamlit - Web application framework
• Ollama - Local LLM inference

Project Maintainer: Muhammad Hashim Awan

• GitHub: @hashimaawan
• Email: awanhashim800@gmail.com

If this project helped you, please consider giving it a ⭐!

If you use this project in your research, please cite: