# ylingfeng/avt architecture

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

- Interactive diagram: https://gitdiagram.com/ylingfeng/avt
- Repository: https://github.com/ylingfeng/avt

## Overview

##### Project Type and Purpose
- Type: A command-line, data-processing pipeline rather than a web/service application.
- Purpose: Given raw video footage, run a sequence of stages—sectioning, captioning, story composition, video assembly, evaluation—using LLM agents and heuristics to produce trimmed, coherent highlight reels.

##### File Structure
- Top‐level directories:
– tools/: individual Python scripts (get_section_data.py, get_caption.py, get_story.py, get_video.py, get_evaluation.py) each implements one pipeline stage.
– config/: YAML configuration for each tool, driving parameters, file paths, LLM prompts.
– llms/: adapters for external LLM providers (Gemini, GPT).
– utils/: shared helpers (media I/O, parsing, formatting, YouTube download, metrics).
– data/: input datasets and all intermediate/final outputs organized under data/avt and other corpora.

##### README for Architectural Insights
- Sequential stages are clearly defined:
1) section data extraction
2) caption generation via LLM
3) narrative/story composition via LLM
4) video assembly (cut & concatenate)
5) evaluation/metrics
- Data flows between stages under data/avt (caption/, section_data/, output/{caption,story,evaluation}).
- External dependencies: LLM APIs (Gemini, OpenAI), YouTube/video files (via utils/youtube.py), ffmpeg or similar (implied by video tools).

##### Main Components & Their Interactions
a. Components
- CLI Orchestrator (shell commands invoking tools/*.py)
- Configuration Manager (YAML loader in each tool)
- Pipeline Stage Modules (one script per stage under tools/)
- LLM Adapter Layer (llms/gpt.py, llms/gemini.py calling external APIs)
- Utils Library (media I/O, parsing, video processing, printing)
- Data Store (local file system under data/)
- External Services (LLM endpoints, YouTube/video hosting)
b. Relationships & Data Flow
- CLI → Tool Script → Config Loader + Utils + LLM Adapters
- Tool Script reads raw/intermediate files from data/avt → processes → writes outputs back to data/avt
- LLM Adapters call external LLM API → return structured captions or story segments
- Utils/video modules (ffmpeg wrappers) assemble final .mp4 outputs
- Evaluation script reads outputs → computes metrics → writes to data/avt/output/evaluation
c. Architectural Patterns & Principles
- Pipeline pattern with clearly separated stages
- Single-responsibility modules: each tool does one logical step
- Config-driven behavior: YAML files decouple parameters from code
- Adapter pattern for LLM services (llms/ folder)
- Utility library for cross-cutting concerns (utils/)
d. Key Technologies & Libraries
- Python 3.x for scripting
- YAML for configuration (PyYAML)
- External LLM APIs (OpenAI, Gemini)
- ffmpeg or moviepy (via utils/video.py)
- youtube-dl or similar (via utils/youtube.py)

##### Detail
- Every stage’s inputs, outputs, and dependencies.
- That each tool imports from llms/ and utils/.
- Adapter pattern in llms/ wrapping external API calls.
- Config files driving each module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Orchestrator"]:::orchestrator
    CLI --> Stage1

    Stage1["get_section_data.py"]:::stage
    Stage1 --> Stage2

    Stage2["get_caption.py"]:::stage
    Stage2 --> Stage3

    Stage3["get_story.py"]:::stage
    Stage3 --> Stage4

    Stage4["get_video.py"]:::stage
    Stage4 --> Stage5

    Stage5["get_evaluation.py\n+ get_metrics.py"]:::stage

    dataStore["Data Store\n(data/avt)"]:::data
    dataStore --> Stage1
    Stage1 --> dataStore
    Stage2 --> dataStore
    Stage3 --> dataStore
    Stage4 --> dataStore
    Stage5 --> dataStore

    subgraph "External Services"
        YouTube["YouTube/Video Source"]:::external
        LLM["LLM Services\n(OpenAI/Gemini)"]:::external
    end
    YouTube --> Stage1
    Stage2 --> LLM
    Stage3 --> LLM

    subgraph "LLM Adapter Layer"
        GPT["gpt.py"]:::adapter
        Gemini["gemini.py"]:::adapter
    end
    Stage2 --> GPT
    Stage2 --> Gemini
    Stage3 --> GPT
    Stage3 --> Gemini

    subgraph "Utils Library"
        UtilsAll["utils/"]:::utils
    end
    Stage1 --> UtilsAll
    Stage2 --> UtilsAll
    Stage3 --> UtilsAll
    Stage4 --> UtilsAll
    Stage5 --> UtilsAll

    subgraph "Config Manager"
        ConfigMgr["config/"]:::config
    end
    Stage1 --> ConfigMgr
    Stage2 --> ConfigMgr
    Stage3 --> ConfigMgr
    Stage4 --> ConfigMgr
    Stage5 --> ConfigMgr

    subgraph "Static Assets"
        Assets["assets/"]:::asset
        Font["font/"]:::asset
    end

    click CLI "https://github.com/ylingfeng/avt/tree/main/tools/"
    click ConfigMgr "https://github.com/ylingfeng/avt/tree/main/config/"
    click Stage1 "https://github.com/ylingfeng/avt/blob/main/tools/get_section_data.py"
    click Stage2 "https://github.com/ylingfeng/avt/blob/main/tools/get_caption.py"
    click Stage3 "https://github.com/ylingfeng/avt/blob/main/tools/get_story.py"
    click Stage4 "https://github.com/ylingfeng/avt/blob/main/tools/get_video.py"
    click Stage5 "https://github.com/ylingfeng/avt/blob/main/tools/get_evaluation.py"
    click GPT "https://github.com/ylingfeng/avt/blob/main/llms/gpt.py"
    click Gemini "https://github.com/ylingfeng/avt/blob/main/llms/gemini.py"
    click UtilsAll "https://github.com/ylingfeng/avt/tree/main/utils/"
    click dataStore "https://github.com/ylingfeng/avt/tree/main/data/"
    click Assets "https://github.com/ylingfeng/avt/tree/main/assets/"
    click Font "https://github.com/ylingfeng/avt/tree/main/font/"

    classDef orchestrator fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef stage fill:#E8F6D7,stroke:#228B22,color:#228B22;
    classDef data fill:#F5F5F5,stroke:#A9A9A9,color:#696969;
    classDef external fill:#FFF5BA,stroke:#DAA520,color:#DAA520,stroke-dasharray: 5 5;
    classDef adapter fill:#FFE4E1,stroke:#DC143C,color:#DC143C;
    classDef utils fill:#E0FFFF,stroke:#20B2AA,color:#20B2AA;
    classDef config fill:#FFF0F5,stroke:#C71585,color:#C71585;
    classDef asset fill:#F0E68C,stroke:#BDB76B,color:#BDB76B;
```
