SentimentAI — Final Year Project

A production-ready, deployable sentiment analysis system with ML backend, REST API, and React frontend.

---

📋 Project Overview

SentimentAI is a full-stack sentiment analysis application that classifies text as Positive, Negative, or Neutral and additionally detects 8 emotions (joy, anger, sadness, fear, surprise, disgust, trust, anticipation) with confidence scores and keyword extraction.

Tech Stack

Layer	Technology
Backend API	FastAPI (Python)
ML Model	Hybrid Lexicon + Rule Engine
Frontend	React 18 + Recharts
Containerization	Docker + Docker Compose
CI/CD	GitHub Actions
Deployment	Render.com / Fly.io / Railway

---

🏗️ Project Structure

sentiment-analyzer/
├── backend/
│   ├── main.py              # FastAPI application & routes
│   └── requirements.txt
├── model/
│   └── predictor.py         # ML prediction engine
├── frontend/
│   ├── src/
│   │   ├── App.jsx           # Router & layout
│   │   ├── pages/
│   │   │   ├── Analyze.jsx   # Single text analysis
│   │   │   ├── BatchAnalyze.jsx  # Bulk analysis
│   │   │   └── Dashboard.jsx # Charts & metrics
│   │   ├── components/
│   │   │   ├── ResultCard.jsx
│   │   │   └── HistoryPanel.jsx
│   │   └── utils/api.js      # API client
│   ├── Dockerfile
│   └── package.json
├── tests/
│   └── test_api.py           # 17 unit + integration tests
├── .github/workflows/ci.yml  # GitHub Actions
├── Dockerfile                # Backend Docker image
├── docker-compose.yml        # Full stack orchestration
├── render.yaml               # Render.com deployment
└── fly.toml                  # Fly.io deployment

---

🚀 Quick Start

Option A — Run locally (Python)

# Clone & install backend
git clone https://github.com/yourname/sentiment-analyzer
cd sentiment-analyzer
pip install -r backend/requirements.txt

# Start backend
uvicorn backend.main:app --reload --port 8000

# In a new terminal — start frontend
cd frontend
npm install --legacy-peer-deps
npm start

Open http://localhost:3000

Option B — Docker Compose (recommended)

docker-compose up --build

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/api/docs

---

🔌 API Reference

POST /api/analyze

Analyze a single text.

Request:

{
  "text": "I absolutely love this product!",
  "include_details": true
}

Response:

{
  "text": "I absolutely love this product!",
  "sentiment": "Positive",
  "confidence": 0.912,
  "scores": { "positive": 0.87, "negative": 0.06, "neutral": 0.07 },
  "emotions": { "joy": 1.0, "anticipation": 0.5 },
  "keywords": ["love"],
  "processing_time_ms": 2.1,
  "timestamp": "2024-01-15T10:30:00"
}

POST /api/analyze/batch

Analyze up to 50 texts at once.

Request:

{ "texts": ["I love this!", "This is terrible.", "Okay I guess."] }

GET /health

Service health check.

GET /api/stats

Usage statistics.

---

🧠 Model Architecture

The prediction engine uses a hybrid approach:

1. Tokenization — lowercasing, punctuation normalization
2. Lexicon scoring — 100+ positive/negative words with sentiment weights
3. Negation handling — detects NOT/NEVER patterns and inverts scores
4. Intensifier amplification — "very", "extremely" etc. boost scores by 1.2–1.5×
5. Sigmoid normalization — maps raw scores to [0,1] probability distributions
6. Emotion detection — matches against 8 emotion lexicons
7. Keyword extraction — identifies top sentiment-bearing terms

Upgrade path: Replace predictor.py's predict() with HuggingFace cardiffnlp/twitter-roberta-base-sentiment for state-of-the-art accuracy with zero API changes.

---

🧪 Testing

# Run full test suite (17 tests)
pytest tests/ -v

# With coverage
pytest tests/ --cov=backend --cov=model --cov-report=html

Test categories:

• TestPredictor — 8 model unit tests (positive/negative/neutral/negation/intensifier)
• TestAPI — 9 integration tests (all endpoints, validation, batch)

---

☁️ Deployment

Deploy to Render.com (FREE)

1. Push to GitHub
2. Go to render.com → New → Blueprint
3. Connect your repo — Render will auto-detect render.yaml
4. Set REACT_APP_API_URL in frontend env to your backend URL

Deploy to Fly.io

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Deploy backend
fly launch
fly deploy

# Set env
fly secrets set ENV=production

Deploy to Railway

# Install Railway CLI
npm install -g @railway/cli

railway login
railway new
railway up

---

📊 Features

• ✅ Single text sentiment analysis with confidence scores
• ✅ Batch analysis (up to 50 texts) with CSV export
• ✅ 8-category emotion detection
• ✅ Sentiment keyword extraction
• ✅ Real-time dashboard with charts (Recharts)
• ✅ Request history panel
• ✅ Interactive API docs (Swagger UI at /api/docs)
• ✅ 17 automated tests (unit + integration)
• ✅ Docker + Docker Compose support
• ✅ GitHub Actions CI/CD pipeline
• ✅ One-click deploy configs for Render, Fly.io, Railway
• ✅ Sub-5ms response times
• ✅ CORS-enabled for any frontend origin

---

📚 Report Talking Points

Problem Statement

Sentiment analysis is critical for businesses to understand customer feedback at scale. Manual analysis of thousands of reviews or social posts is infeasible.

Methodology

Hybrid lexicon-based approach chosen for: zero training data requirement, interpretable decisions, sub-millisecond inference, and free deployment. Rule-based negation and intensifier handling addresses key weaknesses of pure bag-of-words models.

Results

• 17/17 automated tests passing
• Correct classification of positive, negative, and neutral examples
• Proper negation inversion ("not good" → Negative)
• Emotion detection across 8 Plutchik-model categories

Future Work

• Replace lexicon engine with fine-tuned RoBERTa transformer
• Add user authentication + persistent history
• Multilingual support
• Browser extension for real-time page analysis

---

🎓 Academic References

1. Taboada, M. et al. (2011). Lexicon-based methods for sentiment analysis. Computational Linguistics.
2. Plutchik, R. (1980). A general psychoevolutionary theory of emotion. Academic Press.
3. Hutto, C. & Gilbert, E. (2014). VADER: A parsimonious rule-based model for sentiment analysis. ICWSM.
4. Liu, B. (2012). Sentiment analysis and opinion mining. Synthesis Lectures on HLT.