Multi-Agent Math Teaching System

A sophisticated multi-agent system for teaching mathematics with interactive visualizations using Manim. This system uses a hierarchical agent architecture to understand user questions, generate mathematical explanations, and create educational visualizations.

🏗️ Architecture

The system consists of three specialized agents working together:

1. Orchestrator Agent

• Role: Main coordinator and user interface
• Responsibilities:
  • Analyzes user queries and determines knowledge gaps
  • Coordinates between other agents
  • Synthesizes final responses
  • Generates probing questions for better understanding

2. Math Specialist Agent

• Role: Mathematical reasoning and explanation
• Responsibilities:
  • Provides step-by-step mathematical explanations
  • Solves problems with detailed solutions
  • Tailors content to user's knowledge level
  • Identifies key concepts and common mistakes

3. Manim Coding Agent

• Role: Visualization creation and animation
• Responsibilities:
  • Translates explanations into Manim code
  • Creates educational animations and visualizations
  • Handles different visualization types (graphs, geometric constructions, etc.)
  • Optimizes visualizations for learning

🚀 Features

• Intelligent Query Analysis: Understands user questions and knowledge levels
• Adaptive Explanations: Tailors mathematical content to user expertise
• Rich Visualizations: Creates beautiful, educational animations using Manim
• Multi-format Support: Generates MP4, GIF, and other video formats
• REST API: Easy integration with web applications
• Comprehensive Logging: Detailed logging for debugging and monitoring
• Extensible Design: Easy to add new agents and capabilities

🚀 Quick Start with Docker (Recommended)

Option 1: Automated Setup

# Clone the repository
git clone <repository-url>
cd multi-agent-math-system

# Run the automated setup script
./scripts/setup.sh

Option 2: Manual Setup

# 1. Clone and navigate
git clone <repository-url>
cd multi-agent-math-system

# 2. Copy configuration
cp example-config.yaml config.yaml

# 3. Edit config.yaml with your API keys
nano config.yaml

# 4. Start with Docker Compose
docker-compose up -d

Option 3: Quick Start (if already configured)

./scripts/quick-start.sh

📦 Alternative Installation (Local Development)

If you prefer to run locally without Docker:

1. Clone the repository:

   git clone <repository-url>
   cd multi-agent-math-system

2. Install dependencies:

   pip install -r requirements.txt

3. Install Manim (if not already installed):

   # For Ubuntu/Debian
   sudo apt update
   sudo apt install build-essential python3-dev libcairo2-dev libpango1.0-dev ffmpeg
   
   # For macOS
   brew install cairo pango ffmpeg
   
   # Then install manim
   pip install manim

🎯 Usage

Docker Usage (Recommended)

Start the System

docker-compose up -d

Stop the System

docker-compose down

View Logs

docker-compose logs -f

Access the API

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Status: http://localhost:8000/status

Local Usage (Alternative)

Command Line Interface

Run the main script for interactive mode:

python main.py

REST API

Start the FastAPI server:

python -m src.api.fastapi_app

The API will be available at http://localhost:8000 with interactive docs at http://localhost:8000/docs.

API Endpoints

• POST /query - Process a math query and generate explanation with visualization
• POST /probing-questions - Get probing questions to better understand user needs
• GET /status - Get system status and capabilities
• GET /video/{filename} - Download generated video files
• GET /health - Health check endpoint

Example API Usage

import requests

# Process a query
response = requests.post("http://localhost:8000/query", json={
    "query": "Explain derivatives",
    "user_level": "intermediate"
})

result = response.json()
print(f"Explanation: {result['explanation']}")
print(f"Video: {result['visualization']['video_path']}")

Programmatic Usage

import asyncio
from src.core.multi_agent_system import MultiAgentMathSystem

async def main():
    # Initialize the system
    math_system = MultiAgentMathSystem()
    
    # Process a query
    result = await math_system.process_query("What is the derivative of x²?")
    
    print(f"Status: {result['status']}")
    print(f"Video: {result['visualization']['video_path']}")

asyncio.run(main())

🧪 Testing

Run the test suite:

# Run all tests
pytest

# Run specific test files
pytest tests/test_agents.py
pytest tests/test_system.py

# Run with coverage
pytest --cov=src

🐳 Docker Configuration

Features

• Optimized Build: Multi-stage Dockerfile for smaller image size
• Easy Setup: Runs as root for simple local development
• Health Checks: Automatic health monitoring
• Volume Mounts: Persistent data and easy configuration updates
• Resource Limits: Memory management for stable operation

Quick Commands

# Setup and start
./scripts/setup.sh

# Quick start (if configured)
./scripts/quick-start.sh


# View logs
docker-compose logs -f

# Stop system
docker-compose down

📁 Project Structure

multi-agent-math-system/
├── src/
│   ├── agents/           # Agent implementations
│   │   ├── orchestrator.py
│   │   ├── math_specialist.py
│   │   └── manim_coding.py
│   ├── core/             # Core system components
│   │   └── multi_agent_system.py
│   ├── tools/            # Specialized tools
│   │   └── manim_tool.py
│   ├── api/              # API implementation
│   │   └── fastapi_app.py
│   └── utils/            # Utility functions
│       └── logging_config.py
├── scripts/              # Setup and utility scripts
│   ├── setup.sh         # Automated setup script
│   ├── quick-start.sh   # Quick start script
│   └── deploy.sh        # Deployment script
├── docs/                 # Documentation
│   ├── GETTING_STARTED.md # Complete setup guide
│   ├── DOCKER_SETUP.md  # Docker setup guide
│   └── CUSTOMIZATION.md # Customization guide
├── example-configs/      # Example configurations
│   ├── config.openai.yaml
│   ├── config.anthropic.yaml
│   └── config.local.yaml
├── tests/                # Test files
├── output/               # Generated visualizations
├── logs/                 # Log files
├── media/                # Media files
├── main.py              # Main entry point
├── requirements.txt     # Dependencies
├── Dockerfile.optimized # Optimized multi-stage Dockerfile
├── docker-compose.yml   # Docker Compose configuration
├── config.yaml          # Configuration file
├── example-config.yaml  # Example configuration
└── README.md           # This file

🔧 Configuration

Logging

Configure logging in src/utils/logging_config.py:

from src.utils.logging_config import setup_logging

# Set up logging
setup_logging(
    level="INFO",           # DEBUG, INFO, WARNING, ERROR, CRITICAL
    log_file="system.log",  # Optional log file
    log_dir="logs"          # Log directory
)

Output Directory

Change the output directory for generated visualizations:

math_system = MultiAgentMathSystem(output_dir="my_visualizations")

🎨 Supported Visualization Types

• Function Graphs: Plot mathematical functions and their derivatives
• Geometric Constructions: Interactive geometric proofs and constructions
• Algebraic Manipulations: Step-by-step equation solving
• Statistical Plots: Data visualization and statistical concepts
• 3D Visualizations: Three-dimensional mathematical objects
• Animation Sequences: Complex multi-step mathematical processes
• Interactive Demos: User-controlled mathematical explorations

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Manim for beautiful mathematical animations
• Agno for the agent framework
• FastAPI for the REST API
• 3Blue1Brown for inspiration in mathematical visualization

📚 Documentation

• Getting Started Guide - Complete setup and usage guide
• Docker Setup Guide - Detailed Docker configuration
• Customization Guide - Advanced customization options
• API Documentation - Interactive API documentation (when running)

📞 Support

For questions, issues, or contributions, please open an issue on GitHub or contact the development team.