# showlab/code2video architecture

> Architecture diagram of the GitHub repository showlab/code2video, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/showlab/code2video
- Repository: https://github.com/showlab/code2video

## Overview

##### Project type and purpose
- This is an **open-source, full-pipeline tool** for **automated educational video generation** (“Code2Video”), driven by a **tri-agent architecture** (Planner, Coder, Critic) that leverages LLMs and executable Manim code.

##### File structure
- Top-level directories:
- figures/ (static images for README)
- json_files/ (topic lists, mappings, quiz data)
- prompts/ (prompt templates and classes for each agent stage)
- src/ (core orchestration, utilities, configs, eval scripts, shell runners)
- Key files in src/:
- agent.py — orchestrates the pipeline
- gpt_request.py & api_config.json — handles LLM calls
- external_assets.py — IconFinder/VLM integrations
- scope_refine.py & utils.py — support functions
- run_agent.sh / run_agent_single.sh — entry-point scripts
- eval_AES.py, eval_TQ.py — evaluation modules

##### README for additional insights
- Tri-Agent Design:
1. **Planner** – Expands a knowledge point into a storyboard.
2. **Coder** – Synthesizes and debugs Manim code.
3. **Critic** – Refines layout using a VLM.
- Dependencies: Python, Manim, LLM API (e.g. Claude-4-Opus), VLM API (Gemini), IconFinder API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Shell Scripts
    User["User"]:::external
    RunAgent["run_agent.sh"]:::code
    RunAgentSingle["run_agent_single.sh"]:::code
    User --> RunAgent
    User --> RunAgentSingle
    click RunAgent "https://github.com/showlab/code2video/blob/main/src/run_agent.sh"
    click RunAgentSingle "https://github.com/showlab/code2video/blob/main/src/run_agent_single.sh"

    %% Orchestrator
    Orchestrator["Orchestrator\nagent.py"]:::code
    RunAgent --> Orchestrator
    RunAgentSingle --> Orchestrator
    click Orchestrator "https://github.com/showlab/code2video/blob/main/src/agent.py"

    %% Data Stores
    json_files[(JSON Configs & Topics)]:::data
    assets[(Assets\nicons, references, videos)]:::data
    Orchestrator --> json_files
    Orchestrator --> assets
    click json_files "https://github.com/showlab/code2video/tree/main/json_files/"
    click assets "https://github.com/showlab/code2video/tree/main/assets/"

    %% Prompt Modules
    subgraph "Prompt Modules"
        BaseClass["base_class.py"]:::code
        Stage1["stage1.py"]:::code
        Stage2["stage2.py"]:::code
        Stage3["stage3.py"]:::code
        Stage4["stage4.py"]:::code
        Stage5Eva["stage5_eva.py"]:::code
        Stage5Un["stage5_unlearning.py"]:::code
    end
    Orchestrator --> BaseClass
    Orchestrator --> Stage1
    Orchestrator --> Stage2
    Orchestrator --> Stage3
    Orchestrator --> Stage4
    Orchestrator --> Stage5Eva
    Orchestrator --> Stage5Un
    click BaseClass "https://github.com/showlab/code2video/blob/main/prompts/base_class.py"
    click Stage1 "https://github.com/showlab/code2video/blob/main/prompts/stage1.py"
    click Stage2 "https://github.com/showlab/code2video/blob/main/prompts/stage2.py"
    click Stage3 "https://github.com/showlab/code2video/blob/main/prompts/stage3.py"
    click Stage4 "https://github.com/showlab/code2video/blob/main/prompts/stage4.py"
    click Stage5Eva "https://github.com/showlab/code2video/blob/main/prompts/stage5_eva.py"
    click Stage5Un "https://github.com/showlab/code2video/blob/main/prompts/stage5_unlearning.py"

    %% LLM Handler & Config
    GPTRequest["gpt_request.py"]:::code
    APIConfig["api_config.json"]:::code
    Orchestrator --> GPTRequest
    Orchestrator --> APIConfig
    click GPTRequest "https://github.com/showlab/code2video/blob/main/src/gpt_request.py"
    click APIConfig "https://github.com/showlab/code2video/blob/main/src/api_config.json"

    %% External Assets & Utilities
    ExternalAssets["external_assets.py"]:::code
    Utils["utils.py"]:::code
    ScopeRefine["scope_refine.py"]:::code
    Orchestrator --> ExternalAssets
    Orchestrator --> Utils
    Orchestrator --> ScopeRefine
    click ExternalAssets "https://github.com/showlab/code2video/blob/main/src/external_assets.py"
    click Utils "https://github.com/showlab/code2video/blob/main/src/utils.py"
    click ScopeRefine "https://github.com/showlab/code2video/blob/main/src/scope_refine.py"

    %% Requirements
    Req["requirements.txt"]:::code
    Orchestrator --> Req
    click Req "https://github.com/showlab/code2video/blob/main/src/requirements.txt"

    %% Pipeline Agents
    Planner["Planner Agent"]:::code
    Coder["Coder Agent"]:::code
    Renderer["Renderer\n(Manim CLI)"]:::code
    Critic["Critic Agent"]:::code

    Orchestrator --> Planner
    Orchestrator --> Coder
    Orchestrator --> Renderer
    Orchestrator --> Critic

    %% External Services
    LLM["LLM API\n(Claude)"]:::external
    VLM["VLM API\n(Gemini)"]:::external
    IconService["IconFinder API"]:::external

    %% Agent Interactions
    Planner --> Stage1
    Planner --> GPTRequest
    GPTRequest --> LLM
    Planner --> Storyboard["storyboard JSON"]:::data

    Coder --> Stage2
    Coder --> GPTRequest
    GPTRequest --> LLM
    Coder --> Script["Manim script"]:::data

    Script --> Renderer
    Renderer --> RawVideo["raw video segments"]:::data

    RawVideo --> Critic
    Critic --> Stage3
    Critic --> Stage4
    Critic --> VLM
    Critic --> Refinements["refinement parameters"]:::data

    Refinements --> Renderer
    Renderer --> PolishedVideo["polished video"]:::data

    %% External Assets Fetching
    Renderer --> IconService
    IconService --> assets

    %% Output Store & Evaluation
    Output["Output Store\nCASES/FOLDER_PREFIX"]:::data
    PolishedVideo --> Output

    subgraph "Evaluation Modules"
        EvalTQ["eval_TQ.py"]:::eval
        EvalAES["eval_AES.py"]:::eval
    end
    Output --> EvalTQ
    Output --> EvalAES
    click EvalTQ "https://github.com/showlab/code2video/blob/main/src/eval_TQ.py"
    click EvalAES "https://github.com/showlab/code2video/blob/main/src/eval_AES.py"

    %% Styles
    classDef code fill:#cfe2f3,stroke:#6fa8dc;
    classDef data fill:#d9ead3,stroke:#8fbc8f,stroke-width:2px;
    classDef external fill:#fce5cd,stroke:#f6b26b;
    classDef eval fill:#d9d2e9,stroke:#b4a7d6;
```
