NPS Analyst in a Box Promoters, passives, detractors — and a team of agents that turns 600 survey answers into a leadership brief

Start here · the problem statement

The problem, explained with 10 customers

The situation

Future with Shivank Bank asks every customer one question: "On a scale of 0 to 10, how likely are you to recommend our bank to a friend?" — and then "Why did you give this score?"

• 9–10 · Promoter happy, will recommend the bank
• 7–8 · Passive (neutral) okay, but would switch easily
• 0–6 · Detractor unhappy, likely to leave and complain

A tiny example: 10 customers in September

Getting that number takes one line of code. The hard part is the four questions the CEO will ask next:

1. How bad is it? NPS fell from +30 last month to −20 in one month.
2. Why? Read the comments: three of the five detractors (#6, #7, #8) complain about OTP or login after the app update. That's the cause.
3. How much money is at risk? The three OTP customers bring ₹26,000 a year in total. The one fee complaint (#9) brings ₹3,00,000. The loudest problem (OTP) is not the most expensive one (fees).
4. What do we do? Fix OTP first — it moves the score the most. Phone customer #9 today — that one account is worth more than the other nine put together.

With 10 customers, you can do all of this in your head.

The real problem

The bank actually has 600 customers, 536 written comments and 3 months of data. Last quarter, two analysts spent three days in Excel reading every comment, colour-coding topics, slicing scores by month, product and channel, working out the money at risk, and writing one page for the CEO. That's the job we hand to agents — one question per agent:

Python does all the counting and maths, so the numbers are always exact. The agents do what Excel can't: read comments, decide where to look next, connect complaints to money, and write it up.

Understand it

What we are building, and why a bank cares

P1The ask: four questions for Thursday

P2Just-enough NPS (three ideas, nothing more)

Every NPS survey asks one question: "How likely are you to recommend Future with Shivank Bank to a friend or colleague?" on a 0–10 scale, usually followed by "What is the main reason for your score?"

Idea 1 · Three buckets

Idea 2 · One subtraction

NPS runs from −100 (everyone is a detractor) to +100 (everyone is a promoter). It is a score, not a percentage — write "+18.5", never "18.5%". Passives add nothing to the top line, but they are in the total you divide by. Play with that below.

Idea 3 · Small groups wobble

The same NPS from 26 answers and from 600 answers are not equally trustworthy. Our tools attach a 95% margin of error to every NPS: count each answer as +1, 0 or −1, and NPS is just their average × 100. With few answers that average wobbles. For example, a segment that scores +15 from only 26 answers has a margin of error of about ±31 points: its real score could be anything from −16 to +46.

P3NPS is a money number

The CX team is judged on NPS. The CFO is judged on revenue. Our project connects the two with one line of finance — expected loss, the same idea an insurance actuary uses:

P4The architecture: a CX insights team in code

Build it

Getting started

You write the code yourself. Build it bottom-up, the same way as Section 4: data → tools → agents → orchestrator → main. The survey file is given to you.

P5Setup, folders & data

python3 -m venv .venv
source .venv/bin/activate              # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env                   # Windows: copy .env.example .env  → then paste your OPENAI_API_KEY

# NPS analyst in a box — install with:  pip install -r requirements.txt   (Python 3.11–3.13)
openai-agents>=0.4        # the OpenAI Agents SDK (Agent, Runner, function_tool, .as_tool) — brings openai + pydantic
pandas>=2.2               # every number: NPS, segments, revenue at risk
python-dotenv>=1.0        # reads OPENAI_API_KEY from .env

# Copy this file to .env (same folder) and paste your key. Never commit .env.
OPENAI_API_KEY=sk-...

# Optional
# NPS_MODEL=gpt-4o                        # any model your key can use, e.g. gpt-4.1 or gpt-5-mini
# NPS_SURVEY_PATH=data/nps_survey.csv     # or point at your own survey CSV

This is the suggested layout. Every file except data/nps_survey.csv is yours to write.

The data: data/nps_survey.csv

600 survey answers from July to September 2026 (200 a month); 536 of them have a written comment. One row is one customer's answer. The bank, the customers and their answers are fictional.

Download it: nps_survey.csv (64 KB). If it opens as text in your browser, right-click the link, choose "Save link as…" and save it as data/nps_survey.csv. Or run this from your project folder:

mkdir -p data
curl -L -o data/nps_survey.csv "https://d2beiqkhq929f0.cloudfront.net/public_assets/assets/000/248/987/original/nps_survey.csv?1792931898"
# Windows PowerShell: mkdir data; curl.exe -L -o data/nps_survey.csv "https://d2beiqkhq929f0.cloudfront.net/public_assets/assets/000/248/987/original/nps_survey.csv?1792931898"

Own it

Your project

P6Milestones, stretch goals and rubric

Stretch goals (pick two)

1. LLM theme tagger — tag each comment with an LLM that must pick from a fixed list of themes (a Literal[...] type), cache the tags to CSV, and compare the top themes with your keyword rules.
2. A guardrail that blocks bad briefs — if fact_check fails, send the brief back to the writer with the failed checks, at most twice.
3. A label-aware fact check — check each number next to its label (for example, the line that mentions 2026-08), not just anywhere in the brief.
4. Close-the-loop drafts — a new agent drafts a callback note per detractor; a human approves every note before anything is sent.
5. Your own data — any CSV with the same columns runs with --survey. Different segments? Edit SEGMENT_COLUMNS.
6. A month-on-month view — re-run on each month's slice and have the writer compare this brief with last month's.

Rubric (100 points)

Wrap-up

What to remember

1. NPS = % promoters − % detractors, on all answers. 9–10 / 7–8 / 0–6. A score from −100 to +100, not a percentage.
2. Small groups wobble. Show the margin of error; never crown a 26-answer segment.
3. Loud ≠ expensive. Rank fixes by NPS points and by rupees at risk, and show the trade-off.
4. Code computes, agents reason. Every number, verdict and alert comes from Python or a table.
5. Same skeleton as Section 4: parallel analysis → dependent planning → synthesis, with a hand-off form between phases.
6. Check the output with code. A fact check after every run turns a demo into something you can send to a CEO.