# Interactive 3D math lessons with a live AI tutor

Explore algebra, calculus, and physics through visual scenes you can question, manipulate, and learn from.

## See It in Action

## Vision

AlgeBench transforms AI from an answer machine into a learning companion. It builds interactive mathematical worlds, performs the tedious work, and reveals the structures worth exploring, while preserving the joy of discovery for the learner. Always available, it serves as an infinitely patient tutor, helping users develop genuine understanding rather than simply consume answers.

Spin up a lesson, move the sliders, rotate the model, listen to the explanation, then interrupt with what, how, or why. The narrator answers in real time while the visualization stays connected to the math.

## Who It's For

🎓

### Students

Build intuition by manipulating equations, surfaces, vectors, and proofs instead of only memorizing formulas.

👩‍🏫

### Educators

Create guided lessons that let students explore ideas at their own pace with narration, sliders, and visual checkpoints.

📖

### Self-Learners

Teach yourself with an AI tutor that can explain the current scene, answer follow-up questions, and adapt to your level.

🛠️

### Builders

Prototype mathematical scenes, lesson formats, and AI-assisted learning workflows on top of an open source stack.

## What Makes AlgeBench Different

#### 3D Scenes

Spin, zoom, and inspect mathematical objects in scenes that respond to your input

🗣️

#### Live AI Narrator

Ask questions out loud while the tutor explains the scene and answers in context

🧮

#### Visual Proofs

Step through derivations with highlighted changes tied back to the visual model

🌐

#### Semantic Graphs

See variables, operators, and relationships as an interactive map of the equation

🤖

#### Scene Generation

Turn mathematical ideas into interactive lessons with narration, sliders, and visual structure

🔓

#### Open Source

Study the code, extend the lesson format, or adapt the project for your own courses

## Run Locally

Run AlgeBench on your own machine in one of two ways. Either way you'll need a free Gemini API key.

### Option 1 — Clone the repo

Requires Python 3.10+. The launcher sets up its virtual environment and installs dependencies on first run.

    git clone https://github.com/ibenian/algebench
    cd algebench
    export GEMINI_API_KEY=your_key_here
    ./algebench

Then open localhost:8785 in your browser.

### Option 2 — Docker image from Hugging Face

No clone, no Python setup — just Docker. Runs the prebuilt image from the Hugging Face Space registry.

    docker run -it --pull=always -p 7860:7860 --platform=linux/amd64 \
      -e GEMINI_API_KEY="your_key_here" \
      registry.hf.space/ibenian-algebench:latest

Then open localhost:7860 in your browser. `--pull=always` fetches the newest build; `--platform=linux/amd64` is needed on Apple Silicon and other ARM hosts.

## Frequently Asked Questions

- Can I use AlgeBench online right now?
  Yes! The production app is live at algebench.org. There's also a staging environment at algebench-staging.onrender.com where upcoming features are previewed. You can still run it locally for development — see the Getting Started section.
- Why run locally?
  It's faster, and you get to use your own `GEMINI_API_KEY` — billed to your own account — instead of the shared public key on the hosted version, which is rate-limited across all visitors.
- What do I need to run it locally?
  Just a `GEMINI_API_KEY` environment variable. You can create one for free at Google AI Studio. We recommend making a dedicated key for AlgeBench so you can track API usage separately. See the Run Locally section above for the exact commands.
- What does AlgeBench use the Gemini API for?
  It powers two core features: an AI tutor you can ask questions to that understands the full lesson context — giving you intelligent, relevant answers as you learn — and real-time text-to-speech so the tutor can speak to you naturally as you explore.
- Does AlgeBench support other AI models?
  Not at the moment. We're prioritizing improving the learning experience before expanding model support. Multi-model compatibility is something we'll consider in the future.

## Follow the Demos

Watch walkthroughs, experiments, and new scene demos on the AlgeBench YouTube channel.

Try the hosted app instantly, or clone the repo to run it locally and contribute.

Try It Live Blog Get Started on GitHub Developer Dashboard