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 hackathon, organized by Cerebral Valley.

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 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:

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
• Exa API Key — Exa Dashboard
• YouTube Data API Key — Google Cloud Console → APIs & Services → Enable "YouTube Data API v3" → Create Credentials → API Key → select "Public data"
• MongoDB Atlas (optional) — MongoDB Atlas free tier
• Voyage AI (optional) — Voyage AI

Build & Run

# 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):

{
  "mcpServers": {
    "video-factory": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Usage

MCP Tools

launch_video_generation — Start a video generation job.

{
  "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.

{
  "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.