# yaninsanity/tubewhale architecture

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

- Interactive diagram: https://gitdiagram.com/yaninsanity/tubewhale
- Repository: https://github.com/yaninsanity/tubewhale

## Overview

##### Project Type and Purpose
- TubeWhale is an open‑source AI‑powered multi‑agent video‑processing pipeline (not a web app) that searches YouTube, transcribes audio, summarizes content, stores results, and produces a report.
- It is built as a CLI/ETL tool that orchestrates a series of agents to perform discrete steps of the video‑analysis workflow.

##### File Structure
- Top‑level:
- main.py – orchestrator and entry point.
- agents/ – modules implementing individual AI agents (search, transcript, audio, summarizer, standardizer).
- utils/ – shared utilities (config, database access, OpenAI/YouTube wrappers, helpers).
- requirements.txt, .github/workflows – CI and deployment.
- tests/ – pytest suites for agents and utils.
- Persistence:
- SQLite (utils/database.py and utils/async_database.py).
- Configuration:
- .env or openai_config.yaml for API keys and flags.

##### Readme Insights
- Reveals an 8‑step pipeline:
1. Keyword brainstorming (GPT‑4)
2. YouTube search & metadata
3. Metadata persistence
4. Transcription & summarization
5. Audio analysis fallback
6. Comment fetching
7. Standardization
8. Final JSON report
- Uses concurrency, optional full‑audio analysis, and cost/usage logging.

##### Main Components and Their Roles
- CLI / Config Loader: parses CLI flags and .env, produces a Config object.
- Orchestrator (main.py): reads config, sets up agents, kicks off workflow.
- Agents:
- SearchAgent – calls YouTube API, deduplicates, ranks.
- TranscriptAgent – tries captions, falls back to Whisper.
- AudioAgent – full‑audio Whisper + GPT or chunked fallback.
- SummarizerAgent – calls GPT to summarize text.
- StandardizerAgent – formats summaries to JSON schema.
- Utilities:
- YouTubeWrapper (utils/youtube.py) – low‑level API calls.
- OpenAIWrapper (utils/openAIServices.py) – manages prompts, responses.
- Database Layer (utils/database.py / async_database.py) – CRUD operations.
- Helper Functions (utils/helper.py) – common routines, retries, logging.
- Database (SQLite): tables for videos, transcripts, summaries, comments, ai_interactions, logs.
- External Services: YouTube Data API, Whisper (locally via FFmpeg), OpenAI GPT-4.

##### Clear Workflow Sequence
1. Load configuration and initialize DB connection.
2. Keyword Brainstorming: spawn SearchAgent to expand base keyword.
3. YouTube Search: for each expanded keyword, fetch TOP_K videos.
4. Deduplication & Scoring: remove duplicates, sort by view/like/comment.
5. Persist Metadata: insert into videos table.
6. Transcription & Summaries:
a. Use TranscriptAgent to fetch captions or Whisper transcribe.
b. Pass transcript to SummarizerAgent for GPT‑4 summary.
c. Log tokens/cost.
7. (Optional) Audio Analysis with AudioAgent.
8. Comment Fetching: retrieve comments, store in comments table.
9. Standardization: StandardizerAgent transforms summaries to JSON schema.
10. Final Report: aggregator reads DB, writes report_<timestamp>.json with metrics.

##### Relationships and Data Flow
- The orchestrator triggers each agent in sequence.
- Config → Orchestrator → Agents
- Agents ↔ Database (read/write)
- Agents ↔ External Services (YouTube API / OpenAI)
- Final Report Generator → local file system

##### Architectural Patterns and Principles
- Modular multi‑agent design: each agent has a single responsibility.
- Layered utility modules for API wrappers and database concerns.
- Orchestration over direct calls: main.py acts as the director.
- Concurrency: parallel processing of videos controlled by CONCURRENCY setting.
- Retry and fallback strategies in Agents (captions → Whisper).

- Data persistence layer and file outputs.
- External dependencies distinctly.
- Keep labels concise but descriptive.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration Layer
    subgraph "Configuration"
        Config["Config Loader"]:::internal
        ConfigFile["API Config File"]:::file
        Requirements["Requirements File"]:::file
    end
    Config -->|"1"| Orchestrator

    %% Core Orchestrator and Agents
    subgraph "Core"
        Orchestrator["Orchestrator (main.py)"]:::internal
        subgraph "Agents"
            Search["SearchAgent"]:::internal
            Transcript["TranscriptAgent"]:::internal
            Audio["AudioAgent"]:::internal
            Summarizer["SummarizerAgent"]:::internal
            Standardizer["StandardizerAgent"]:::internal
        end
    end
    Orchestrator -->|"2"| Search
    Orchestrator -->|"2"| Transcript
    Orchestrator -->|"2"| Audio
    Orchestrator -->|"2"| Summarizer
    Orchestrator -->|"2"| Standardizer

    %% Utilities Layer
    subgraph "Utilities"
        YTW["YouTubeWrapper"]:::internal
        OAI["OpenAIWrapper"]:::internal
        Helper["Helper Functions"]:::internal
    end

    %% External Services
    subgraph "External Services"
        ExternalYT["YouTube Data API"]:::external
        ExternalAI["OpenAI GPT-4"]:::external
        ExternalWhisper["Whisper/FFmpeg"]:::external
    end

    %% Database
    subgraph "Persistence"
        DB["SQLite Database"]:::database
    end

    %% Reporting
    subgraph "Reporting"
        Report["Report Generator"]:::internal
        FS["Local File System"]:::external
    end

    %% Testing and CI/CD
    subgraph "Testing"
        Tests["Test Suite"]:::external
    end
    subgraph "CI/CD"
        CI["CI/CD Workflow"]:::external
    end

    %% Data Flows
    Search -->|"3"| YTW
    Transcript -->|"4"| YTW
    Transcript -->|"4"| ExternalWhisper
    Audio -->|"5"| ExternalWhisper
    Audio -->|"5"| OAI
    Summarizer -->|"6"| OAI
    Standardizer -->|"9"| Helper

    YTW --> ExternalYT
    OAI --> ExternalAI

    Search -->|"7"| DB
    Transcript -->|"8"| DB
    Audio -->|"7"| DB
    Summarizer -->|"6"| DB
    Standardizer -->|"9"| DB

    DB -->|"10"| Report
    Report -->|"11"| FS

    Orchestrator --> Tests
    CI --> Orchestrator

    %% Click Events
    click Config "https://github.com/yaninsanity/tubewhale/blob/main/utils/config.py"
    click ConfigFile "https://github.com/yaninsanity/tubewhale/blob/main/utils/openai_config.yaml"
    click Requirements "https://github.com/yaninsanity/tubewhale/blob/main/requirements.txt"
    click Orchestrator "https://github.com/yaninsanity/tubewhale/blob/main/main.py"
    click Search "https://github.com/yaninsanity/tubewhale/blob/main/agents/search_agent.py"
    click Transcript "https://github.com/yaninsanity/tubewhale/blob/main/agents/transcript_agent.py"
    click Audio "https://github.com/yaninsanity/tubewhale/blob/main/agents/audio_agent.py"
    click Summarizer "https://github.com/yaninsanity/tubewhale/blob/main/agents/summarizer_agent.py"
    click Standardizer "https://github.com/yaninsanity/tubewhale/blob/main/agents/standardizer_agent.py"
    click YTW "https://github.com/yaninsanity/tubewhale/blob/main/utils/youtube.py"
    click OAI "https://github.com/yaninsanity/tubewhale/blob/main/utils/openAIServices.py"
    click Helper "https://github.com/yaninsanity/tubewhale/blob/main/utils/helper.py"
    click Tests "https://github.com/yaninsanity/tubewhale/tree/main/tests/"
    click CI "https://github.com/yaninsanity/tubewhale/blob/main/.github/workflows/deploy.yml"
    click DB "https://github.com/yaninsanity/tubewhale/blob/main/utils/database.py"
    click DB "https://github.com/yaninsanity/tubewhale/blob/main/utils/async_database.py"

    %% Styles
    classDef internal fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef external fill:#FFCC80,stroke:#E65100,color:#E65100
    classDef database fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef file fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A
```
