SatyaTejaChukka/youtube-rag-backend

TubeRAG

TubeRAG is a privacy-first, open-source Retrieval-Augmented Generation (RAG) web application that enables users to ask natural language questions about any YouTube channel, playlist, or multiple separate video links. It extracts transcripts, indexes them with hybrid search techniques, and provides accurate answers grounded strictly in the video content—complete with clickable source citations that jump straight to the exact timestamp on YouTube.

✨ Features

1. Hybrid Search (Vector + Keyword)

Combines ChromaDB dense vector similarity search (for conceptual meaning and semantic matches) with a SQLite FTS5 (Full-Text Search) keyword index (for exact code snippets, acronyms, dates, and names). Results are combined using Reciprocal Rank Fusion (RRF) to produce highly accurate rankings.

2. Parent-Child Chunk Retrieval

• —Child Chunks (~150 tokens): Small, granular chunks optimized for precise vector matching in the search database.
• —Parent Context Spans (~700 tokens): Large, contiguous context spans. When a child chunk matches the query, the retriever expands the window to fetch its surrounding parent block, providing the LLM with sufficient context for high-quality, comprehensive answers.

3. Integrated Local Re-ranking

Supports a two-stage retrieval pipeline with a UI setting to toggle between:

• —None (Fastest): Bypasses the re-ranking step for instant execution.
• —FlashRank (Local CPU): Uses an ultra-lightweight ONNX-quantized cross-encoder model (ms-marco-MiniLM-L-6-v2, ~15MB) running directly on the server's CPU with low latency (~100ms) and no external API keys.

4. Granular Progress Tracking & Parallel Ingestion

• —Concurrent Ingestion: Resolves and indexes multiple YouTube URLs in parallel (using asyncio with a semaphore limit of 3 to avoid YouTube IP bans).
• —Granular UI Feedback: Displays real-time individual progress rows (with thumbnails, titles, and states: queued → downloading → embedding → completed/skipped/failed) for all videos in a batch.

5. Smart Anti-Blocking & Cookie Support

Integrates standard Netscape cookie files (cookies.txt or YT_COOKIES env variable) to impersonate browser sessions and bypass YouTube HTTP 429: Too Many Requests blocks when indexing long playlists or channels.

🏗️ Architecture & Stack

   ┌──────────────────────────────────────────────────────────┐
   │                       WEB BROWSER                        │
   │  ┌────────────────────────┐    ┌──────────────────────┐  │
   │  │ React 19 / Vite SPA    │◄──►│ IndexedDB (Dexie.js) │  │
   │  │ (Chat UI & Progress)   │    │ (API Keys & Settings)│  │
   │  └────────────────────────┘    └──────────────────────┘  │
   └───────────────▲──────────────────────────────────────────┘
                   │ HTTPS API / SSE Stream
   ┌───────────────▼──────────────────────────────────────────┐
   │                    BACKEND (Docker)                      │
   │  ┌────────────────────────┐    ┌──────────────────────┐  │
   │  │ FastAPI Server         │◄──►│ SentenceTransformers │  │
   │  │ (routers/ingest, ask)  │    │ (Local Embeddings)   │  │
   │  └───────────▲────────────┘    └──────────────────────┘  │
   │              │ SQLAlchemy Async                          │
   │  ┌───────────▼────────────┐    ┌──────────────────────┐  │
   │  │ SQLite Database        │◄──►│ ChromaDB             │  │
   │  │ (FTS5 Index & Metadata)│    │ (Vector Store)       │  │
   │  └────────────────────────┘    └──────────────────────┘  │
   └──────────────────────────────────────────────────────────┘

• —Frontend: React 19, TypeScript, Vanilla CSS Custom Design, Vite, Dexie.js (for secure, browser-only API key storage).
• —Backend: Python 3.11, FastAPI, SQLAlchemy Async, SQLite (Relational Store + FTS5 Indexing), yt-dlp, tiktoken.
• —AI & NLP: sentence-transformers (runs locally for embeddings), flashrank (ONNX reranker on CPU), Groq API / local Ollama (for generation).

🚀 Getting Started

The easiest way to run TubeRAG locally is using Docker. This ensures all system packages (like ffmpeg for yt-dlp and compilers for ChromaDB) are configured correctly.

Prerequisites

• —Docker Desktop
• —A Groq API Key

Quickstart with Docker

1. 1.Clone the repository:

   git clone https://github.com/yourusername/youtube-rag.git
   cd youtube-rag

1. 1.(Optional) Setup Environment Variables: Create a .env file inside the backend folder:

   cp backend/.env.example backend/.env

Edit backend/.env to include your default credentials (e.g. GROQ_API_KEY).

1. 1.Start the application:

   docker compose up -d --build

1. 1.Access the application: Open [http://localhost:5173](http://localhost:5173) in your browser.

[!NOTE] The very first video ingestion will take a moment longer as the backend downloads the BAAI/bge-small-en-v1.5 sentence-transformer model weights.

💡 Usage Guide

1. Configure Settings

Click the Settings (Gear Icon) in the sidebar:

• —AI Provider: Choose Groq (paste your API key) or Ollama (for fully offline local execution).
• —Reranker Mode: Select None (Fastest) or FlashRank (Local CPU).
• —Groq API Key Link: If you don't have a Groq key, click the direct link at the bottom of the Settings modal to generate one instantly.

2. Index YouTube Content

Paste one or more links into the sidebar input field:

• —Channel: https://youtube.com/@freecodecamp (indexes channel videos).
• —Playlist: https://youtube.com/playlist?list=PL...
• —Single Video: https://youtube.com/watch?v=...
• —Multiple Batch Links: Paste multiple links separated by line breaks or commas. Click Index Source and monitor real-time, per-video progress.

3. Ask Questions & Citations

Select an indexed source in the sidebar and chat with your video library. TubeRAG returns responses token-by-token using Server-Sent Events (SSE).

• —Click any citation card under Referenced in to open the video on YouTube at the exact timestamp where the reference was spoken.
• —If a question cannot be resolved by the transcript excerpts, the system gracefully informs you and hides the reference list.

🔒 Security & Privacy (BYOK)

• —No Server Storage of Keys: API keys entered in the Settings modal are stored strictly inside your browser's IndexedDB. They are transmitted dynamically in request headers (X-API-Key) and are never saved to the backend database or logs.
• —Server Data Directory: Vector indexes (chroma_db) and metadata (app.db) reside locally on the host server.

🔧 Developer Configuration

Backend settings can be configured via environment variables in backend/.env: