npm package: @nishant1195/manim-ai-fixer
Description: AI-powered Manim animation generator with automatic error fixing using Google Gemini
Author: Your Name
Latest version: 1.0.1

# 🎬 Manim AI Fixer

AI-powered Manim animation generator with automatic error fixing. Uses Google's Gemini AI to generate and self-correct Manim code until it works.

[![npm version](https://badge.fury.io/js/manim-ai-fixer.svg)](https://www.npmjs.com/package/manim-ai-fixer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🤖 **AI-Powered Code Generation** - Describe animations in plain English
- 🔄 **Automatic Error Fixing** - AI detects and fixes errors automatically (up to 5 iterations)
- 🎥 **Video Output** - Generates MP4 animations ready to use
- 💾 **Saves Working Code** - Keeps the final Python code for reference
- 🎨 **Simple CLI** - Easy command-line interface
- ⚡ **Fast & Free** - Uses Google's free Gemini API

## 📋 Prerequisites

Before installing, ensure you have:

### 1. Node.js (v18.0.0 or higher)
```bash
node --version
```
**Download:** https://nodejs.org/

### 2. Python (3.8 or higher)
```bash
python --version
```
**Download:** https://python.org/

### 3. Manim Community Edition
```bash
pip install manim
# Verify installation
manim --version
```
**Documentation:** https://docs.manim.community/

### 4. FFmpeg (Required by Manim)
```bash
ffmpeg -version
```

**Installation by OS:**
- **macOS:** `brew install ffmpeg`
- **Ubuntu/Debian:** `sudo apt install ffmpeg`
- **Windows:** Download from https://ffmpeg.org/download.html

### 5. Google Gemini API Key (Free)
1. Visit: https://makersuite.google.com/app/apikey
2. Sign in with Google account
3. Click **"Create API Key"**
4. Copy the key (format: `AIzaSy...`)

**Free tier limits:** 60 requests/minute, 1500 requests/day

---

## 🚀 Quick Start

### 1. Install globally
```bash
npm install -g manim-ai-fixer
```

### 2. Set your API key

**Windows (PowerShell):**
```powershell
$env:GEMINI_API_KEY="your_api_key_here"
```

**Windows (Command Prompt):**
```cmd
set GEMINI_API_KEY=your_api_key_here
```

**macOS/Linux:**
```bash
export GEMINI_API_KEY="your_api_key_here"
```

### 3. Create your first animation
```bash
manim-ai "Create a blue circle that grows and turns red"
```

### 4. Find your video
```bash
ls output/
# output_1234567890.mp4 ← Your video!
```

---

## 📖 Usage

### Basic Syntax
```bash
manim-ai "your animation description"
```

### Examples

**Simple Shapes:**
```bash
manim-ai "Create a red square"
manim-ai "Show a triangle transforming into a circle"
manim-ai "Draw a blue pentagon"
```

**Animations:**
```bash
manim-ai "Create a circle that rotates 360 degrees"
manim-ai "Show text 'Hello World' that fades in"
manim-ai "Make a square that moves from left to right"
```

**Mathematical Visualizations:**
```bash
manim-ai "Graph the function y = x squared from -3 to 3"
manim-ai "Show a unit circle with sine and cosine"
manim-ai "Visualize the Pythagorean theorem with animated squares"
```

**Complex Animations:**
```bash
manim-ai "Create three circles in a triangle formation that rotate together"
manim-ai "Show a sine wave animating from left to right with a red dot tracing it"
manim-ai "Animate the formula E = mc² with each letter appearing one by one"
```

---

## ⚙️ Configuration

### Option 1: Environment Variables (Temporary)

Set before each use:
```bash
# Windows PowerShell
$env:GEMINI_API_KEY="your_key"
$env:MAX_ITERATIONS="5"
$env:MANIM_QUALITY="ql"

# macOS/Linux
export GEMINI_API_KEY="your_key"
export MAX_ITERATIONS="5"
export MANIM_QUALITY="ql"
```

### Option 2: .env File (Permanent - Recommended)

Create a `.env` file in your working directory:

```bash
GEMINI_API_KEY=your_api_key_here
MAX_ITERATIONS=5
MANIM_QUALITY=ql
TIMEOUT_MS=60000
```

### Configuration Options

| Variable | Default | Description |
|----------|---------|-------------|
| `GEMINI_API_KEY` | *required* | Your Google Gemini API key |
| `MAX_ITERATIONS` | `5` | Maximum retry attempts for error fixing |
| `MANIM_QUALITY` | `ql` | Video quality: `ql` (low/fast), `qm` (medium), `qh` (high) |
| `TIMEOUT_MS` | `60000` | Execution timeout in milliseconds (60 seconds) |

---

## 📂 Output

After successful execution, find your files in the `output/` folder:

```
output/
├── output_1234567890.mp4      # Your generated animation video
└── final_code_1234567890.py   # The working Python/Manim code
```

You can:
- Share the video directly
- Edit the Python code for customization
- Learn from the generated code

---

## 🔄 How It Works

1. **Input** - You describe the animation in plain English
2. **Generate** - Gemini AI creates Manim Python code
3. **Execute** - Code runs with Manim to create video
4. **Check** - If errors occur, AI analyzes them
5. **Fix** - AI corrects the code automatically
6. **Retry** - Repeats up to 5 times until success
7. **Output** - Saves both video and working code

---

## 🐛 Troubleshooting

### ❌ "GEMINI_API_KEY not found"

**Solution:**
```bash
# Set the environment variable
export GEMINI_API_KEY="your_key_here"

# Or create a .env file (see Configuration section)
```

### ❌ "python not found" or "manim not found"

**Solution:**
```bash
# Install Python from python.org
# Then install Manim
pip install manim

# Verify
python --version
manim --version
```

### ❌ "FFmpeg not found"

**Solution:**
Install FFmpeg for your OS (see Prerequisites section)

### ❌ API Rate Limit Exceeded

**Issue:** Free tier allows 60 requests/minute

**Solution:**
- Wait 1 minute and try again
- Reduce `MAX_ITERATIONS` in config
- Consider Google AI Studio paid tier for higher limits

### ❌ Execution Timeout

**Issue:** Complex animations take too long

**Solution:**
```bash
# Increase timeout (in .env or environment)
TIMEOUT_MS=120000  # 2 minutes
```

### ❌ Code Still Fails After 5 Iterations

**Solution:**
- Try simplifying your prompt
- Break complex animations into smaller parts
- Check the generated code in `temp/` folder for issues
- Manually edit the Python code and run with `manim` directly

---

## 💡 Tips for Best Results

### ✅ Good Prompts
- **Specific:** "Create a blue circle that rotates clockwise"
- **Simple:** Start with basic shapes and animations
- **Clear:** "Show a square transforming into a triangle"

### ❌ Avoid
- **Vague:** "Make something cool"
- **Too complex:** "Create a full quantum physics simulation with 50 objects"
- **Ambiguous:** "Do the thing with colors"

### 🎯 Prompt Examples by Difficulty

**Beginner:**
```bash
manim-ai "Create a green circle"
manim-ai "Show a red square"
```

**Intermediate:**
```bash
manim-ai "Create a circle that transforms into a square"
manim-ai "Show text 'Hello' that fades in and out"
```

**Advanced:**
```bash
manim-ai "Graph sine and cosine functions on the same axes"
manim-ai "Visualize a binary search tree with 7 nodes"
```

---

## 🏗️ Development

### Clone and Setup

```bash
git clone https://github.com/yourusername/manim-ai-fixer.git
cd manim-ai-fixer
npm install
```

### Create .env file

```bash
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
```

### Run Locally

```bash
npm start "Create a simple circle"
```

### Project Structure

```
manim-ai-fixer/
├── src/
│   ├── index.js           # Main orchestrator & entry point
│   ├── gemini-service.js  # Gemini AI API service
│   ├── manim-runner.js    # Manim code executor
│   ├── config.js          # Configuration loader
│   └── utils.js           # Helper functions (logging, formatting)
├── bin/
│   └── cli.js             # CLI entry point for npm
├── output/                # Generated videos and code
├── temp/                  # Temporary Python files
├── .env                   # Your API keys (not in git)
├── .gitignore            # Git ignore patterns
├── package.json          # npm configuration
└── README.md            # This file
```

---

## 🔧 Advanced Usage

### Using with npm scripts

If you clone the repository:

```bash
# Run with default test prompt
npm test

# Run with custom prompt
npm start "your prompt here"

# Development mode (auto-reload)
npm run dev
```

### Programmatic Usage

```javascript
import { ManimPipeline } from 'manim-ai-fixer';

const pipeline = new ManimPipeline();
await pipeline.run("Create a rotating cube");
```

### Custom Configuration

```javascript
import { config } from 'manim-ai-fixer/src/config.js';

// Override defaults
config.maxIterations = 10;
config.manimQuality = 'qh';  // High quality
```

---

## 📊 System Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Node.js | 18.0.0 | Latest LTS |
| Python | 3.8 | 3.10+ |
| RAM | 4GB | 8GB+ |
| Disk Space | 2GB | 5GB+ |
| Internet | Required | Stable connection |

---

## 🤝 Contributing

Contributions are welcome! Here's how:

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

### Development Guidelines

- Follow existing code style
- Add comments for complex logic
- Test thoroughly before submitting
- Update README if adding features

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

---

## 🙏 Acknowledgments

- **Manim Community** - Amazing animation library
  - Website: https://www.manim.community/
  - GitHub: https://github.com/ManimCommunity/manim
  
- **Google Gemini AI** - Powerful AI model
  - Website: https://deepmind.google/technologies/gemini/
  
- **FFmpeg** - Video processing
  - Website: https://ffmpeg.org/

---

## 📞 Support & Contact

- **Issues:** [GitHub Issues](https://github.com/yourusername/manim-ai-fixer/issues)
- **Discussions:** [GitHub Discussions](https://github.com/yourusername/manim-ai-fixer/discussions)
- **npm:** [Package Page](https://www.npmjs.com/package/manim-ai-fixer)

---

## 🎓 Learn More

### Manim Resources
- [Official Documentation](https://docs.manim.community/)
- [Example Gallery](https://docs.manim.community/en/stable/examples.html)
- [Discord Community](https://discord.gg/mMRrZQW)

### Google Gemini AI
- [API Documentation](https://ai.google.dev/docs)
- [Pricing](https://ai.google.dev/pricing)

---

## ⭐ Show Your Support

If this project helped you, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting features
- 📢 Sharing with others

---

## 📈 Changelog

### Version 1.0.0 (2024)
- ✨ Initial release
- 🤖 Gemini AI integration
- 🔄 Automatic error fixing
- 🎥 Video generation
- 📝 Code saving

---

## 🔮 Roadmap

- [ ] Support for more AI models (Claude, GPT-4)
- [ ] Interactive prompt builder
- [ ] Animation templates library
- [ ] Web-based UI
- [ ] Batch processing
- [ ] Custom styling presets

---

**Made with ❤️ using AI and Manim**

```
 ___  ___            _              ___  _____   ______  _
 |  \/  |           (_)            / _ \|_   _| |  ___|(_)
 | .  . |  __ _  _ __  _  _ __ _ | |_| | | |   | |_    _ __  __ ___  _ __
 | |\/| | / _` || '_ \| || '_ ` ||  _  | | |   |  _|  | |\ \/ // _ \| '__|
 | |  | || (_| || | | || || | | || | | |_| |_  | |    | | >  <|  __/| |
 \_|  |_/ \__,_||_| |_||_||_| |_|\_| |_/\___/  \_|    |_|/_/\_\\___||_|
```

---

**Happy Animating! 🎬✨**