🧠 Sentiment Analysis API with BERT

A production-ready sentiment analysis system using a fine-tuned BERT model, served via a FastAPI REST endpoint. Classifies text into positive, negative, or neutral sentiment with confidence scores.

---

📌 Features

• Fine-tuned bert-base-uncased on SST-2 and Yelp review datasets
• 3-class sentiment classification (positive / neutral / negative)
• REST API with single and batch prediction endpoints
• Confidence scores and per-class probability breakdown
• Auto-documentation via Swagger UI at /docs
• Full evaluation pipeline with confusion matrix and ROC-AUC

---

🗂️ Project Structure

sentiment-bert/
├── src/
│   ├── train.py          # Fine-tuning script
│   ├── api.py            # FastAPI inference server
│   ├── preprocess.py     # Data loading & cleaning
│   └── evaluate.py       # Model evaluation & metrics
├── data/                 # Training/test CSVs (generated)
├── models/               # Saved model weights
├── notebooks/            # Exploratory analysis
├── tests/
│   └── test_sentiment.py # Unit & integration tests
├── results/              # Evaluation outputs
└── requirements.txt

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Prepare Data

python src/preprocess.py
# Creates data/train.csv with ~3000 labeled samples

3. Fine-tune BERT

python src/train.py
# Trains for 3 epochs, saves best model to models/bert_sentiment/

4. Start the API

uvicorn src.api:app --host 0.0.0.0 --port 8000 --reload
# Swagger docs available at http://localhost:8000/docs

---

📡 API Usage

Single Prediction

curl -X POST "http://localhost:8000/predict" \
     -H "Content-Type: application/json" \
     -d '{"text": "This product is absolutely amazing!"}'

Response:

{
  "text": "This product is absolutely amazing!",
  "sentiment": "positive",
  "confidence": 0.9741,
  "scores": {
    "negative": 0.0089,
    "neutral": 0.0170,
    "positive": 0.9741
  },
  "inference_time_ms": 43.2
}

Batch Prediction

curl -X POST "http://localhost:8000/predict/batch" \
     -H "Content-Type: application/json" \
     -d '{"texts": ["Great product!", "Terrible service.", "It was okay."]}'

---

📊 Model Performance

Metric	Score
Accuracy	~91.3%
F1 (weighted)	~91.1%
ROC-AUC	~97.2%

Results on held-out test set after 3 epochs of fine-tuning.

---

🧪 Run Tests

pytest tests/ -v

---

📈 Evaluate Saved Model

python src/evaluate.py --data data/test.csv --output_dir results/
# Generates results/confusion_matrix.png and results/eval_report.txt

---

🛠️ Tech Stack

Tool	Purpose
HuggingFace Transformers	BERT model & tokenizer
PyTorch	Deep learning framework
FastAPI	REST API server
scikit-learn	Metrics & evaluation
Datasets	HuggingFace dataset loading

---

📚 References

• BERT: Pre-training of Deep Bidirectional Transformers
• HuggingFace Transformers Documentation
• FastAPI Documentation

---

📄 License

MIT License — free to use and modify.