FeedbackIQ ingests raw customer reviews — pasted text, CSV, or Excel — classifies each one across seven dimensions using a large language model, and delivers a live analytics dashboard, a RAG-grounded AI action plan, automatic theme discovery, and a professional PDF report. Built for businesses that receive customer feedback and want to know exactly what to fix first.
Upload your reviews, get a complete intelligence report in under a minute.
- What It Does
- Supported Industries
- Key Features In Depth
- Architecture
- How the AI Action Plan Works
- How Review Clustering Works
- Anti-Hallucination Stack
- Tech Stack
- Running Locally
- Testing
- What Makes FeedbackIQ Different
- Roadmap
Upload your customer reviews and within a minute FeedbackIQ delivers:
- Seven-dimensional classification of every review — sentiment, primary and secondary category, aspect-level breakdown, urgency, emotion, core issue, and confidence
- Custom categories per business — you define your own feedback categories during setup, so classification is specific to your business rather than generic buckets
- A visual analytics dashboard — sentiment distribution, emotion breakdown, category volumes, an urgency heatmap, and top negative issues
- Automatic theme discovery — within each category, similar reviews are clustered into distinct recurring themes so you see what customers are actually repeating
- A RAG-grounded AI action plan — prioritised, specific recommendations drawn from a curated knowledge base of proven business solutions, each tied to your real data
- Trend analysis across multiple analyses — sentiment trajectory, category drift, and emerging versus resolved issues over time
- A professional PDF report — a downloadable multi-section report suitable for sharing with stakeholders
- Webhook alerts — get notified when critical issues spike, sentiment drops, or a new top issue emerges
FeedbackIQ's AI action plan is built and validated for five industries, each with a dedicated curated knowledge base of proven solutions:
| Industry | Coverage |
|---|---|
| E-commerce | Delivery, fulfilment, product quality, pricing, checkout, returns |
| SaaS | Onboarding, activation, churn, billing, performance, feature adoption |
| Hospitality | Check-in, cleanliness, food quality, staff service, amenities |
| Retail | Staff helpfulness, queues, stock availability, store experience, loyalty |
| Logistics | Delivery accuracy, tracking, damage prevention, driver professionalism |
Businesses outside these five can still use the full platform — classification, dashboard, clustering, and trends all work for any industry. The action plan falls back to a general business-solutions knowledge base for unsupported industries.
Every review is classified into: sentiment (positive/negative/neutral), primary category, secondary category, aspect breakdown (per-category sentiment), urgency (critical/medium/low), emotion (happy/angry/frustrated/disappointed/confused/satisfied/surprised/neutral), core issue (a one-line summary), and confidence.
A sentiment donut, an emotion breakdown, category volume bars, an urgency heatmap cross-referencing categories against urgency levels, and a ranked list of top negative issue areas — all computed from a single aggregation layer that serves as the source of truth.
Within each category, FeedbackIQ clusters semantically similar reviews into distinct recurring themes using sentence embeddings. A single "Delivery Speed" category might break into "slow delivery times," "inconsistent tracking," and "wrong item" — each with a count and a representative customer quote. Clusters are sentiment-pure and reconcile exactly to category totals.
Prioritised recommendations retrieved from a curated knowledge base and matched to each specific issue, with impact/effort/timeframe ratings and a quick win. Every recommendation cites real numbers and a proven, specific tactic.
Across multiple analyses, FeedbackIQ computes sentiment trajectory (improving/declining/stable), category drift (which issues are growing or shrinking), and emerging versus resolved issues.
A multi-section WeasyPrint report — cover, executive summary, analytics charts, urgency analysis, action plan, and full data appendix — generated in memory and downloaded instantly.
Register a webhook URL and receive signed notifications when critical issues spike above threshold, sentiment drops significantly, or a new top issue emerges. Payloads are HMAC-SHA256 signed and delivered asynchronously with retry.
FeedbackIQ is a Python backend with a React frontend, designed so the core engine is fully decoupled from any interface.
feedbackiq/
├── core/ # Pure Python business logic (no web framework)
│ ├── preprocessing.py # 11-stage text cleaning pipeline
│ ├── classifier.py # Groq + Gemini classification engine
│ ├── classifier_async.py # Concurrent classification with semaphore
│ ├── prompt_builder.py # Dynamic classification prompt assembly
│ ├── validator.py # Pydantic output validation
│ ├── aggregator.py # Single source of truth for all metrics
│ ├── action_plan.py # RAG-grounded action plan generation
│ ├── clustering_engine.py # Within-category theme clustering
│ ├── trend_engine.py # Cross-session trend analysis
│ ├── webhook_engine.py # Alert detection and webhook delivery
│ ├── charts.py # Plotly chart builders (no Streamlit imports)
│ ├── pdf_report.py # WeasyPrint + Jinja2 PDF generation
│ ├── results.py # Results DataFrame assembly
│ └── rag/ # Retrieval-augmented generation pipeline
│ ├── embedder.py # sentence-transformers embeddings
│ ├── knowledge_base.py # ChromaDB vector store + retrieval
│ └── documents/ # Curated industry solution knowledge base
│
├── api/ # FastAPI layer
│ ├── main.py # App factory, middleware, lifespan
│ ├── models.py # Request/response schemas
│ ├── auth/ # JWT auth, password hashing, dependencies
│ ├── storage/ # Disk-based user and session stores
│ ├── routes/ # auth, sessions, analyse, dashboard,
│ │ # action-plan, clusters, report, export,
│ │ # trends, webhooks
│ └── middleware/ # Rate limiting, error handlers
│
├── frontend/ # React + TypeScript + Tailwind
├── templates/ # Jinja2 PDF templates
├── config.py # Configuration constants
└── test_pipeline.py # 26-section test suite
aggregator.pyis the single source of truth. Every chart, the action plan, the clustering totals, and the PDF read from one aggregated dictionary. Nothing recomputes metrics independently, so no two parts of the system can ever disagree.core/has zero web-framework dependencies. The business logic is importable in pure Python, fully testable without a server, and was migrated from Streamlit to FastAPI without a single change to the classification engine.- Clustering is a refinement layer, never a foundation. Themes are discovered within deterministic category counts and always reconcile to them — clustering explains the numbers rather than competing with them, preserving the system's reliability.
- Storage is abstracted behind an interface. Development uses disk-based JSON; swapping to PostgreSQL or Redis for production requires changing only the storage layer, not routes or logic.
- Two-provider LLM with automatic fallback. Groq is primary; Gemini takes over automatically on rate-limit errors, with exponential backoff.
The action plan is the platform's most distinctive feature and the hardest to replicate with a raw LLM call.
-
Zero raw review text reaches the action-plan LLM call. It receives only computed statistics from
aggregator.py— counts, percentages, top issues, emotion distribution. This is the primary anti-hallucination control: the model cannot misattribute or confabulate because it is given grounded facts, not thousands of reviews to interpret. -
Per-issue RAG retrieval. For each top issue, FeedbackIQ embeds the actual customer complaint text and retrieves the most relevant proven solutions from a curated ChromaDB knowledge base, filtered by industry and a relevance threshold. A delivery complaint retrieves delivery solutions; a pricing complaint retrieves pricing solutions — no cross-contamination.
-
Grounded generation. The retrieved solutions are injected into the prompt, matched to their specific issue category. The model is instructed to cite the proven approaches and the real numbers, and is explicitly forbidden from generic business language.
-
Self-verification. Before the plan reaches the user, a Python verification pass confirms each recommendation cites real numbers, references the actual issue categories, and avoids generic filler. Failures trigger a regeneration within the existing retry budget.
The result is recommendations like "5 negative reviews cite inconsistent tracking — implement automated SMS updates at each shipping stage using your courier's API; target zero where-is-my-order complaints within 30 days" rather than "improve your delivery processes."
Categories tell you which areas get the most feedback. Clustering tells you what specific things customers are repeating within those areas.
-
Partition by category, then by sentiment. Reviews are grouped by their classified category, then split by sentiment. Clustering runs within each sentiment group, guaranteeing every resulting theme is sentiment-pure by construction — a positive and a negative review about the same topic never land in the same cluster.
-
Embed and cluster. Each review is embedded with the same sentence-transformers model used by the RAG pipeline. Agglomerative clustering with a cosine-distance threshold groups semantically similar reviews — reviews that mean the same thing even in different words.
-
Representative quote per theme. For each cluster, the review closest to the cluster centroid becomes the representative quote shown to the user.
-
Guarantees. Cluster counts plus unique-review counts always reconcile exactly to the category total. Critical-urgency reviews are never dropped. Below 15 total reviews the feature is hidden, since clustering needs sufficient data to be meaningful.
This compresses hundreds of reviews into the handful of distinct themes that actually matter — answering the real question behind all feedback analysis: what are customers repeatedly telling me?
Classification reliability comes from five active layers on every call:
- Temperature 0.0 — classification is deterministic, not creative
- Controlled vocabulary — every allowed value for every field is listed explicitly in the prompt
- Five few-shot examples covering edge cases (strong negative, strong positive, mixed, very short, non-English)
- Pre-validation normalisation — labels lowercased and stripped before validation
- Pydantic validation with retry — invalid output triggers a correction-prefixed retry; categories outside the allowed list are fixed rather than failing
| Layer | Technology |
|---|---|
| Backend | Python, FastAPI, Pydantic, Pandas |
| LLMs | Groq (Llama 3.1) primary, Google Gemini fallback |
| RAG & Clustering | sentence-transformers (all-MiniLM-L6-v2), ChromaDB, scikit-learn |
| WeasyPrint + Jinja2 | |
| Auth | JWT (python-jose), Argon2 password hashing (pwdlib) |
| Frontend | React, TypeScript, Tailwind CSS, Recharts |
| Storage | Disk-based JSON (PostgreSQL-ready via interface) |
All components run free of charge — local embeddings and clustering, free LLM tiers, no paid infrastructure.
- Python 3.11+
- Node.js 18+
- Free API keys from Groq and Google AI Studio
git clone https://github.com/JhanviBarot/FeedBackIQ.git
cd feedbackiq
python -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
pip install -r requirements.txtCreate a .env file in the project root:
GROQ_API_KEY=your_groq_key
GEMINI_API_KEY=your_gemini_key
JWT_SECRET_KEY=generate_with_python_-c_"import secrets; print(secrets.token_hex(32))"
Run the test suite (zero API cost):
python test_pipeline.pyStart the API:
uvicorn api.main:app --reload --port 8000Interactive API docs are available at http://localhost:8000/docs.
cd frontend
npm install
npm run devThe app runs at http://localhost:5173.
The project includes a comprehensive test suite covering the full pipeline — preprocessing, classification logic, aggregation, file parsing, PDF generation, authentication, all API endpoints, trend analysis, webhooks, the RAG pipeline, and review clustering. Every section runs with zero API cost using mocked LLM responses.
python test_pipeline.pyKey invariants protected by the suite include: cluster counts always reconciling to category totals, critical reviews never being dropped, sentiment-pure clustering, RAG relevance filtering, action-plan grounding, and session ownership enforcement.
A raw LLM call can classify a handful of reviews. FeedbackIQ does four things a single LLM call cannot:
-
Consistent structured classification at scale — thousands of reviews classified into your custom categories with zero hallucination, via controlled vocabulary and a Pydantic validation-and-retry pipeline that a raw prompt cannot guarantee.
-
Automatic theme discovery — sentence embeddings and clustering surface the recurring themes within your categories, compressing hundreds of reviews into the distinct issues that actually matter.
-
Longitudinal intelligence — it tracks your feedback across analyses and tells you whether your fixes are working: sentiment trajectory, emerging issues, resolved issues. A stateless LLM call has no memory and cannot do this.
-
RAG-grounded recommendations — action-plan advice is retrieved from a curated knowledge base of proven, quantified business solutions and matched to each specific issue, rather than generated from the model's general priors.
- Predictive alerts — detect early-warning signals (rising frustration, medium-urgency growth) before they become critical
- LLM-generated theme labels — short descriptive labels for each discovered cluster
- Expanded industry coverage for the action-plan knowledge base
- PostgreSQL storage backend for production scale
- Live deployment on free-tier cloud hosting
FeedbackIQ — upload your reviews, get a complete intelligence report in under a minute.