How hypercluster-tech/manimator works
Project Type and Purpose
• This is a full-stack styled, AI-driven visualization service that exposes both a REST API (FastAPI) and a web UI (Gradio).
• Purpose: Take research papers (ArXiv PDFs) or free-form prompts, generate scene descriptions via LLMs, render animations with Manim, and return MP4 videos.
High-Level Components
a. Presentation Layer
• Gradio Web UI (manimator/gradio_app.py) running on port 7860
• SwaggerUI on FastAPI docs (localhost:8000/docs)
b. API Layer (FastAPI)
• Entrypoint: manimator/main.py
• Endpoints organized under manimator/api/:
• scene_description.py (PDF and prompt→scene description)
• animation_generation.py (scene description→animation)
c. Application/Domain Layer
• SceneDescriptionService (uses utils/system_prompts.py, few_shot/few_shot_prompts.py)
• AnimationService (invokes Manim CLI/programmatic API with quality flags)
d. Infrastructure Layer
• LLM Providers (DeepSeek-V3, Llama 3.3 70B, Gemini via LiteLLM)
• PDF fetcher (ArXiv downloader / multipart upload)
• Manim engine (renders .py scenes → .mp4)
• Local file system for temp storage (.gradio/cached_examples, /tmp directories)
• Configuration via .env (model endpoints, API keys)
e. Deployment
• Docker container (Dockerfile)
• Poetry or pip for Python dependencies (pyproject.toml, requirements.txt)
Component Interactions and Data Flow
1. User submits a request via:
• Gradio UI → HTTP POST to Gradio server
• Or cURL / client → FastAPI endpoint
2. FastAPI routes request to the appropriate handler in manimator/api/.
3. Scene Description Phase
• For PDF: download ArXiv PDF → compress → parse → call LLM provider(s) with system prompts & few-shot examples.
• For text prompt: directly call LLM.
• Output: JSON { scene_description: "…" } (Pydantic schema in utils/schema.py).
4. Animation Generation Phase
• Handler receives scene description → writes a Manim scene file → invokes Manim CLI or Python API with quality flags → generates MP4.
• Cleans up temp files.
5. Response: returns video file (video/mp4) to client.
Architectural Patterns & Design Principles
• Layered Architecture: clear separation between Presentation (UI), API, Domain logic, and Infrastructure.
• Modularization:
• api package encapsulates HTTP logic.
• utils holds shared helper functions, schemas, system prompts.
• few_shot and examples for sample prompts & demo videos.
• Dependency Injection: environment variables control LLM provider endpoints; easy to swap providers.
• Single Responsibility: each module handles one concern (PDF processing, scene generation, animation rendering).
Essential Elements to Capture
• Entrypoints (Gradio & FastAPI)
• Core services (scene generation vs. animation generation)
• External dependencies (LLMs, ArXiv PDF)
• Data schemas (Pydantic) and temp storage
• Deployment boundary (Docker)