How yaninsanity/tubewhale works
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.