A free, AI-powered maths tutor for students in Grades 1 to 12.
SuperMaths adapts to your level, generates unlimited practice questions, and gives you instant step-by-step hints whenever you get stuck. No subscriptions, no ads, no question bank — just fresh AI-generated questions every time.
🔗 Live app: supermaths.streamlit.app
Current version: v.1.2 official release Other versions: v.1.1_beta, v.1.0_alpha initial release
- Placement Test — A quick 10-question test that finds your starting level automatically so you begin at exactly the right place
- AI-Generated Questions — Every question is freshly generated by Groq's LLaMA 3.3 70B model. No repeats, no question bank, infinite practice
- Batch Generation — All questions for a session are generated in one API call, so load times are typically 3 to 6 seconds
- Level Assignments — 5 topics per level with 2 quizzes each. Complete them all to unlock the next level
- Level Test — Score 70% or higher to skip straight to the next level without working through every assignment
- Free Practice — Pick any topic at your current level and practise as much as you want. It all counts toward your daily total
- Instant Hints — Stuck on a question? Hit the hint button and get a step-by-step explanation of how to approach it, without giving away the answer
- 31 Badges — Earn badges for milestones, streaks, accuracy, and mastering specific topics like Calculus, Trigonometry, and Linear Algebra
- Video Lessons — Curated YouTube lessons for every topic at every level, right on the dashboard
- Daily Progress — Track how many questions you have answered and your accuracy each day, with a colour-coded progress bar
- Streaks — Keep a daily streak going to earn consistency badges
- Persistent Progress — Everything is saved to MongoDB Atlas so your progress is there whenever you come back
| Layer | Technology |
|---|---|
| Frontend | Streamlit |
| Database | MongoDB Atlas via PyMongo |
| AI Model | Groq — LLaMA 3.3 70B Versatile |
| Hosting | Streamlit Community Cloud |
1. Clone the repository
git clone https://github.com/your-repo/supermaths.git
cd supermaths2. Install dependencies
pip install -r requirements.txt3. Set up your environment variables
Create an api.env file in the project root:
GROQ_API_KEY=your_groq_api_key
MONGO_URI=your_mongodb_connection_string
GROQ_MODEL=llama-3.3-70b-versatile4. Run the app
streamlit run main.pysupermaths/
├── main.py # App entry point and page routing
├── auth.py # Login, sign-up, and cookie-based session persistence
├── database.py # MongoDB connection and all database operations
├── questions.py # Groq API: batch question generation and hints
├── dashboard.py # Main dashboard with stats, assignments, badges, and videos
├── assignments.py # Assignment quiz flow
├── level_test.py # Level test flow
├── baseline.py # Placement test flow
├── practice.py # Free practice mode
├── badges.py # Badge definitions, topic mastery map, and award logic
├── landing.py # Public landing page
├── styles.py # Global CSS and shared UI components (navbar, sidebar)
└── requirements.txt
12 levels covering the full Grades 1 to 12 curriculum.
| Level | Topics |
|---|---|
| 1 | Addition, Subtraction, Counting, Number Patterns, Place Value |
| 2 | Multiplication, Division, Times Tables, Word Problems, Mental Maths |
| 3 | Fractions, Decimals, Rounding, Negative Numbers, Basic Geometry |
| 4 | Basic Algebra, Percentages, Ratios, Area & Perimeter, Data & Graphs |
| 5 | Linear Equations, Geometry, Probability, Averages, Sequences |
| 6 | Systems of Equations, Functions, Indices, Circle Theorems, Transformations |
| 7 | Quadratics, Trigonometry, Vectors, Simultaneous Equations, Inequalities |
| 8 | Statistics, Advanced Algebra, Surds, Graph Sketching, Proof |
| 9 | Pre-Calculus, Logarithms, Binomial Theorem, Parametric Equations, Numerical Methods |
| 10 | Limits, Differentiation, Integration, Differential Equations, Complex Numbers |
| 11 | Advanced Integration, Series, Further Calculus, Mechanics, Statistics 2 |
| 12 | Multivariable Calculus, Linear Algebra, Real Analysis, Abstract Algebra, Number Theory |
There are 31 badges across five categories. Most are earned automatically as you use the app.
| Badge | How to earn |
|---|---|
| 👣 First Step | Answer your first question |
| 🔟 Getting Going | Answer 10 questions total |
| 💯 Century | Answer 100 questions total |
| 🚀 Five Hundred | Answer 500 questions total |
| 🌟 The Thousand | Answer 1000 questions total |
| Badge | How to earn |
|---|---|
| ⬆️ Level Up | Advance to the next level |
| 📈 Getting Serious | Reach Level 3 |
| 🏅 Halfway There | Reach Level 5 |
| 🎓 Advanced Scholar | Reach Level 7 |
| 🏆 Expert | Reach Level 10 |
| 👑 Grandmaster | Reach Level 12 |
| Badge | How to earn |
|---|---|
| ⭐ Perfect Score | Score 5/5 on any quiz |
| 🌠 Hat-Trick Ace | Score 5/5 on three quizzes |
| 🧠 No Hints Needed | Complete a quiz without using a hint |
| 🎯 Sharpshooter | Keep 90%+ accuracy over 20+ questions |
| 🔩 Iron Accuracy | Keep 95%+ accuracy over 50+ questions |
| ⚡ Speed Runner | Pass a Level Test |
| 💥 Test Crusher | Pass 3 Level Tests |
| Badge | How to earn |
|---|---|
| 🔥 Daily Grind | Answer 10 questions in a day |
| 🌋 On Fire | Answer 30 questions in a day |
| ⚡ Unstoppable | Answer 50 questions in a day |
| 🎩 Hat-Trick | Answer questions 3 days in a row |
| 📅 Week Warrior | Answer questions 7 days in a row |
| 🗓️ Monthly Master | Answer questions 30 days in a row |
| Badge | How to earn |
|---|---|
| ∫ Calculus Master | Complete all Differentiation & Integration quizzes |
| Σ Series Master | Complete all Series & Further Calculus quizzes |
| α Algebra Master | Complete all Advanced & Abstract Algebra quizzes |
| 📐 Geometry Master | Complete all Geometry & Circle Theorems quizzes |
| 📊 Stats Master | Complete all Statistics & Probability quizzes |
| 🔢 Number Theorist | Complete all Number Theory quizzes |
| 📡 Trig Master | Complete all Trigonometry quizzes |
| 🧮 Linear Algebra Master | Complete all Vectors & Linear Algebra quizzes |
| ⚙️ Mechanics Master | Complete all Mechanics quizzes |
| 📜 Proof Master | Complete all Proof & Real Analysis quizzes |
| 🌐 Multivariable Master | Complete all Multivariable Calculus quizzes |
| Version | Summary |
|---|---|
| v1.2 | Batch question generation (~10x faster), locked answer display, double-save fix, 31 badges, medal UI, gradient progress bar |
| v1.1 | Assignment pre-generation, answer switching fix, progress bar redesign |
| v1.0 | Initial release |
Built by @Kflone5 and @anonimwindows228
Free to use · No ads · Grades 1 to 12 · Powered by AI