Automated Weekly Marketing Report Builder (V3.1)

Overview

A modular Python automation system that processes marketing CSV exports, detects ISO weeks automatically, aggregates weekly KPIs, performs structured week-over-week analysis, and generates:

• A formatted TXT executive report
• A structured PDF performance report
• An AI-powered strategic executive summary

Version 3.1 introduces deterministic classification, revenue-based risk tagging, structured AI output, and risk-sensitive tone control.

This project demonstrates production-oriented AI integration with controlled architecture and cost governance.

---

What This Project Does

• Loads marketing performance CSV from the input/ folder
• Cleans and standardizes:
  • Column names
  • Numeric fields
  • Date columns
  • Missing values
• Detects ISO weeks automatically
• Processes each week independently
• Skips weeks already processed (via history tracking)
• Aggregates weekly KPI totals
• Calculates derived KPI:
  • CTR (Click-Through Rate)
• Performs week-over-week comparison
• Classifies each week into:
  • Baseline
  • Growth
  • Performance Drop
  • Efficiency Drop
  • Mixed Signal
  • Stable
• Assigns risk level:
  • High
  • Medium
  • Low
• Generates structured AI executive summary
• Applies risk-sensitive tone modulation
• Generates formatted TXT and PDF reports
• Maintains history.csv to prevent duplicate processing

---

Weekly Report Includes

For each detected ISO week, the system generates:

• summary_week_X.txt
• summary_week_X.pdf

Each PDF report includes:

• Report title
• Week number
• Reporting period
• Executive overview (AI-generated, structured)
• Week type classification
• Risk level tagging
• Aggregated KPI table:
  • Impressions
  • Clicks
  • CTR (%)
  • Conversions
  • Revenue

---

AI Executive Summary (V3.1)

The AI summary is:

• Structured into defined sections
• Constrained by token limits
• Based on delta signal (not raw metrics)
• Deterministically classified before interpretation
• Risk-aware (tone adapts to High risk weeks)
• Designed for executive readability (short, direct sentences)

Architecture separation:

• Data Layer
• Comparison Layer
• Classification Layer
• AI Interpretation Layer

Ensuring stability, consistency, and cost control.

---

Project Structure

input/                      # Raw marketing CSV export
output/                     # Generated reports + history.csv

src/
├── config.py               # Paths and risk thresholds
├── loader.py               # Reads CSV files
├── cleaner.py              # Cleans and standardizes data
├── aggregator.py           # Aggregates numeric totals + CTR
├── comparison.py           # Week-over-week comparison + classification
├── history_logger.py       # Tracks processed weeks
├── ai_payload.py           # Builds structured KPI payload
├── ai_summary.py           # AI structured executive summary (V3.1)
├── summary_report.py       # Generates formatted TXT report
├── pdf_report.py           # Generates formatted PDF report

main.py                     # Runs full reporting pipeline

---

How to Run

1. Install dependencies

pip install -r requirements.txt

2. Set your OpenAI API key as an environment variable

Mac/Linux

export OPENAI_API_KEY="your_key_here"

Windows

setx OPENAI_API_KEY "your_key_here"

3. Place CSV file inside

input/

4. Run

python main.py

Reports will be saved in:

output/

---

Requirements

• Python 3.12 (recommended)
• pandas
• reportlab
• openai

---

Future Improvements (Roadmap)

• Add CPA (Cost per Acquisition)
• Add ROAS calculation
• Add AOV tracking
• Add weighted risk scoring
• Add 4-week trend comparison
• Add token usage logging
• Add automation layer (n8n integration)
• Add dashboard interface
• Add error logging system

---

Status

Version 3.1 — Structured AI reporting engine with deterministic classification and risk-aware tone control.

Last Updated: March 2026