Smadex Creative Copilot

Smadex Creative Copilot is a predictive analytics and decision-support platform designed to mitigate creative fatigue in mobile advertising. By integrating machine learning and generative AI, the system transitions campaign management from standard descriptive reporting to prescriptive, data-driven strategy.

The Problem

Mobile advertisers manage thousands of ad creatives simultaneously. Over time, these assets suffer from "Creative Fatigue," resulting in diminished click-through rates (CTR) and lower return on ad spend (ROAS). While traditional Business Intelligence tools can identify that an ad has failed, they lack the capability to parse visual features and explain why the failure occurred or how to prevent it in future iterations.

The Solution

This project provides an end-to-end data pipeline and interactive dashboard that solves the attribution and prediction gap in creative performance:

• Portfolio Health Monitoring: Deploys heuristic rules to instantly flag inefficient spend and identify high-potential assets.

• Feature Attribution and Explainability: Processes visual metadata (e.g., text density, color dominance, structural hooks) through an LLM to generate structured, natural-language insights explaining performance drivers.

• Predictive Simulation: Utilizes a trained Random Forest classifier to forecast the probability of success for hypothetical, user-designed creatives before budget is allocated.

Core Features

1. Portfolio Health and Alerts

A high-level command center for media buyers focusing on immediate financial impact.

• Global KPIs: Aggregated tracking of Spend, Conversions, Average ROAS, and CTR.

• Algorithmic Segmentation: Automatically categorizes creatives into actionable clusters:

  • Critical Risk: Assets exceeding spend thresholds with unprofitable ROAS.
  • Scale Opportunities: Highly profitable assets operating under budget capacity.
  • Fatigue Watchlist: Creatives exhibiting severe CTR decay relative to their launch metrics.

2. Creative Inspector

A deep-dive analytical tool for individual asset evaluation.

• Time-Series Analysis: Maps daily CTR trajectories against campaign-level baselines to isolate the exact inflection point of audience fatigue.

• AI Explainability: Interfaces with the OpenAI API to translate continuous and categorical visual features into structured marketing insights, identifying the exact variables driving success or failure.

3. AI Ad Simulator (Predictive Sandbox)

A modeling environment for creative strategy and testing.

• Parameter Input: Users configure core attributes (Duration, Theme, Color, Hook Type) and computer-vision scores (Readability, Clutter, Motion, Text Density).

• Random Forest Inference: The system runs real-time inference on the input vector, outputting the exact probability distribution across four lifecycle states (Top Performer, Stable, Fatigued, Underperformer) alongside feature importance weightings.

System Architecture and File Structure

smadex-copilot/
│
├── data/                                 # Local data directory
│   ├── assets/                           # Visual PNG assets
│   ├── advertisers.csv                   # Raw advertiser metadata
│   ├── campaigns.csv                     # Raw campaign configurations
│   ├── creative_summary.csv              # Lifetime creative performance
│   ├── creative_daily_country_os_stats.csv # Granular time-series data
│   └── master_data.csv                   # Pre-joined master dataset
│
├── app.py                                # Main Streamlit frontend application
├── train_model.py                        # Pipeline to train and serialize the ML model
├── random_forest_model.joblib            # Serialized model weights and parameters
│
├── preprocessing.py                      # Data access layer and optimized getters
├── merge_data.py                         # ETL script for joining raw CSVs
├── metrics.py                            # Mathematical engine for derived KPIs
├── explainability.py                     # LLM integration for feature attribution
└──  classifier_ml.py                     # Batch prediction and anomaly detection

Installation and Setup

1. Prerequisites

Ensure Python 3.10+ is installed on your local environment.

1. Install Dependencies

Install the required libraries via pip:

pip install pandas numpy streamlit plotly scikit-learn openai pillow

1. Prepare the Environment

Ensure the required dataset files are located in the data/ directory as specified in the architecture tree. If master_data.csv is missing, execute the ETL pipeline:

python merge_data.py

1. Model Training

The predictive simulator requires a trained model instance. Execute the training script to generate the serialized .joblib file:

python train_model.py

1. Environment Variables

To enable the LLM-driven explainability features, set your OpenAI API key in your terminal environment:

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

1. Launch the Application

Start the Streamlit server:

streamlit run app.py

Built With

• openai
• pandas
• python
• scikit-learn
• streamlit