| --- |
| 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: |
|
|
| ```bash |
| # 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: |
| ```bash |
| 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`. |
|
|
