Automated Question Validation (Gemini 3 Pro via OpenRouter)

Comprehensive Validation System

The validation tool now tests all question types for every level (1-34) using the actual app UI. It uses Puppeteer to launch the app with special URL parameters:

• ?testLevel=N — Forces the app to generate a question at level N
• ?testType=M — Forces the app to generate question type M within that level

This ensures every pathway in the question generator is tested, not just random samples.

Screenshots are captured from the real app, with full MathJax rendering, for each question type. AI responses from Gemini 3 Pro (via OpenRouter) are saved for every question for manual cross-checking.

See tools/README.md for full details.

Algebra Helper - Interactive Math Trainer

🚀 Launch the App Now!

An intelligent, adaptive math practice tool that helps students master mathematics from basic arithmetic through calculus, using personalized feedback and dynamic difficulty adjustment.

📱 Works Offline! Install as a PWA (Progressive Web App) on your phone or computer and use it anywhere, even on an airplane! See the Offline PWA Guide for installation instructions.

---

📚 For Students

How This Tool Helps You

Algebra Helper is your personal math trainer that adapts to your skill level in real-time. Here's what makes it special:

• 🎯 Personalized Learning: The app starts by calibrating to your current skill level, ensuring you're neither bored with easy problems nor frustrated with impossible ones.

• ⚡ Immediate Feedback: Get instant validation of your answers with clear explanations when you make mistakes. No waiting for grading—get instant feedback!

• 🤔 "I Don't Know" Option: Stuck? No problem! Use the "I don't know" button to skip any question without penalty. You'll see the correct answer and explanation, and the app will automatically make future questions easier to help you learn at your own pace.

• 📈 Progressive Challenge: As you improve, the difficulty automatically increases. Master easier concepts before moving to harder ones.

• 🔥 Momentum Mode: Build a streak of correct answers and watch your level accelerate! The more you succeed, the faster you progress.

• 💪 Comprehensive IB Math HL AA Coverage: Practice makes perfect. The app covers all topics from basic arithmetic through advanced IB Math HL Analysis & Approaches:

  • Level 0-1: Basic arithmetic (addition, subtraction, division, reverse formats)
  • Level 1-2: Squares, cubes, and roots (forward and reverse)
  • Level 2-3: Multiplication tables, powers of 10, division
  • Level 3-4: Fractions (addition, subtraction, multiplication, division, simplification)
  • Level 4-5: Decimals & percentages (conversion, ordering, operations)
  • Level 5-6: Simple linear equations (one variable)
  • Level 6-7: Two-step equations, parallel/perpendicular lines
  • Level 7-8: Inequalities (solving, sign rules)
  • Level 8-9: Expanding expressions (distributive property)
  • Level 9-10: Factorising quadratics
  • Level 10-11: Quadratics (solving, completing the square, discriminant, inequalities)
  • Level 11-12: Polynomials (operations, factor theorem, remainder theorem, polynomial division)
  • Level 12-13: Exponentials & logarithms (properties, equations, log laws)
  • Level 13-14: Sequences & series (arithmetic, geometric, sigma notation, binomial theorem, financial applications)
  • Level 14-15: Functions (evaluation, composition, inverse)
  • Level 15-16: Trigonometry (standard angles, exact values)
  • Level 16-17: Advanced trigonometry (identities, radians, double angle formulas, ambiguous case of sine rule)
  • Level 17-18: Vectors (2D operations, magnitude, dot product)
  • Level 18-19: Complex numbers (operations, modulus, powers of i)
  • Level 19-20: Basic differentiation (power rule, inverse functions)
  • Level 20-21: Advanced calculus (chain rule, product rule, critical points)
  • Level 21-22: Statistics (mean, median, mode, range)
  • Level 22-23: Probability (simple, complementary, combinations)
  • Level 23-24: Advanced probability (conditional, independence, expected value)
  • Level 24-25: Integration & series (power rule, geometric series, partial fractions)
  • Level 25-26: Proof by induction (sequences, series, divisibility)
  • Level 26-27: Proof by contradiction (irrationality, infinite primes, counterexamples)
  • Level 27-28: Matrix algebra (operations, determinants, inverses)
  • Level 28-29: 3D vectors (cross product, vector equations)
  • Level 29-30: Complex numbers polar form (De Moivre's theorem, conversions)
  • Level 30-31: Advanced integration (substitution, integration by parts)
  • Level 31-32: Differential equations (separation of variables, first-order, Euler's method)
  • Level 32-33: Probability distributions (binomial, normal, continuous random variables, mean & variance)
  • Level 33+: Hypothesis testing (null/alternative hypotheses, Type I/II errors)

How to Use

1. Calibration Phase: The app will show you problems and ask if they're too hard, just right, or too easy. Answer honestly! The app uses a quick binary search (4-6 questions) to accurately find your level.
2. Learning Phase: Once calibrated, practice with multiple-choice questions at your level. Answer quickly to maximize your progress!
3. Build Momentum: Get 3 correct answers in a row to activate Turbo Mode 🔥 for faster progression. Hover over Turbo Mode to see how it works!
4. Learn from Mistakes: Read the explanations when you get something wrong to understand the correct approach.
5. "I don't know" Option: Stuck on a problem? Click "I don't know" to see the correct answer and explanation without penalty. The app will automatically adjust to give you easier questions next.

📱 Use Offline (PWA)

Works on airplanes and anywhere without internet!

1. First-time setup (requires internet once):

   • Visit the app URL while online
   • Wait for the page to fully load
   • On Android/Chrome: Tap menu → "Install app" or "Add to Home Screen"
   • On iOS/Safari: Tap Share → "Add to Home Screen"

2. Use offline:

   • Launch the app from your home screen
   • All features work without internet!
   • Your progress is saved locally

📖 Detailed instructions: See Offline PWA Guide

---

📊 Self-Reflection & Analytics

Google Sheets Integration v2.0 - Enhanced Homework Tracking! ✨

Export your practice sessions for analysis in Google Sheets without complex API setup or Google Cloud authentication. The new v2.0 update makes your practice feel like homework that counts toward requirements!

Key Features

• ✅ No Google API Keys or OAuth - Simple CSV export/import workflow
• ✅ Privacy-Friendly - You control when and what to export
• ✅ Pre-Filtered Data - Only meaningful sessions (>2 min, >50% correct) exported
• ✅ Easy Setup - Manual CSV import or optional one-time Apps Script installation
• ✨ NEW: Duplicate Detection - Prevents re-importing the same sessions
• ✨ NEW: Top Topics Display - Shows 2-3 main topics practiced per session
• ✨ NEW: Homework-Friendly Format - Clear, professional presentation for tracking requirements

Quick Start

Exporting Your Sessions:

1. Complete practice sessions (>2 minutes with good accuracy)
2. Click Stats (📈) → "📊 Export Sessions" button
3. Optional: Share the downloaded CSV file with mentor or parent for review

Analyzing in Google Sheets:

1. Open Google Sheets
2. File → Import → Upload your CSV file
3. Choose "Append to current sheet" to combine multiple exports
4. Review your progress trends and patterns

Advanced: Install the provided Google Apps Script (one-time setup) for a custom import menu with additional features.

Exported Data Includes

• Date of practice session
• Your name (if set)
• Duration and question counts
• Score percentage
• Topics practiced with breakdown

Documentation

• 📖 GOOGLE_SHEETS_INTEGRATION.md - Complete integration guide
• 📚 ANALYTICS_GUIDE.md - Comprehensive analysis guide
• 📝 google-sheets-import.gs - Apps Script code (optional)
• 📊 sample-export.csv - Example export file

---

📖 Educational Philosophy

Algebra Helper is built on research-backed pedagogical principles designed for student self-help. For a comprehensive review of the learning science foundation, see PEDAGOGY.md.

Key Learning Principles

Worked Examples & Practice (Cognitive Load Theory)

Learn by working through specific examples with immediate practice. Research shows worked examples are effective for novice learners by reducing cognitive load (Sweller & Cooper, 1985), especially when combined with self-explanation prompts (Chi et al., 1989).

Current Implementation: Multiple-choice practice with explanations on errors. "Why" questions every few problems promote conceptual understanding.

Immediate Feedback

The tool provides instant verification and explanations. Research on feedback shows that immediate feedback prevents error consolidation and maintains engagement (Hattie & Timperley, 2007). Elaborative feedback addressing misconceptions is more effective than simple verification.

Current Implementation: Immediate right/wrong indication with brief explanatory feedback on errors.

Adaptive Difficulty (Zone of Proximal Development)

Based on Vygotsky's theory, learning is optimal when tasks are challenging but achievable. The app uses a binary search algorithm to calibrate initial difficulty, then dynamically adjusts based on performance to keep you in the productive learning zone.

Current Implementation: Adaptive difficulty with "I don't know" option to prevent frustration. Future versions will track skills separately and provide scaffolding beyond just difficulty adjustment.

Constructive Feedback

Effective feedback addresses three questions (Hattie & Timperley, 2007): Where am I going? (goals), How am I doing? (progress), and Where to next? (improvement strategies).

Current Implementation: Brief explanations showing correct method. Enhanced versions will include common misconception addressing and conceptual reasoning.

Motivation & Engagement

Progress indicators and level advancement provide clear goals and achievement markers. Research on gamification shows it can increase engagement when designed thoughtfully (Deci & Ryan, 1985; Hanus & Fox, 2015).

Design Choice: Balanced approach with mastery-oriented progression and "I don't know" option to reduce performance pressure.

Evidence-Based Practices in Development

• Spaced Repetition: Revisiting concepts over time improves retention (Cepeda et al., 2006)
• Interleaved Practice: Mixing problem types enhances learning (Rohrer & Taylor, 2007)
• Metacognitive Strategies: Self-monitoring and reflection improve understanding (Schraw & Dennison, 1994)

Appropriate Use & Limitations

✅ This Tool is Effective For:

• Procedural fluency practice
• Self-directed skill reinforcement
• Self-assessment
• Independent practice at your own pace
• Building confidence through adaptive difficulty

⚠️ This Tool Does Not Replace:

• Formal instruction and structured learning
• Collaborative problem-solving with peers
• Deep conceptual exploration
• Real-world application projects
• Mathematical reasoning and communication practice

📊 Effectiveness: We are committed to evidence-based practice and continuous improvement. See PEDAGOGY.md for our validation framework and research methodology.

Tips for Effective Use

📊 Self-Assessment

• Use the calibration phase to understand where you are in your algebra journey
• Monitor the "Last 5 Avg" accuracy to track your progress

🏠 Independent Practice

• Practice 15-20 minutes daily for best results
• Work at your own pace without pressure

👥 Study with Friends

• Work through problems together with study partners
• Discuss wrong answers to deepen understanding

🎯 Focus on Weak Areas

• If struggling with specific concepts, use the calibration to adjust your level
• The adaptive system ensures you're not overwhelmed

⏱️ Regular Practice

• Quick 5-10 minute practice sessions help maintain skills
• Consistent practice is more effective than cramming

Important Notes

• 🔒 Future versions will include user accounts for progress tracking
• 📝 This tool is designed for student self-help and independent practice
• 🐛 Debug mode is disabled by default; enable it only for development/testing

---

💻 For Programmers

Technologies Used

Algebra Helper is a single-file, client-side web application built with modern web technologies:

Frontend Framework

• Vanilla JavaScript: No frameworks required—pure ES6+ JavaScript for maximum performance
• Tailwind CSS: Utility-first CSS via CDN for rapid UI development and consistent styling
• MathJax 3: LaTeX math rendering with SVG output for crisp, accessible mathematical notation

Architecture & Algorithms

Binary Search Calibration with Statistical Confidence

// Finds optimal difficulty with confidence checks
if (student_knows) {
    minLevel = currentLevel;
} else {
    maxLevel = currentLevel;
}
nextLevel = (minLevel + maxLevel) / 2;

// Ends when multiple criteria are met:
// - Minimum 6 responses collected
// - Range converged to < 1.5 levels
// - Recent responses show mixed signals (both pass/fail)
// - Responses clustered around boundary level

Adaptive Difficulty with Momentum

• Correct answers: +0.2 level (or +0.5 in streak mode)
• First wrong answer: -0.3 level
• Consecutive wrong answers: -0.8 level (frustration breaker)

Problem Generation

• Procedural generation ensures infinite unique problems
• Each difficulty band has specific problem templates
• Distractors are algorithmically generated to be plausible but incorrect

Key Features

1. No Backend Required: All logic runs client-side—deploy to any static host
2. Responsive Design: Works on mobile, tablet, and desktop
3. Fast Performance: Question generation and rendering in <100ms
4. Accessible: MathJax provides screen-reader compatible math rendering

Code Structure

APP {
    level: 5.0,           // Current difficulty (1-10)
    streak: 0,            // Consecutive correct answers
    mode: 'calibration',  // 'calibration' or 'learning'
    history: [],          // Binary success/fail for last 5
    speedHistory: [],     // Response speed: 1 for fast, 0.5 for normal, 0 for slow
}

Generator {
    getQuestion(level)    // Returns problem object
    lvl1() - lvl5()      // Problem templates per band
}

Debug Mode

Set DEBUG_MODE = true (line 105) to:

• Highlight correct answers with yellow border
• Add visual debug markers
• Enable rapid testing

Running Locally

# Clone the repository
git clone https://github.com/raymondclowe/algebra_helper.git
cd algebra_helper

# Open in browser (no build step required!)
open algebra-helper.html
# or
python -m http.server 8000  # then visit http://localhost:8000

Deployment

GitHub Pages

This project is automatically deployed to GitHub Pages when changes are pushed to the main branch:

• Live URL: https://raymondclowe.github.io/algebra_helper/
• Deployment Workflow: .github/workflows/static.yml
• Deployment includes: index.html, algebra-helper.html, README.md

The deployment workflow:

1. Triggers on push to main branch or manual workflow dispatch
2. Creates a clean deployment directory with only necessary files
3. Uploads and deploys to GitHub Pages
4. Completes in ~30 seconds

To deploy to other static hosting services (Netlify, Vercel, etc.), simply upload the HTML files—no build step required!

Data Model and Integrity

Student data is stored locally using IndexedDB and localStorage. See comprehensive documentation:

• DATA_MODEL.md - Complete data structure documentation, schema versions, and migration guidelines
• AGENTS.md - Guidelines for AI agents and developers on preserving student data integrity

Key principle: Student data is irreplaceable. All changes to data structures, level mappings, or topic names must maintain backward compatibility.

Contributing

This is an open-source educational tool. Contributions welcome! Some ideas:

• Add more problem types (inequalities, simultaneous equations, etc.)
• Expand existing categories (more trigonometry identities, advanced calculus)
• Improve distractor generation algorithms
• Add accessibility features (keyboard navigation, high contrast mode)
• Internationalization (i18n) support

---

🚀 Next Steps & Roadmap

We're committed to making Algebra Helper even better. Here's what's planned:

📋 IB Syllabus Coverage Enhancement

We've completed a comprehensive review of IB Math AA syllabus coverage and identified 35 enhancement opportunities across four priority phases. See detailed documentation:

• SYLLABUS_COVERAGE_REVIEW.md - Complete analysis of all gaps and priorities
• SYLLABUS_GAP_SUMMARY.md - Quick reference guide with implementation plan
• SYLLABUS_IMPLEMENTATION_TRACKER.md - Progress tracking and status
• SYLLABUS_COVERAGE_MATRIX.md - Visual mapping of IB topics to levels

Key Insight: Graphing questions are now feasible using SVG/JavaScript (same approach as the existing trig diagram generator).

Phase 1 Priorities (12 High-Priority Core Topics):

• Financial applications (compound interest, depreciation)
• Parallel/perpendicular lines
• Quadratic inequalities
• Rational functions & asymptotes
• Graph transformations
• Sine and cosine rule
• Arc length and sector area
• Tangent and normal lines
• Definite integrals & area calculations
• Standard deviation & variance
• Linear regression & correlation
• Quadratic vertex form

Phase 3 Priorities (5 Visual/Graphing Topics using SVG):

• Function graphing & reading (identify intercepts, turning points)
• Trig function graphs (amplitude, period, transformations)
• Data visualization (histograms, box plots, scatter plots)
• Graphical equation solving (find intersections)
• Derivative graph relationships (f and f' connections)

Quick Wins (Low Effort, High Impact):

• Arc length and sector area (5-6 questions)
• Tangent and normal lines (4-6 questions)
• Standard deviation (5-8 questions)

Short Term (Next 3 Months)

• Syllabus Gap Phase 1: Implement high-priority core topics (see above)
• Better Mobile UX: Optimize touch targets and layout for smartphones
• Performance Metrics: Track average time per problem and learning velocity
• Explanation Improvements: More detailed step-by-step breakdowns for wrong answers

Medium Term (6 Months)

• Syllabus Gap Phase 2: Add HL-specific topics (permutations, Bayes, L'Hôpital, etc.)
• Topic Selection: Let students choose specific algebra topics to practice
• Export Results: Download practice session summaries as PDF/CSV
• Advanced Pedagogy:
  • Learning path recommendations
  • Identifying knowledge gaps
  • Personalized study plans

Long Term (12+ Months)

• Syllabus Gap Phase 3: Visual/graphing topics using SVG (function graphs, data viz, etc.)
• Syllabus Gap Phase 4: Lower-priority enhancements
• User Accounts: Backend storage for progress tracking across devices
• Google One-Tap Login: Seamless authentication for saving scores
• Multi-Language Support: Translate into Spanish, French, Mandarin, etc.

Research & Innovation

• Experiment with different feedback mechanisms
• A/B test various gamification approaches
• Partner with education researchers to measure learning outcomes
• Explore integration with Learning Management Systems (LMS)

---

🐛 Debug Mode

What is Debug Mode?

Debug mode is a developer feature that visually highlights the correct answer in multiple-choice questions. It's useful for:

• Testing new problem types
• Verifying distractor generation logic
• Quick QA during development
• Demo/training purposes

How to Enable/Disable

Enable: Set DEBUG_MODE = true in algebra-helper.html (line 105)

const DEBUG_MODE = true;  // Correct answers have yellow dashed border

Disable: Set DEBUG_MODE = false (default for production)

const DEBUG_MODE = false; // Production mode

Important Warnings

⚠️ Scores Are Not Saved in Debug Mode

• Debug mode is for testing only
• Student progress will not persist
• Use production mode for real practice sessions

⏱️ Debug Mode Timeout

• Debug mode automatically expires after 10 minutes
• This prevents accidental use in production environments
• Refresh the page to reset the timer

🔒 Security Note

• Debug mode is visible in client-side code
• For production deployments, consider a server-side flag
• Future versions will remove debug markers from production builds

Debug Visual Indicators

• Yellow dashed border around correct answer
• "✓ DEBUG" badge in top-right corner of correct option
• Calculator/No-calculator icons for problem requirements

---

📚 Research & References

Key Learning Science Principles

This tool is informed by research in cognitive psychology and mathematics education. For complete references and pedagogical analysis, see PEDAGOGY.md.

Core References:

• Cognitive Load Theory: Sweller, J., & Cooper, G. A. (1985). The use of worked examples as a substitute for problem solving in learning algebra. Cognition and Instruction, 2(1), 59-89.
• Feedback Research: Hattie, J., & Timperley, H. (2007). The power of feedback. Review of Educational Research, 77(1), 81-112.
• Self-Explanation: Chi, M. T., et al. (1989). Self-explanations: How students study and use examples in learning to solve problems. Cognitive Science, 13(2), 145-182.
• Spaced Practice: Cepeda, N. J., et al. (2006). Distributed practice in verbal recall tasks. Psychological Bulletin, 132(3), 354.
• Interleaved Practice: Rohrer, D., & Taylor, K. (2007). The shuffling of mathematics problems improves learning. Instructional Science, 35(6), 481-498.
• Motivation: Deci, E. L., Koestner, R., & Ryan, R. M. (1999). A meta-analytic review of experiments examining the effects of extrinsic rewards on intrinsic motivation. Psychological Bulletin, 125(6), 627.

Validation & Continuous Improvement

We are committed to evidence-based practice:

• 📊 Pilot studies planned with control groups
• 📈 Learning analytics to measure effectiveness
• 🔬 Iterative improvement based on data
• 🎓 Partnership with education researchers

See PEDAGOGY.md for our complete validation framework, measurement plans, and ongoing research commitments.

---

📄 License

This project is open source and available for educational use.

🤝 Contact & Support

Questions? Suggestions? Found a bug?

• Open an issue on GitHub
• Contribute via pull requests

---

Happy Learning! 🎓