README.md

metadata

title: PDF → Manim → LLM App
emoji: 🎬
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 6.8.0
python_version: '3.11'
app_file: app.py
pinned: false

🎬 PDF → Manim Animation Pipeline

A Hugging Face Spaces Gradio app that converts any PDF into an animated Manim video and delivers it to your inbox.

---

🚀 Quick Start

1. Upload to Hugging Face Spaces

Create a new Space on huggingface.co/spaces with:

• SDK: Gradio
• Hardware: CPU Basic (or better — more RAM = faster renders)

Upload all files in this folder.

---

2. Set Environment Secrets

In your Space settings → Secrets, add:

Secret Name	Value
SMTP_EMAIL	Your Gmail address (e.g. you@gmail.com)
SMTP_PASSWORD	Gmail App Password (16-char, not login pw)

How to get a Gmail App Password:

1. Enable 2-Step Verification on your Google account.
2. Go to myaccount.google.com/apppasswords.
3. Create a new app password for "Mail".

⚠️ Never commit secrets to your repo. Only use the Spaces secret store.

---

3. Usage

1. Open your Space URL.
2. Upload a PDF file.
3. Enter your email address (saved in browser — no need to re-enter).
4. Enter your Gemini API key (saved in browser) — get one free at aistudio.google.com.
5. Click Generate Video.
6. Watch live status updates — the generated Manim code appears in-app, and the video arrives in your inbox!

---

🏗️ Architecture

PDF Upload
    │
    ▼
Extract Text (pypdf)
    │
    ▼
Gemini 2.5 Flash (google-genai)
    │  → generated code shown live in UI
    ▼
Manim Render (-qm, 1280×720, 30fps)
    │
    ▼
Video < 24MB?  ──YES──▶ Email Attachment
    │                        │
   NO                        │
    ▼                        │
Catbox.moe Upload            │
    │                        │
    ▼                        │
Email Link ◀─────────────────┘
    │
    ▼
Cleanup temp files

---

⚙️ Configuration

Setting	Default	Location
Max concurrent jobs	100	app.py → JobQueue(max_jobs=)
Thread workers	8	app.py → JobQueue(max_workers=)
Manim quality	-qm 720p30	pipeline.py → _render_manim
Render timeout	600s	pipeline.py → _render_manim
Catbox retries	5	utils.py

---

📁 File Structure

.
├── app.py              # Gradio UI + streaming status + BrowserState persistence
├── pipeline.py         # Job pipeline orchestrator
├── queue_manager.py    # Thread-pool queue with state tracking
├── utils.py            # PDF, Gemini, email, Catbox helpers
├── requirements.txt    # Python dependencies
├── packages.txt        # System packages (LaTeX, ffmpeg, cairo…)
└── README.md           # This file

---

🔒 Security Notes

• Gemini API keys are passed per-request and never stored server-side.
• Email/API key persisted in browser localStorage (client only).
• SMTP credentials live only in HF Secrets (env vars).
• All temporary files deleted after pipeline completion.
• Each job uses a UUID to prevent path collisions.

---

🐛 Troubleshooting

Issue	Fix
SMTP_EMAIL not set	Add the secret in HF Space settings
latex not found	Ensure packages.txt is in your Space root
Render timeout	Use a higher-tier Space hardware
Gemini API error	Check your API key and quota
Empty PDF	PDF must have selectable text (not scanned image)
Large video	Catbox fallback used automatically