Initial HF Space deployment

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.adv/
+adv/
+.env
+.DS_Store
+data/app.db
+client_secret.json

app/ads1/ads_analyst.py

@@ -0,0 +1,144 @@
+import pandas as pd
+from typing import Dict
+
+from app.recs.generate import generate_explanation
+
+TARGET_CPL = 20.0
+
+# -------------------------
+# 1. DATA BUILDERS
+# -------------------------
+
+def build_campaign_snapshot(dfs: dict) -> dict:
+    df = dfs["campaigns"]
+
+    total_spend = df["cost"].sum()
+    total_clicks = df["clicks"].sum()
+    total_impr = df["impressions"].sum()
+    total_leads = df["conversions"].sum()
+
+    ctr = (total_clicks / total_impr * 100) if total_impr else 0
+    cpl = (total_spend / total_leads) if total_leads else 0
+
+    return {
+        "spend": round(total_spend, 2),
+        "clicks": int(total_clicks),
+        "impressions": int(total_impr),
+        "leads": int(total_leads),
+        "ctr": round(ctr, 2),
+        "cpl": round(cpl, 2),
+    }
+
+
+def build_simple_trend(df_hourly: pd.DataFrame) -> dict:
+    df = df_hourly.copy()
+    df["date"] = pd.to_datetime(df["date"])
+    df = df.sort_values("date")
+
+    mid = len(df) // 2
+    first, second = df.iloc[:mid], df.iloc[mid:]
+
+    def agg(x):
+        return {
+            "cost": x["cost"].sum(),
+            "clicks": x["clicks"].sum(),
+            "impressions": x["impressions"].sum(),
+        }
+
+    a, b = agg(first), agg(second)
+
+    def pct(old, new):
+        return ((new - old) / old * 100) if old else 0
+
+    return {
+        "spend_change_pct": round(pct(a["cost"], b["cost"]), 1),
+        "clicks_change_pct": round(pct(a["clicks"], b["clicks"]), 1),
+        "impressions_change_pct": round(pct(a["impressions"], b["impressions"]), 1),
+    }
+
+
+def build_top_drivers(dfs: dict) -> dict:
+    kw = dfs["keywords"].copy()
+
+    kw["cpl"] = kw["cost"] / kw["conversions"].replace(0, 1)
+
+    worst = kw.sort_values("cpl", ascending=False).head(3)
+    best = kw.sort_values("cpl", ascending=True).head(3)
+
+    return {
+        "best_keywords": best[["keyword", "cpl", "conversions"]].to_dict("records"),
+        "worst_keywords": worst[["keyword", "cpl", "conversions"]].to_dict("records"),
+    }
+
+
+def build_signals(dfs: dict) -> dict:
+    kw = dfs["keywords"].copy()
+
+    kw["ctr"] = kw["clicks"] / kw["impressions"].replace(0, 1)
+
+    return {
+        "low_ctr_ratio": round((kw["ctr"] < 0.02).mean(), 2),
+        "wasted_spend_ratio": round((kw["conversions"] == 0).mean(), 2),
+    }
+
+
+# -------------------------
+# 2. CONTEXT BUILDER
+# -------------------------
+
+def build_ads_analyst_context(dfs: dict) -> dict:
+    return {
+        "campaign": build_campaign_snapshot(dfs),
+        "trend": build_simple_trend(dfs["hourly"]),
+        "top_drivers": build_top_drivers(dfs),
+        "signals": build_signals(dfs),
+    }
+
+
+# -------------------------
+# 3. PROMPT BUILDER
+# -------------------------
+
+def build_ads_analyst_prompt(context: dict) -> str:
+    return f"""
+You are an Ads performance analyst.
+
+Return ONLY 3–5 insights.
+No reasoning. No explanation of steps.
+
+Campaign:
+{context["campaign"]}
+
+Trend:
+{context["trend"]}
+
+Top drivers:
+{context["top_drivers"]}
+
+Signals:
+{context["signals"]}
+
+Format:
+- short bullet points only
+- Simple language, no jargon
+- Focus on actionable insights
+"""
+
+
+# -------------------------
+# 4. MAIN ORCHESTRATOR (THIS IS WHAT MAIN.PY CALLS)
+# -------------------------
+
+def run_ads_analyst_card(dfs: dict) -> str:
+    context = build_ads_analyst_context(dfs)
+    prompt = build_ads_analyst_prompt(context)
+
+    print("\n========== PROMPT ==========")
+    print(prompt)
+
+    result = generate_explanation(prompt)
+
+    print("\n========== LLM OUTPUT ==========")
+    print(result)
+
+    return result

app/ads1/ads_queries.py

@@ -0,0 +1,79 @@
+# app/ads1/reports.py
+
+CAMPAIGNS_QUERY = """
+SELECT
+  campaign.id,
+  campaign.name,
+  campaign.status,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros,
+  metrics.conversions,
+  metrics.ctr
+FROM campaign
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+DEVICES_QUERY = """
+SELECT
+  segments.device,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros
+FROM campaign
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+HOURLY_QUERY = """
+SELECT
+  segments.date,
+  segments.hour,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros
+FROM campaign
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+GEO_QUERY = """
+SELECT
+  geographic_view.country_criterion_id,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros
+FROM geographic_view
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+SEARCH_TERMS_QUERY = """
+SELECT
+  search_term_view.search_term,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros
+FROM search_term_view
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+KEYWORDS_QUERY = """
+SELECT
+  campaign.id,
+  campaign.name,
+  ad_group.id,
+  ad_group.name,
+  ad_group_criterion.keyword.text,
+  metrics.impressions,
+  metrics.clicks,
+  metrics.cost_micros,
+  metrics.conversions
+FROM keyword_view
+WHERE segments.date DURING LAST_30_DAYS
+"""
+
+RECOMMENDATIONS_QUERY = """
+SELECT
+  recommendation.type,
+  recommendation.resource_name,
+  recommendation.campaign
+FROM recommendation
+"""

app/ads1/budget_optimizer.py

@@ -0,0 +1,134 @@
+from app.recs.generate import generate_explanation
+
+def build_campaign_summary(dfs: dict) -> dict:
+    df = dfs["keywords"]
+
+    total_cost = df["cost"].sum()
+    total_conv = df["conversions"].sum()
+
+    avg_cpl = (
+        total_cost / total_conv
+        if total_conv > 0
+        else 0
+    )
+
+    return {
+        "total_spend": round(total_cost, 2),
+        "total_conversions": int(total_conv),
+        "avg_cpl": round(avg_cpl, 2),
+    }
+
+def build_scale_candidates(dfs: dict):
+    kw = dfs["keywords"].copy()
+
+    kw["cpl"] = (
+        kw["cost"] /
+        kw["conversions"].replace(0, 1)
+    )
+
+    account_avg = (
+        kw["cost"].sum() /
+        max(kw["conversions"].sum(), 1)
+    )
+
+    winners = kw[
+        (kw["conversions"] > 0)
+        & (kw["cpl"] < account_avg * 0.7)
+    ]
+
+    winners = winners.sort_values(
+        "conversions",
+        ascending=False
+    )
+
+    return winners.head(3)[[
+        "keyword",
+        "ad_group_name",
+        "cpl",
+        "conversions"
+    ]].to_dict("records")
+
+def build_cut_candidates(dfs: dict):
+    kw = dfs["keywords"].copy()
+
+    kw["cpl"] = (
+        kw["cost"] /
+        kw["conversions"].replace(0, 1)
+    )
+
+    account_avg = (
+        kw["cost"].sum() /
+        max(kw["conversions"].sum(), 1)
+    )
+
+    losers = kw[
+        (kw["cost"] > 0)
+        & (
+            (kw["conversions"] == 0)
+            |
+            (kw["cpl"] > account_avg * 1.5)
+        )
+    ]
+
+    losers = losers.sort_values(
+        "cost",
+        ascending=False
+    )
+
+    return losers.head(3)[[
+        "keyword",
+        "ad_group_name",
+        "cost",
+        "conversions",
+        "cpl"
+    ]].to_dict("records")
+
+def build_budget_optimizer_context(dfs: dict):
+
+    summary = build_campaign_summary(dfs)
+
+    return {
+        "summary": summary,
+        "scale_candidates": build_scale_candidates(dfs),
+        "cut_candidates": build_cut_candidates(dfs),
+    }
+
+def build_budget_optimizer_prompt(context):
+
+    return f"""
+You are a Google Ads budget optimization expert.
+
+Your goal is to identify where budget should be increased and where it should be reduced.
+
+Campaign Summary:
+{context["summary"]}
+
+Best Opportunities To Scale:
+{context["scale_candidates"]}
+
+Worst Budget Drains:
+{context["cut_candidates"]}
+
+Rules:
+- Return exactly 3 to 5 bullet points.
+- Use simple business language.
+- Mention where budget should increase.
+- Mention where budget should decrease.
+- Focus on efficiency and lead generation.
+- No reasoning process.
+"""
+
+def run_budget_optimizer_card(dfs):
+
+    context = build_budget_optimizer_context(dfs)
+
+    prompt = build_budget_optimizer_prompt(context)
+
+    rec = {
+        "campaign_id": "BUDGET_OPTIMIZER",
+        "type": "budget_optimization",
+        "action": "reallocate_budget",
+        "reason": prompt,
+    }
+
+    return generate_explanation(rec)

app/ads1/connector.py

@@ -0,0 +1,87 @@
+from logging import config
+from xmlrpc import client
+import os
+from google.ads.googleads.client import GoogleAdsClient
+
+def get_client():
+    required = [
+        "GOOGLE_ADS_DEVELOPER_TOKEN",
+        "GOOGLE_ADS_CLIENT_ID",
+        "GOOGLE_ADS_CLIENT_SECRET",
+        "GOOGLE_ADS_REFRESH_TOKEN"
+    ]
+
+    for r in required:
+        if not os.getenv(r):
+            raise ValueError(f"Missing env var: {r}")
+
+    config = {
+        "developer_token": os.getenv("GOOGLE_ADS_DEVELOPER_TOKEN"),
+        "client_id": os.getenv("GOOGLE_ADS_CLIENT_ID"),
+        "client_secret": os.getenv("GOOGLE_ADS_CLIENT_SECRET"),
+        "refresh_token": os.getenv("GOOGLE_ADS_REFRESH_TOKEN"),
+        "login_customer_id": os.getenv("GOOGLE_ADS_LOGIN_CUSTOMER_ID"),
+        "use_proto_plus": True
+    }
+
+    client = GoogleAdsClient.load_from_dict(config)
+    return client
+
+
+def list_campaigns(customer_id):
+    client = get_client()
+    ga_service = client.get_service("GoogleAdsService")
+
+    query = """
+        SELECT
+          campaign.id,
+          campaign.name,
+          campaign.status
+        FROM campaign
+        LIMIT 20
+    """
+
+    response = ga_service.search(customer_id=customer_id, query=query)
+
+    results = []
+
+    for row in response:
+        results.append({
+            "id": row.campaign.id,
+            "name": row.campaign.name,
+            "status": row.campaign.status.name
+        })
+
+    return results
+
+def get_campaign_metrics(customer_id):
+    client = get_client()
+    ga_service = client.get_service("GoogleAdsService")
+
+    query = """
+        SELECT
+          campaign.id,
+          metrics.impressions,
+          metrics.clicks,
+          metrics.cost_micros,
+          metrics.conversions,
+          metrics.ctr
+        FROM campaign
+        WHERE segments.date DURING LAST_30_DAYS
+    """
+
+    response = ga_service.search(customer_id=customer_id, query=query)
+
+    data = []
+
+    for row in response:
+        data.append({
+            "campaign_id": row.campaign.id,
+            "impressions": row.metrics.impressions,
+            "clicks": row.metrics.clicks,
+            "cost": row.metrics.cost_micros / 1e6,
+            "conversions": row.metrics.conversions,
+            "ctr": row.metrics.ctr,
+        })
+
+    return data

app/ads1/fetch_ads_data.py

@@ -0,0 +1,156 @@
+# app/ads1/runner.py
+
+import pandas as pd
+from app.ads1.connector import get_client
+from app.ads1.ads_queries import (
+    CAMPAIGNS_QUERY,
+    DEVICES_QUERY,
+    HOURLY_QUERY,
+    GEO_QUERY,
+    SEARCH_TERMS_QUERY,
+    KEYWORDS_QUERY,
+    RECOMMENDATIONS_QUERY,
+)
+
+def run_query(client, customer_id, query):
+    service = client.get_service("GoogleAdsService")
+    response = service.search(customer_id=customer_id, query=query)
+
+    rows = []
+    for r in response:
+        rows.append(r)
+
+    return rows
+
+
+def fetch_all_data(customer_id):
+    client = get_client()
+
+    service = client.get_service("GoogleAdsService")
+
+    def execute(query):
+        response = service.search(customer_id=customer_id, query=query)
+        return list(response)
+
+    print("🔄 Fetching campaigns...")
+    campaigns = execute(CAMPAIGNS_QUERY)
+
+    print("🔄 Fetching devices...")
+    devices = execute(DEVICES_QUERY)
+
+    print("🔄 Fetching hourly data...")
+    hourly = execute(HOURLY_QUERY)
+
+    print("🔄 Fetching geo data...")
+    geo = execute(GEO_QUERY)
+
+    print("🔄 Fetching search terms...")
+    search_terms = execute(SEARCH_TERMS_QUERY)
+
+    print("🔄 Fetching keywords...")
+    keywords = execute(KEYWORDS_QUERY)
+
+    print("🔄 Fetching recommendations...")
+    recommendations = execute(RECOMMENDATIONS_QUERY)
+
+    return {
+        "campaigns": campaigns,
+        "devices": devices,
+        "hourly": hourly,
+        "geo": geo,
+        "search_terms": search_terms,
+        "keywords": keywords,
+        "recommendations": recommendations
+    }
+
+
+def to_dataframes(raw_data):
+    dfs = {}
+
+    # Campaigns
+    dfs["campaigns"] = pd.DataFrame([
+        {
+            "id": r.campaign.id,
+            "name": r.campaign.name,
+            "status": r.campaign.status.name,
+            "impressions": r.metrics.impressions,
+            "clicks": r.metrics.clicks,
+            "cost": r.metrics.cost_micros / 1e6,
+            "ctr": r.metrics.ctr,
+            "conversions": r.metrics.conversions or 0 
+        }
+        for r in raw_data["campaigns"]
+    ])
+
+    # Devices
+    dfs["devices"] = pd.DataFrame([
+        {
+            "device": r.segments.device.name,
+            "clicks": r.metrics.clicks,
+            "impressions": r.metrics.impressions,
+            "cost": r.metrics.cost_micros / 1e6
+        }
+        for r in raw_data["devices"]
+    ])
+
+    # Hourly
+    dfs["hourly"] = pd.DataFrame([
+        {
+            "date": r.segments.date,
+            "hour": r.segments.hour,
+            "clicks": r.metrics.clicks,
+            "impressions": r.metrics.impressions,
+            "cost": r.metrics.cost_micros / 1e6
+        }
+        for r in raw_data["hourly"]
+    ])
+
+    # Geo
+    dfs["geo"] = pd.DataFrame([
+    {
+        "country_id": r.geographic_view.country_criterion_id,
+        "clicks": r.metrics.clicks,
+        "impressions": r.metrics.impressions,
+        "cost": r.metrics.cost_micros / 1e6
+    }
+    for r in raw_data["geo"]
+])
+
+    # Search terms
+    dfs["search_terms"] = pd.DataFrame([
+        {
+            "search_term": r.search_term_view.search_term,
+            "clicks": r.metrics.clicks,
+            "impressions": r.metrics.impressions,
+            "cost": r.metrics.cost_micros / 1e6
+        }
+        for r in raw_data["search_terms"]
+    ])
+
+    # Keywords
+    dfs["keywords"] = pd.DataFrame([
+    {
+        "campaign_id": r.campaign.id,
+        "campaign_name": r.campaign.name,
+        "ad_group_id": r.ad_group.id if r.ad_group else None,
+        "ad_group_name": r.ad_group.name if r.ad_group else None,
+        "keyword": r.ad_group_criterion.keyword.text if r.ad_group_criterion.keyword else None,
+        "clicks": r.metrics.clicks,
+        "impressions": r.metrics.impressions,
+        "cost": r.metrics.cost_micros / 1e6,
+        "conversions": r.metrics.conversions,
+        "ctr": r.metrics.ctr,
+    }
+    for r in raw_data["keywords"]
+])
+    
+    dfs["recommendations"] = pd.DataFrame([
+    {
+        "type": r.recommendation.type.name,
+        "resource_name": r.recommendation.resource_name,
+        "campaign": r.recommendation.campaign
+    }
+    for r in raw_data["recommendations"]
+])
+
+    return dfs

app/controller/session_loader.py

@@ -0,0 +1,21 @@
+from app.ads1.fetch_ads_data import fetch_all_data, to_dataframes
+import os
+
+_cached_dfs = None
+
+def load_google_ads_data(force_refresh=False):
+    global _cached_dfs
+
+    customer_id = os.getenv("GOOGLE_ADS_CUSTOMER_ID")
+
+    if not customer_id:
+        raise ValueError("GOOGLE_ADS_CUSTOMER_ID missing")
+
+    if _cached_dfs is not None and not force_refresh:
+        return _cached_dfs
+
+    raw = fetch_all_data(customer_id)
+    dfs = to_dataframes(raw)
+
+    _cached_dfs = dfs
+    return dfs

app/db/models.py

@@ -0,0 +1,41 @@
+from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey
+from sqlalchemy.orm import declarative_base, relationship
+from datetime import datetime
+
+Base = declarative_base()
+
+class Campaign(Base):
+    __tablename__ = "campaigns"
+
+    id = Column(Integer, primary_key=True)
+    google_campaign_id = Column(String, unique=True)
+    name = Column(String)
+
+    budget = Column(Float)
+    spend = Column(Float)
+    clicks = Column(Integer)
+    impressions = Column(Integer)
+
+    ctr = Column(Float)
+    leads = Column(Integer)
+    cpl = Column(Float)
+
+    last_synced = Column(DateTime, default=datetime.utcnow)
+
+    recommendations = relationship("Recommendation", back_populates="campaign")
+
+class Recommendation(Base):
+    __tablename__ = "recommendations"
+
+    id = Column(Integer, primary_key=True)
+
+    campaign_id = Column(Integer, ForeignKey("campaigns.id"))
+
+    recommendation_type = Column(String)
+    action = Column(String)
+    reason = Column(String)
+
+    status = Column(String, default="Pending")  # Pending / Approved / Rejected
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+    campaign = relationship("Campaign", back_populates="recommendations")

app/db/repo.py

@@ -0,0 +1,61 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from app.db.models import Base, Campaign, Recommendation
+
+engine = create_engine("sqlite:///ads.db")
+
+SessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=engine
+)
+
+def init_db():
+    Base.metadata.create_all(bind=engine)
+
+def get_campaigns():
+    session = SessionLocal()
+    try:
+        return session.query(Campaign).all()
+    finally:
+        session.close()
+
+def get_recommendations():
+    session = SessionLocal()
+    try:
+        return session.query(Recommendation).all()
+    finally:
+        session.close()
+
+def approve_recommendation(recommendation_id: int):
+    session = SessionLocal()
+    try:
+        recommendation = (
+            session.query(Recommendation)
+            .filter(Recommendation.id == recommendation_id)
+            .first()
+        )
+
+        if recommendation:
+            recommendation.status = "Approved"
+            session.commit()
+
+        return "Recommendation approved"
+    finally:
+        session.close()
+
+def reject_recommendation(recommendation_id: int):
+    session = SessionLocal()
+    try:
+        recommendation = (
+            session.query(Recommendation)
+            .filter(Recommendation.id == recommendation_id)
+            .first()
+        )
+        if recommendation:
+            recommendation.status = "Rejected"
+            session.commit()
+        return "Recommendation rejected"
+    finally:
+        session.close()

app/models/llm.py

@@ -0,0 +1,24 @@
+from huggingface_hub import hf_hub_download
+from llama_cpp import Llama
+
+_model = None
+
+def load_model():
+    global _model
+
+    if _model is not None:
+        return _model
+
+    model_path = hf_hub_download(
+        repo_id="Abiray/MiniCPM5-1B-GGUF",
+        filename="minicpm5-1b-Q4_K_M.gguf",
+    )
+
+    _model = Llama(
+        model_path=model_path,
+        n_ctx=4096,
+        n_threads=4,
+        verbose=False,
+    )
+
+    return _model

app/recs/generate.py

@@ -0,0 +1,44 @@
+from typing import Dict, Iterator
+import re
+from app.models.llm import load_model
+
+TARGET_CPL = 20.0
+
+
+def fallback_explanation(rec: Dict = None) -> str:
+    return "This recommendation was generated from campaign performance metrics."
+
+
+def sanitize_explanation(text: str, rec: Dict = None) -> str:
+    cleaned = re.sub(r"\s+", " ", text).strip()
+
+    if not cleaned or len(cleaned) < 10:
+        return fallback_explanation(rec)
+
+    return cleaned
+
+def generate_explanation(prompt: str, rec: Dict = None, stream: bool = False):
+    print("🔥 LLM CALLED")
+
+    llm = load_model()
+
+    try:
+
+        response = llm.create_chat_completion(
+        messages=[
+            {"role": "system", "content": "You are an expert marketing analyst for Google Ads.You MUST NOT output reasoning, thinking, or tags like <think>.You MUST ONLY output final answer."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=0.7,)
+        raw = response["choices"][0]["message"]["content"]
+
+        clean = re.sub(r"<think>.*?</think>", "", raw, flags=re.DOTALL)
+        clean = re.sub(r"(?s).*?Reasoning:.*?\n", "", clean)
+        clean = re.sub(r"(?s).*?Step \d+.*?\n", "", clean)
+
+        print(clean)
+        return clean
+
+    except Exception as e:
+        print("❌ LLM ERROR:", e)
+        return fallback_explanation(rec)

app/recs/rules.py

@@ -0,0 +1,53 @@
+from typing import Dict, List
+
+TARGET_CPL = 20.0
+CTR_THRESHOLD = 2.0
+
+def generate_recommendations(metrics: List[Dict]) -> List[Dict]:
+    """
+    Rule engine that converts metrics → recommendations
+    """
+    recommendations = []
+
+    for m in metrics:
+        campaign_id = m["campaign_id"]
+        cpl = m["cpl"]
+        ctr = m["ctr"]
+
+        # Rule 1: High CPL
+        if cpl > TARGET_CPL * 1.5:
+            recommendations.append({
+                "campaign_id": campaign_id,
+                "type": "high_cpl",
+                "action": "reduce_budget",
+                "reason": f"CPL {cpl} is significantly above target {TARGET_CPL}",
+                "cpl": cpl,
+                "target_cpl": TARGET_CPL,
+                "ctr": ctr,
+            })
+
+        # Rule 2: Strong campaign
+        elif cpl < TARGET_CPL * 0.8:
+            recommendations.append({
+                "campaign_id": campaign_id,
+                "type": "strong_campaign",
+                "action": "increase_budget",
+                "reason": f"CPL {cpl} is well below target {TARGET_CPL}",
+                "cpl": cpl,
+                "target_cpl": TARGET_CPL,
+                "ctr": ctr,
+            })
+
+        # Rule 3: Low CTR
+        if ctr < CTR_THRESHOLD:
+            recommendations.append({
+                "campaign_id": campaign_id,
+                "type": "low_ctr",
+                "action": "review_ad_copy",
+                "reason": f"CTR {ctr}% is below threshold {CTR_THRESHOLD}%",
+                "cpl": cpl,
+                "target_cpl": TARGET_CPL,
+                "ctr": ctr,
+            })
+
+    return recommendations

app/ui/dashboard.py

@@ -0,0 +1,69 @@
+import gradio as gr
+import pandas as pd
+from app.controller.session_loader import load_google_ads_data
+
+# DATA LOADER
+# -------------------------
+def load_dashboard():
+    dfs = load_google_ads_data()
+    df = dfs["campaigns"].copy()
+
+    if df.empty:
+        return (
+            0, 0, 0, 0,
+            pd.DataFrame(columns=[
+                "Campaign", "Spend", "Leads", "CPL", "CTR"
+            ])
+        )
+
+    # derive missing fields safely
+    df["leads"] = df["conversions"] if "conversions" in df.columns else 0
+    df["cpl"] = df["cost"] / df["leads"].replace(0, 1)
+    df["ctr"] = df["ctr"]
+
+    formatted = pd.DataFrame({
+        "Campaign": df["name"],
+        "Spend": df["cost"],
+        "Leads": df["leads"],
+        "CPL": df["cpl"],
+        "CTR": df["ctr"],
+    })
+
+    return (
+        round(formatted["Spend"].sum(), 2),
+        int(formatted["Leads"].sum()),
+        round(formatted["CPL"].mean(), 2),
+        len(formatted),
+        formatted
+    )
+
+# UI BUILDER
+# -------------------------
+def build_dashboard():
+    gr.Markdown("## Campaign Dashboard")
+
+    with gr.Row():
+        total_spend = gr.Number(label="Total Spend")
+        total_leads = gr.Number(label="Total Leads")
+        average_cpl = gr.Number(label="Average CPL")
+        active_campaigns = gr.Number(label="Active Campaigns")
+
+    campaign_table = gr.Dataframe(
+        label="Campaign Performance",
+        interactive=True   # IMPORTANT: needed for row click
+    )
+
+    refresh_btn = gr.Button("Refresh Dashboard")
+    refresh_btn.click(
+        fn=load_dashboard,
+        outputs=[
+            total_spend,
+            total_leads,
+            average_cpl,
+            active_campaigns,
+            campaign_table,
+        ],
+    )
+
+    # ✅ IMPORTANT FIX: return table so main.py can attach .select()
+    return campaign_table

app/ui/recommendations.py

@@ -0,0 +1,77 @@
+import gradio as gr
+import pandas as pd
+
+from app.db.repo import (
+    get_recommendations,
+    approve_recommendation,
+    reject_recommendation,
+)
+
+def load_recommendations():
+    recommendations = get_recommendations()
+    data = []
+    for recommendation in recommendations:
+        campaign_name = ""
+        if recommendation.campaign:
+            campaign_name = recommendation.campaign.name
+        data.append(
+            {
+                "ID": recommendation.id,
+                "Campaign": campaign_name,
+                "Recommendation": recommendation.action,
+                "Status": recommendation.status,
+            }
+        )
+    return pd.DataFrame(data)
+
+
+def approve_action(rec_id):
+    approve_recommendation(int(rec_id))
+    return (
+        "Recommendation approved",
+        load_recommendations(),
+    )
+
+def reject_action(rec_id):
+    reject_recommendation(int(rec_id))
+    return (
+        "Recommendation rejected",
+        load_recommendations(),
+    )
+
+def build_recommendations_page():
+    gr.Markdown("## Recommendations")
+    recommendation_table = gr.Dataframe(
+        label="Recommendations",
+        interactive=False,
+    )
+    recommendation_id = gr.Number(
+        label="Recommendation ID"
+    )
+    status_message = gr.Textbox(
+        label="Status"
+    )
+    with gr.Row():
+        approve_btn = gr.Button("Approve")
+        reject_btn = gr.Button("Reject")
+    refresh_btn = gr.Button("Refresh")
+    refresh_btn.click(
+        fn=load_recommendations,
+        outputs=recommendation_table,
+    )
+    approve_btn.click(
+        fn=approve_action,
+        inputs=recommendation_id,
+        outputs=[
+            status_message,
+            recommendation_table,
+        ],
+    )
+    reject_btn.click(
+        fn=reject_action,
+        inputs=recommendation_id,
+        outputs=[
+            status_message,
+            recommendation_table,
+        ],
+    )

docs/superpowers/plans/2026-06-03-ads-automation-prd.md

@@ -0,0 +1,285 @@
+# Ads Automation 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 v1 of a Google Ads recommendation-and-approval system for a preschool that monitors campaigns, generates structured recommendations using MiniCPM5-1B, and applies approved safe changes (budget adjustments, pause/resume, add negative keywords). Deploy as a Gradio app on a Hugging Face Space (CPU) with SQLite as the app source of truth.
+
+**Architecture:** Single Gradio app with an embedded scheduler (APScheduler + SQLite jobstore). Deterministic rule engine produces candidate deltas; MiniCPM5 generates human-readable recommendation text. Google Ads integration uses `google-ads` Python client with admin OAuth. App persists to SQLite and syncs to Google Sheets for visibility.
+
+**Tech Stack:** Python 3.10+, Gradio, SQLAlchemy, APScheduler, google-ads, google-auth, llama-cpp-python, pandas, requests, pytest.
+
+---
+
+### Task 1: Scaffold project layout
+
+**Files:**
+- Create: `app/__init__.py`
+- Create: `app/main.py` (Gradio entrypoint)
+- Create: `app/ads/connector.py`
+- Create: `app/db/models.py`
+- Create: `app/db/repo.py`
+- Create: `app/recs/rules.py`
+- Create: `app/models/llm.py`
+- Create: `app/scheduler/jobs.py`
+- Create: `scripts/seed_demo.py`
+- Create: `requirements.txt`
+- Create: `README.md`
+
+- [ ] Step 1: Create repository layout and `requirements.txt`.
+
+Create `requirements.txt` with:
+
+```text
+gradio
+sqlalchemy
+alembic
+apscheduler
+google-ads
+google-auth
+pandas
+requests
+llama-cpp-python
+pytest
+python-dotenv
+gspread
+oauth2client
+
+tqdm
+```
+
+Run locally to verify environment installs:
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+Expected: packages install without fatal errors.
+
+- [ ] Step 2: Commit the scaffold files (empty imports and module docstrings acceptable) and run a smoke start of `app/main.py` to ensure import graph is valid.
+
+Run:
+
+```bash
+python -c "import app; print('scaffold ok')"
+```
+
+Expected: prints `scaffold ok`.
+
+---
+
+### Task 2: Implement SQLite schema + ORM
+
+**Files:**
+- Modify: `app/db/models.py`
+- Create: `app/db/migrate.py` (simple create-tables script)
+- Create: `app/db/repo.py` (CRUD helpers)
+
+- [ ] Step 1: Define SQLAlchemy models for `Campaign`, `AdGroup`, `Keyword`, `Lead`, `Recommendation`, `AuditLog`.
+
+Example `Campaign` model snippet (to include in file):
+
+```python
+from sqlalchemy import Column, Integer, String, Boolean, Float, JSON, DateTime
+from sqlalchemy.ext.declarative import declarative_base
+from datetime import datetime
+
+Base = declarative_base()
+
+class Campaign(Base):
+    __tablename__ = 'campaigns'
+    id = Column(Integer, primary_key=True)
+    google_campaign_id = Column(String, unique=True, nullable=False)
+    name = Column(String)
+    managed = Column(Boolean, default=False)
+    budget = Column(Float)
+    target_cpl_override = Column(Float, nullable=True)
+    last_synced = Column(DateTime, default=datetime.utcnow)
+```
+
+- [ ] Step 2: Implement `migrate.py` to create tables.
+
+Run to verify:
+
+```bash
+python app/db/migrate.py
+python - <<'PY'
+from app.db.repo import SessionLocal
+print('db ok')
+PY
+```
+
+Expected: DB file created and `db ok` printed.
+
+- [ ] Step 3: Add unit tests for model creation in `tests/test_db.py` using `pytest`.
+
+---
+
+### Task 3: Google Ads connector + admin OAuth
+
+**Files:**
+- Create: `app/ads/connector.py` (wraps `google-ads` client)
+- Create: `app/ads/oauth.py` (helper for OAuth flow)
+- Modify: `app/main.py` (admin settings UI to start OAuth or paste tokens)
+
+- [ ] Step 1: Implement OAuth helper that can accept client_id/client_secret and produce a refresh_token (manual paste fallback supported).
+
+- [ ] Step 2: Implement connector functions:
+  - `list_campaigns()` (returns campaigns metadata)
+  - `get_campaign_metrics(campaign_ids, start_date, end_date)` (returns spend, clicks, impressions, CTR, conversions/leads)
+  - `apply_budget_change(campaign_id, new_budget)`
+  - `pause_keyword(keyword_id)`
+  - `add_negative_keyword(campaign_id, phrase)`
+
+- [ ] Step 3: Mock Google Ads in tests `tests/test_ads_connector.py` using recorded fixtures or a simple interface stub.
+
+Verification:
+
+- Run `python -c "from app.ads.connector import list_campaigns; print(list_campaigns()[:1])"` with mocked creds to ensure no crashes.
+
+---
+
+### Task 4: Rule engine (deterministic signals)
+
+**Files:**
+- Modify: `app/recs/rules.py`
+
+- [ ] Step 1: Implement moving-average smoothing (3-day simple moving average) and min-sample guards.
+
+- [ ] Step 2: Implement the default rules from the spec. Each rule returns a candidate delta dict when fired.
+
+- [ ] Step 3: Unit tests in `tests/test_rules.py` covering each rule with synthetic metric inputs and expected candidate deltas.
+
+---
+
+### Task 5: MiniCPM5 wrapper and prompt pipeline
+
+**Files:**
+- Modify/Create: `app/models/llm.py`
+- Modify: `app/recs/generate.py` (build prompt, call llm, validate JSON)
+
+- [ ] Step 1: Implement a thin wrapper using `llama_cpp` from `llama-cpp-python` to load GGUF from HF Hub path. Support a `load_model(llm_repo_id, llm_filename, cache_dir)` call.
+
+- [ ] Step 2: Implement prompt template that accepts a JSON payload and instructs the model to return a single `recommendation` JSON object following the schema. Example instructions must enforce JSON-only output.
+
+- [ ] Step 3: Implement output validation using `jsonschema` or Python checks; reject and retry + fallback to deterministic textual reason if parsing fails.
+
+- [ ] Step 4: Unit tests for `generate.py` to assert correct parseable output given a mocked model runner.
+
+Notes: target inference via `llama-cpp-python` with the quantized GGUF. For Space CPU mode, expect slower responses; implement a request timeout and a cached most-recent recommendation for UI responsiveness.
+
+---
+
+### Task 6: Gradio UI pages
+
+**Files:**
+- Modify/Create: `app/main.py` (Gradio app)
+- Modify/Create: `app/ui/dashboard.py`
+- Modify/Create: `app/ui/campaigns.py`
+- Modify/Create: `app/ui/recommendations.py`
+- Modify/Create: `app/ui/leads.py`
+- Modify/Create: `app/ui/admin.py`
+
+- [ ] Step 1: Implement `Main Dashboard` with summary cards and a small time-series chart (use `pandas` to prepare data and `gradio` components to display). Include a button to trigger on-demand review.
+
+- [ ] Step 2: `Campaigns` page: table with per-campaign KPIs and a toggle to mark campaign as `managed`.
+
+- [ ] Step 3: `Recommendations` page: list recommendations, view details, Approve/Reject controls with scheduling and staged rollout UI.
+
+- [ ] Step 4: `Lead Manager` page: table to mark leads as `booked`, manual-add lead form, and export button to Google Sheets.
+
+- [ ] Step 5: `Admin` page: set global `target_cpl`, manage HF Secrets link, manual OAuth flow start.
+
+Verification: start the Gradio app locally:
+
+```bash
+python app/main.py
+# visit http://localhost:7860
+```
+
+Expected: App loads, pages render, no JS errors.
+
+---
+
+### Task 7: Scheduler + Auto-apply
+
+**Files:**
+- Modify/Create: `app/scheduler/jobs.py`
+- Modify/Create: `app/scheduler/bootstrap.py`
+
+- [ ] Step 1: Wire APScheduler with SQLite jobstore and add daily job to run the review loop.
+
+- [ ] Step 2: Implement apply jobs that call the Ads connector to enact approved changes and write audit logs and rollback snapshots.
+
+- [ ] Step 3: Tests: `tests/test_scheduler.py` with in-memory jobstore verifying a job runs and changes recorded in DB.
+
+---
+
+### Task 8: Google Sheets sync & Lead capture
+
+**Files:**
+- Create: `scripts/sheet_sync.py`
+- Modify: `app/leads/sync.py`
+
+- [ ] Step 1: Implement Google Sheets API write-only sync for leads; use service-account or OAuth depending on deployment constraints.
+
+- [ ] Step 2: Implement landing page form that writes to DB and triggers immediate UI visibility.
+
+- [ ] Step 3: Tests: `tests/test_sheets.py` with a mocked sheets client.
+
+---
+
+### Task 9: Seeded demo data & testing
+
+**Files:**
+- Modify/Create: `scripts/seed_demo.py`
+
+- [ ] Step 1: Implement seed script that creates sample campaigns, keywords, synthetic metrics and leads to exercise rules and model pipeline.
+
+- [ ] Step 2: Add end-to-end smoke test `tests/test_e2e.py` that runs seed, triggers a review, generates recommendations (mocked LLM), and simulates approval + apply (with Ads connector mocked).
+
+---
+
+### Task 10: Documentation & HF Space deploy
+
+**Files:**
+- Modify/Create: `README.md` (run/deploy instructions)
+- Modify/Create: `Dockerfile` or HF `requirements.txt` and `runtime.txt` if needed
+
+- [ ] Step 1: Write deployment steps for HF Space (including HF Secrets setup and model cache instructions).
+
+- [ ] Step 2: Provide a small `try it` section in `README.md` showing how to run locally and how to seed demo data.
+
+Example local run commands:
+
+```bash
+# local dev
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+python app/db/migrate.py
+python scripts/seed_demo.py
+python app/main.py
+```
+
+**Expected:** Developer can run seeded demo locally and browse to the Gradio app.
+
+---
+
+## Self-Review Checklist
+
+1. Spec coverage: every requirement in the design spec maps to Tasks 1–10 above.
+2. No placeholders: each step includes the commands/files needed to implement and test.
+3. Type consistency: models, repo, and file names used consistently above.
+
+---
+
+## Handoff / Execution choices
+
+Plan complete and saved to `docs/superpowers/plans/2026-06-03-ads-automation-prd.md`. Two execution options:
+
+1. Subagent-Driven (recommended) — run `subagent-driven-development` agent per task, review between tasks.
+2. Inline Execution — I (or the `executing-plans` agent) implement tasks in this session according to the checklist.
+
+Which approach do you want? Reply with `subagent` or `inline`.

docs/superpowers/plans/simplified.md

@@ -0,0 +1,481 @@
+# 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:
+
+```text
+gradio
+sqlalchemy
+google-ads
+pandas
+llama-cpp-python
+pytest
+python-dotenv
+requests
+```
+
+Verify:
+
+```bash
+python -m venv .venv
+pip install -r requirements.txt
+```
+
+Expected: all packages install successfully.
+
+* [ ] Step 2: Verify imports.
+
+```bash
+python -c "import app; print('scaffold ok')"
+```
+
+Expected:
+
+```text
+scaffold ok
+```
+
+---
+
+### Task 2: SQLite Models
+
+**Files:**
+
+* Modify: `app/db/models.py`
+
+* Modify: `app/db/repo.py`
+
+* [ ] Step 1: Create `Campaign` model.
+
+Fields:
+
+```python
+id
+google_campaign_id
+name
+budget
+spend
+clicks
+impressions
+ctr
+leads
+cpl
+last_synced
+```
+
+* [ ] Step 2: Create `Recommendation` model.
+
+Fields:
+
+```python
+id
+campaign_id
+recommendation_type
+action
+reason
+status
+created_at
+```
+
+Status values:
+
+```text
+Pending
+Approved
+Rejected
+```
+
+* [ ] Step 3: Create database initialization helper.
+
+Verify:
+
+```bash
+python -c "from app.db.repo import init_db; init_db(); print('db ok')"
+```
+
+Expected:
+
+```text
+db ok
+```
+
+---
+
+### Task 3: Google Ads Read-Only Connector
+
+**Files:**
+
+* Modify: `app/ads/connector.py`
+
+* [ ] Step 1: Implement:
+
+```python
+list_campaigns()
+```
+
+Returns:
+
+```python
+[
+  {
+    "id": "...",
+    "name": "...",
+    "budget": ...
+  }
+]
+```
+
+* [ ] Step 2: Implement:
+
+```python
+get_campaign_metrics()
+```
+
+Returns:
+
+```python
+[
+  {
+    "campaign_id": "...",
+    "spend": ...,
+    "clicks": ...,
+    "impressions": ...,
+    "ctr": ...,
+    "leads": ...,
+    "cpl": ...
+  }
+]
+```
+
+* [ ] Step 3: Add mock tests for connector responses.
+
+Expected:
+
+```bash
+$env:PYTHONPATH="."
+pytest
+```
+
+passes.
+
+---
+
+### Task 4: Rule Engine
+
+**Files:**
+
+* Modify: `app/recs/rules.py`
+
+* [ ] Step 1: Implement High CPL Rule.
+
+Condition:
+
+```text
+CPL > Target CPL × 1.5
+```
+
+Recommendation:
+
+```text
+Reduce budget allocation
+```
+
+* [ ] Step 2: Implement Strong Campaign Rule.
+
+Condition:
+
+```text
+CPL < Target CPL × 0.8
+```
+
+Recommendation:
+
+```text
+Increase budget allocation
+```
+
+* [ ] Step 3: Implement Low CTR Rule.
+
+Condition:
+
+```text
+CTR < 2%
+```
+
+Recommendation:
+
+```text
+Review ad copy and keywords
+```
+
+* [ ] Step 4: Return structured recommendation objects.
+
+Example:
+
+```json
+{
+  "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:
+
+```python
+load_model()
+```
+
+* [ ] Step 2: Generate explanations from recommendation payloads.
+
+Input:
+
+```json
+{
+  "campaign":"Preschool Search",
+  "cpl":42,
+  "target_cpl":20,
+  "action":"reduce_budget"
+}
+```
+
+Output:
+
+```text
+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:
+
+```text
+Total Spend
+Total Leads
+Average CPL
+Active Campaigns
+```
+
+* [ ] Step 3: Add Recommendations Page.
+
+Display:
+
+| Campaign | Recommendation | Status |
+| -------- | -------------- | ------ |
+
+* [ ] Step 4: Add Approve button.
+
+Updates:
+
+```text
+Pending → Approved
+```
+
+* [ ] Step 5: Add Reject button.
+
+Updates:
+
+```text
+Pending → Rejected
+```
+
+Verification:
+
+```bash
+python app/main.py
+```
+
+Expected:
+
+Dashboard loads successfully.
+
+---
+
+### Task 7: Demo Data
+
+**Files:**
+
+* Modify: `scripts/seed_demo.py`
+
+* [ ] Step 1: Generate sample campaigns.
+
+Create:
+
+```text
+5 campaigns
+```
+
+* [ ] Step 2: Generate synthetic metrics.
+
+Create:
+
+```text
+30 days of data
+```
+
+* [ ] Step 3: Generate recommendations.
+
+Ensure dashboard always contains examples.
+
+Verification:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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**.

docs/superpowers/specs/2026-06-03-ads-automation-design.md

@@ -0,0 +1,100 @@
+# Ads Automation — v1 Design
+
+Date: 2026-06-03
+Project: Preschool Ads Automation (Google Ads)
+Scope: Hugging Face Space deploy, CPU runtime, recommendation-and-approval automation for Google Search campaigns.
+
+**Summary**
+- Deliver a single Gradio app that monitors Google Ads campaigns, generates structured recommendations using a local MiniCPM5-1B model (GGUF via `llama-cpp-python`), and applies approved, limited safe changes (budget adjustments, pause/resume, add negative keywords).  
+- App source-of-truth: SQLite. Syncs to Google Sheets for visibility.  
+- Scheduler: APScheduler in-process with SQLite jobstore; daily review loop + manual runs.  
+- Auth/secrets: HF Secrets for deployed Space; `.env` for local dev. Admin access via single password.
+
+**High-level Architecture**
+- Frontend: Gradio app with pages: Dashboard, Campaigns, Recommendations, Lead Manager, Audit & Logs, Settings.  
+- Backend modules (Python):
+  - `app/ads/`: Google Ads connector (official `google-ads` Python client) + admin OAuth flow to obtain refresh token.  
+  - `app/db/`: SQLAlchemy models and repository layer (SQLite).  
+  - `app/recs/`: deterministic rule engine (thresholds, smoothing) that produces candidate deltas.  
+  - `app/models/`: MiniCPM5 wrapper using `llama-cpp-python` that accepts a JSON instruction and returns structured JSON recommendations.  
+  - `app/scheduler/`: APScheduler bootstrap + job definitions (daily review, retry logic, on-demand runs).  
+  - `scripts/`: utilities (seed demo data, sheet sync, admin tasks).
+
+**Data Model (core tables)**
+- `campaigns` {id, google_campaign_id, name, managed:bool, budget, target_cpl_override, last_synced}  
+- `ad_groups` {id, campaign_id, google_ad_group_id, name}  
+- `keywords` {id, ad_group_id, google_keyword_id, text, match_type, active, last_metrics}  
+- `leads` {id, source, campaign_id, utm, name, phone, email, created_at, status(booked/visited/other)}  
+- `recommendations` {id, timestamp, campaign_id, entity_type, action, delta (json), reason, risk, confidence, origin_rule, apply_options, approved_by, applied_by, audit_json}  
+- `audit_logs` {id, user, action, payload, timestamp}
+
+**Recommendation Pipeline**
+1. Metrics ingestion: request last N days of metrics via Google Ads API (default 7/30-day windows). Store snapshots in SQLite.  
+2. Rule engine: evaluate deterministic rules (3-day smoothed moving averages, min-sample guards). If a rule fires, create a candidate delta.  
+3. Model prompt: build JSON-only prompt with: recent aggregates, supporting time-series summary, candidate delta, and entity metadata.  
+4. MiniCPM5 (local GGUF via `llama-cpp-python`) returns structured recommendation JSON following agreed schema.  
+5. Persist recommendation, send in-app notification/email/webhook.  
+6. Approver (admin) reviews in Recommendations page, chooses immediate/scheduled/staged apply or rejects.  
+7. If approved and auto-apply allowed, scheduler enqueues the apply job; apply executes via Google Ads client and writes audit and rollback metadata.
+
+**Rule Defaults (v1)**
+- Pause keyword: CPL > 1.5×target CPL for 3 consecutive days AND clicks ≥ 10.  
+- Add negative keyword: impressions ≥ 500, clicks ≥ 20, leads = 0, CTR < 0.5% for 7 days.  
+- Increase budget: CPL < 0.8×target CPL for 3 days AND leads ≥ 3 → +10% budget (cap per-campaign).  
+- Decrease budget: CPL > 1.25×target CPL for 3 days AND spend ≥ $20/day → −15% budget.
+
+**Recommendation Schema (v1)**
+- `id`, `timestamp`, `campaign_id`, `campaign_name`, `entity_type`, `action`, `delta`, `estimated_impact`, `reason`, `risk`, `confidence`, `origin_rule`, `supporting_metrics`, `apply_options`, `rollback_plan`, `audit`.
+
+**Auto-apply Safety**
+- Allowed actions: budget adjustments, pause/resume, negative keyword additions only.  
+- Approval required for any apply; app supports immediate, scheduled, or staged rollout (e.g., 25→50→100% over 48h).  
+- All changes include rollback metadata; maintain previous setting snapshot and a reversible job.
+
+**Model/Prompting**
+- Use `Abiray/MiniCPM5-1B-GGUF` (GGUF file). Load via `llama-cpp-python` at startup; cache in Space environment.  
+- Prompt must be strict: return only the `recommendation` JSON. Include a short human-readable summary for UI display.  
+- Model role: generate human-friendly `reason`, `risk`, `confidence`, and `estimated_impact` text. Deterministic numbers (spend/lead deltas) come from rule engine heuristics.
+
+**Lead Capture & Attribution**
+- Primary lead capture: single landing page form that writes to app DB (captures UTM parameters).  
+- Leads sync to Google Sheets (read-only audit view). Approver marks `booked` visits in Lead Manager; app updates lead status and syncs back to Sheets.
+
+**Auth & Secrets**
+- Deploy-time secrets stored in HF Secrets (Google OAuth client_id/secret, developer token, admin password). Local dev: `.env` only.  
+- Admin auth: single admin password for approving changes; optional read-only viewer links.
+
+**Deployment**
+- Target: Hugging Face Space (CPU-enabled). Use `requirements.txt` including `gradio`, `sqlalchemy`, `google-ads`, `google-auth`, `apscheduler`, `llama-cpp-python`.  
+- At startup: download GGUF from HF Hub if not cached, load model via `llama-cpp-python` with quantized Q4_K_M file.  
+- Provide `scripts/seed_demo.py` to populate seeded demo mode and `scripts/sheet_sync.py` for manual sync.
+
+**Testing & Demo Mode**
+- Seeded demo data for presentation mode when no live campaigns are available.  
+- Unit tests for rule engine, recommendation schema validation, DB migrations, and Google Ads connector mocks.
+
+**Privacy & Safety**
+- No secrets in repo. Provide clear audit trail for any change applied to Google Ads. Approver must explicitly approve before any change that modifies live campaigns.  
+
+**Next Steps (implementation checklist)**
+- [ ] Scaffold repo layout and `requirements.txt`  
+- [ ] Implement SQLite schema + SQLAlchemy models  
+- [ ] Implement admin OAuth flow and `google-ads` connector (read-only + mutating calls)  
+- [ ] Implement rule engine and recommendation generator (model wrapper)  
+- [ ] Build Gradio UI pages and flows (approve/apply)  
+- [ ] Implement APScheduler loop + job persistence  
+- [ ] Add Google Sheets sync and `scripts/`  
+- [ ] Write README, HF Space instructions, and seeded demo data  
+
+**Appendix — Key decisions (v1)**
+- Mode: Recommendation-and-approval (no fully autonomous without approval)  
+- KPI: Qualified leads / booked campus visits (CPL optimization)  
+- Channels: Google Search Ads only (v1)  
+- Auto-apply actions: budgets, pause/resume, negative keywords  
+- Model: MiniCPM5-1B (GGUF) used for textual recommendation generation only  
+
+---
+
+Spec authored by: GitHub Copilot assistant (design session)
+
+Please review this spec file and tell me if you want any edits before I write the implementation plan.

get_refresh_token.py

@@ -0,0 +1,14 @@
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SCOPES = ["https://www.googleapis.com/auth/adwords"]
+
+flow = InstalledAppFlow.from_client_secrets_file(
+    "client_secret.json",  # 👈 your downloaded file name
+    SCOPES
+)
+
+creds = flow.run_local_server(port=0)
+
+print("\n===== REFRESH TOKEN =====\n")
+print(creds.refresh_token)
+print("\n=========================\n")

main.py

@@ -0,0 +1,99 @@
+import gradio as gr
+import pandas as pd
+from dotenv import load_dotenv
+
+from app.db.repo import init_db
+from app.ui.dashboard import load_dashboard, build_dashboard
+from app.controller.session_loader import load_google_ads_data
+
+from app.ads1.ads_analyst import run_ads_analyst_card
+from app.ads1.budget_optimizer import run_budget_optimizer_card
+
+load_dotenv()
+init_db()
+
+# HELPERS
+def on_campaign_select(campaign_name):
+    dfs = load_google_ads_data()
+
+    filtered = dfs.copy()
+    filtered["campaigns"] = dfs["campaigns"][
+        dfs["campaigns"]["name"] == campaign_name
+    ]
+    return filtered
+
+def run_ads_card(state):
+    if not state:
+        return "⚠️ Please select a campaign from the Dashboard first."
+    return run_ads_analyst_card(state["dfs"])
+
+def run_budget_card(state):
+    if not state:
+        return "⚠️ Please select a campaign from the Dashboard first."
+    return run_budget_optimizer_card(state["dfs"])
+
+def campaign_row_selected(evt: gr.SelectData):
+    """
+    Triggered when user clicks a row in the dashboard table
+    """
+
+    df = load_dashboard()[4]  # campaign table returned by load_dashboard()
+    campaign_name = df.iloc[evt.index[0]]["Campaign"]
+    dfs = on_campaign_select(campaign_name)
+
+    return (
+        {
+            "campaign_name": campaign_name,
+            "dfs": dfs
+        },
+        f"## 📊 Selected Campaign: {campaign_name}"
+    )
+
+# GRADIO APP
+with gr.Blocks(title="Ads Assistant") as demo:
+
+    campaign_state = gr.State()
+    gr.Markdown("# 🎯 Preschool Ads Dashboard")
+
+    # TAB 1: DASHBOARD
+    # -------------------------
+    with gr.Tab("Dashboard"):
+
+        campaign_table = build_dashboard()
+
+    # TAB 2: CAMPAIGN ANALYSIS
+    # -------------------------
+    with gr.Tab("Campaign Analysis"):
+
+        selected_campaign = gr.Markdown(
+            "👈 Select a campaign from the Dashboard tab"
+        )
+
+        analyst_btn = gr.Button("Run Ads Analysis")
+        budget_btn = gr.Button("Run Budget Optimization")
+
+        output = gr.Markdown()
+
+        analyst_btn.click(
+            fn=run_ads_card,
+            inputs=campaign_state,
+            outputs=output
+        )
+
+        budget_btn.click(
+            fn=run_budget_card,
+            inputs=campaign_state,
+            outputs=output
+        )
+
+    # CONNECT TABLE CLICK → STATE
+    # -------------------------
+    campaign_table.select(
+        fn=campaign_row_selected,
+        outputs=[
+            campaign_state,
+            selected_campaign
+        ]
+    )
+
+demo.launch()

requirements.txt

@@ -0,0 +1,8 @@
+gradio>=5.0.0
+sqlalchemy      # for wat is this ?
+google-ads>=27.0.0
+pandas
+llama-cpp-python==0.2.90
+pytest
+python-dotenv
+requests

run_ads_data_pipeline.py

@@ -0,0 +1,23 @@
+from dotenv import load_dotenv
+load_dotenv()
+
+from app.ads1.fetch_ads_data import fetch_all_data, to_dataframes
+import os
+
+CUSTOMER_ID = os.getenv("GOOGLE_ADS_CUSTOMER_ID")
+
+def main():
+    raw = fetch_all_data(CUSTOMER_ID)
+    dfs = to_dataframes(raw)
+
+    for name, df in dfs.items():
+        print("\n====================")
+        print(name.upper())
+        print("====================")
+        print(df.head())
+
+    return dfs
+
+
+if __name__ == "__main__":
+    dfs = main()

run_inspect.py

@@ -0,0 +1,25 @@
+from dotenv import load_dotenv
+load_dotenv()
+from app.ads1.connector import list_campaigns, get_campaign_metrics
+import pandas as pd
+import os
+
+CUSTOMER_ID = os.getenv("GOOGLE_ADS_CUSTOMER_ID")
+
+def inspect_google_ads():
+    campaigns = list_campaigns(CUSTOMER_ID)
+
+    print("4️⃣ Campaigns received:", len(campaigns))
+
+    print(pd.DataFrame(campaigns))
+
+    metrics = get_campaign_metrics(CUSTOMER_ID)
+
+    print("6️⃣ Metrics received:", len(metrics))
+
+    print(pd.DataFrame(metrics))
+
+
+if __name__ == "__main__":
+    inspect_google_ads()
+

scripts/seed_demo.py

@@ -0,0 +1,144 @@
+import sys
+from pathlib import Path
+
+# ✅ FIX: ensure project root is first in path BEFORE imports
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+import random
+from datetime import datetime
+
+from app.db.repo import init_db, SessionLocal
+from app.db.models import Campaign, Recommendation
+from app.recs.rules import generate_recommendations
+
+
+CAMPAIGN_NAMES = [
+    "Preschool Search",
+    "Brand Awareness",
+    "Local Leads",
+    "Early Education Ads",
+    "Enrollment Push"
+]
+
+
+# -------------------------
+# Campaign generation
+# -------------------------
+def generate_campaigns(session):
+    campaigns = []
+
+    for i, name in enumerate(CAMPAIGN_NAMES):
+        campaign = Campaign(
+            google_campaign_id=f"gc_{1000+i}",
+            name=name,
+            budget=random.randint(50, 200),
+            spend=0,
+            clicks=0,
+            impressions=0,
+            ctr=0.0,
+            leads=0,
+            cpl=0.0,
+            last_synced=datetime.utcnow()
+        )
+        session.add(campaign)
+        campaigns.append(campaign)
+
+    session.commit()
+    return campaigns
+
+
+# -------------------------
+# Metrics simulation
+# -------------------------
+def simulate_metrics(session, campaigns):
+    for campaign in campaigns:
+        spend = 0
+        clicks = 0
+        impressions = 0
+        leads = 0
+
+        for _ in range(30):
+            daily_impressions = random.randint(50, 500)
+            daily_clicks = int(daily_impressions * random.uniform(0.01, 0.1))
+            daily_spend = daily_clicks * random.uniform(0.5, 3.0)
+            daily_leads = int(daily_clicks * random.uniform(0.05, 0.3))
+
+            impressions += daily_impressions
+            clicks += daily_clicks
+            spend += daily_spend
+            leads += daily_leads
+
+        ctr = clicks / impressions if impressions else 0
+        cpl = spend / leads if leads else 0
+
+        campaign.spend = round(spend, 2)
+        campaign.clicks = clicks
+        campaign.impressions = impressions
+        campaign.leads = leads
+        campaign.ctr = round(ctr, 4)
+        campaign.cpl = round(cpl, 2)
+        campaign.last_synced = datetime.utcnow()
+
+    session.commit()
+
+
+# -------------------------
+# Recommendations via rule engine
+# -------------------------
+def seed_recommendations(session, campaigns):
+    # ✅ prevent duplicate entries on re-run
+    session.query(Recommendation).delete()
+    session.commit()
+
+    metrics = [
+        {
+            "campaign_id": c.id,
+            "cpl": c.cpl,
+            "ctr": c.ctr,
+        }
+        for c in campaigns
+    ]
+
+    recs = generate_recommendations(metrics)
+
+    for r in recs:
+        session.add(Recommendation(
+            campaign_id=r["campaign_id"],
+            recommendation_type=r["type"],
+            action=r["action"],
+            reason=r["reason"],
+            status="Pending",
+            created_at=datetime.utcnow()
+        ))
+
+    session.commit()
+
+
+# -------------------------
+# Main pipeline
+# -------------------------
+def main():
+    print("Initializing DB...")
+    init_db()
+
+    session = SessionLocal()
+
+    try:
+        print("Seeding campaigns...")
+        campaigns = generate_campaigns(session)
+
+        print("Simulating metrics...")
+        simulate_metrics(session, campaigns)
+
+        print("Generating recommendations...")
+        seed_recommendations(session, campaigns)
+
+        print("✅ Demo database seeded successfully!")
+
+    finally:
+        session.close()
+
+
+if __name__ == "__main__":
+    main()

test.py

@@ -0,0 +1,19 @@
+from app.recs.generate import generate_explanation
+
+rec = {
+    "campaign_id": "Test",
+    "type": "high_cpl",
+    "action": "reduce_budget",
+    "reason": "CPL too high",
+    "cpl": 42,
+    "target_cpl": 20,
+    "ctr": 1.2,
+}
+
+# for x in generate_explanation(rec, stream=True):
+#     print(x)
+
+gen = generate_explanation(rec, stream=True)
+
+for i, chunk in enumerate(gen):
+    print(f"[{i}]", chunk)

test_model.py

@@ -0,0 +1,83 @@
+from llama_cpp import Llama
+import re
+
+print("Script started")
+
+# llm = Llama.from_pretrained(
+#     repo_id="mradermacher/MiniCPM4.1-8B-GGUF",
+#     filename="MiniCPM4.1-8B.IQ4_XS.gguf",
+#     n_ctx=4096,
+#     verbose=False
+# )
+
+llm = Llama.from_pretrained(
+    repo_id="Abiray/MiniCPM5-1B-GGUF",
+    filename="minicpm5-1b-Q4_K_M.gguf",
+    n_ctx=3048,
+    verbose=True
+)
+
+prompt = """
+You are a senior Google Ads performance analyst.
+
+You must output ONLY 3–5 bullet insights.
+
+STRICT RULES:
+- Do NOT include reasoning
+- Do NOT include calculations
+- Do NOT include step-by-step analysis
+- Do NOT use <think> tags
+- Do NOT show working or explanations
+- Only final insights allowed
+
+Use only the provided data. Do not derive new metrics.
+
+DATA:
+
+Campaign:
+- Name: Preschool Search
+- Spend: 1200
+- Clicks: 300
+- Impressions: 15000
+- Conversions: 30
+
+Trends:
+- Spend increasing steadily over last 10 days
+- Clicks increasing steadily
+- Impressions increasing slightly faster than clicks
+
+Keywords:
+- preschool near me → strong performance (15 conversions, low cost)
+- nursery admission → moderate (5 conversions)
+- best preschool london → poor (0 conversions, high cost)
+- early learning center → good (8 conversions)
+
+Signals:
+- CTR: 0.35 (low)
+- Wasted spend: 0.25 (high)
+
+Business targets:
+- Target CPL: 20
+- Current CPL: 40
+
+OUTPUT RULES:
+- Exactly 3–5 bullets
+- No numbering
+- No explanations
+- No thinking traces
+- Each bullet must be independently useful for decision-making
+"""
+
+response = llm.create_chat_completion(
+    messages=[
+        {"role": "system", "content": "You are an expert marketing analyst for Google Ads."},
+        {"role": "user", "content": prompt}
+    ],
+    temperature=0.7,
+)
+
+raw = response["choices"][0]["message"]["content"]
+
+clean = re.sub(r"<think>.*?</think>", "", raw, flags=re.DOTALL).strip()
+
+print(clean)

tests/test_connector.py

@@ -0,0 +1,28 @@
+from app.ads.connector import list_campaigns, get_campaign_metrics
+
+def test_list_campaigns():
+    campaigns = list_campaigns()
+
+    assert isinstance(campaigns, list)
+    assert len(campaigns) > 0
+
+    for c in campaigns:
+        assert "id" in c
+        assert "name" in c
+        assert "budget" in c
+
+
+def test_get_campaign_metrics():
+    metrics = get_campaign_metrics()
+
+    assert isinstance(metrics, list)
+    assert len(metrics) > 0
+
+    for m in metrics:
+        assert "campaign_id" in m
+        assert "spend" in m
+        assert "clicks" in m
+        assert "impressions" in m
+        assert "ctr" in m
+        assert "leads" in m
+        assert "cpl" in m

tests/test_e2e.py

@@ -0,0 +1,125 @@
+import pytest
+from unittest.mock import patch
+
+from app.recs.rules import generate_recommendations
+from app.recs.generate import generate_explanation
+from app.db.repo import init_db, SessionLocal
+from app.db.models import Campaign, Recommendation
+
+
+# -------------------------
+# DB fixture
+# -------------------------
+@pytest.fixture
+def session():
+    init_db()
+    db = SessionLocal()
+    yield db
+    db.close()
+
+
+# -------------------------
+# Step 1: seed campaigns (DB → metrics extraction simulation)
+# -------------------------
+def seed_campaign_metrics(session):
+    campaigns = [
+        Campaign(
+            google_campaign_id="c1",
+            name="High CPL Campaign",
+            budget=100,
+            spend=500,
+            clicks=100,
+            impressions=2000,
+            ctr=5.0,
+            leads=5,
+            cpl=100.0,
+        ),
+        Campaign(
+            google_campaign_id="c2",
+            name="Low CPL Campaign",
+            budget=100,
+            spend=200,
+            clicks=150,
+            impressions=3000,
+            ctr=5.0,
+            leads=20,
+            cpl=10.0,
+        ),
+        Campaign(
+            google_campaign_id="c3",
+            name="Low CTR Campaign",
+            budget=100,
+            spend=300,
+            clicks=20,
+            impressions=3000,
+            ctr=1.0,
+            leads=5,
+            cpl=60.0,
+        ),
+    ]
+
+    session.add_all(campaigns)
+    session.commit()
+
+    return campaigns
+
+
+# -------------------------
+# Convert DB → rule engine input format
+# -------------------------
+def extract_metrics(session):
+    campaigns = session.query(Campaign).all()
+
+    return [
+        {
+            "campaign_id": c.google_campaign_id,
+            "cpl": c.cpl,
+            "ctr": c.ctr,
+        }
+        for c in campaigns
+    ]
+
+
+# -------------------------
+# E2E TEST
+# -------------------------
+def test_e2e_pipeline(session):
+
+    # STEP 1: seed DB
+    seed_campaign_metrics(session)
+
+    metrics = extract_metrics(session)
+
+    # STEP 2: rule engine
+    recs = generate_recommendations(metrics)
+
+    assert len(recs) > 0, "Rule engine returned no recommendations"
+
+    # (Optional sanity check)
+    assert any(r["type"] == "high_cpl" for r in recs)
+    assert any(r["type"] == "low_ctr" for r in recs)
+
+    # STEP 3: mock LLM (MiniCPM)
+    def fake_llm_response(rec):
+        return f"Mock explanation for {rec['campaign_id']}"
+
+    with patch("app.recs.generate.load_model", return_value=None), \
+         patch("app.recs.generate.generate_explanation") as mocked:
+
+        mocked.side_effect = fake_llm_response
+
+        enriched = [
+            {
+                **r,
+                "explanation": generate_explanation(r)
+            }
+            for r in recs
+        ]
+
+    # STEP 4: verify enrichment
+    assert len(enriched) == len(recs)
+
+    for e in enriched:
+        assert "explanation" in e
+        assert e["explanation"] is not None
+        assert isinstance(e["explanation"], str)