---
language:
- en
license: apache-2.0
pipeline_tag: text-classification
library_name: python
tags:
- emotion-detection
- emotion-analysis
- conversation-analysis
- affective-computing
- explainable-ai
task_categories:
- text-classification
model-index:
- name: emotion-shift-detector
  results: []
---

# Emotion Shift Detector 🧠📈

**EmotionShiftDetector** is an AI system that detects **subtle emotional transitions across conversations**, not just isolated sentiment in individual messages.

Instead of answering *“What emotion is this message?”*, it answers:
> **“How is the emotion changing over time?”**

The model is designed for **conversation analysis, mental-health tools, customer support analytics, and emotion-aware AI agents**.

---

## 🔍 What Problem Does It Solve?

Traditional sentiment analysis treats messages independently.  
EmotionShiftDetector focuses on **emotional dynamics** by identifying:

- Emotional escalation or de-escalation  
- Mood shifts across dialogue turns  
- Sudden emotional changes that indicate risk, frustration, or recovery  

---

## ✨ Key Features

- 🧠 Emotion classification per conversation turn  
- 🔄 Detection of emotional shifts over time  
- 🗣️ Human-readable explanations for each shift  
- 🧩 Modular and explainable design  
- 🤗 Hugging Face–ready pipeline  
- 🎛️ Gradio demo included  
- 🧪 Test-covered core components  

---

## 📂 Project Structure

```
emotion-shift-detector/
├── config/
├── data/
├── src/
├── training/
├── pipelines/
├── scripts/
├── tests/
├── notebooks/
├── app.py
├── README.md
├── model_card.md
├── requirements.txt
└── LICENSE
```

---

## ⚙️ Installation

```bash
pip install -r requirements.txt
```

---

## 🚀 Quick Usage

```python
from src.inference import EmotionShiftPipeline

pipeline = EmotionShiftPipeline()

conversation = [
    "I am feeling okay today",
    "This is getting frustrating",
    "Now I am really angry"
]

result = pipeline(conversation)
print(result)
```

---

## 🎛️ Gradio Demo

```bash
python app.py
```

---

## 🧠 How It Works

1. Text Preprocessing  
2. Emotion Classification  
3. Shift Detection  
4. Explanation Engine