SAT Prep WhatsApp Agent

AceSAT Education AI-Agent hackathon submission

Problem

Good SAT prep tools assume a laptop, a stable internet connection, and often a subscription fee — all of which shut out students who most need help closing the score gap. WhatsApp already runs on basically every phone, including on weak 2G/3G connections, with no app download. This agent puts a real AI tutor inside that existing channel.

How it works

1. A student texts the Twilio WhatsApp sandbox number to start.
2. The bot sends one SAT question at a time (math or reading/writing), plain text only — nothing that breaks on basic phones.
3. If the student answers wrong, the bot asks one quick follow-up ("How did you get that?") and uses Gemini 2.5 Flash to classify the mistake as a concept gap, careless error, misread, or time pressure issue based on the student's own explanation.
4. Concept-gap mistakes get a short, grounded explanation pulled via RAG (MongoDB Atlas Vector Search) from a hand-written knowledge base note for that exact skill — so the explanation never drifts from verified content. The other three mistake types get a direct, lighter-weight response (no retrieval needed).
5. Every attempt is logged against the student's profile, tagged by skill area. A weekly check-in (manual trigger for the demo; a cron job in production) messages the student's weakest 1-2 skill areas.
6. If a student is stuck on the same skill 4+ attempts running, they're flagged for mentor follow-up — visible on a small admin dashboard.

Questions themselves are always pulled from a static, hand-verified 24-question bank (data/questions.json) — never generated live — so there's zero risk of the model inventing a question with a wrong answer key. RAG is used only to ground explanations.

Stack

• Next.js (App Router) — API routes + admin dashboard
• MongoDB (+ Atlas Vector Search) — students, questions, attempts, and the embedded RAG note store
• Twilio WhatsApp Sandbox — the entire messaging interface
• Google Gemini 2.5 Flash — mistake classification, grounded explanations, weekly summaries
• Voyage AI or OpenAI embeddings — for the RAG knowledge base only

Setup

npm install
cp .env.example .env   # fill in MongoDB URI, Twilio, Gemini, and an embeddings key

1. MongoDB Atlas: create a free cluster, get the connection string into MONGODB_URI.
2. Seed the question bank: npm run seed:questions
3. Embed the RAG notes: npm run seed:notes (requires VOYAGE_API_KEY or OPENAI_API_KEY)
4. Create the Atlas Vector Search index on the notes collection, field embedding, matching your embedding provider's dimension (voyage-3-lite = 512, text-embedding-3-small = 1536). Name it to match VECTOR_INDEX_NAME in .env.
5. Twilio WhatsApp Sandbox: join your sandbox, point its webhook at https://<your-ngrok-or-vercel-url>/api/whatsapp.
6. Run it: npm run dev, then (for local testing) ngrok http 3000 and update the Twilio webhook URL.
7. Seed a demo student for the admin dashboard/video: node scripts/seed-demo-student.js
8. Admin dashboard: visit /admin.
9. Trigger a weekly check-in manually: POST /api/checkin?phone=whatsapp:+1XXXXXXXXXX

Browser demo (WhatsApp-style, same backend)

If you're short on time to get the live Twilio sandbox fully wired for the video, /demo is a WhatsApp-styled chat UI in the browser that calls the exact same handleIncomingMessage() function the real Twilio webhook uses (app/api/demo-chat/route.js → lib/conversation.js). Question flow, mistake classification, and RAG retrieval are identical — only the transport differs (JSON over HTTP instead of Twilio's webhook).

To use it: finish steps 1-4 in Setup above (Mongo + question seed are required; notes/vector index recommended), then npm run dev and open http://localhost:3000/demo. No Twilio, ngrok, or ngrok-side webhook config needed for this path.

Be explicit about this in your demo video and Devpost submission. The real WhatsApp integration (Twilio webhook, sandbox-ready) is fully built and included in this repo — say so. Also say plainly that the video itself was recorded against the /demo browser prototype rather than a live WhatsApp thread, for demo-day reliability. Something like:

"This agent is built to run over real WhatsApp via Twilio — the webhook integration is in the repo at app/api/whatsapp. For this demo video, we're showing it through a browser prototype styled after WhatsApp, hitting the identical backend logic, so the walkthrough isn't dependent on a live sandbox connection during recording."

No login beyond phone number, no payments, no gamification, no native app, no fancy UI — WhatsApp is the entire product surface, and the admin page is just enough to demo the mentor-flag logic.

Notes on this scaffold

This repo was scaffolded end-to-end (data model, conversation state machine, Twilio webhook, mistake classification, RAG retrieval, weak-tag computation, mentor flagging, admin dashboard, seed scripts) but has not been run against live Twilio/MongoDB Atlas/embedding credentials — wire in real keys and test the full loop before recording the demo video.