# 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.
