The Problem

Manual creation of high‑quality mathematical videos is time‑consuming and requires expertise in both proof writing and animation. Teams that need large libraries of instructional content must repeatedly hire subject‑matter experts, scriptwriters, and animators, which drives cost and slows release cycles.

What This Does

MathVizAI is an end‑to‑end pipeline that receives a math problem and produces a polished video, complete with narrated audio and Manim‑generated visuals. The repository is a portfolio of four self‑contained projects:

  • golden_set – 51 Python files that store curated “golden” Manim examples (e.g., _2015_complex_multiplication_article.py). These files are the source of the Retrieval‑Augmented Generation (RAG) vector store.
  • pipeline – 10 modules that orchestrate the multi‑agent workflow (pipeline/orchestrator.py, pipeline/solver.py, pipeline/evaluator.py, pipeline/video_generator.py, etc.).
  • utils – 5 helper modules (utils/file_manager.py, utils/llm_client.py, utils/RateLimiter.py, …) that wrap LLM calls, file I/O, and rate‑limiting.
  • src – a single entry point (main.py) that wires the orchestration together.

Key files: config.py (hub module imported by 13 others), pipeline/orchestrator.py (high instability, imports 11 other modules), and pipeline/video_generator.py (deep nesting, 8‑level indentation).

How It Is Wired

Execution starts at main.py (line 19). main() imports the PipelineOrchestrator from pipeline/orchestrator.py and calls its run() method, which triggers the following high‑impact call chain (counts are resolved static edges):

  1. construct (in many golden‑set classes) → play (351 callers) → Manim rendering.
  2. generate_single_audio (via self.model.generate in utils/llm_client.py) → external TTS service (Microsoft VibeVoice).
  3. embed (in embedding.py) → vector store lookup (_get_repo_store called from 8 places) → retrieval of relevant golden‑set snippets.

The hub module config.py is imported by 13 other modules; any change here has a wide blast radius. pipeline/orchestrator.py imports 11 downstream modules, making it the most unstable component (instability 0.92). The most frequently called functions—play, get_center, rotate, get_points—are defined in the golden‑set animation classes; they collectively drive the visual output.

No circular dependencies were detected, but deep nesting (max 8 levels) appears in utils/llm_client.py, pipeline/video_generator.py, and pipeline/tts_generator.py, increasing cognitive load for future maintainers. Broad except: blocks in pipeline/video_renderer.py, embedding.py, and pipeline/video_synchronizer.py swallow errors, reducing resilience.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/MathVizAI
cd MathVizAI

# Install Python dependencies
pip install -r requirements.txt

# Copy example env and fill in any required keys (e.g., API tokens)
cp .env.example .env   # edit .env as needed

# Run the pipeline on a single problem
python main.py

The README does not specify additional CLI flags or sub‑commands; the above reflects the only concrete entry point (main.py). If the repository later adds a configuration file for model credentials, they should be placed in .env as indicated by the example file.

Real‑World Use

A university’s online learning platform could invoke main.py for each new homework problem submitted by instructors. The platform would store the generated MP4 files (produced by the Manim play calls) alongside the original problem text, then embed the video URL in the course’s LMS. The same pipeline can be scheduled nightly to batch‑process a backlog of problems, feeding the vector store with new golden examples as they are created.

Code Health & Issues

  • High – No test suite – 74 source files, no tests.
  • High – No CI/CD workflow – repository lacks .github/workflows or other CI config.
  • Medium – No dependency lockfile – only requirements.txt; reproducible builds are not guaranteed.
  • Medium – Large binaries not LFS‑tracked – VectorStore/3b1b_videos/index.faiss (67 MB) and related blobs exceed 5 MB.

Additional measured findings (not repeated): deep nesting in three modules, duplicated 6‑line blocks across 28 golden‑set files, oversized files (> 1 900 lines) in the golden‑set, and file handles opened without context managers.

The Bottom Line

MathVizAI provides a compelling proof‑of‑concept for fully automated math video generation, with a clear modular pipeline and a reusable “golden set” RAG component. However, the codebase suffers from a lack of tests, CI, and proper binary handling, and several modules are overly complex. It is suitable for teams prepared to invest in refactoring and adding an engineering safety net before using it in production.