Meta Ad Intelligence — Autonomous Ad Analysis & Clustering System

A comprehensive, end-to-end AI platform designed to extract, analyze, and cluster Meta (Facebook/Instagram) advertising creatives. It intercepts real-time Meta Ads Library data, extracts creative recipes using Multimodal AI, builds strategic brand playbooks, and clusters top-performing advertising patterns.

---

🏗 System Architecture

Meta Ads Library
       │
       ▼
┌─────────────────────────┐
│     Collector Agent     │ ──► Playwright + GraphQL Interception
└───────────┬─────────────┘
            │
            ▼
 💾 Storage (`storage/brands/<brand>/`)
            │
            ▼
┌─────────────────────────┐
│     Creative Agent      │ ──► Gemini AI / Creative Recipe Extraction
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│   Intelligence Engine   │ ──► Strategy Analysis, Clustering & Playbooks
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│     Frontend UI         │ ──► React + Vite Dashboard
└─────────────────────────┘

---

📂 Core Components Overview

1. 🕷️ Collector Agent (collector_agent/)

Navigates the Meta Ads Library using Playwright, intercepts internal AdLibrarySearchPaginationQuery GraphQL responses, normalizes ad metadata, and downloads media assets locally.

• Key Features:

  • Headless/Headed browser operation with anti-bot detection patches.
  • Intercepts raw GraphQL network payloads before rendering.
  • Deduplicates ads across multiple test runs.
  • Downloads high-resolution images, video files, and auto-generates thumbnails.

• Output Structure:

  collector_agent/storage/brands/<brand_slug>/
  ├── brand_report.json          # Summary: total ads, media count, duration
  ├── ads_index.jsonl            # One JSON line per extracted ad
  └── ads/
      └── <ad_id>/
          ├── metadata.json      # Flat, normalized AdRecord
          ├── raw_graphql.json   # Original raw GraphQL payload
          ├── thumbnail.jpg      # Preview image
          ├── image_0.jpg        # Downloaded image asset(s)
          └── video_0.mp4        # Downloaded video asset(s)
  

---

2. 🧪 Testing & Inspection Utility (test_collector.py)

A dedicated command-line utility to test, inspect, and validate the Collector Agent's output without needing the frontend or full pipeline running.

🚀 How to Test the Collector Agent

A. Run a Collection Test

Run the collector agent for any target brand (e.g., collect up to 5 ads):

python test_collector.py --brand "Nike" --max-ads 5

Run with visible browser window (useful for visual debugging):

python test_collector.py --brand "Adidas" --max-ads 5 --no-headless

B. List All Collected Brands

View all brands currently stored in local storage along with ad & media counts:

python test_collector.py --list-brands

C. Inspect Extracted Brand Data

Inspect summary reports and extracted ads table without scraping again:

python test_collector.py --inspect --brand "Plix"

D. Inspect a Specific Ad in Detail

Examine all metadata, copy text, downloaded files, and GraphQL payload for a single ad:

python test_collector.py --inspect --brand "Plix" --ad-id "1593449608624161"

E. Direct Collector Entry Point

python collector_agent/run.py --brand "Zomato" --max-ads 10

---

3. 🎨 Creative Agent (creative_agent/) & Test Utility (test_creative.py)

Uses Multimodal AI (Google Gemini / Azure GPT-4o) to analyze ad copy and media (images/videos) to extract Creative Recipes:

• Visual Hook & Copy Hook classification.
• Color palettes and design typography.
• Dominant advertising framework (PAS, AIDA, Social Proof, Urgency, etc.).
• CTA strategy & target audience intent.

🧪 How to Test the Creative Agent (test_creative.py)

A. Run Creative AI Analysis for a Brand

Run recipe extraction for all collected ads of a brand (e.g. Plix):

python test_creative.py --brand "plix"

B. Force Re-Analysis (Override Existing Recipes)

python test_creative.py --brand "plix" --force

C. Analyze a Single Specific Ad ID

python test_creative.py --brand "plix" --ad-id "1593449608624161"

D. Inspect Extracted Recipes (Without Re-running AI)

python test_creative.py --inspect --brand "plix"

E. Inspect Detailed Taxonomy of a Single Ad Recipe

python test_creative.py --inspect --brand "plix" --ad-id "1593449608624161"

F. List Brand Recipe Status Across All Brands

python test_creative.py --list-brands

---

💾 Test Results Persistence (test_results/)

Whenever you run test commands using test_collector.py, test_creative.py, or test_intelligence.py, all generated reports, summaries, tables, and inspection outputs are automatically saved to test_results/ for future reference:

test_results/
├── collector/
│   ├── <brand_slug>_<timestamp>.txt   # Timestamped collector test log
│   └── <brand_slug>_latest.txt        # Most recent collector test log
├── creative/
│   ├── <brand_slug>_<timestamp>.txt   # Timestamped creative agent test log
│   └── <brand_slug>_latest.txt        # Most recent creative agent test log
└── intelligence/
    ├── <brand_slug>_<timestamp>.txt   # Timestamped pipeline & data flow log
    ├── <brand_slug>_latest.txt        # Most recent intelligence test log
    └── <brand_slug>_data_flow.json    # Complete JSON payload passed to Frontend UI

4. 🧠 Intelligence Engine (intelligence_engine/) & Test Utility (test_intelligence.py)

FastAPI backend service that aggregates creative recipes across brands to compute strategic insights:

• Brand Playbook: Dominant themes, messaging hooks, and asset distributions.
• Clustering & Confidence: Groups similar ad recipes and calculates confidence scores.
• API Endpoints:
  • GET /brands — List analyzed brands.
  • GET /analyze/brands — Trigger strategy analysis.
  • GET /analysis/<id> — Retrieve full strategic breakdown.

🧪 How to Test the Intelligence Engine (test_intelligence.py)

A. Run Pipeline Analysis for a Brand

python test_intelligence.py --brand "plix"

B. Run Multi-Brand Overlap Analysis

python test_intelligence.py --brand "plix,zomato"

C. Inspect Saved Analysis & Data Flow JSON

python test_intelligence.py --inspect --brand "plix"

D. List All Brands Ready for Analysis

python test_intelligence.py --list-brands

---

5. 💻 Frontend Dashboard (frontend/)

React + Vite UI displaying visual analytics, brand comparison metrics, creative recipe breakdowns, and playbook strategies.

• 📄 For complete technical breakdown of frontend pages, navigation flow, API mapping, and data presentation specifications, see FRONTEND_DOCUMENTATION.md.

---

📊 Currently Extracted & Tested Brands

Brand	Total Ads	Images	Videos	Last Test Status
Plix	5	6	5	✅ Completed (175.3s)
Zomato	5	2	3	✅ Completed
Purplle	15	7	2	✅ Completed
Samsung	13	0	0	✅ Completed
Nike	10	25	0	✅ Completed
Apple	5	18	2	✅ Completed
Nothing	5	0	0	✅ Completed

---

🛠 Prerequisites & Installation

1. Python Dependencies:

   pip install -r collector_agent/requirements.txt
   playwright install chromium

2. Environment Configuration: Copy .env.example to .env and set your API keys:

   GEMINI_API_KEY=your_gemini_api_key_here
   HEADLESS=true

3. Running the Full Pipeline Backend:

   python -m intelligence_engine.run

4. Running the Frontend:

   cd frontend
   npm run dev