ReviewSense Analytics

Production-ready multilingual sentiment intelligence platform

Hybrid Transformer Routing • Confidence-Aware Decisions • Explainable AI

⭐ If you like this project, consider giving it a star!

---

🎬 Live Demo

_{Real-time multilingual sentiment analysis • Bulk CSV processing • Explainability • Interactive dashboard}

---

🌍 Why This Matters

• Businesses receive multilingual, mixed-language feedback daily
• Traditional models fail on code-switched (Hinglish) inputs
• Translation errors silently degrade prediction quality
• Incorrect sentiment → wrong business decisions

ReviewSense solves this with reliable, explainable, multilingual intelligence

---

⚡ Key Highlights

• Hybrid transformer routing (RoBERTa + XLM-R + NLLB)
• Hinglish normalization for real-world inputs
• Translation trust validation (fail-safe fallback)
• Margin-based decision layer (ambiguity control)
• Entropy-based confidence calibration
• Explainability via LIME + ABSA
• Real-time + bulk processing pipeline

---

🧩 Use Cases

• E-commerce product review analysis
• Social media sentiment monitoring
• Multilingual customer feedback systems
• Market research & brand intelligence

---

🎯 Problem

• Multilingual input breaks traditional models
• Translation introduces hidden errors
• Confidence scores are misleading
• Ambiguous predictions are mishandled
• Lack of explainability

---

💡 Solution Overview

Layer	Purpose
Language Routing	Detect English / Hinglish / Multilingual
Hinglish Normalization	Clean code-mixed input
Translation (NLLB)	Convert multilingual → English
Validation Layer	Verify translation quality
Model Layer	RoBERTa / XLM-R inference
Decision Layer	Margin-based ambiguity handling
Confidence Layer	Entropy calibration
Explainability	LIME + ABSA

---

🧠 Core Innovations

• Model-first architecture (no heuristics)
• Margin-based ambiguity detection
• Entropy-based confidence (not softmax)
• Translation trust gating system

---

🧩 Architecture Diagram

---

📊 Performance

Metric	Value
Accuracy	~91%
Precision	~0.92
Recall	~0.91
F1 Score	~0.90

_{Evaluated on mixed multilingual dataset (real-world inputs)}

---

🖼️ UI Preview

Home	Live Prediction
Model Dashboard	Multilingual Analysis

---

🏗️ Tech Stack

Layer	Technology
Backend	FastAPI, Uvicorn
Frontend	React, TypeScript
Models	RoBERTa, XLM-R
Translation	Meta NLLB
Explainability	LIME, ABSA
ML Stack	PyTorch, Transformers
Data	Pandas, NumPy

---

📂 Project Structure (Engineering-Level)

ReviewSense-Analytics/
│
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── routes/
│   │   ├── services/
│   │   ├── schemas/
│   │   ├── core/
│   │   └── utils/
│   └── tests/
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── styles/
│
├── src/
│   ├── models/
│   ├── pipeline/
│   ├── preprocessing/
│   ├── translation/
│   ├── decision/
│   └── predict.py
│
├── docs/
│   └── images/
│
├── scripts/
├── reports/
├── data/
└── start.ps1

---

🔌 API Overview

Method	Endpoint	Description
GET	/health	Health check
POST	/predict	Real-time sentiment
POST	/bulk	Bulk CSV processing
GET	/metrics	Model metrics
POST	/feedback	Feedback logging

---

🛠 Setup Instructions

🔧 Prerequisites

Ensure your system has:

• Python 3.10+
• Node.js 18+ (with npm)
• Git

---

📥 Clone & Install

git clone https://github.com/amansethhh/ReviewSense-Analytics.git
cd ReviewSense-Analytics

1. Python Virtual Environment (at the project root)

# Create virtual environment
python -m venv venv

# Activate it
# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

# macOS / Linux
source venv/bin/activate

# Install backend dependencies
pip install -r backend/requirements.txt

2. Node.js Dependencies

# Install root orchestration tools (concurrently, wait-on)
npm install

# Install frontend dependencies
cd frontend
npm install
cd ..

Tip: You can also run npm run install:all from the project root to install both root and frontend dependencies in one command.

---

🚀 Running the Application

⚡ One-Click Start (Recommended)

From the project root, run one of these:

# Option A — npm (starts backend + frontend together)
npm start

# Option B — PowerShell script (Windows)
.\start.ps1

Both methods will:

• Kill any existing processes on ports 8000, 5173, 5174
• Start the FastAPI backend on http://localhost:8000
• Wait for the backend to become healthy
• Start the Vite React frontend on http://localhost:5173

---

🔧 Manual Start (Step-by-Step)

If you prefer to start services individually:

Terminal 1 — Backend (FastAPI)

# From the project root (with venv activated)
python backend/start_backend.py

Or directly with uvicorn:

cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 — Frontend (Vite + React)

cd frontend
npm run dev

---

🌐 Access Points

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
Health Check	http://localhost:8000/health

---

🔗 Environment Configuration

The .env files are pre-configured. If you need to customize them:

File	Key Variable	Default
.env (root)	BACKEND_URL	http://localhost:8000
frontend/.env	VITE_API_URL	http://localhost:8000

---

🧪 How to Use

• 🔍 Live Prediction
  Enter multilingual or Hinglish text → get sentiment, confidence, explanation

• 📦 Bulk Analysis
  Upload CSV file → process batch sentiment predictions

• 📊 Dashboard
  View analytics, insights, and model outputs

---

📁 System Flow

Input → API → NLP Pipeline → Model → Decision Layer → Output → Dashboard

---

📝 Notes

First run may take time due to model loading Ensure internet connection for translation models (NLLB) Use small datasets initially for faster testing

---

⚠️ Design Principles

• No heuristics
• Model-first decisions
• Deterministic outputs
• Translation-aware routing
• Fully traceable pipeline

---

🔮 Future Work

• Domain-specific fine-tuning
• Advanced translation scoring
• Sarcasm detection upgrade
• CI/CD + deployment pipeline

---

📜 License

MIT License

---

Built with ❤️ by amansethhh