# 🎬 MCP-Powered Video RAG

> Ask natural language questions about your videos — powered by **Whisper + ChromaDB + Groq + FastMCP**. Fully **free** and runs **locally**.

## Architecture & How It Works

![System Architecture](assets/diagram.png)

```
Your Video → Whisper (transcription) → ChromaDB (vector store)
                                              ↓
                              Antigravity IDE ← MCP Server ← Your Question
                                              ↓
                                         Groq LLM (free) → Answer + Timestamps
```

## Stack (All Free)
| Component | Tool |
|---|---|
| Transcription | OpenAI Whisper (local) |
| Embeddings | sentence-transformers (local) |
| Vector DB | ChromaDB (local) |
| MCP Framework | FastMCP |
| LLM for Q&A | Groq (free tier) |

---

## ⚡ Quick Start

### 1. Install dependencies
```bash
uv sync
```

### 2. Get your FREE Groq API key
Go to [https://console.groq.com/](https://console.groq.com/) → create account → copy API key.

### 3. Set up environment
```bash
copy .env.example .env
# Edit .env and paste your GROQ_API_KEY
```

### 4. Add the MCP server to Antigravity IDE
Copy `mcp_config.json` contents into your Antigravity IDE MCP settings.
Update `GROQ_API_KEY` with your actual key.

### 5. Place videos in the `videos/` folder
Supports: `.mp4`, `.mkv`, `.avi`, `.mov`, `.webm`, `.mp3`, `.wav`

---

## 🛠️ Available MCP Tools

| Tool | Description |
|---|---|
| `ingest_video(video_path)` | Transcribe & index a video file |
| `search_video(query)` | Semantic search over transcripts |
| `ask_video(question)` | Full RAG Q&A with timestamps |
| `list_videos()` | Show all indexed videos |
| `delete_video(video_path)` | Remove a video from the index |

---

## 📖 Example Usage (in Antigravity IDE)

```
ingest_video("videos/my_lecture.mp4")

ask_video("What are the main topics discussed?")

search_video("neural networks explained", n_results=3)

ask_video("What did the speaker say about backpropagation?", video_name="my_lecture.mp4")
```

---

## ⚙️ Configuration (.env)

```env
GROQ_API_KEY=your_key_here        # Required — get free at console.groq.com
WHISPER_MODEL=base                # tiny | base | small | medium | large
EMBEDDING_MODEL=all-MiniLM-L6-v2  # local embedding model
GROQ_MODEL=llama-3.1-8b-instant  # Groq model for Q&A
CHROMA_DB_PATH=./chroma_db        # where to persist the vector DB
```

## 💡 Tips
- Use `WHISPER_MODEL=tiny` for fastest transcription (less accurate)
- Use `WHISPER_MODEL=medium` for high accuracy (slower)
- The first run downloads Whisper and embedding models (~200MB each) — subsequent runs are instant
- ChromaDB data persists across restarts in `./chroma_db/`