BinyamHuggingFace/k2math

K2Math - AI Math Tutorial Generator

AI-powered math tutorial video generator using Manim and Google Gemini. Creates structured, template-based educational videos with proper layout to avoid positioning errors.

Quick Start

# Install dependencies
uv sync

# Set API key
echo "GEMINI_API_KEY=your_key" > .env

# Run app
streamlit run app.py

Key Features

• —Template-Based Generation: Fixed layouts prevent object overlap
• —Grid Layouts: All content uses arrange_in_grid to prevent overflow
• —Smart Template Selection: Automatically chooses split-screen vs step-by-step
• —Multi-Stage AI Pipeline: Template selection → Outline → Content → Code generation

Templates

1. Split-Screen (Default for most problems)

• —Left: Animation/diagram/graph
• —Right: Solution steps in grid
• —Use for: Functions, geometry, physics, calculus

2. Step-by-Step

• —Centered content with grid layout
• —Use for: Pure algebra, equation solving (no visualization needed)

3. Graph Visualization

• —Axes on left, analysis steps on right
• —Automatic for questions with "graph", "plot", "function", "derivative"

Design Principles

✅ Always use `arrange_in_grid` - Prevents text overflow ✅ No `SurroundingRectangle` or circles - Positioning is unreliable ✅ Use bold/colors for emphasis - Safer than geometric highlighting ✅ Split-screen for most problems - Even equations benefit from visual space ✅ Auto-add graphs - Quadratic equations automatically get graphs

Project Structure

mathmanim/
├── app.py                  # Main Streamlit app (run this)
├── src/                    # Source code modules
│   ├── templates/          # Manim scene templates
│   ├── generators/         # AI generation pipeline
│   └── utils.py
├── assets/                 # Static files (CSS)
├── data/                   # Runtime data (chat history)
├── CLAUDE.md              # Architecture docs
└── README.md              # This file

How It Works

1. 1.Template Selection: Keyword matching (graph→splitscreen, solve→stepby_step)
2. 2.Outline Generation: AI creates high-level structure
3. 3.Content Generation: AI fills template slots with equations/explanations
4. 4.Code Assembly: Template generates valid Manim code with grid layouts
5. 5.Rendering: Manim renders the video

Configuration

Depth Levels

• —Low: 2-3 steps, basic
• —Med: 4-6 steps, moderate (default)
• —High: 6-8 steps, comprehensive

Video Quality

Edit app.py to change -qm to -ql (faster) or -qh (better quality)

Deployment

Hugging Face Spaces

This app is configured for Hugging Face Spaces deployment:

• —Writable directories: All temporary files use /tmp (writable in HF Spaces)
• —Media output: Manim renders to /tmp/media (see manim.cfg)
• —Logs: Generation metrics saved to /tmp/data/generation_metrics.csv
• —Docker: Dockerfile creates temp directories on build

No additional configuration needed for HF Spaces deployment.

Troubleshooting

Label warnings: Fixed - labels now provided to all Streamlit widgets

Text overflow: All templates use arrange_in_grid with 2 columns

Wrong template: Check keyword matching in tutorial_generator.py:69-86

LaTeX errors: Install texlive-full (Ubuntu) or mactex (macOS)

Permission errors on HF Spaces: Ensure all file operations use /tmp directory (already configured)

Example Questions

Solve the quadratic equation: x² + 5x + 6 = 0
Find the derivative of f(x) = x³ + 2x² - 5x + 1
A 5kg block slides down a 30° incline. Find acceleration.
Graph the function f(x) = x² - 4x + 3

Resources

• —Manim Docs
• —Manim Grouping Guide
• —CLAUDE.md - Detailed architecture

Built with Manim + Streamlit + Gemini AI