Customer Feedback Analyzer

A two-part application that turns raw customer reviews into structured, actionable insights using Google's Gemini API. Paste in a batch of reviews and instantly get sentiment, score, topic, and improvement suggestions for each one, plus an aggregate summary and theme breakdown.

Overview

Businesses accumulate customer feedback faster than anyone has time to read it. This project automates that first pass: it classifies each review's sentiment, scores it, tags the underlying theme (delivery, taste, price, service, etc.), and — for negative reviews — proposes a concrete fix. Results are visualized in a dashboard and persisted to a local database for historical tracking.

The application is split into two independently runnable services:

• Backend API (api.py) — a FastAPI service that accepts a single review and returns a structured analysis, powered by Gemini's structured output mode.
• Frontend dashboard (app.py) — a Streamlit app that lets a user paste multiple reviews, batches calls to the backend, renders a results table and summary charts, and saves reports to SQLite.

Screenshots

Input	Results

Theme breakdown	Saved history

Features

• Sentiment classification (positive / negative / neutral) with a 1–5 score
• Automatic topic/theme tagging per review
• Actionable, one-line improvement suggestions for negative reviews
• Aggregate summary: total reviews, average score, percent positive
• Pie chart breakdown of reviews by theme
• Persistent history via a local SQLite database, with filtering by sentiment
• Clean separation between API, UI, and data-access layers

Tech Stack

Layer	Technology
Backend API	FastAPI
Frontend	Streamlit
LLM	Gemini API (google-genai)
Data validation	Pydantic
Storage	SQLite
Charts	Matplotlib

Project Structure

customer_feedback_analyzer/
├── api.py                  # FastAPI backend: /analyze endpoint
├── app.py                  # Streamlit frontend dashboard
├── database.py              # SQLite persistence layer
├── docs/
│   └── screenshots/          # README screenshots
├── sample_reviews.txt        # Example reviews for quick testing
├── sample.env               # Template for environment variables
├── requirements.txt          # Pip dependencies
├── pyproject.toml            # Project metadata / dependencies (uv-compatible)
├── .python-version           # Pinned Python version
└── LICENSE                   # MIT license

Prerequisites

• Python 3.12+
• A Google Gemini API key

Installation

1. Clone the repository

   git clone https://github.com/atanus1502/customer_feedback_analyzer.git
   cd customer_feedback_analyzer

2. Create a virtual environment and install dependencies

   python3 -m venv .venv
   source .venv/bin/activate   # on Windows: .venv\Scripts\activate
   pip install -r requirements.txt

3. Configure environment variables

   Copy sample.env to .env and add your Gemini API key:

   cp sample.env .env

   GOOGLE_API_KEY=your_key_here
   

Usage

The backend and frontend run as separate processes. Start each in its own terminal, with the virtual environment activated in both.

Terminal 1 — start the API:

fastapi dev api.py

The API will be available at http://127.0.0.1:8000, with interactive docs at http://127.0.0.1:8000/docs.

Terminal 2 — start the dashboard:

streamlit run app.py

Streamlit will open the app in your browser (default: http://localhost:8501).

From the dashboard:

1. Paste customer reviews into the text box (one per line), or click Load sample reviews to use sample_reviews.txt.
2. Click Analyze.
3. Review the results table, summary metrics, and theme pie chart.
4. Click Save to database to persist the results, or expand Saved history to browse everything analyzed so far.

API Reference

POST /analyze

Analyzes a single review and returns a structured result.

Request body:

{ "text": "The food was great but delivery took over an hour." }

Response:

{
  "label": "negative",
  "score": 2,
  "theme": "delivery",
  "suggestion": "Improve delivery times so food arrives fresh and on schedule."
}

Field	Type	Description
label	string	"positive", "negative", or "neutral"
score	int	Sentiment score from 1 (very bad) to 5 (very good)
theme	string	Single-word topic the review is mainly about
suggestion	string	One-line fix, populated only when label is "negative"

System Prompt

Each request to /analyze sends the review text to Gemini (gemini-flash-lite-latest) along with the following instructions, using structured output mode to guarantee a response matching the Analysis schema:

Analyze this customer review.
label must be 'positive', 'negative', or 'neutral'.
score must be a number from 1 (very bad) to 5 (very good).
theme must be ONE lowercase word for the main topic (for example: delivery, taste, price, service, quality).
suggestion: only if label is 'negative', write ONE short line suggesting how the business could fix this specific complaint. If label is not 'negative', suggestion must be an empty string.
Review: {review_text}

Data Storage

Analyzed reviews are stored in a local SQLite database (feedback.db, created automatically on first run) with the schema:

Column	Type
id	INTEGER PRIMARY KEY
review	TEXT
label	TEXT
score	INTEGER
theme	TEXT
suggestion	TEXT

Troubleshooting

• Rows show "error" in the dashboard — the backend isn't running or isn't reachable at http://127.0.0.1:8000. Start it with fastapi dev api.py first.
• Authentication errors from Gemini — confirm GOOGLE_API_KEY is set correctly in .env and that the key is active.

License

Licensed under the MIT License.