# 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.