STEM Sage

An AI STEM coach that diagnoses, explains, hints, quizzes, and adapts in one guided flow.

STEM Sage turns AI into a structured tutoring system rather than a free-form chatbot. A student submits a STEM question by text or image, and the app identifies the topic, estimates difficulty, generates a step-by-step explanation, offers adaptive hints (not spoilers), and creates a short quiz. The learner's responses update a lightweight mastery model so the next recommendation is personalized.

Built for the AI-for-Education hackathon by Aryan Choudhary (aryancta@gmail.com).

---

Features

• Text or image problem intake — paste a question, drop a photo, or load a sample. Browser-side Tesseract.js handles OCR.
• AI topic diagnosis — subject, topic, difficulty, and a confidence meter for every problem.
• Step-by-step explanation mode — leveled (simple / standard / advanced) with optional "why this step matters" notes.
• Adaptive hint ladder — three progressive hints instead of spoilers, tracked per session.
• Mini quiz — multiple-choice, fill-in-the-blank, and short-answer questions with instant feedback.
• Mastery tracker — per-topic score in SQLite, ring charts on the dashboard, streak counter.
• Recommended next lesson — personalized topic + difficulty based on quiz performance.
• Multilingual mode — English, Hindi, and Spanish toggles with graceful fallback.
• Voice narration — optional browser-based text-to-speech for the current step.
• Session history — review past sessions, scores, and mastery deltas.
• Accessible, polished UI — shadcn/ui, Tailwind, Framer Motion, generous contrast and focus states.

Tech stack

• Next.js 14 (App Router) + React 18 + TypeScript
• Tailwind CSS + shadcn/ui + Lucide + Framer Motion
• Prisma ORM + SQLite (single-file persistence)
• Zod for validation
• Tesseract.js (client-side OCR)
• Web Speech API (client-side text-to-speech)
• Local rule-based AI orchestration — no external API keys required

Quick start (local)

# 1. Install
npm install

# 2. Setup database
npx prisma migrate deploy
npm run db:seed

# 3. Run dev server
npm run dev
# open http://localhost:3000

Run with Docker

docker build -t stem-sage .
docker run -p 3000:3000 stem-sage

Then open http://localhost:3000. The container ships with a pre-seeded SQLite database, sample sessions, and mastery records so the demo looks populated from the first click.

Screens

Page	Path	Notes
Landing	/	Hero, feature cards, 5-stage tutoring loop, impact stats, CTA
Dashboard	/dashboard	Problem intake, subject chips, OCR status, mastery rings, recent sessions
Tutoring session	/session/[id]	Diagnosis panel, step timeline, hint ladder, quiz, recommendation, sticky mastery sidebar
History	/history	Filterable session cards with scores and mastery deltas
Settings	/settings	Language, voice narration, explanation depth, data reset, privacy note

Architecture

src/
├── app/
│   ├── page.tsx                 # Landing
│   ├── dashboard/               # Student workspace
│   ├── session/[id]/            # Tutoring experience
│   ├── history/                 # Session history
│   ├── settings/                # Preferences & accessibility
│   └── api/                     # Next.js route handlers
│       ├── health/
│       ├── ocr/
│       ├── ai/{diagnose,explain,quiz,recommend}/
│       └── sessions/[id]/{hints,quiz}/
├── lib/
│   ├── ai.ts                    # Rule-based AI orchestration
│   ├── session.ts               # Session creation/transformation
│   ├── mastery.ts               # Mastery scoring + updates
│   ├── ocr.ts                   # Server-side OCR stub
│   ├── db.ts                    # Prisma client singleton
│   ├── validators.ts            # Zod schemas
│   └── constants.ts             # Subjects, topics, thresholds
├── components/                  # Site header/footer, hero, feature grid,
│                                #   problem-intake, diagnosis, explanation,
│                                #   hint-ladder, quiz, recommendation, mastery
│                                #   overview, history list, settings, UI kit
└── styles/globals.css
prisma/
├── schema.prisma                # LearningSession, ExplanationStep, Hint,
│                                # QuizQuestion, QuizResponse, MasteryRecord,
│                                # UserPreference
└── seed.ts                      # Demo data for first run

API

Method	Path	Purpose
GET	/api/health	Health + DB ping
POST	/api/sessions	Create tutoring session (diagnosis + explanation + quiz)
GET	/api/sessions	List recent sessions
GET	/api/sessions/:id	Fetch full session payload
POST	/api/sessions/:id/hints	Reveal next hint level
POST	/api/sessions/:id/quiz	Submit answers → score, mastery update, recommendation
POST	/api/ai/diagnose	Classify subject, topic, difficulty
POST	/api/ai/explain	Step-by-step explanation
POST	/api/ai/quiz	Generate quiz
POST	/api/ai/recommend	Next-lesson recommendation
POST	/api/ocr	OCR stub (client-side Tesseract used in browser)

All request bodies are validated with Zod. Any validation failure returns 400 with an error message.

Data privacy

Everything lives in a local SQLite file inside the container. No external AI calls are made and no telemetry is collected. The Settings page documents this prominently.

Accessibility

• Keyboard-focusable primary interactions, visible focus rings.
• High-contrast typography and semantic badges.
• Optional voice narration and multilingual summaries.
• All icons paired with text labels for screen readers.

---

Made with ❤️ for learners everywhere.