AI Math Tutor - Socratic Learning Assistant

An AI-powered math tutor that guides students through problem-solving using the Socratic method. Students learn by discovering solutions through guided questioning rather than receiving direct answers. All responses are dynamically generated by OpenAI's GPT-4, ensuring genuine AI-powered learning with no hardcoded responses. Link: https://ai-math-tutor-dun.vercel.app/

📚 Documentation

This project includes comprehensive documentation:

• ARCHITECTURE.md - System architecture and technical design
• EXAMPLES.md - Example walkthroughs demonstrating Socratic dialogue (10+ examples)
• PROMPT_ENGINEERING.md - Prompt engineering approach and Socratic method implementation
• TESTING_GUIDE.md - Comprehensive testing guide for all problem types
• UTILITIES.md - Development utilities and tools guide
• VERCEL_SETUP.md - Quick Vercel deployment guide (fix API key errors)
• memory-bank/ - Project memory bank with context and patterns

🎯 Project Overview

Build an AI tutor that:

• Accepts math problems via text or image upload
• Engages students in Socratic dialogue to guide learning
• Maintains conversation context throughout the session
• Adapts to student understanding level
• Never provides direct answers, only guidance
• All responses powered by OpenAI GPT-4 (no hardcoded fallbacks)

✨ Features

Core Features ✅

• Problem Input

  • Text entry with validation
  • Image upload with drag-and-drop
  • OpenAI Vision API for OCR and problem parsing
  • Support for printed and handwritten text
  • Automatic problem type detection

• Socratic Dialogue

  • Multi-turn conversation with context management
  • Never provides direct answers - only guiding questions
  • Progressive hint system (4 levels)
  • Adaptive scaffolding based on student understanding
  • Intelligent completion detection

• Math Rendering

  • LaTeX/KaTeX support for equations
  • Inline and block math formatting
  • Proper equation display

• Web Interface

  • Clean, minimalist chat UI
  • Mobile responsive design
  • Conversation history
  • Real-time progress tracking
  • Session persistence (survives hot reloads)

Stretch Features ✅

• Step Visualization - Animated breakdown of solution steps
• Voice Interface - Text-to-speech (natural human voice) + speech-to-text input
• Voice-Visual Synchronization - Synchronized voice explanations with visual highlights and whiteboard interactions
• Interactive Whiteboard - Integrated canvas for visual explanations with AI tutor feedback
  • Draw diagrams, equations, and visual work directly in the chat interface
  • Send drawings to AI tutor for visual analysis and feedback
  • AI tutor can see and reference your drawings using OpenAI Vision API
  • Toggle whiteboard on/off with a button in the chat header
  • Always accessible during problem-solving sessions
• Difficulty Modes - Adjust scaffolding by grade level (Elementary, Middle School, High School, Advanced)
• Problem Generation - AI-powered problem generation with difficulty selection

Learning Features ✅

• Problem History - Save and search through past problems with Solved/Bookmarked filters
• Bookmarks - Bookmark favorite problems for quick access
• Learning Dashboard - Track progress, time spent, problems by type, efficiency scores
• Learning Paths - AI-generated personalized learning journeys with concept dependencies
• Learning Goals - Set and track learning goals with progress monitoring
• Multi-Goal Tracking - Track multiple learning goals simultaneously with priority ordering
• Adaptive Practice - AI-powered practice recommendations based on performance and weak areas
• Learning Path Recommendations - Personalized next-step suggestions based on mastery levels
• Smart Nudges - Contextual reminders and encouragement to maintain study habits
• Study Streak - Track consecutive days of study with daily login bonuses
• Achievements - Earn badges for milestones (first problem, streaks, hints, etc.)
• Study Reminders - Customizable study notifications
• Problem Suggestions - AI suggests problem types to practice based on history
• Formula Reference - Quick access to common math formulas
• Practice Mode - One-click random problem generation
• Progress Tracking - Intelligent progress detection with completion recognition
• Concept Mastery - Automatic concept extraction and mastery tracking

Additional Features ✅

• Unified Settings Menu - Settings, Notifications, XP System, Study Reminders, and Data Backup & Restore in one place
• Unified Tools Menu - Search, Tips, and Formulas accessible from a single menu
• Progress Hub - Quick access to Stats, Goals, Timer, and Streak tracking
• Learning Hub - Dashboard, History, Practice Mode, and Problem Suggestions
• Gamification Hub - Achievements and Leaderboard
• XP & Leveling System - Earn XP for solving problems, level up, track progress with recent activity
• Referral System - Share referral codes, earn XP bonuses for referrals
• Daily Goals - Set and track daily study goals
• Study Timer - Track time spent studying
• Study Streak - Maintain consecutive days of practice
• Achievement System - Earn badges for milestones and achievements
• Leaderboard - Compare progress with other users, see rankings and XP
• Profile Management - Create and manage student profiles, link students to parents/teachers
• Parent/Teacher Dashboard - Monitor linked students' progress and activity
• Student Analytics - Detailed analytics with charts for problems solved, XP earned, and study time
• Teacher Monitoring Mode - View student sessions in real-time without affecting their progress
• Data Backup & Restore - Export and import learning data
• Settings Panel - Customize voice, font size, auto-save, API key, dark mode
• Keyboard Shortcuts - Efficient navigation and actions (Ctrl+K for search, ? for tips)
• Conversation Export - Export conversations for review
• Print View - Print-friendly conversation layout
• Error Recovery - Graceful error handling with retry options
• Offline Indicator - Network status awareness
• Accessibility - Full keyboard navigation, ARIA labels, screen reader support

🚀 Quick Start

Prerequisites

• Node.js 18+ (recommended: Node.js 20+)
• npm or yarn
• OpenAI API key (get from https://platform.openai.com/api-keys)

Setup Instructions

1. Clone or navigate to the project directory

   cd AITutor

2. Install dependencies

   npm install

3. Set up environment variables

   # Create .env.local file
   touch .env.local

   Add the following to .env.local:

   OPENAI_API_KEY=your_openai_api_key_here

   Note: Make sure there are no leading/trailing spaces in your API key!

4. Run development server

   # Standard dev server
   npm run dev
   
   # Or use the start script (stops any existing process on port 3002)
   ./start

   The start script (./start) will:

   • Stop any process running on port 3002
   • Start the dev server on port 3002
   • Ensure .env.local is reloaded

5. Open in browser

   • Navigate to http://localhost:3002 (or port shown in terminal)

Building for Production

# Build the application
npm run build

# Start production server
npm start

API Key Management

The app supports multiple ways to provide your OpenAI API key:

1. Environment Variable (Recommended for local development)

   • Add to .env.local: OPENAI_API_KEY=sk-your-key
   • Restart dev server after adding/changing

2. Settings Panel (Fallback for deployed apps)

   • Open Settings (gear icon)
   • Enter API key in the input field
   • Key is stored in browser localStorage
   • Works as fallback when environment variable is not available

3. Deployment (AWS Amplify, Vercel, etc.)

   • Add OPENAI_API_KEY to environment variables in your deployment platform
   • No need to set it in Settings panel

🌐 Deployment

Vercel

See VERCEL_SETUP.md for detailed instructions.

Quick steps:

1. Push code to GitHub
2. Import project in Vercel
3. Add OPENAI_API_KEY to environment variables
4. Deploy

AWS Amplify

1. Connect GitHub repository to AWS Amplify
2. Add OPENAI_API_KEY to environment variables:
   • Go to App Settings → Environment Variables
   • Add OPENAI_API_KEY with your key value
3. Deploy

Docker

A Dockerfile is included for containerized deployments:

docker build -t ai-math-tutor .
docker run -p 3000:3000 -e OPENAI_API_KEY=your_key ai-math-tutor

📖 Example Interaction

Student: [uploads "2x + 5 = 13"]
Tutor: "What are we trying to find?"
Student: "x"
Tutor: "Right! To get x alone, we need to undo the +5 and ×2. Which should we undo first?"
Student: "the +5?"
Tutor: "Exactly! How do we undo adding 5?"
Student: "subtract 5"
Tutor: "Perfect! So what happens when we subtract 5 from both sides?"

🧪 Testing

Quick Test

# Start dev server
npm run dev

# Or use start script
./start

# Open http://localhost:3002

Comprehensive Testing

• TESTING_GUIDE.md - Core features testing
• Test various problem types: arithmetic, algebra, geometry, word problems, multi-step

Test Scripts

# Test all problem types
npm run test:all

# Test specific type
npm run test:type arithmetic

# Test parsing
npm run test:parse "2x + 5 = 13"

# Test chat
npm run test:chat "2x + 5 = 13"

🏗️ Architecture

See ARCHITECTURE.md for detailed system design.

Tech Stack:

• Frontend: Next.js 14, React 18, Tailwind CSS, KaTeX
• Backend: Next.js API Routes
• LLM: OpenAI GPT-4 (Vision + Dialogue)
• State Management: React hooks, localStorage
• Deployment: Vercel, AWS Amplify, Docker

Key Components:

• services/problemParser.ts - Parse problems from text/images
• services/dialogueManager.ts - Orchestrate conversations
• services/contextManager.ts - Manage session context (with global storage for dev mode)
• services/socraticPromptEngine.ts - Generate Socratic prompts
• components/chat/ChatUI.tsx - Main chat interface
• components/ProblemHistory.tsx - Problem history and bookmarks
• components/LearningDashboard.tsx - Learning analytics

📝 Socratic Approach

The system follows these principles:

1. Never give direct answers - Only guide through questions
2. Progressive disclosure - Start broad, narrow to specifics
3. Adaptive scaffolding - Increase hints if stuck >2 turns
4. Encouraging language - Positive reinforcement throughout
5. Completion recognition - Detect when student solves the problem and celebrate

All responses are dynamically generated by OpenAI GPT-4 using carefully crafted Socratic prompts. There are no hardcoded responses or fallbacks.

🔧 Troubleshooting

Issue: OpenAI API errors

• Verify your API key is correct in .env.local (no leading/trailing spaces)
• Check your OpenAI account has sufficient credits
• Ensure the API key has access to GPT-4 models
• Try entering the API key in Settings panel as fallback
• Restart dev server after changing .env.local

Issue: Sessions disappearing

• Fixed: Sessions now persist across hot reloads using global storage
• If issues persist, check browser console for errors

Issue: Progress shows "Solved!" incorrectly

• Fixed: Progress detection now uses definitive completion phrases
• Only shows "Solved!" when tutor explicitly confirms completion

Issue: Image parsing not working

• Ensure images are in JPG or PNG format
• Check file size is under 10MB
• Verify OpenAI Vision API access

Issue: Math equations not rendering

• Check browser console for errors
• Ensure KaTeX CSS is loaded
• Verify LaTeX syntax in responses

Issue: API key not working in deployed app

• Check environment variables are set in deployment platform
• Use Settings panel to enter API key as fallback
• Verify API key format (should start with sk- or sk-proj-)

🎯 Recent Improvements

Latest Updates (December 2024)

🎓 Phase 3: Parent/Teacher Dashboard

• ✅ Parent/Teacher Dashboard - Complete monitoring solution for parents and teachers:
  • Link students via email or shareable invite codes
  • View all linked students from a unified dashboard
  • Switch between Personal account and student views
• ✅ Student Analytics - Detailed performance insights with charts:
  • Problems solved over time (line chart)
  • XP earned tracking
  • Study time analytics
  • Concept mastery breakdown
• ✅ Teacher Monitoring Mode - Observe student learning in real-time:
  • View active sessions without affecting student progress
  • Quick stats overview (problems, XP, streak, level)
  • Session history and conversation summaries

🚀 Phase 2: Adaptive Learning Features

• ✅ Adaptive Practice - AI-powered practice recommendations based on performance patterns
• ✅ Multi-Goal Tracking - Set and track multiple learning goals with priority ordering
• ✅ Learning Path Recommendations - Personalized next-step suggestions based on mastery
• ✅ Smart Nudges - Contextual reminders and encouragement for consistent study habits

Previous Updates (November 2024)

🔧 Bug Fixes & Improvements

• ✅ Enhanced Problem Completion Detection - Smarter detection that recognizes:
  • "Great job! You've calculated..." as completion
  • "Well done!" with context as completion
  • No longer falsely blocked by words like "what" in non-question contexts
  • Better handling of phrases like "calculated that Emma has..."
• ✅ Fixed Leaderboard Display - Users with XP now properly appear on leaderboard:
  • Fixed Supabase .is(null) filter reliability issues
  • In-memory filtering for accurate null checks
  • All users with XP now show correctly
• ✅ Improved Chat Text Overflow - Long text and math formulas now fit properly in chat bubbles
• ✅ LaTeX Rendering in Problem Cards - Math expressions render correctly in problem displays
• ✅ Problem of the Day - Daily challenge system with XP rewards

Major AI Tutor Enhancements (Inspired by OpenAI x Khan Academy Demo)

🎨 Enhanced Whiteboard System

• ✅ Professional Drawing Tools - Full-featured whiteboard with:
  • 6 Drawing Modes: Freehand, Line, Rectangle, Circle, Triangle, Text labels
  • Math Symbols Toolbar: Quick insert for π, √, ∑, ∫, ∞, ±, ×, ÷, ², ³, °, ∠
  • Text Labels: Click to add text annotations to diagrams
  • Shape Preview: Real-time preview while drawing shapes
  • Review Button: Get AI feedback on drawings before sending
  • Send Button: Submit final drawing to tutor
  • Integrated into chat interface (always accessible during problem solving)

🧠 Conceptual Understanding Tracking

• ✅ Automatic Concept Detection - Tracks 20+ math concepts:
  • Algebra: Linear Equations, Quadratic, Factoring, Exponents, Roots, Slope
  • Geometry: Pythagorean Theorem, Area (Circle/Triangle/Rectangle), Perimeter, Angles, Volume
  • Arithmetic: Fractions, Decimals, Percentages, Ratios
• ✅ Mastery Calculation - Smart algorithm based on:
  • Solve rate (70% weight)
  • Hint usage (20% weight)
  • Time efficiency (10% weight)
• ✅ Dashboard Integration - Visual progress tracking:
  • Concepts needing practice highlighted
  • Organized by category (Algebra, Geometry, Arithmetic)
  • Color-coded mastery levels (Green=Mastered, Blue=Learning, Gray=Needs Work)
  • Progress bars showing mastery percentage

🤖 AI Visual Feedback

• ✅ Enhanced Drawing Analysis - AI provides specific feedback:
  • References specific parts of drawings ("I see you drew a triangle with...")
  • Suggests visual improvements ("Try drawing a perpendicular line here")
  • Acknowledges correct visual work
  • Guides with visual suggestions ("Let's add labels to make it clearer")
• ✅ Review Functionality - Students can get feedback before submitting:
  • "Review" button for feedback-only requests
  • "Send" button for final submission
  • More collaborative, real-time learning experience

UI/UX Enhancements

• ✅ Enhanced Whiteboard Integration - Integrated whiteboard into chat interface (inspired by OpenAI x Khan Academy demo):
  • Whiteboard appears above chat interface when enabled
  • Toggle button (✏️) in chat header for quick access
  • Professional drawing tools and math symbols
  • Review and Send buttons for interactive feedback
  • AI tutor can see and analyze drawings using OpenAI Vision API
  • Visual feedback and references in tutor responses
  • Always visible by default when stretch features enabled
• ✅ Unified Menu System - Consolidated related features into organized hubs:
  • Settings Menu: Settings, Notifications, XP & Level, Study Reminders, Data Backup
  • Tools Menu: Search Problems, Helpful Tips, Formula Reference
  • Progress Hub: Quick Stats, Daily Goals, Study Timer, Study Streak
  • Learning Hub: Dashboard, Problem History, Practice Mode, Problem Suggestions
  • Gamification Hub: Achievements, Leaderboard
• ✅ Minimalist Design - Clean button layout with consistent spacing
• ✅ Optimized Button Positioning - Progress Hub on left, all other menus on right
• ✅ Proper Z-Index Layering - Settings menu appears above other menus when open

Technical Improvements

• ✅ Multimodal AI Integration - Whiteboard drawings sent to OpenAI Vision API for visual analysis
• ✅ Concept Tracking System - Automatic concept extraction and mastery calculation
• ✅ Enhanced Drawing Tools - Canvas-based shape drawing with state management
• ✅ Visual Feedback System - Enhanced prompts for better whiteboard analysis
• ✅ Enhanced Voice Input - Improved microphone permissions and error handling
• ✅ Voice-Visual Synchronization - AI voice explanations synchronize with visual highlights, whiteboard drawing mode changes, and message animations. When the AI mentions drawing shapes or highlights elements, visual updates occur in real-time during speech playback.
• ✅ Browser Compatibility - Better Firefox detection and graceful degradation
• ✅ Session persistence across Next.js hot reloads
• ✅ Intelligent progress detection with completion recognition
• ✅ Enhanced bookmark functionality with search and filtering
• ✅ All responses from OpenAI (no hardcoded fallbacks)
• ✅ Improved error handling and user feedback
• ✅ Text normalization for better problem display
• ✅ API key management with multiple fallback options
• ✅ Added required Next.js error components (error.tsx, not-found.tsx)
• ✅ Fixed ESLint warnings and errors for production builds

🤝 Contributing

This project is built by Davaakhatan Zorigtbaatar. See project documentation for details.

📧 Contact

Davaakhatan Zorigtbaatar - [email protected]

Built by Davaakhatan Zorigtbaatar

📄 License

[Add license information]

---

Reference: Inspired by OpenAI x Khan Academy demo: https://www.youtube.com/watch?v=IvXZCocyU_M

Built with: Next.js, React, OpenAI GPT-4, Tailwind CSS, KaTeX