README.md

metadata

title: Bert Sentiment Api
emoji: 🔗
colorFrom: green
colorTo: green
sdk: docker
pinned: false
license: mit
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/67d7a90493e0004ce35798ed/YVex6OlxZf5nD8lb6Pd3M.png
short_description: High-accuracy Sentiment Analysis API using a fine-tuned BERT

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Sentiment Analyzer 🧠

A premium, interactive web application for real-time sentiment analysis. This project leverages a fine-tuned BERT model to classify text as Positive or Negative with high accuracy, wrapped in a modern, aesthetically pleasing React frontend.

---

📘 Beginner's Corner: What is this?

If you are new to Machine Learning, welcome! 👋

What is Sentiment Analysis? Imagine you have a super-smart assistant who reads a sentence and instantly tells you if the person is happy, angry, or disappointed. That is Sentiment Analysis. It's widely used by companies to understand customer feedback, monitor social media, and improve products.

How does it work? We don't just look for keywords like "good" or "bad". We use a sophisticated AI model called BERT that understands the context of a sentence. For example, it knows that "not bad" is actually positive, even though it contains the word "bad".

---

🧠 Deep Dive: The BERT Architecture

This project is built on BERT (Bidirectional Encoder Representations from Transformers), a revolutionary model developed by Google.

1. The Transformer "Engine"

At its core, BERT uses a Transformer architecture. Unlike older models that read text from left to right (like humans do), Transformers read the entire sentence at once. This allows the model to understand the relationship between every word simultaneously.

2. Bidirectional Context

The "B" in BERT stands for Bidirectional.

• Unidirectional models read: "The quick brown..." (can't see what's coming next).
• BERT reads: "...quick brown fox..." (sees both "quick" and "fox" to understand "brown"). This allows BERT to understand nuance. For example, it can distinguish between a "river bank" and a "bank account" based on the surrounding words.

3. Fine-Tuning

We didn't build BERT from scratch (that takes supercomputers!). We used a technique called Transfer Learning:

1. Pre-training: Google trained BERT on massive amounts of text (Wikipedia, Books) to teach it the English language.
2. Fine-tuning: We took this "smart" model and gave it a specific job: "Read these reviews and tell me if they are positive or negative." This is what makes our model specialized for Sentiment Analysis.

---

🔭 Project Scope

Current Capabilities

• Real-time Analysis: Instant feedback as you type or submit text.
• Binary Classification: accurately identifies Positive vs Negative sentiment.
• Confidence Scoring: Tells you how sure the model is about its prediction (e.g., "99.8% confident").
• Interactive UI: A high-end user interface that demonstrates how AI can be presented beautifully.

Future Roadmap

• Batch Processing: Upload a CSV file of thousands of reviews for bulk analysis.
• Multi-Class Sentiment: Detecting Neutral, Angry, Sad, or Sarcastic tones.
• History Tracking: Saving past analyses to a database.
• API Integration: Allowing other developers to use this backend as a service.

---

✨ Features

🚀 Advanced NLP Backend

• BERT Model: Utilizes BertForSequenceClassification fine-tuned for sentiment analysis.
• High Performance: Optimized for fast inference on local machines (supports MPS/CPU).
• Flask API: Robust REST API handling prediction requests.
• CORS Enabled: Configured to securely handle cross-origin requests from the frontend.

🎨 Premium Frontend Experience

• Interactive DotGrid Background: A physics-based background where dots react to mouse movements and clicks with inertia and shockwave effects (powered by GSAP).
• Variable Proximity Heading: The main title dynamically adjusts its font weight and size based on how close your mouse cursor is (powered by Framer Motion).
• ShinyText Effect: A subtle, premium shimmer animation on the subtitle.
• Glassmorphism Design: Modern, frosted-glass UI elements with smooth hover effects and transitions.
• Dynamic Feedback: Visual cues for positive (Green) and negative (Red) results, including a confidence confidence bar.

---

🛠️ Tech Stack

Backend

• Python 3.x: The programming language for the AI logic.
• Flask: A lightweight web framework to create the API.
• PyTorch: The deep learning library running the BERT model.
• Transformers: Hugging Face's library to easily load and use BERT.

Frontend

• React 18: The library for building the user interface.
• Vite: A super-fast tool for building and running the frontend.
• GSAP & Framer Motion: Libraries for complex, high-performance animations.
• CSS3: Custom styling for the glassmorphism and layout.

---

📦 Installation Guide (Local)

Prerequisites

You need these installed on your computer:

• Python 3.8+: To run the backend.
• Node.js 16+: To run the frontend.

1. Backend Setup (The Brain)

This sets up the server that runs the AI model.

1. Navigate to the backend folder:

   cd backend
   

2. Install the necessary "tools" (libraries) for Python:

   pip install -r requirements.txt
   

   This installs Flask, PyTorch, and Transformers.

2. Frontend Setup (The Face)

This sets up the website you interact with.

1. Open a new terminal and navigate to the frontend folder:

   cd frontend
   

2. Install the necessary "tools" (packages) for the website:

   npm install
   

   This downloads React, GSAP, and other interface libraries.

3. Running Locally

1. Start Backend:

   # In backend folder
   python app.py
   

2. Start Frontend:

   # In frontend folder
   npm run dev
   

3. Open the link shown (e.g., http://localhost:5173).

---

☁️ Deployment Guide (Step-by-Step)

This project uses a Split Deployment strategy.

• Why? The BERT model is large (hundreds of MBs). Free frontend hosting (like Vercel) cannot handle this size.
• Solution: We host the "Brain" (Model) on Hugging Face Spaces (which offers free CPU hosting for models) and the "Face" (Frontend) on Vercel (which is optimized for React).

Part 1: Deploying the Backend (Hugging Face Spaces)

1. Create an Account: Go to huggingface.co and sign up.
2. Create a Space:
   • Click on your profile picture -> New Space.
   • Space Name: bert-sentiment-api (or similar).
   • License: MIT.
   • SDK: Select Docker.
   • Docker Template: Select Blank.
   • Space Hardware: Keep it as CPU Basic (Free).
   • Click Create Space.
3. Upload Files:
   • Go to the Files tab of your new Space.
   • Click Add file -> Upload files.
   • Drag and drop the following files from your local hf_space folder:
     • app.py
     • requirements.txt
     • Dockerfile
   • CRITICAL: Drag and drop ALL FILES from your local saved_bert_sentiment_model folder into the root.
     • Do not upload the folder itself, upload the files INSIDE it.
     • You should see config.json, pytorch_model.bin, etc., listed right next to app.py.
   • Click Commit changes to main.
4. Wait for Build:
   • The Space will show "Building". This might take 2-5 minutes.
   • When it says Running, your API is ready!
5. Get the API URL:
   • Click the three dots (⋮) in the top right -> Embed this space.
   • Copy the Direct URL. It looks like: https://username-space.hf.space.

Part 2: Deploying the Frontend (Vercel)

1. Push to GitHub:
   • Ensure your project is pushed to a GitHub repository.
2. Import to Vercel:
   • Go to vercel.com and log in.
   • Click Add New... -> Project.
   • Select your GitHub repository.
3. Configure Project:
   • Framework Preset: Select Vite.
   • Root Directory: Click Edit and select frontend.
4. Environment Variables:
   • Expand the Environment Variables section.
   • Key: VITE_API_URL
   • Value: Paste the Direct URL from Hugging Face (Part 1, Step 5).
     • Example: https://ganesharihanth-bert-sentiment-api.hf.space
     • Note: Remove any trailing slash / at the end.
5. Deploy:
   • Click Deploy.
   • Wait for the confetti! 🎉

Part 3: Verification

• Open your Vercel app URL.
• Type "I am so happy this works!" and click Analyze.
• If you see "Positive" and a confidence score, everything is connected!

---

📡 API Documentation

For developers who want to use the backend programmatically.

POST /predict

Analyzes the sentiment of the provided text.

Request Body:

{
  "text": "I love this product!"
}

Response:

{
  "sentiment": "Positive",
  "confidence": 0.998,
  "label": 1
}

---

📂 Project Structure

Sentiment analysis/
├── backend/                   # Local Flask API
│   ├── app.py
│   └── requirements.txt
├── frontend/                  # React Frontend
│   ├── src/
│   │   ├── App.jsx            # Main Logic
│   │   └── ...
│   └── package.json
├── hf_space/                  # Deployment files for Hugging Face
│   ├── app.py
│   ├── requirements.txt
│   └── Dockerfile
├── saved_bert_sentiment_model/  # The "Brain" (Model files)
└── README.md                  # You are reading this!

🤝 Contributing

Contributions are welcome! If you have ideas to make the UI cooler or the model smarter, feel free to fork the repo and submit a Pull Request.

📝 License

This project is open source and available under the MIT License.