DEPLOY_TO_HF.md

🚀 Quick Deployment Guide for Hugging Face Spaces

This is a quick reference for deploying NeuroAnim to Hugging Face Spaces.

Prerequisites

✅ You have created a Hugging Face Space ✅ You have your API keys ready

Step-by-Step Deployment

1. Create Your Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in:
   • Owner: Your username
   • Space name: neuroanim (or your choice)
   • License: MIT
   • Select the SDK: Gradio
   • Space hardware: CPU basic (free) - can upgrade later
4. Click "Create Space"

2. Configure Secrets (IMPORTANT!)

1. Go to your Space → Settings → Variables and secrets

2. Add these secrets:

   HUGGINGFACE_API_KEY = your_huggingface_token_here
   

   Optional (but recommended):

   ELEVENLABS_API_KEY = your_elevenlabs_key_here
   BLAXEL_API_KEY = your_blaxel_key_here
   MANIM_SANDBOX_IMAGE = your_sandbox_image_here
   

3. Click "Save" for each secret

3. Push Your Code

You have two options:

Option A: Using Git (Recommended)

# Navigate to your project
cd "/media/bhaves/Volume 2/manim-agent"

# Add HF Space as remote (replace YOUR_USERNAME and YOUR_SPACE_NAME)
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# Create a deployment branch (optional but recommended)
git checkout -b hf-deploy

# Copy the HF-specific README
cp README_HF.md README.md

# Add and commit deployment files
git add requirements.txt README.md app.py orchestrator.py
git add mcp_servers/ utils/ neuroanim/ manim_mcp/
git add pyproject.toml .gitignore
git commit -m "Initial Hugging Face Space deployment"

# Push to HF Space
git push space hf-deploy:main

Option B: Web Upload (Easier but slower)

1. Go to your Space → Files and versions tab
2. Click "Add file" → "Upload files"
3. Upload these files/folders:
   • app.py ⭐ (main entry point)
   • requirements.txt ⭐ (dependencies)
   • README_HF.md → rename to README.md ⭐
   • orchestrator.py
   • pyproject.toml
   • Folders: mcp_servers/, utils/, neuroanim/, manim_mcp/
4. Click "Commit changes to main"

4. Monitor Build

1. Go to your Space → App tab
2. Watch the build logs (bottom of page)
3. Wait 5-10 minutes for first build
4. Look for: Running on public URL: https://...

5. Test Your Space

Once deployed:

1. Enter a topic: "Pythagorean Theorem"
2. Select audience: "high_school"
3. Duration: 2 minutes
4. Quality: "Medium"
5. Click "Generate Animation"
6. Wait for generation (may take 3-5 minutes)
7. Verify video plays and downloads work

Troubleshooting

Build Fails

• Check Logs tab for errors
• Verify requirements.txt is correct
• Ensure all files are uploaded

"API Key Not Set" Error

• Go to Settings → Variables and secrets
• Add HUGGINGFACE_API_KEY
• Restart Space (Settings → Factory reboot)

Slow or Timeout

• Upgrade hardware: Settings → Change hardware
• Try GPU T4 for faster rendering
• Reduce animation duration for testing

Import Errors

• Check all folders are uploaded (mcp_servers/, utils/, etc.)
• Verify folder structure matches local

Hardware Recommendations

Hardware	Cost	Best For
CPU basic	Free	Testing, demos
CPU upgrade	$0.03/hr	Light usage
GPU T4	$0.60/hr	Production, fast rendering

Next Steps

✅ Share your Space URL with others ✅ Enable community features (Settings → Visibility) ✅ Add example videos to README ✅ Monitor usage in Analytics tab

Getting Your Space URL

Your Space will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

Share this link to let others use your animation generator!

---

Need help? Check the full deployment guide in implementation_plan.md