# lakshmisravyavedantham/gurukul-ai architecture

> Architecture diagram of the GitHub repository lakshmisravyavedantham/gurukul-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lakshmisravyavedantham/gurukul-ai
- Repository: https://github.com/lakshmisravyavedantham/gurukul-ai

## Overview

Gurukul AI is a local-first educational video generator. Its main workflow takes a topic through research and script generation, creates scene images and narration, animates the scenes with a selected model, then assembles and subtitles the finished video. A separate agentic pipeline can generate animation variants, score and refine them, escalate models, and maintain a leaderboard. The README documents the model choices and optional cloud TTS/upscaling; the supplied excerpts do not show every internal call, so uncertain wiring is omitted.

Main entry points: [`app.py`](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py) (Gradio generator), [`agentic_pipeline.py`](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py) (Agentic pipeline), [`web_research.py`](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/web_research.py) (Topic research), [`wan_animate.py`](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/wan_animate.py) (Wan and LTX engines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Topic and Script"]
  node_app["Gradio generator<br/>[app.py]"]
  node_research["Topic research<br/>[web_research.py]"]
  node_script["Scene script<br/>[generate_topic.py]"]
end

subgraph group_media["Scene Media"]
  node_image["Scene images<br/>[app.py]"]
  node_audio["Narration audio<br/>[app.py]"]
  node_kokoro["Kokoro TTS<br/>[app.py]"]
  node_elevenlabs["ElevenLabs TTS<br/>[app.py]"]
  node_animate["Scene animation<br/>[app.py]"]
  node_wan["Wan and LTX engines<br/>[wan_animate.py]"]
end

subgraph group_video["Video Output"]
  node_assemble["Video assembly<br/>[assemble_video.py]"]
  node_subtitles["Word subtitles<br/>[subtitles.py]"]
  node_final["Educational video<br/>[animated.mp4]"]
end

subgraph group_improve["Self Improvement"]
  node_agentic["Agentic pipeline"]
  node_models["Animation models"]
  node_critic["Video critic"]
  node_polisher["Topaz upscaler"]
  node_leaderboard[("Leaderboard dataset")]
end

node_user(("Video creator"))
node_research_services["DuckDuckGo and Wikipedia"]
node_comfy["ComfyUI"]
node_topic_user(("Topic input"))

node_user -->|"uses"| node_app
node_topic_user -->|"provides topic"| node_research
node_app -->|"requests research"| node_research
node_research -->|"searches"| node_research_services
node_research -->|"supplies facts"| node_script
node_app -->|"generates scenes"| node_script
node_app -->|"generates images"| node_image
node_app -->|"generates narration"| node_audio
node_audio -->|"uses local TTS"| node_kokoro
node_audio -.->|"uses optional TTS"| node_elevenlabs
node_app -->|"animates scenes"| node_animate
node_animate -->|"selects engine"| node_wan
node_wan -->|"submits workflows"| node_comfy
node_app -->|"assembles clips"| node_assemble
node_app -->|"adds subtitles"| node_subtitles
node_assemble -->|"writes video"| node_final
node_subtitles -->|"writes subtitles"| node_final
node_agentic -->|"generates variants"| node_models
node_agentic -->|"scores outputs"| node_critic
node_agentic -.->|"upscales best"| node_polisher
node_agentic -->|"records scores"| node_leaderboard

click node_app "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_research "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/web_research.py"
click node_script "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/generate_topic.py"
click node_image "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_audio "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_kokoro "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_elevenlabs "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_animate "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py"
click node_wan "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/wan_animate.py"
click node_assemble "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/assemble_video.py"
click node_subtitles "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/subtitles.py"
click node_final "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/output/animated.mp4"
click node_agentic "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py"
click node_models "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py"
click node_critic "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py"
click node_polisher "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py"
click node_leaderboard "https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_research,node_script,node_comfy toneBlue
class node_image,node_audio,node_kokoro,node_elevenlabs,node_animate,node_wan toneAmber
class node_assemble,node_subtitles,node_final toneMint
class node_agentic,node_models,node_critic,node_polisher,node_leaderboard toneRose
class node_user,node_research_services,node_topic_user toneIndigo
```

## Components

### Topic and Script

- [Gradio generator](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [Topic research](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/web_research.py): `web_research.py`
- [Scene script](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/generate_topic.py): `generate_topic.py`

### Scene Media

- [Scene images](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [Narration audio](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [Kokoro TTS](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [ElevenLabs TTS](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [Scene animation](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/app.py): `app.py`
- [Wan and LTX engines](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/wan_animate.py): `wan_animate.py`

### Video Output

- [Video assembly](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/assemble_video.py): `assemble_video.py`
- [Word subtitles](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/subtitles.py): `subtitles.py`
- [Educational video](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/output/animated.mp4): `output/animated.mp4`

### Self Improvement

- [Agentic pipeline](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py): `agentic_pipeline.py`
- [Animation models](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py): `agentic_pipeline.py`
- [Video critic](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py): `agentic_pipeline.py`
- [Topaz upscaler](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py): `agentic_pipeline.py`
- [Leaderboard dataset](https://github.com/lakshmisravyavedantham/gurukul-ai/blob/main/agentic_pipeline.py): `agentic_pipeline.py`

### Other components

- **Video creator**
- **DuckDuckGo and Wikipedia**
- **ComfyUI**
- **Topic input**

## Connections

- Video creator → Gradio generator: uses
- Topic input → Topic research: provides topic
- Gradio generator → Topic research: requests research
- Topic research → DuckDuckGo and Wikipedia: searches
- Topic research → Scene script: supplies facts
- Gradio generator → Scene script: generates scenes
- Gradio generator → Scene images: generates images
- Gradio generator → Narration audio: generates narration
- Narration audio → Kokoro TTS: uses local TTS
- Narration audio → ElevenLabs TTS: uses optional TTS
- Gradio generator → Scene animation: animates scenes
- Scene animation → Wan and LTX engines: selects engine
- Wan and LTX engines → ComfyUI: submits workflows
- Gradio generator → Video assembly: assembles clips
- Gradio generator → Word subtitles: adds subtitles
- Video assembly → Educational video: writes video
- Word subtitles → Educational video: writes subtitles
- Agentic pipeline → Animation models: generates variants
- Agentic pipeline → Video critic: scores outputs
- Agentic pipeline → Topaz upscaler: upscales best
- Agentic pipeline → Leaderboard dataset: records scores