MathCrew 🧮

AI-powered adaptive math tutor for kids (Grade 1–6)

A web-based math learning app for elementary students, powered by a CrewAI multi-agent pipeline with Google Gemini + Ollama hybrid architecture.

Motivation

Built as a personal project to help my daughter practice math at home, and as an experiment with CrewAI's multi-agent orchestration. What started as a simple worksheet generator evolved into a full adaptive tutoring system.

• 4 AI agents collaborate: problem generation → feedback → error analysis → scaffolded practice
• Problem Bank — caches generated problems to save LLM calls (reuses problems with matching conditions)
• 3 curriculum styles: Common Core · RSM · Singapore Math
• Gamification: XP / levels / streaks / 15 badges / confetti animations
• Multi-student support with PIN login
• Chart.js-powered dashboard

---

Screenshots

Login	New Student Setup

Problem	Agent Pipeline

Wrong Answer + Scaffold	Correct Answer + Achievement

Dashboard	Achievements

---

Features

Feature	Description
AI 4-Agent Pipeline	Manager → Creator → Helper → Analyst sequential execution
Real-time SSE UI	Live agent pipeline progress displayed in the browser
Adaptive Scaffolding	On wrong answers: error analysis (computational/conceptual/procedural/careless) + auto-generated practice problems
Problem Bank	Caches problems by grade+style+topic, skips Creator LLM call on cache hit
Multi-Curriculum	Choose from Common Core · RSM (Russian Math) · Singapore Math
Gamification	XP · Levels (1–50) · Streak bonuses · 15 badges · Confetti animations
Multi-Student + PIN	Per-student profiles, PIN protection, independent learning history
Dashboard	Accuracy trends · Per-topic performance · Achievement overview (Chart.js)

---

Tech Stack

Layer	Technology
Backend	Python 3.10+ / Starlette (async)
AI Agents	CrewAI
Primary LLM	Google Gemini 2.5 Flash
Local LLM	Ollama (gemma3:4b)
Database	SQLite3
Realtime	Server-Sent Events (SSE)
Frontend	Vanilla JS / Chart.js / canvas-confetti

---

Prerequisites

Requirement	Note
Python 3.10+	Required
Gemini API Key	Required — see setup guide below
Ollama	Optional — needed for local LLM

---

Quick Start

# 1. Clone
git clone https://github.com/freesoft/MathCrew.git
cd MathCrew

# 2. Create & activate virtual environment
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install "crewai[google-genai]" starlette sse-starlette uvicorn python-dotenv

# 4. Configure environment variables
cp .env.example .env       # or create manually
# Add GEMINI_API_KEY=your_key_here to .env

# 5. Run
python web_tutor.py
# → http://localhost:8000

---

Gemini API Key Setup

1. Go to Google AI Studio
2. Click Get API Key → Create API Key
3. Add the key to your .env file:

   GEMINI_API_KEY=your_key_here
   

4. Free tier limits: 15 requests/min, 1,500 requests/day (as of 2025, subject to change)

---

Ollama Setup (Optional)

To run the Helper agent locally for faster feedback:

1. Install from https://ollama.com
2. Pull the model:

   ollama pull gemma3:4b

3. Configure in .env:

   USE_LOCAL_LLM=true    # (default) Use Ollama for Helper
   USE_LOCAL_LLM=false   # Use Gemini for all agents
   

If Ollama is not installed, set USE_LOCAL_LLM=false and all agents will use Gemini.

Choosing a Local Model

The default gemma3:4b is lightweight and good for simple feedback. For stronger math reasoning, consider upgrading:

Model	VRAM	Math Performance	Best For
gemma3:4b (default)	~3 GB	Basic	Simple feedback, low-end hardware
qwen3:8b	~6 GB	Good	8 GB GPU, significant upgrade over gemma3
qwen3:14b	~10 GB	Strong	16 GB GPU, recommended for full local mode
deepseek-r1:14b	~10 GB	Strong (math-specialized)	Math-heavy reasoning tasks
llama4-scout:17b	~12 GB	Strong	Natural English, general purpose
qwen3:32b	~20 GB	Closest to Gemini Flash	24 GB GPU (RTX 4090 etc.)

To switch models, just pull and update web_tutor.py:

ollama pull qwen3:14b

# In web_tutor.py, change the local_llm model:
local_llm = LLM(model="ollama/qwen3:14b", base_url="http://localhost:11434")

Full local mode (all agents on Ollama, no data leaves your machine) is planned for a future release — ideal for schools and privacy-sensitive deployments.

---

AI Agent Architecture

[Manager] → [Creator] → [Helper] → [Analyst]
   │            │           │           │
  Gemini      Gemini     Ollama      Gemini
                ▲
                │
        [Problem Bank] ── hit → skip Creator (saves LLM call)

Agent	Model	Purpose
Learning Manager	Gemini 2.5 Flash	Analyzes learning history, decides next problem direction
Problem Creator	Gemini 2.5 Flash	Generates grade- and topic-appropriate math problems (JSON output)
Solution Helper	Ollama gemma3:4b	Encouraging feedback on correct/wrong answers, step-by-step explanations
Misconception Analyst	Gemini 2.5 Flash	Error analysis — computational / conceptual / procedural / careless

Why only Helper uses a local model: immediate feedback needs speed, while accurate problem generation and analysis require Gemini's accuracy.

---

Problem Bank

Generated problems are cached in the problem_bank table and reused when the same conditions (grade + curriculum_style + topic) are requested.

• Regular problems: After Manager runs, extract topic → query bank → on hit, skip Creator (saves 1 LLM call)
• Scaffold problems: Query bank → on hit, skip Creator (saves all LLM calls — no Manager for scaffolds)
• Compares against each student's last 20 problems to avoid serving duplicates
• Sorted by times_served ASC, RANDOM() — least-served problems are prioritized

---

Curriculum Styles

Style	Approach
Common Core	Conceptual understanding + real-world problems, visual models (number lines, tape diagrams)
RSM	Logical reasoning + algebraic thinking, 1–2 years ahead of standard curriculum
Singapore Math	CPA (Concrete-Pictorial-Abstract) approach, bar models, number sense mastery

Students can select their curriculum style during profile creation or in settings. The chosen style determines per-grade scope and pedagogy injected into all agent prompts.

---

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	—	Google Gemini API key
USE_LOCAL_LLM	No	true	true = use Ollama for Helper, false = use Gemini for all

---

Project Structure

MathCrew/
├── web_tutor.py        # Web server + API routes + CrewAI agent pipeline + Problem Bank logic
├── db.py               # SQLite schema + Problem Bank + gamification logic (XP/levels/achievements)
├── math_tutor.py       # CLI version (standalone, runs in terminal without web)
├── templates/
│   └── index.html      # Frontend SPA (Vanilla JS + Chart.js + confetti)
├── .env                # API keys (gitignored)
├── .gitignore
└── README.md

---

Customization Guide

Changing Models

Edit LLM configuration in web_tutor.py:

# Change Gemini model
gemini_llm = LLM(model="gemini/gemini-2.5-pro", api_key=...)

# Change local model (see "Choosing a Local Model" section for recommendations)
local_llm = LLM(model="ollama/qwen3:14b", base_url="http://localhost:11434")

Privacy Note

When using cloud LLMs (Gemini, OpenAI), student data — names, grade levels, answers, mistakes, and learning history — is sent to external servers. For apps used by children, this matters more than you might think.

What is COPPA? The Children's Online Privacy Protection Act is a US federal law that regulates online collection of personal information from children under 13. The 2024 amendments (fully effective 2025) strengthen requirements significantly: parental consent is opt-in by default, and operators must minimize data collection. If your child uses an AI tutor that sends their work to cloud servers, COPPA likely applies.

What is FERPA? The Family Educational Rights and Privacy Act protects student education records in K-12 schools. When a school adopts an EdTech tool, FERPA requires that student data is used only for educational purposes and not shared with third parties for unrelated use. Schools must ensure any cloud service they use has appropriate data handling agreements.

Why does local mode matter? In local mode (USE_LOCAL_LLM=true with all agents on Ollama), your child's name, grade, answers, mistakes, and learning patterns never leave your machine. There is no external data transmission, no third-party data processing, and no legal gray area. This is the simplest path to full compliance.

For school deployments:

• Recommended: Full local mode with a capable model (e.g., qwen3:14b on 16 GB VRAM)
• If cloud is necessary: Use only services that guarantee US data residency and do not use student data for model training. Gemini API paid tier meets both criteria (free tier data may be used for product improvement); Azure OpenAI US East/West is another option
• See LICENSE.md for contact info regarding institutional use

Editing Curriculum

Modify the CURRICULUM_STYLES dict in web_tutor.py:

CURRICULUM_STYLES = {
    "common_core": {
        "display_name": "Common Core",
        "pedagogy": "Focus on conceptual understanding...",
        "grades": {
            1: "Addition and subtraction within 20...",
            # ... edit per-grade scope
        },
    },
    # Add new styles here
}

Topic List

Update both KNOWN_TOPICS in web_tutor.py and the TOPICS array in templates/index.html.

Adding Achievements

Add a new entry to the ACHIEVEMENTS dict in db.py, then add the condition in check_achievements():

# Add to ACHIEVEMENTS
"new_badge": {"name": "Badge Name", "icon": "🎖️", "desc": "Description"}

# Add condition in check_achievements()
"new_badge": some_condition,

XP Formula

In db.py get_gamification_stats():

• Correct answer: 10 XP
• Scaffold correct: 8 XP
• Wrong answer: 2 XP
• Streak bonuses: 3-streak +3, 5-streak +5, 10-streak +10, 20-streak +20

Level Formula

level = min(int(0.4 * sqrt(xp)) + 1, 50)

---

API Endpoints

Method	Endpoint	Description
GET	/	Main page (index.html)
GET	/api/students	List all students
GET	/api/student	Current logged-in student info
POST	/api/login	PIN login
POST	/api/setup	Create/update student profile
POST	/api/logout	Logout
POST	/api/new-problem	Generate new problem (runs agent pipeline)
POST	/api/submit-answer	Submit answer + grading
POST	/api/skip	Skip current problem
POST	/api/scaffold-problem	Generate scaffold practice problem after wrong answer
GET	/api/gamification	XP · level · streak status
GET	/api/achievements	Achievement/badge list + unlock status
GET	/api/stats	Per-topic accuracy stats
GET	/api/score-over-time	Score trend data over time
GET	/api/history	Full problem history
GET	/api/events	SSE stream (real-time agent status)

---

Support

If MathCrew is helpful for your family, consider supporting the project:

License

PolyForm Strict 1.0.0 — free for personal and non-commercial use.

For commercial use, educational institutions, or schools, please reach out via LinkedIn (linked on GitHub profile) to request approval.