# Multi-Perspective Customer Feedback Analyzer

A beginner-friendly LangGraph project that demonstrates **true parallel multi-agent orchestration**.

## What it does

For every customer review, four independent AI workers run in parallel:

1. Sentiment Agent
2. Issue Analysis Agent
3. Urgency & Churn Agent
4. Routing Agent

Their strict structured JSON outputs fan-in to a deterministic aggregator, which computes a 0–100 priority score and produces a final structured analysis.

## Architecture

```text
                        ┌──> Sentiment Agent ──────┐
                        │                          │
Customer Feedback ──────┼──> Issue Agent ─────────┤
                        │                          ├──> Fan-In Aggregator
                        ├──> Urgency/Churn Agent ──┤          │
                        │                          │          ├──> Priority Score
                        └──> Routing Agent ────────┘          │
                                                            └──> Text Report
```

## Why the four agents can run in parallel

None of them depends on another worker's output. They all read the same original customer feedback and write to different state keys. LangGraph can therefore execute them concurrently before the aggregator runs.

## Priority formula

```text
Priority Score =
40% Urgency
+ 35% Churn Risk
+ 25% Sentiment Severity
```

The three inputs are normalized to 0–100 before weighting.

Priority levels:

```text
0–30   LOW
31–60  MEDIUM
61–80  HIGH
81–100 CRITICAL
```

## Dataset

`data/customer_reviews.jsonl` contains 100 synthetic customer reviews covering bugs, feature requests, billing, support, security, performance, usability, churn signals, and positive feedback.

## Setup — Windows PowerShell

```powershell
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
```

Open `.env` and add your Groq API key:

```env
GROQ_API_KEY=your_real_key_here
GROQ_MODEL=openai/gpt-oss-120b
```

## Run one review first

```powershell
python run_single.py
```

## Run all 100 reviews

```powershell
python run_batch.py
```

Structured results are saved to:

```text
outputs/analyzed_reviews.jsonl
```

## Run deterministic tests

```powershell
pytest -q
```

These tests do not call Groq. They verify the priority-score formula and level boundaries.

## Project structure

```text
multi-perspective-customer-feedback-analyzer/
├── data/
│   └── customer_reviews.jsonl
├── outputs/
├── src/
│   ├── __init__.py
│   ├── agents.py
│   ├── aggregator.py
│   ├── data_loader.py
│   ├── graph.py
│   ├── llm.py
│   ├── report.py
│   ├── schemas.py
│   └── state.py
├── tests/
│   └── test_priority.py
├── .env.example
├── requirements.txt
├── run_single.py
├── run_batch.py
└── README.md
```

## Learning goals

This project intentionally focuses on:

- multi-agent specialization
- LangGraph StateGraph
- fan-out
- parallel LLM execution
- strict structured JSON outputs
- Pydantic validation
- fan-in aggregation
- deterministic scoring
- batch processing
- text-based reporting

It intentionally does **not** add memory, RAG, MCP, databases, guardrails, caching, or a frontend. Those concepts deserve separate projects rather than being hidden inside one oversized tutorial.

---

# FastAPI Dashboard Version

## What the dashboard adds

- KPI cards for total reviews, critical reviews, negative sentiment, and average priority
- Sentiment doughnut chart
- Priority distribution chart
- Department-routing chart
- Issue-type breakdown
- Searchable/filterable review table
- Live feedback analyzer using the same 4 parallel LangGraph agents
- FastAPI JSON endpoints and automatic `/docs`

## Important: copy your existing 100-review results

If you already ran `python run_batch.py` in the original project, copy this file into this dashboard project:

```text
outputs/analyzed_reviews.jsonl
```

Or simply run the batch again in this project.

## Install

```powershell
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
```

Put your Groq API key in `.env`:

```env
GROQ_API_KEY=your_real_key_here
GROQ_MODEL=openai/gpt-oss-120b
```

## Start dashboard

```powershell
python run_dashboard.py
```

Open:

```text
http://127.0.0.1:8000
```

API docs:

```text
http://127.0.0.1:8000/docs
```

## API routes

```text
GET  /                 -> dashboard UI
GET  /api/dashboard    -> aggregated dashboard JSON
POST /api/analyze      -> live 4-agent analysis
GET  /health           -> health check
```
