AdGenius - AI Video Advertisement Generation System

A multi-agent AI system that creates personalized video advertisements by analyzing viewer behavior, recommending content, and generating video prompts.

🚀 Quick Start

# 1. Run the start script
./START_HERE.sh

# 2. Open your browser to http://localhost:5000

# 3. Enter viewing history and click "Generate Ads"

📋 Prerequisites

• Python 3.10+ with uv package manager
• AWS Account with Bedrock access (for Claude 3.5 Sonnet)
• AWS CLI configured (aws configure)
• Wavespeed API Key (optional, for video generation)

🔧 Installation

# Clone the repository
git clone <your-repo-url>
cd ad-genius-system

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --extra web

# Configure AWS credentials (if not already done)
aws configure

🏗️ Project Structure

ad-genius-system/
├── agents/                 # AI Agent definitions
│   ├── viewer_analytics_agent.py
│   ├── content_recommender_agent.py
│   ├── ad_strategist_agent.py
│   ├── prompt_generator_agent.py
│   └── video_generator_agent.py
│
├── orchestration/          # Agent coordination
│   ├── ad_swarm.py        # Swarm mode (autonomous handoffs)
│   └── production_graph.py # Graph mode (structured pipeline)
│
├── tools/                  # Agent tools & utilities
│   ├── catalog_tools.py    # Content catalog access
│   ├── persona_builder.py  # Viewer profiling
│   ├── prompt_templates.py # Prompt engineering
│   └── nova_reel_tools.py  # Video generation (Wavespeed API)
│
├── config/                 # Configuration
│   └── bedrock_config.py   # AWS Bedrock & model config
│
├── templates/              # Frontend HTML
│   └── index.html          # Main web interface
│
├── generated_videos/       # Output directory for videos
├── examples/               # Example code & usage
├── docs/                   # Additional documentation
│
├── main.py                 # CLI entry point
├── web_app.py              # Web application
├── streaming_hook.py       # Real-time progress updates
└── START_HERE.sh           # Quick start script

🎯 How It Works

1. Viewer Analytics Agent

• Analyzes viewing history patterns
• Builds psychological viewer persona
• Identifies viewing archetypes (Trend Chaser, Quality Connoisseur, etc.)

2. Content Recommender Agent

• Uses persona to find matching content
• Calculates affinity scores
• Returns top 3 recommendations with rationale

3. Ad Strategist Agent

• Designs creative ad concepts
• Defines visual approach, messaging, emotional hooks
• Creates A/B test variants

4. Prompt Generator Agent

• Converts ad concepts to video generation prompts
• Adds technical specifications (duration, resolution, style)
• Optimizes for video generation models

5. Video Generator Agent (Optional)

• Generates actual video files using Wavespeed AI
• Downloads videos locally
• Provides video URLs and metadata

🌐 Usage Modes

Web Interface (Recommended)

./START_HERE.sh
# Opens on http://localhost:5000

Features:

• Real-time agent progress updates
• 2x2 agent results grid
• Streaming console logs
• Video generation toggle
• Graph/Swarm mode selector

Command Line Interface

# Swarm mode (autonomous agent collaboration)
uv run python3 main.py --mode swarm --user-id user_001 --viewing-history "Title 1" "Title 2"

# Graph mode (structured pipeline)
uv run python3 main.py --mode graph --user-id user_001 --viewing-history "Title 1" "Title 2"

🎬 Video Generation Setup

To enable video generation:

1. Get Wavespeed API Key:

   • Sign up at https://wavespeed.ai
   • Copy your API key

2. Set Environment Variable:

   export WAVESPEED_API_KEY="your-api-key-here"

3. Enable in Web UI:

   • Toggle "Generate Video" in the web interface
   • Generated videos appear in generated_videos/

⚙️ Configuration

AWS Bedrock

Edit config/bedrock_config.py:

AWS_REGION = "us-east-1"  # Your AWS region
MODEL_ID = "anthropic.claude-3-5-sonnet-20241022-v2:0"

Catalog URL

The system fetches content from a remote catalog API. Configure in config/bedrock_config.py:

CATALOG_URL = "https://your-catalog-api.com/items"

🔍 Orchestration Modes

Swarm Mode

• Autonomous: Agents decide next steps
• Dynamic: Non-deterministic flow
• Streaming: Real-time UI updates
• Use Case: Interactive development, debugging

Graph Mode

• Structured: Fixed execution pipeline
• Deterministic: Same input = same flow
• Reliable: Better for production
• Use Case: Batch processing, consistent results

📊 API Endpoints

POST   /api/generate           # Start ad generation job
GET    /api/job/{job_id}       # Get job status
GET    /api/job/{job_id}/stream # Server-sent events stream
GET    /generated_videos/{file} # Download generated video

🧪 Testing

# Run with mock backend (no AWS required)
cp archive/old_tests/demo_mock.py .
uv run python3 demo_mock.py

📝 Environment Variables

# AWS Credentials (or use aws configure)
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"

# Optional: Video generation
export WAVESPEED_API_KEY="your-wavespeed-key"

🐛 Troubleshooting

"AWS credentials not found"

# Configure AWS CLI
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."

"Port 5000 already in use"

# Kill existing process
killall -9 python3

# Or change port in web_app.py
app.run(port=5001)

Video generation fails

# Check API key is set
echo $WAVESPEED_API_KEY

# Check debug log
tail -f video_gen_debug.log

📚 Additional Documentation

• docs/CLAUDE.md - Claude Code integration guide

🤝 Contributing

This is an internal project. For questions or contributions, contact the team.

📄 License

Proprietary - All Rights Reserved

🔗 Dependencies

• Strands - Multi-agent orchestration framework
• Flask - Web framework
• AWS Bedrock - Claude 3.5 Sonnet access
• Wavespeed AI - Video generation (optional)

📞 Support

For issues or questions:

1. Check the troubleshooting section
2. Review logs in video_gen_debug.log
3. Contact the development team

---

Version: 1.0.0 Last Updated: 2025-11-29 Status: Production Ready