⚡ Campaign Intelligence Hub

An advanced, AI-powered marketing operations dashboard that ingests multi-channel campaign data, detects performance anomalies using statistical deviation analysis, scores campaign health, and generates strategic optimization recommendations using GPT-4o.

🌐 Live Demo | Built by Rahul Muddhapuram

---

📖 Table of Contents

• 🔍 System Architecture & Workflow
• ✨ Core Features & Capabilities
• 🛠️ Technology Stack
• 📂 Directory Structure
• ⚡ Quick Start & Installation
• 📐 Core Logic & Algorithms
  • 1. Anomaly Detection Engine
  • 2. Health Scoring Classification
  • 3. Generative AI Analysis
• 📊 CSV Data Schema
• 📜 License

---

🔍 System Architecture & Workflow

The Campaign Intelligence Hub processes portfolio-wide marketing data through a modular pipeline. From initial CSV ingestion to visual rendering and LLM-driven synthesis, here is how the system operates:

flowchart TD
    A[Data Ingestion] -->|Upload CSV / Load Demo Dataset| B[Data Processing & Feature Engineering]
    B -->|Calculate Metrics: ROAS, CTR, CPA, Conv %| C[Health Scoring & Classification Engine]
    C -->|Calculate Score 0-100| D{Health Category}
    D -->|Score >= 55| D1[Healthy]
    D -->|30 <= Score < 55| D2[At Risk]
    D -->|Score < 30| D3[Critical]

    B --> E[Anomaly Detection Engine]
    E -->|1.5σ CTR/Conv Deviation| E1[Statistical Anomalies]
    E -->|Spend > $5k & Conv < 3| E2[Low Conversion Anomalies]
    E -->|Spend > $1k & ROAS < 0.5x| E3[Low ROAS Anomalies]

    B --> F[AI Analysis Engine]
    F -->|OpenAI Key Present| F1[GPT-4o Chat Completion API]
    F -->|No Key Fallback| F2[Rule-Based Expert System]

    D1 & D2 & D3 & E1 & E2 & E3 & F1 & F2 --> G[Interactive Streamlit Dashboard]

    subgraph Dashboard Views
        G --> H1[📊 Performance Tab]
        G --> H2[🔍 Anomalies Tab]
        G --> H3[🤖 AI Analysis Tab]
        G --> H4[📋 Campaign Table Tab]
        G --> H5[🗺️ Channel Mix Tab]
    end

Loading

---

✨ Core Features & Capabilities

• 📊 Dynamic Performance Analytics: Interactive Plotly visualizations detailing channel ROAS, spend vs. revenue scatter plots, health distribution, and conversions across different funnel stages.
• 🔍 Statistical Anomaly Detection: Automatically flags underperforming campaigns using standard deviations ($\sigma$) and business heuristics, highlighting "Spend at Risk."
• 🤖 AI-Powered Strategy Agent: Integrates OpenAI's GPT-4o to synthesize complex multi-channel performance data into concise executive summaries, key findings, and action items. Includes a rule-based fallback system.
• 📋 Interactive Campaign Ledger: A detailed, filterable data grid featuring a health-score-based progress bar, allowing users to drill down by channel, team, quarter, or health status.
• 🗺️ Channel Mix & Efficiency: Utilizes multi-level Treemaps to visualize budget allocation by channel/stage, coupled with a CPA vs. ROAS efficiency matrix to identify high-performing segments.

---

🛠️ Technology Stack

• Frontend & Dashboard Framework: Streamlit (engineered with a customized dark theme, JetBrains Mono + Outfit typography)
• Interactive Visualizations: Plotly (Express & Graph Objects)
• AI Engine: OpenAI GPT-4o API (using structured prompt guidelines)
• Data Science Pipeline: pandas, NumPy
• Styling: HTML5, Custom CSS3 overrides for modular card layouts and UI enhancement

---

📂 Directory Structure

campaign-intel-hub/
├── .streamlit/
│   └── config.toml          # Custom Streamlit UI styling & theme setup
├── app.py                   # Main application containing all UI and engines
├── demo_campaign_data.csv   # HubSpot-modeled campaign dataset
├── requirements.txt         # Project package dependencies
├── README.md                # Premium project documentation
└── .gitignore               # Ignored version control files

---

⚡ Quick Start & Installation

Option A: Local Python Virtual Environment

1. Clone the Repository

   git clone https://github.com/rahul0443/campaign-intel-hub.git
   cd campaign-intel-hub

2. Set Up Virtual Environment

   python3 -m venv .venv
   source .venv/bin/activate

3. Install Dependencies

   pip install -r requirements.txt

4. Run the Streamlit Dashboard

   streamlit run app.py

---

Option B: Conda Environment

1. Create and Activate Conda Env

   conda create -n campaign-intel python=3.10 -y
   conda activate campaign-intel

2. Install Requirements

   pip install -r requirements.txt

3. Launch Dashboard

   streamlit run app.py

---

Optional: Enable GPT-4o Analysis

To enable the generative AI analysis, set your OpenAI API key as an environment variable before running the application:

export OPENAI_API_KEY="your-openai-api-key-here"

Note: If no API key is detected, the engine gracefully falls back to a rule-based expert analysis model.

---

📐 Core Logic & Algorithms

1. Anomaly Detection Engine

A campaign is flagged as an anomaly if it meets any of the following statistical or business-rule conditions:

• CTR Anomaly: The campaign CTR is more than $1.5$ standard deviations below the channel mean: $$\text{CTR} < \mu_{\text{channel}} - 1.5 \times \sigma_{\text{channel}}$$
• Conversion Rate Anomaly: The conversion rate is more than $1.5$ standard deviations below the channel mean: $$\text{Conversion Rate} < \mu_{\text{channel}} - 1.5 \times \sigma_{\text{channel}}$$
• Low ROAS Flag: Attributed ROAS $< 0.5\text{x}$ on a campaign with spend $> $1,000$.
• Low Conversion Flag: Conversions $< 3$ on an active campaign with spend $> $5,000$.

2. Health Scoring Classification

Each campaign features an engagement score (scaled from $0$ to $100$) which is categorized as:

• 🟢 Healthy: Score $\ge 55$
• 🟡 At Risk: $30 \le \text{Score} < 55$
• 🔴 Critical: Score $< 30$

3. Generative AI Analysis

When triggered, the app compiles the portfolio's top-level KPIs (Total Spend, Revenue, ROAS), channel aggregates, and top 8 anomaly campaigns into a JSON payload. This is sent to the gpt-4o model with system prompts instructing it to produce structured executive highlights, bulleted findings, and budget reallocation suggestions.

---

📊 CSV Data Schema

You can upload custom datasets via the sidebar. Ensure your CSV contains the following fields (column mapping is highly flexible and accepts standard marketing aliases):

Column	Data Type	Required	Description
campaign_name	String	Yes	Name of the campaign
channel	String	Yes	Marketing channel (e.g., Email, Paid Search, Paid Social)
spend	Float	Yes	Total budget spend ($)
impressions	Integer	Yes	Total impressions served
clicks	Integer	Yes	Total link clicks
conversions	Integer	Yes	Total number of goal conversions
revenue_attributed	Float	Yes	Total revenue generated directly by campaign ($)
engagement_score	Float	Yes	Raw health metric score (0 to 100)
funnel_stage	String	No	Funnel stage placement (Awareness, Consideration, Decision, Retention)
team	String	No	Owning marketing team (e.g., Brand, Growth, Lifecycle)
quarter	String	No	Fiscal quarter (e.g., Q3 2025)
status	String	No	Campaign status (Active, Paused, Completed)

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.