README.md

metadata

title: Urdu Sentiment & Emotion Analysis Engine
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 4.26.0
app_file: app.py
pinned: false

Urdu Sentiment and Emotion Analysis Engine

Welcome to the Urdu Sentiment and Emotion Analysis Engine project! This repository contains the code for a multilingual NLP system that classifies sentiment (Positive, Negative, Neutral) and emotion (Joy, Anger, Fear, Sadness) from Urdu, Roman Urdu, and mixed-language text using a fine-tuned XLM-RoBERTa transformer.

Current Progress: Phase 9 (Modal.com Deployment — In Progress)

The project has successfully completed Phases 1 through 8. The AI models are fully trained, uploaded to Hugging Face Hub (usman-ai-dev/urdu-sentiment-xlmr & usman-ai-dev/urdu-emotion-xlmr), and integrated into a production-ready FastAPI web server with Uvicorn. The frontend features a dark-mode Glassmorphism dashboard with an interactive 3D WebGL Three.js particle wave background, floating ambient glowing orbs, real-time cursor spotlight, Chart.js analytics, and automated live tweet feed streaming. Phase 9 deploys the full stack to Modal.com with a custom domain (urdu-sentiment.hmuhammadusman.com).

Repository Structure

• app.py: FastAPI Web Server exposing all REST API routes (/analyze, /analytics, /detect-language, /live-feed, /health).
• predictor.py: Object-Oriented class handling model loading, Softmax probability scoring, and subword attention extraction.
• lang_detector.py: Language identification module for Urdu Script, Roman Urdu, English, and Mixed text.
• templates/index.html: Main dashboard HTML template.
• static/: Frontend visual assets:
  • css/style.css: Glassmorphism design system, dark theme tokens, and dynamic background glow animations.
  • js/bg3d.js: Three.js 3D WebGL particle wave and floating embers motion engine.
  • js/main.js: Interactivity handlers, GSAP timelines, Chart.js charts, and FastAPI endpoint fetch calls.
• upload_to_hub.py: Automated model upload script for Hugging Face Hub integration.
• modal_app.py: Modal.com deployment entrypoint — wraps FastAPI app for serverless cloud deployment.
• requirements.txt: Environment dependencies required for training and the FastAPI server.
• Dockerfile: Container configuration configured to run FastAPI with Uvicorn on port 7860.
• test_models.py: Utility script to run interactive CLI inference without starting the server.
• training/: Core scripts for data processing and model fine-tuning.
  • dataset.py: PyTorch Dataset implementation utilizing unified canonical label mappings.
  • train_sentiment.py: Training script for the sentiment classification model (Multi-GPU enabled).
  • train_emotion.py: Training script for the emotion classification model (Multi-GPU enabled).
• evaluation/: Scripts for evaluating model performance and generating attention visualizations.
• results/: Contains output matrices and evaluation reports.

(Note: The models/ directory containing the 1GB .safetensors files is ignored via .gitignore due to size constraints. The models will be hosted on Hugging Face Hub for cloud deployment.)

Environment Setup

To get started, create a virtual environment and install the required dependencies:

# Create a virtual environment
python -m venv urdu_env

# Activate the virtual environment
# On Windows:
urdu_env\Scripts\activate
# On Linux/Mac:
source urdu_env/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the API Server

To start the backend server:

python app.py

The server will boot up and listen on http://127.0.0.1:5000.

Available API Routes:

Method	Route	Description
GET	/	Serves main landing dashboard HTML page
POST	/analyze	Main prediction endpoint — accepts {"text": "..."} and returns sentiment, emotion, confidence distributions, language type, and word attention
GET	/analytics	Returns session analytics — total texts, sentiment breakdown, emotion counts, and top keywords
POST	/detect-language	Accepts {"text": "..."} and returns detected language (Urdu Script, Roman Urdu, English, Mixed)
GET	/live-feed	Streams simulated real-time tweet feed predictions
GET	/health	Health check endpoint for Docker / deployment monitors
GET	/docs	Interactive Swagger API documentation UI

Deployment (Phase 9 — Modal.com)

• Phase 8 ✅: Models pushed to Hugging Face Hub. predictor.py updated to load from Hub.
• Phase 9: Deploy full FastAPI stack to Modal.com (free $30/month credit tier).
  • Run: modal deploy modal_app.py
  • Custom domain: urdu-sentiment.hmuhammadusman.com
  • GitHub Actions auto-deploys on every push to main.