Content
# RealReel
An AI agent that generates ICP-targeted product marketing videos and **gets measurably better every run** through a self-improving loop of reference mining, generation, self-critique, and continual learning.
Built at the [AI Engineer World's Fair 2026](https://www.ai.engineer/worldsfair/2026) hackathon, organized by [Cerebral Valley](https://cerebralvalley.ai/e/aiewf-hackathon-2026).
## The Problem
Creating product marketing videos is slow, expensive, and generic. Most tools produce one-size-fits-all output that doesn't resonate with any specific audience. There's no feedback loop — you ship a video and hope it works.
## The Solution
RealReel is a video generation agent built around a **self-improvement loop**. Given a product URL and an Ideal Customer Profile (ICP), it:
1. **Mines** what already resonates with your ICP — discovers high-performing reference content via [Exa](https://exa.ai) semantic search and ranks it by real engagement data from the YouTube Data API.
2. **Extracts patterns** — feeds the reference corpus to Gemini to build a `ResonanceProfile`: what hooks work, ideal pacing, caption density, visual motifs, and what to avoid.
3. **Generates** a multi-format video — captures your product via Playwright, creates title/CTA cards with Gemini image generation, generates B-roll with Veo 3.1, and composes everything with FFmpeg into platform-specific formats (TikTok/Reels, YouTube, LinkedIn, etc.).
4. **Self-critiques** — a critic agent scores the output against an ICP-derived rubric (hook strength, silent readability, pacing, resonance, CTA clarity, etc.) and issues targeted regeneration actions.
5. **Iterates** — regenerates only the weak components, recomposes, and re-scores until the video passes the quality threshold or hits the iteration cap.
6. **Learns** — persists references, resonance profiles, generation results, and critique scores to MongoDB Atlas (with Voyage embeddings), so future runs for the same ICP cold-start from learned best patterns.
The result: run #20 produces better-targeted videos than run #1, with zero manual tuning.
## Architecture
```
ICP Profile
│
▼
[1] Reference Mining (Exa + YouTube API)
│
▼
[2] Pattern Extraction (Gemini) → ResonanceProfile
│
▼
[3] Generation (Playwright capture + Gemini cards + Veo B-roll + Lyria music)
│
▼
[4] FFmpeg Composition (per-platform render profiles)
│
▼
[5] Self-Critique (Gemini critic agent)
│
├── below threshold → regenerate weak components → back to [3]
│
▼ (passes)
[6] Output + Memory (MongoDB Atlas + Voyage embeddings)
```
## Render Profiles
Videos are composited for each target platform from the same source assets:
| Profile | Resolution | Ratio | Platforms | Duration |
|---|---|---|---|---|
| `social_vertical` | 1080x1920 | 9:16 | TikTok, Reels, Shorts | 15-30s |
| `feed_portrait` | 1080x1350 | 4:5 | Instagram, LinkedIn feed | 15-30s |
| `square` | 1080x1080 | 1:1 | Legacy feed, ad units | 15-30s |
| `landscape` | 1920x1080 | 16:9 | Twitter, LinkedIn, web | 20-45s |
| `youtube` | 1920x1080 | 16:9 | YouTube watch page | 30-60s |
## Setup
### Prerequisites
- Docker
- API keys (see below)
### Environment Variables
Create a `.env` file in the project root:
```env
GEMINI_API_KEY=your_gemini_api_key
EXA_API_KEY=your_exa_api_key
YOUTUBE_API_KEY=your_youtube_data_api_v3_key
# Optional — enables cross-run learning
MONGODB_URI=mongodb+srv://user:pass@cluster/dbname
VOYAGE_API_KEY=your_voyage_api_key
```
**Getting the keys:**
- **Gemini API Key** — [Google AI Studio](https://aistudio.google.com/apikey)
- **Exa API Key** — [Exa Dashboard](https://dashboard.exa.ai)
- **YouTube Data API Key** — [Google Cloud Console](https://console.cloud.google.com) → APIs & Services → Enable "YouTube Data API v3" → Create Credentials → API Key → select "Public data"
- **MongoDB Atlas** (optional) — [MongoDB Atlas](https://cloud.mongodb.com) free tier
- **Voyage AI** (optional) — [Voyage AI](https://www.voyageai.com)
### Build & Run
```bash
# Build the Docker image
docker build -t product-video-factory .
# Run the server
docker run --rm --env-file .env -p 8000:8000 -v "$(pwd)/output:/app/output" product-video-factory
```
The MCP server starts on `http://localhost:8000/mcp` using Streamable HTTP transport.
### Connect an MCP Client
Add this to your MCP client configuration (e.g. `.mcp.json` for Claude Code):
```json
{
"mcpServers": {
"video-factory": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp"
}
}
}
```
## Usage
### MCP Tools
**`launch_video_generation`** — Start a video generation job.
```json
{
"url": "https://your-product.com",
"video_prompt": "Show the dashboard, create a new project, demonstrate the AI features",
"icp": {
"name": "Seed-stage technical founders",
"persona": "Engineers who became founders; trust live product footage and peer signal.",
"pains": ["manual GTM eats build time", "generic demos don't show the actual product"],
"desired_outcomes": ["ship marketing without a marketer", "proof the tool works in 20s"],
"platforms": ["youtube", "linkedin"],
"seed_accounts": [],
"seed_reference_urls": ["https://youtube.com/watch?v=example"],
"keywords": ["product demo dev tool", "founder launch video"],
"tone": "builder-to-builder, fast, technical, zero fluff",
"banned_styles": ["corporate voiceover", "stock footage", "slow logo intro"]
},
"profiles": ["social_vertical", "landscape"],
"max_iterations": 3
}
```
Returns a `job_id` immediately. The job runs in the background.
**`monitor_job_status`** — Poll a running job.
```json
{
"job_id": "a1b2c3d4"
}
```
Returns full status including logs, per-iteration critique scores, and output file paths.
### MCP Resource
**`factory://dashboard`** — Markdown summary of all jobs.
## Project Structure
```
realreel/
├── server.py # FastMCP server + job coordinator
├── loop.py # Self-improvement loop controller
├── icp.py # ICP + ResonanceProfile dataclasses
├── mining.py # Exa + YouTube reference mining
├── resonance.py # Gemini pattern extraction
├── pipeline.py # Playwright capture + Gemini cards + Veo + Lyria
├── critic.py # Self-critique against ICP rubric
├── compose.py # FFmpeg graph builder
├── profiles.py # Render profile definitions
├── memory.py # MongoDB Atlas + Voyage continual-learning store
├── publish.py # Gated publish + engagement pull
├── templates/ # Device frame PNGs for mockup compositing
└── output/ # Generated artifacts (volume-mounted)
```
## How the Self-Critique Works
The critic scores each video on 7 dimensions (0-10):
| Dimension | What it measures |
|---|---|
| Hook strength | Lands within target window, ICP-relevant |
| Silent readability | Fully lands muted (autoplay reality) |
| Pacing | Cut cadence vs ResonanceProfile target |
| ICP resonance | Matches hook/motif/tone patterns for this ICP |
| Safe area compliance | Nothing critical under platform UI overlays |
| CTA clarity | CTA legible and unambiguous |
| Brand consistency | Type/color/logo consistent across segments |
Videos scoring below 7.0 weighted average trigger targeted regeneration — only the weak components are rebuilt, not the entire video.
