Retail Campaign Intelligence (FastAPI + React)

A full-stack demo that analyzes retail ad campaigns, generates creative recommendations, and previews updated creatives.

Prerequisites

• Windows 10/11 (PowerShell) or macOS/Linux
• Python 3.10+
• Node 18+

Project layout

react_retail/
  backend/               # FastAPI app
  frontend/              # React (Vite + TS) app
  AD_Campagin_*.png      # Original campaign images
  ad_campaign_metrics*.csv, sales_camp_data.csv

Backend (FastAPI)

1. Create venv and install deps

cd backend
python -m venv .venv
. .venv/Scripts/Activate.ps1   # Windows PowerShell
# source .venv/bin/activate    # macOS/Linux
pip install -r requirements.txt

2. Run API (dev)

uvicorn app.main:app --reload --port 8000

The API sets its working directory to the repo root so CSVs and original images resolve correctly.

Key endpoints

• GET /api/agents/metrics → aggregated campaign metrics
• POST /api/agents/visuals → visual recommendations text (optionally narrowed by campaign_subset)
• POST /api/agents/sales → sales intelligence (optionally narrowed by campaign_subset)
• GET /api/agents/workflow → runs full workflow (metrics + recs)
• GET /api/agents/visuals/current-image?campaign=Campaign%20A&prefer_generated=false → returns original creative by default; when prefer_generated=true, returns most recent generated image if available
• POST /api/agents/visuals/generate → accepts current creative + suggestions, calls Google GenAI image-to-image, and writes to frontend/public/generated/. Returns public URL and data URL for instant preview
• Activity feed: GET/POST /api/activity (used by the frontend Recent Activity panel)

Environment variables (optional, recommended for image generation):

• GOOGLE_API_KEY_PAID or GOOGLE_API_KEY — enables Google GenAI image generation

Frontend (React + Vite + TypeScript)

1. Install and run dev server

cd frontend
npm install
npm run dev

The dev server proxies /api to http://localhost:8000.

2. Build for production

npm run build

Static assets are emitted to frontend/dist/. Serve with any static web server (e.g., npx serve dist), while the FastAPI backend continues to serve /api.

Behavior notes

• Visuals: first load shows the original creative. When you click “Generate Updated Creative” (or “Aggressive Changes”), the newly generated image is shown immediately in-session and saved under frontend/public/generated/.
• On refresh/new session: the page shows the original again (unless you explicitly ask for prefer_generated=true).
• Recent Activity: shows Visual Analysis started, Creative generated (notes Aggressive), and Approvals. Rejections are recorded but hidden from the feed.

Troubleshooting

• Ensure CSV and PNG files exist at the repo root.
• If image generation returns no image, verify GOOGLE_API_KEY_PAID (or GOOGLE_API_KEY) is set.
• Windows venv activation (PowerShell): . .venv/Scripts/Activate.ps1

License

Internal demo. Use at your discretion.