docs/superpowers/plans/simplified.md

Ads Automation Hackathon Implementation Plan

For agentic workers: REQUIRED: Use the subagent-driven-development agent (recommended) or executing-plans agent to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a Google Ads recommendation dashboard for a preschool that monitors campaign performance, generates AI-powered recommendations using MiniCPM5-1B, and allows a human to review, approve, or reject recommendations. Deploy as a Gradio app on a Hugging Face Space (CPU) with SQLite as the source of truth.

Architecture: Single Gradio application. Google Ads metrics are imported into SQLite. A deterministic rule engine identifies opportunities and issues. MiniCPM5 generates human-readable explanations for recommendations. Recommendations are displayed in a dashboard where users can approve or reject them. No automatic ad changes are performed.

Tech Stack: Python 3.10+, Gradio, SQLAlchemy, google-ads, pandas, llama-cpp-python, pytest, python-dotenv.

---

Task 1: Scaffold Project Layout

Files:

• Create: app/__init__.py

• Create: app/main.py

• Create: app/ads/connector.py

• Create: app/db/models.py

• Create: app/db/repo.py

• Create: app/recs/rules.py

• Create: app/recs/generate.py

• Create: app/models/llm.py

• Create: app/ui/dashboard.py

• Create: app/ui/recommendations.py

• Create: scripts/seed_demo.py

• Create: requirements.txt

• Create: README.md

• Step 1: Create repository structure and install dependencies.

Requirements:

gradio
sqlalchemy
google-ads
pandas
llama-cpp-python
pytest
python-dotenv
requests

Verify:

python -m venv .venv
pip install -r requirements.txt

Expected: all packages install successfully.

• Step 2: Verify imports.

python -c "import app; print('scaffold ok')"

Expected:

scaffold ok

---

Task 2: SQLite Models

Files:

• Modify: app/db/models.py

• Modify: app/db/repo.py

• Step 1: Create Campaign model.

Fields:

id
google_campaign_id
name
budget
spend
clicks
impressions
ctr
leads
cpl
last_synced

• Step 2: Create Recommendation model.

Fields:

id
campaign_id
recommendation_type
action
reason
status
created_at

Status values:

Pending
Approved
Rejected

• Step 3: Create database initialization helper.

Verify:

python -c "from app.db.repo import init_db; init_db(); print('db ok')"

Expected:

db ok

---

Task 3: Google Ads Read-Only Connector

Files:

• Modify: app/ads/connector.py

• Step 1: Implement:

list_campaigns()

Returns:

[
  {
    "id": "...",
    "name": "...",
    "budget": ...
  }
]

• Step 2: Implement:

get_campaign_metrics()

Returns:

[
  {
    "campaign_id": "...",
    "spend": ...,
    "clicks": ...,
    "impressions": ...,
    "ctr": ...,
    "leads": ...,
    "cpl": ...
  }
]

• Step 3: Add mock tests for connector responses.

Expected:

$env:PYTHONPATH="."
pytest

passes.

---

Task 4: Rule Engine

Files:

• Modify: app/recs/rules.py

• Step 1: Implement High CPL Rule.

Condition:

CPL > Target CPL × 1.5

Recommendation:

Reduce budget allocation

• Step 2: Implement Strong Campaign Rule.

Condition:

CPL < Target CPL × 0.8

Recommendation:

Increase budget allocation

• Step 3: Implement Low CTR Rule.

Condition:

CTR < 2%

Recommendation:

Review ad copy and keywords

• Step 4: Return structured recommendation objects.

Example:

{
  "campaign":"Preschool Search",
  "type":"high_cpl",
  "action":"reduce_budget"
}

---

Task 5: MiniCPM5 Recommendation Generator

Files:

• Modify: app/models/llm.py

• Modify: app/recs/generate.py

• Step 1: Load MiniCPM5 GGUF using llama-cpp-python.

Implement:

load_model()

• Step 2: Generate explanations from recommendation payloads.

Input:

{
  "campaign":"Preschool Search",
  "cpl":42,
  "target_cpl":20,
  "action":"reduce_budget"
}

Output:

This campaign's cost per lead is significantly above target. Consider reducing budget allocation until conversion efficiency improves.

• Step 3: Validate output and provide fallback text if model response fails.

• Step 4: Add mocked tests.

---

Task 6: Dashboard UI

Files:

• Modify: app/main.py

• Modify: app/ui/dashboard.py

• Modify: app/ui/recommendations.py

• Step 1: Build Campaign Dashboard.

Display:

Campaign	Spend	Leads	CPL	CTR

• Step 2: Add dashboard summary cards.

Examples:

Total Spend
Total Leads
Average CPL
Active Campaigns

• Step 3: Add Recommendations Page.

Display:

Campaign	Recommendation	Status

• Step 4: Add Approve button.

Updates:

Pending → Approved

• Step 5: Add Reject button.

Updates:

Pending → Rejected

Verification:

python app/main.py

Expected:

Dashboard loads successfully.

---

Task 7: Demo Data

Files:

• Modify: scripts/seed_demo.py

• Step 1: Generate sample campaigns.

Create:

5 campaigns

• Step 2: Generate synthetic metrics.

Create:

30 days of data

• Step 3: Generate recommendations.

Ensure dashboard always contains examples.

Verification:

python scripts/seed_demo.py

Expected:

Database populated with demo content.

---

Task 8: End-to-End Testing

Files:

• Create: tests/test_e2e.py

• Step 1: Seed demo data.

• Step 2: Run rule engine.

• Step 3: Generate MiniCPM explanations using mocked model.

• Step 4: Verify recommendations appear in database.

Expected:

pytest

passes.

---

Task 9: Hugging Face Space Deployment

Files:

• Modify: README.md

• Modify: requirements.txt

• Step 1: Add deployment instructions.

• Step 2: Document model download procedure.

• Step 3: Document local development workflow.

Example:

pip install -r requirements.txt
python scripts/seed_demo.py
python app/main.py

Expected:

Developer can run locally and deploy to HF Spaces.

---

Self-Review Checklist

1. Google Ads metrics can be viewed.
2. Rule engine generates recommendations.
3. MiniCPM generates explanations.
4. Recommendations can be approved/rejected.
5. Dashboard works with seeded demo data.
6. No automatic campaign modifications.
7. No scheduler required.
8. No Google Sheets integration required.
9. Deployable on Hugging Face Spaces.

---

Handoff / Execution Choices

Plan complete. Two execution options:

1. Subagent-Driven (recommended) — run subagent-driven-development task-by-task.
2. Inline Execution — implement tasks sequentially in a single session.

Recommended for hackathon: subagent-driven-development.