🎭 BERT Arabic Emotions Classifier

FastAPI-based emotion detection API for Arabic text using fine-tuned BERT-medium-arabic on the Emotone-AR dataset.

🎯 Model

HuggingFace: Zeyadelgabas/bert-medium-arabic-Egyar-emotones

Detects 8 emotions in Arabic text:

• 😐 none
• 😠 anger
• 😊 joy
• 😢 sadness
• ❤️ love
• 🤝 sympathy
• 😮 surprise
• 😨 fear

⚠️ Model Limitations

The model has some limitations due to:

• Insufficient training data - Limited dataset size
• Data labeling issues - Inconsistent annotations
• Language variety mismatch - Trained on MSA (Modern Standard Arabic) but tested on Egyptian dialect

Use with caution for production applications. Results may vary with dialectal Arabic text.

📦 Installation

git clone https://github.com/yourusername/bert-ar-emotions.git
cd bert-ar-emotions
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

⚙️ Setup

1. Create .env file (see .env.example):

APP_NAME=BERT Arabic Emotions API
VERSION=1.0.0
API_SECRET_KEY=your-secret-key-here

2. Download model (if not included):

# Model should auto-download from HuggingFace on first run

🚀 Usage

Start server:

python main.py

Server runs at http://127.0.0.1:8001

📡 API Endpoints

🔮 Single Text Prediction

POST /predict

📚 Batch Text Prediction

POST /predict-batch

💡 Examples

Single Prediction

Request:

curl -X POST "http://127.0.0.1:8001/predict" \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "شفت فلم حلو اوي امبارح"}'

Response:

{
  "output": {
    "joy": 97.85,
    "anger": 0.48,
    "love": 0.41
  }
}

Batch Prediction

Request:

import requests

url = "http://127.0.0.1:8001/predict-batch"
headers = {"X-API-Key": "your-secret-key"}

texts = [
    "شفت فلم حلو اوي امبارح",
    "بسمع التراك دا بقالي ساعه اهو ولسه في نصه",
    "فلسطين يوم ما دخلوا اليهود ارضك زعلوا العرب"
]

response = requests.post(url, headers=headers, json={"texts": texts})
print(response.json())

Response:

{
  "predictions": [
    {
      "output": {
        "joy": 97.85,
        "anger": 0.48,
        "love": 0.41
      }
    },
    {
      "output": {
        "surprise": 80.97,
        "joy": 14.05,
        "sadness": 1.90
      }
    },
    {
      "output": {
        "sadness": 54.99,
        "anger": 37.40,
        "fear": 3.33
      }
    }
  ]
}

📊 Understanding Results

The API returns top 3 emotions with confidence scores (0-100%):

Input	Top Emotion	Interpretation
"شفت فلم حلو اوي امبارح"	😊 Joy (97.85%)	Positive movie review
"بسمع التراك دا بقالي ساعه"	😮 Surprise (80.97%)	Unexpected enjoyment
"فلسطين يوم ما دخلوا..."	😢 Sadness (54.99%)	Political concern

📚 Documentation

Interactive API docs: http://127.0.0.1:8001/docs

🏗️ Project Structure

BERT-AR-EMOTIONS/
├── Src/
│   ├── config.py       # Config & model loading
│   ├── logger.py       # Logging setup
│   ├── schemas.py      # Request/response models
│   └── utils.py        # Helper functions
├── assets/
│   ├── label_names.joblib
│   └── label2id.joblib
├── notebooks/
│   └── BERT_ar_classifier.ipynb
├── main.py
├── .env
└── .env.example

🔧 Troubleshooting

Model not loading:

• Check internet connection (downloads from HuggingFace)
• Ensure sufficient disk space (~500MB)

Low accuracy on Egyptian dialect:

• Model performs better on MSA
• Consider preprocessing dialectal text

API key error:

• Verify .env file exists
• Check API_SECRET_KEY matches request header

📝 Notes

• Returns only top 3 emotions (sorted by confidence)
• Confidence scores are percentages (0-100)
• Works best with MSA Arabic text
• Egyptian dialect may produce less accurate results

📄 License

MIT License

---

Model: HuggingFace Hub
Author: Zeyad Elgabbas
GitHub: @Zeyadelgabbas