AI Learning Platform
A working prototype with two learning modules behind one entry point:
| Module | For | What it does |
|---|
Textbook AI Tutor (/tutor) | Teachers, tutors, Classes 1–10 (demo: Class 1 English) | Upload a textbook PDF (or use the built-in demo reader), choose question types / count / difficulty / scope, generate source-grounded questions, review and edit them with page citations, run the quiz, and score it. |
Early Learning Studio (/early) | LKG–UKG children with an adult nearby | English A–Z and a curated Hindi set. Hear each letter and its picture words, then trace it with finger, stylus or mouse and get gentle spoken feedback. |
No accounts. Works fully without an API key in a clearly labelled demo mode; add a key to switch question
writing and open-answer grading to a live model.
The earlier static design mockup is preserved unchanged in ../opendesign/. This app replaces it with a real
implementation and reuses its design direction, letter data and demo passages.
Quick start
Requirements: Node.js ≥ 20.9 (tested on 24), npm.
npm install
npm run dev # http://localhost:3000
That's it — demo mode works immediately. To enable live AI mode:
cp .env.example .env.local
# then set ONE of these in .env.local:
# LLM_API_KEY=AIza... (Google Gemini — also enables embeddings)
# LLM_API_KEY=gsk_... (Groq)
# LLM_API_KEY=sk-or-... (OpenRouter)
npm run dev
The provider is detected from the key prefix (or set LLM_PROVIDER). The header badge shows Demo mode or
Live · model-name; GET /api/status reports the same in JSON.
Scripts
| Command | What it does |
|---|
npm run dev / build / start | Next.js dev server / production build / production server |
npm run lint · npm run typecheck | ESLint · TypeScript |
npm test | Vitest unit + API tests (73) — PDF extraction, chunking, retrieval, grounding validation, scoring, tracing geometry, lesson data, route handlers, live-mode adapter with a mocked provider |
npm run test:e2e | Playwright end-to-end tests (18, desktop + phone) against a production build in forced demo mode. Uses the installed Chrome (channel: "chrome"); run npx playwright install chromium and remove channel to use bundled Chromium |
npm run assets:audio | Regenerates the bundled voice clips (needs Python edge-tts + network) |
npm run assets:glyphs | Rebuilds Hindi letter outlines from the Baloo 2 font |
npm run assets:pictures | Downloads the picture SVGs (Noto Emoji) |
npm run assets:samples | Rebuilds public/samples/*.pdf from the demo reader text |
All generated assets are committed, so none of the assets:* scripts are needed to run the app.
Environment variables
Everything is optional. Keys are read only on the server (import "server-only") and never reach the browser.
| Variable | Purpose | Default |
|---|
LLM_API_KEY | Key for the model provider (or use GEMINI_API_KEY / GROQ_API_KEY / OPENROUTER_API_KEY) | — (demo mode) |
LLM_PROVIDER | gemini · groq · openrouter · openai · custom | auto-detected |
LLM_MODEL | Model name | gemini-2.5-flash · llama-3.3-70b-versatile · google/gemini-2.5-flash · gpt-5-mini |
LLM_BASE_URL | OpenAI-compatible endpoint (required for custom) | preset |
LLM_REASONING_EFFORT | low/medium/high for models that accept it | low for gpt-oss, otherwise unset |
GROUNDING_JUDGE | Second-stage AI evidence check on answer keys | true in live mode |
LLM_TIMEOUT_MS | Per-request timeout | 90000 |
EMBEDDING_PROVIDER / EMBEDDING_API_KEY / EMBEDDING_MODEL / EMBEDDING_DIMENSIONS | Embeddings for hybrid retrieval. Automatic with a Gemini or OpenAI key; Groq/OpenRouter have no embeddings API, so pair them with a Gemini key here or run BM25-only | auto / none |
UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN (or Vercel's KV_REST_API_URL / KV_REST_API_TOKEN) | Durable storage for uploads, quizzes and attempts | unset → local files |
DATA_DIR | Local storage folder | .data (or /tmp/alp-data on Vercel) |
MAX_UPLOAD_MB / MAX_PDF_PAGES | Upload limits (enforced in UI and API) | 15 / 250 (capped at 4.5 MB on Vercel — see below) |
DEMO_MODE | Force deterministic demo behaviour even with a key |
The PRD's DATABASE_URL / OBJECT_STORAGE_* are not used: persistence is Upstash Redis (REST, serverless-safe), and
PDFs are not stored after extraction — only their page text and chunks.
How it works
Textbook AI Tutor
PDF ──► validate (type, size, %PDF magic, page limit)
──► extract per-page text (unpdf / PDF.js text layer) ── no text? → "looks scanned" error
──► detect chapters ("Unit 2 —", "Chapter 3", "पाठ 4"; contents pages ignored)
──► page-bounded, paragraph-aware chunks (~500 tokens, ~100 overlap) + metadata
──► (optional) embeddings ──► store
Quiz config ──► scope filter (chapter / page range) ──► context selection
(whole scope if it fits; else BM25 ⊕ embeddings via reciprocal-rank fusion, ≤2 chunks per page)
──► generate (live model, or demo generator)
──► rule checks ──► dedupe ──► optional AI evidence judge ──► reviewable quiz
- Grounding rules (
src/lib/tutor/validate.ts): citations must point at chunks that were actually supplied;
quotes must appear on the cited page; page numbers always come from chunk metadata, never from the model;
MCQs need 2–4 distinct options and exactly one valid key; blanks need a visible ___ and an accepted answer that
occurs in the evidence; rubric points must sum to the max (auto-corrected and flagged); answers must be supported
by the cited text. Problems that make a question unscorable remove it (with a warning); anything else marks it
Needs review. Fewer questions are returned rather than padding with unsupported ones.
- Prompt safety: textbook text and student answers are wrapped in delimiters, declared untrusted, and
delimiter-escaped. Models only see short source aliases (
S1…), which are mapped back server-side.
- Structured output: JSON mode + Zod validation; invalid output gets exactly one corrective retry, then a
user-safe error with a "use demo generator instead" option. Raw model output is never shown.
- Scoring: MCQ by stored option id (display order is shuffled per attempt); fill-in-the-blank by normalised
match (Unicode NFKC, case, punctuation, articles) against accepted variants; short answer / comprehension by
rubric — the model judges each criterion, the score is the sum of met criteria, clamped; unknown criteria,
low confidence or failures set a teacher-review flag. Students never receive answer keys, rubrics or evidence
before submitting (
toStudentQuestion, covered by tests).
- Demo mode: the built-in reader uses a reviewed, source-tied question bank (24 items); uploaded PDFs get a
deterministic cloze generator (fill-in-the-blank and "which word completes the sentence"). Open answers use a
keyword-rubric checker labelled "Demo keyword check".
Early Learning Studio
- Lessons (
src/lib/early/lessons.ts): English A–Z (2–3 picture words each, letter name + "A for apple" cue +
adult-facing phoneme hint) and Hindi: 10 vowels + 8 consonants with romanised glosses.
- Audio: bundled clips for every letter name, cue, word, instruction and feedback line (separate clips for
letter name and cue). Falls back to the Web Speech API with a matching
en-IN/hi-IN voice; if neither can
play, the UI says so and offers read-aloud text — it never pretends audio played. New audio always stops the
previous sequence; leaving a letter stops speech.
- Tracing (
src/lib/early/geometry.ts, src/components/early/trace-board.tsx): English guides are hand-authored
SVG stroke paths with numbered start dots, direction arrows and an animated "Show me". Hindi guides are the exact
SVG outline of each letter (Baloo 2); its centre line is computed at runtime by rasterising that same path and
thinning it (Zhang–Suen). Ink is stored in normalised 0..1 coordinates. Coverage = share of guide samples with
ink within ~5.5% of the board; an on-guide ratio catches scribbles. ≥70% coverage with ≥55% on-guide → success;
partial traces name the weakest stroke ("Trace line two again") or Hindi region (top line / left / right).
Low scores never block moving on. touch-action: none is applied to the canvas only.
- Progress: per-device
localStorage (explored / traced / attempts / last letter), with a reset in the
grown-ups panel. Nothing is sent to the server.
Project layout
src/app/ routes (App Router) + API route handlers under src/app/api
tutor/(workspace)/ teacher pages: dashboard, document/[id], generate, review/[id]
tutor/(student)/ student pages: quiz/[id], results/[id] (no teacher navigation)
early/[language]/[letter] lessons and /trace (all prerendered via generateStaticParams)
src/lib/tutor/ pure logic: types, schemas, pdf, chunk, retrieve, validate, score, demo bank
src/lib/ai/ provider config, OpenAI-compatible client, generate / evaluate / judge / embed tasks
src/lib/server/ services: ingest, generate, attempts, review, http helpers
src/lib/store/ KV (file · Upstash · memory) + repositories
src/lib/early/ lessons, strokes, glyph outlines, geometry & scoring, audio engine, progress
src/components/ UI (tutor/, early/, ui/)
tests/ Vitest unit + API tests; tests/e2e Playwright specs
scripts/ asset generators
API (PRD §11)
POST/GET /api/documents · GET/DELETE /api/documents/:id (?page=N for a page's text) ·
POST /api/quizzes/generate (NDJSON progress stream) · GET /api/quizzes · GET/DELETE /api/quizzes/:id ·
PATCH/DELETE /api/quizzes/:id/questions/:qid · POST /api/quizzes/:id/questions/:qid/regenerate ·
POST /api/quizzes/:id/attempts · GET /api/attempts/:id · POST /api/attempts/:id/submit ·
GET /api/attempts/:id/results · GET /api/early/lessons?language=en|hi · GET /api/early/lessons/:language/:character ·
GET /api/status. All inputs are validated with Zod; errors are { error: { message } } without stack traces.
Uploads, generation and submissions are rate-limited per IP (best effort, per instance).
Deployment (Vercel)
- Push this folder to a Git repository and import it in Vercel (framework: Next.js, no build settings needed).
- Optional env vars in Project → Settings → Environment Variables:
LLM_API_KEY (and LLM_MODEL), and for
durable data add Upstash Redis from the Vercel Marketplace (it injects KV_REST_API_URL / KV_REST_API_TOKEN).
- Deploy. Or from the CLI:
vercel (preview) / vercel --prod.
Platform notes:
- Upload size: Vercel functions reject request bodies over 4.5 MB, so the effective limit there is
4.5 MB (the UI shows it). Larger books: upload a chapter, or self-host.
- Persistence: without Upstash, uploads/quizzes live in the instance's
/tmp and can disappear — the UI shows a
"temporary" notice. The demo reader and all Early Learning content are built in and always available.
- Timeouts: generation and grading routes set
maxDuration (60–120 s).
Testing
npm test — 73 Vitest tests (unit + route-handler/API) including: answer keys never sent before submission;
demo mode with no key; invalid model JSON → one retry → safe failure; provider auth errors hidden; unsupported
citations rejected; MCQ determinism; fill-blank normalisation; rubric scoring clamped and flagged; scanned and
oversized PDFs; coordinate normalisation and coverage tiers (empty / partial / full / scribble).npm run test:e2e — 18 Playwright tests: full teacher → student → results flow, upload + preview + scanned
error, setup validation, lesson audio/navigation, tracing (empty, partial with stroke hint, full, undo, guide
toggle, show me), Hindi lesson, progress reset, no horizontal scroll at phone width, canvas-only scroll blocking.
Manual acceptance checklist (PRD §15.2)
| Check | Status |
|---|
| Home on desktop and mobile | ✅ automated (layout) + manual screenshots |
| Generate a quiz from demo content | ✅ automated |
| Upload a searchable PDF; pages preserved | ✅ automated (public/samples/sunny-steps-demo-reader.pdf) |
| Invalid and oversized files | ✅ automated (API) + UI message |
| MCQ, fill-blank, short-answer and comprehension questions | ✅ demo bank; live mode needs a key |
| Citations support the question | ✅ citation drawer highlights the quote on the page |
| Edit a question, start a quiz | ✅ automated |
| Correct and incorrect MCQ scoring | ✅ automated |
| Semantically correct short answer, different wording | ⚠️ needs live mode (demo uses keywords) |
| English A: letter audio + two example words | ✅ automated (captions) — listen manually for audio quality |
| Hindi lesson: glyph rendering + audio fallback | ✅ glyphs automated; audio fallback by design |
| Trace with mouse and touch; clear and retry | ✅ mouse automated; touch uses the same pointer events — verify on a device |
| High, partial and empty traces | ✅ automated |
| Navigate letters while audio plays | ✅ audio stops on navigation |
| Refresh: persistence explained | ✅ storage notice in the tutor; progress in localStorage |
| Build and tests, no console errors | ✅ |
Implemented vs deferred
Implemented: everything in the PRD's M1–M5 milestones, plus provider-agnostic live AI (Gemini, Groq,
OpenRouter, OpenAI, any OpenAI-compatible endpoint), hybrid retrieval, an optional AI grounding judge, question
regeneration, Upstash persistence, NDJSON progress streaming, and the automated test suites above.
Deferred / limitations — please read before relying on the prototype:
- OCR is not implemented: scanned PDFs are detected and rejected with an explanation.
- Question-bank import (PRD §6.3, optional) is not implemented; questions are labelled by origin
(AI-generated, rule-based demo, reviewed demo set).
- Hindi stroke order: Hindi letters are traced over their outline without numbered strokes; authoring reviewed
Devanagari stroke paths is future work. "Show me" is disabled for Hindi and says why.
- Lowercase English and the full Hindi alphabet (ऋ, अं, अः and remaining consonants) are not included yet.
- Content review: lesson words, feedback lines and Hindi text were curated for the prototype but have
not been reviewed by a qualified teacher (
reviewed: false). Voice clips are machine-generated placeholders
(Microsoft Edge neural TTS: en-IN-NeerjaNeural, hi-IN-SwaraNeural); record real audio before classroom use.
- Phoneme audio: letter sounds are taught through the "A for apple" / "अ से अनार" cue and words, not isolated
phoneme recordings.
- Live-mode quality depends on the chosen model; AI scores are estimates and flagged for review when uncertain.
- Rate limiting is per server instance (not shared across serverless instances).
- No authentication, roles, or multi-tenant separation (by design for the prototype).
Content & licences
- Demo reader text and question bank: original, written for this prototype (
src/lib/tutor/demo-textbook.ts).
- Pictures: Noto Emoji (Apache 2.0), plus two in-repo drawings.
- Fonts: Fraunces, Figtree, Geist Mono, Baloo 2 via
next/font (SIL OFL). Hindi outlines derive from Baloo 2.
- Icons: Phosphor Icons (MIT).
Troubleshooting
- Still says "Demo mode" after adding a key — restart
npm run dev; check GET /api/status → demoReason.
- "The model provider rejected the request" —
LLM_MODEL isn't available for that provider/key. List models
with curl -H "Authorization: Bearer $KEY" <base-url>/models.
- No sound — check device volume; the lesson shows a read-aloud fallback when audio can't play. Hindi speech
fallback requires a Hindi system voice; bundled clips don't.
- Upload fails on Vercel with a large PDF — the 4.5 MB platform limit; upload one chapter.
- Playwright can't find Chrome — install Chrome, or
npx playwright install chromium and remove channel.
