Explorion

Transform research papers, GitHub repositories, and technical content into visual stories

Quick Setup

Prerequisites

• Node.js 18+
• Python 3.8+
• Docker & Docker Compose (optional)

Automated Setup

Run the setup script for your platform:

Linux/Mac:

./setup.sh

Windows:

setup.bat

The script will:

• ✅ Check all prerequisites
• ✅ Create Python virtual environment
• ✅ Install backend dependencies
• ✅ Install frontend dependencies
• ✅ Create environment files
• ✅ Provide next steps

Manual Setup

If you prefer manual setup, see SETUP.md for detailed instructions.

How It Works

1. Ingest: Paste any arXiv paper, GitHub repository, or technical article URL and watch as it's decomposed into digestible sections
2. Analyze: AI agents analyze each section to identify key concepts and visual opportunities
3. Generate: Multi-agent pipeline creates 3Blue1Brown-style Manim animations for complex ideas
4. Validate: Four-stage quality gates ensure syntactic correctness, spatial coherence, and runtime stability
5. Experience: Read through an interactive scrollytelling interface with embedded animated visualizations

---

Technical Architecture

Explorion consists of two main parts:

• Backend (Python): Uses FastAPI, uv for dependency management, Dedalus SDK for AI orchestration, and Manim for video generation.
• Frontend (Node.js): A Next.js 15 application utilizing Tailwind CSS and shadcn/ui.

---

Detailed Local Setup

Follow these steps to run Explorion on your local machine.

1. Prerequisites

You must have the following system dependencies installed before running the project:

• Node.js (v18 or higher)
• Python (v3.11 or higher)
• uv: The fast Python package installer (pip install uv or natively via curl/powershell)
• Manim Engine Dependencies: (FFmpeg, Cairo, Pango)
  • Windows: Use Chocolatey (choco install ffmpeg pango cairo) or install them manually and add to PATH. Alternatively, follow Manim's Windows Guide.
  • macOS: brew install ffmpeg cairo pango pkg-config
  • Linux (Ubuntu/Debian): sudo apt install ffmpeg libcairo2-dev libpango1.0-dev pkg-config

2. Backend Setup

The backend handles AI generation, web scraping, and Manim video rendering.

1. Navigate to the backend directory:

   cd backend

2. Set up environment variables:

   cp .env.example .env

   Open the newly created .env file and add your API keys:

   • DEDALUS_API_KEY: Required for the LLM agents to function. Get it from Dedalus Labs.
   • GITHUB_TOKEN: (Optional but recommended) For scraping GitHub repositories without hitting API rate limits.
   • TTS_PROVIDER: Set to gtts for free TTS, or configure openai / elevenlabs if you have keys.

3. Install Python dependencies using uv:

   uv sync

   (This will automatically create a virtual environment and install all requirements from uv.lock / pyproject.toml)

4. Start the FastAPI backend server:

   uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

   The API will now be running at http://localhost:8000.

3. Frontend Setup

The frontend provides the interactive scrollytelling interface.

1. Open a new terminal tab/window and navigate to the frontend directory:

   cd frontend

2. Set up frontend environment variables:

   cp .env.local.example .env.local  # If the example file exists

   Ensure inside .env.local that NEXT_PUBLIC_API_URL points to your backend (default is http://localhost:8000). If you want to bypass the backend for frontend UI testing, you can set NEXT_PUBLIC_USE_MOCK=true.

3. Install Node dependencies:

   npm install

4. Start the frontend development server:

   npm run dev

   The UI will now be running at http://localhost:3000.

4. Running Your First Project

1. Open your browser and navigate to http://localhost:3000
2. Enter an arXiv URL (e.g., https://arxiv.org/abs/2508.12111) or a GitHub repository link.
3. Wait as the multi-agent system fetches the text, writes the Manim scripts, and renders the videos. (Monitor your backend terminal for processing logs and any rendering errors).

---

Inspiration

Research papers and complex technical documentation often arrive as monoliths — dense, opaque, intimidating. Within them lies a mosaic of brilliant ideas waiting to be seen.

Explorion transforms fragments of academic text and technical content into animated visual explanations, making complex research and codebases accessible to everyone.

---

Features

Multi-Agent Pipeline Architecture

Explorion uses a sophisticated multi-agent system powered by AI orchestration:

1. Summarizer Agent: Extracts 5 key concepts from any source material
2. Visualization Planner Agent: Converts concepts into detailed scene briefs for animation
3. Manim Coder Agent: Generates production-quality Python animation code
4. Render Engine: Converts Manim code to 3Blue1Brown-style MP4 videos
5. Spatial Validator: Ensures all visual elements fit within frame bounds
6. Section Analyzer: Groups visualizations by paper section for scrollytelling

Supported Content Types

• arXiv Research Papers — Full paper parsing with section extraction
• GitHub Repositories — README and code documentation analysis
• Technical Blog Posts — URL-based content ingestion
• Raw Text/Markdown — Custom documentation and articles

Quality Assurance

Four-stage validation pipeline ensures:

• ✅ Syntactic correctness (valid Manim Python)
• ✅ Spatial coherence (objects within frame bounds)
• ✅ Visual consistency (colors, fonts, layout standards)
• ✅ Runtime stability (successful video rendering)

Interactive Frontend

• Scrollytelling Interface: Read paper sections with embedded videos
• Section Navigation: Jump between concepts with floating dock
• Progress Tracking: See generation status in real-time
• Document Library: Browse all processed content

---

Project Status & Known Issues

Current Enhancement in Progress

Issue: When processing arXiv papers:

• Only 1 visualization video is generated instead of multiple (one per section)
• Videos lack explanatory titles/text identifying the concept

Root Cause:

• Section filtering threshold too aggressive (40-character minimum explanation)
• Manim prompt explicitly forbids displaying descriptive text

Solution: See ISSUE_ANALYSIS.md for detailed technical breakdown and fix instructions.

---

Authors

Created by: Jatin Tilwani and Vardan Agarwal

---

License

This project is open source. Please refer to the LICENSE file for details.

---

Contributing

Contributions are welcome! Please ensure you:

• Follow the existing code style
• Update tests and documentation
• Run validation pipelines before submitting PRs
• Reference any related issues in your PR description

---

Support & Documentation

• Architecture Details: See docs/ARCHITECTURE.md
• Deployment Guide: See docs/DEPLOY.md
• Setup Issues: Check docs/SETUP.md
• Issue Analysis: See ISSUE_ANALYSIS.md