adloop 0.1.0__py3-none-any.whl

adloop/__init__.py

@@ -0,0 +1,21 @@
+"""AdLoop — MCP server connecting Google Ads + GA4 + codebase."""
+
+import sys
+
+__version__ = "0.1.0"
+
+
+def main() -> None:
+    """Entry point for `adloop` console script.
+
+    Routes to the setup wizard when called as ``adloop init``,
+    otherwise starts the MCP server.
+    """
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        from adloop.cli import run_init_wizard
+
+        run_init_wizard()
+    else:
+        from adloop.server import mcp
+
+        mcp.run()

adloop/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m adloop`."""
+
+from adloop import main
+
+main()

adloop/ads/client.py

@@ -0,0 +1,41 @@
+"""Google Ads API client wrapper — thin layer over the google-ads library."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from google.ads.googleads.client import GoogleAdsClient
+
+    from adloop.config import AdLoopConfig
+
+# Pin the API version so library upgrades don't silently break field names,
+# enum values, or mutate operation structures. Bump this deliberately when
+# migrating to a new API version — never let it float to the library default.
+GOOGLE_ADS_API_VERSION = "v23"
+
+
+def get_ads_client(config: AdLoopConfig) -> GoogleAdsClient:
+    """Return an authenticated Google Ads API client pinned to a specific API version."""
+    from google.ads.googleads.client import GoogleAdsClient
+
+    from adloop.auth import get_ads_credentials
+
+    credentials = get_ads_credentials(config)
+
+    client_config = {
+        "developer_token": config.ads.developer_token,
+        "use_proto_plus": True,
+        "version": GOOGLE_ADS_API_VERSION,
+    }
+
+    if config.ads.login_customer_id:
+        client_config["login_customer_id"] = config.ads.login_customer_id.replace("-", "")
+
+    client = GoogleAdsClient(credentials=credentials, **client_config)
+    return client
+
+
+def normalize_customer_id(customer_id: str) -> str:
+    """Strip dashes from customer ID for API calls (123-456-7890 -> 1234567890)."""
+    return customer_id.replace("-", "")

adloop/ads/forecast.py

@@ -0,0 +1,156 @@
+"""Budget estimation via Google Ads Keyword Planner forecast metrics."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+_DEFAULT_MAX_CPC_MICROS = 1_000_000  # 1.00 in account currency
+
+
+def estimate_budget(
+    config: AdLoopConfig,
+    *,
+    keywords: list[dict],
+    daily_budget: float = 0,
+    geo_target_id: str = "2276",
+    language_id: str = "1000",
+    forecast_days: int = 30,
+    customer_id: str = "",
+) -> dict:
+    """Forecast clicks, impressions, and cost for a set of keywords.
+
+    Uses KeywordPlanIdeaService.GenerateKeywordForecastMetrics to estimate
+    campaign performance without creating anything. Useful for budget planning
+    before launching a new campaign.
+
+    keywords: list of {"text": str, "match_type": "EXACT|PHRASE|BROAD", "max_cpc": float (optional)}
+    geo_target_id: geo target constant (2276=Germany, 2840=USA, 2826=UK, 2250=France)
+    language_id: language constant (1000=English, 1001=German, 1002=French, 1003=Spanish)
+    forecast_days: number of days to forecast (default 30)
+    """
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+
+    if not keywords:
+        return {"error": "At least one keyword is required"}
+
+    client = get_ads_client(config)
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+
+    googleads_service = client.get_service("GoogleAdsService")
+    kp_service = client.get_service("KeywordPlanIdeaService")
+
+    campaign = client.get_type("CampaignToForecast")
+    campaign.keyword_plan_network = (
+        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
+    )
+
+    max_bid = max(
+        (int(kw.get("max_cpc", 0) * 1_000_000) for kw in keywords),
+        default=_DEFAULT_MAX_CPC_MICROS,
+    )
+    if max_bid <= 0:
+        max_bid = _DEFAULT_MAX_CPC_MICROS
+    campaign.bidding_strategy.manual_cpc_bidding_strategy.max_cpc_bid_micros = max_bid
+
+    geo_modifier = client.get_type("CriterionBidModifier")
+    geo_modifier.geo_target_constant = googleads_service.geo_target_constant_path(
+        geo_target_id
+    )
+    campaign.geo_modifiers.append(geo_modifier)
+
+    campaign.language_constants.append(
+        googleads_service.language_constant_path(language_id)
+    )
+
+    ad_group = client.get_type("ForecastAdGroup")
+
+    for kw in keywords:
+        text = kw.get("text", "")
+        if not text:
+            continue
+        match_type = kw.get("match_type", "BROAD").upper()
+        cpc_micros = int(kw.get("max_cpc", 0) * 1_000_000) or _DEFAULT_MAX_CPC_MICROS
+
+        biddable = client.get_type("BiddableKeyword")
+        biddable.max_cpc_bid_micros = cpc_micros
+        biddable.keyword.text = text
+        biddable.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, match_type, client.enums.KeywordMatchTypeEnum.BROAD
+        )
+        ad_group.biddable_keywords.append(biddable)
+
+    campaign.ad_groups.append(ad_group)
+
+    request = client.get_type("GenerateKeywordForecastMetricsRequest")
+    request.customer_id = cid
+    request.campaign = campaign
+
+    tomorrow = date.today() + timedelta(days=1)
+    end_date = date.today() + timedelta(days=forecast_days)
+    request.forecast_period.start_date = tomorrow.isoformat()
+    request.forecast_period.end_date = end_date.isoformat()
+
+    response = kp_service.generate_keyword_forecast_metrics(request=request)
+    metrics = response.campaign_forecast_metrics
+
+    clicks = getattr(metrics, "clicks", None)
+    impressions = getattr(metrics, "impressions", None)
+    avg_cpc_micros = getattr(metrics, "average_cpc_micros", None)
+    cost_micros = getattr(metrics, "cost_micros", None)
+    ctr = getattr(metrics, "click_through_rate", None)
+
+    total_cost = round(cost_micros / 1_000_000, 2) if cost_micros else None
+    avg_cpc = round(avg_cpc_micros / 1_000_000, 2) if avg_cpc_micros else None
+
+    days = max(forecast_days, 1)
+    daily = {
+        "clicks": round(clicks / days, 1) if clicks else None,
+        "impressions": round(impressions / days, 1) if impressions else None,
+        "cost": round(total_cost / days, 2) if total_cost else None,
+    }
+
+    insights = []
+    if total_cost is not None and clicks is not None and clicks > 0:
+        effective_cpa_budget = total_cost / clicks * 10
+        insights.append(
+            f"Estimated {clicks:.0f} clicks over {forecast_days} days at "
+            f"~{avg_cpc} avg CPC. Total estimated cost: {total_cost:.2f}."
+        )
+    if daily_budget > 0 and daily["cost"] is not None:
+        if daily_budget < daily["cost"]:
+            capture_pct = round(daily_budget / daily["cost"] * 100)
+            insights.append(
+                f"Daily budget of {daily_budget:.2f} would capture ~{capture_pct}% "
+                f"of available traffic (estimated daily cost: {daily['cost']:.2f})."
+            )
+        else:
+            insights.append(
+                f"Daily budget of {daily_budget:.2f} is sufficient to capture "
+                f"most available traffic (estimated daily cost: {daily['cost']:.2f})."
+            )
+
+    if impressions is not None and clicks is not None and impressions > 0 and clicks == 0:
+        insights.append(
+            "Forecast shows impressions but zero clicks — keywords may be too "
+            "generic or CPCs too low for competitive positions."
+        )
+
+    return {
+        "forecast_period": {
+            "start": tomorrow.isoformat(),
+            "end": end_date.isoformat(),
+        },
+        "estimated_clicks": clicks,
+        "estimated_impressions": impressions,
+        "estimated_cost": total_cost,
+        "estimated_avg_cpc": avg_cpc,
+        "estimated_ctr": round(ctr, 4) if ctr else None,
+        "daily_estimates": daily,
+        "keywords_used": len([kw for kw in keywords if kw.get("text")]),
+        "insights": insights,
+    }

adloop/ads/gaql.py

@@ -0,0 +1,178 @@
+"""GAQL (Google Ads Query Language) tool — run arbitrary queries."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+def execute_query(
+    config: AdLoopConfig, customer_id: str, query: str
+) -> list[dict]:
+    """Execute a GAQL query and return results as a list of flat dicts.
+
+    Shared by run_gaql (the MCP tool) and the individual read tools
+    in ads/read.py.
+    """
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+
+    client = get_ads_client(config)
+    service = client.get_service("GoogleAdsService")
+    cid = normalize_customer_id(customer_id)
+
+    fields = _parse_select_fields(query)
+
+    rows = []
+    for row in service.search(customer_id=cid, query=query):
+        r = {}
+        for field in fields:
+            r[field] = _extract_field(row, field)
+        rows.append(r)
+
+    return rows
+
+
+def run_gaql(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    query: str = "",
+    format: str = "table",
+) -> dict:
+    """Execute an arbitrary GAQL query and return formatted results."""
+    if not query:
+        return {"error": "Query string is required."}
+
+    try:
+        rows = execute_query(config, customer_id, query)
+    except Exception as e:
+        return {"error": _parse_gaql_error(e), "query": query}
+
+    if format == "table":
+        return _format_table(rows, query)
+    elif format == "csv":
+        return _format_csv(rows, query)
+    return {"rows": rows, "row_count": len(rows), "query": query}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_GAQL_ERROR_HINTS = {
+    "EXPECTED_REFERENCED_FIELD_IN_SELECT_CLAUSE": (
+        "Fields used in ORDER BY or HAVING must also appear in the SELECT clause. "
+        "Add the missing field to your SELECT."
+    ),
+    "UNRECOGNIZED_FIELD": "Check the field name — it may be misspelled or not available on this resource.",
+    "INVALID_RESOURCE_NAME": "The resource name in FROM is invalid. Check GAQL resource names.",
+    "PROHIBITED_FIELD_COMBINATION": (
+        "Some fields can't be selected together. Metrics and certain resource fields "
+        "may conflict. Try splitting into separate queries."
+    ),
+    "QUERY_NOT_ALLOWED": "This query type is not supported for this resource or access level.",
+    "INVALID_ARGUMENT": "Check your WHERE clause values — date formats, status strings, and IDs must be valid.",
+}
+
+
+def _parse_gaql_error(exc: Exception) -> str:
+    """Extract a human-readable message from Google Ads gRPC errors."""
+    raw = str(exc)
+    for code, hint in _GAQL_ERROR_HINTS.items():
+        if code in raw:
+            return f"{code}: {hint}"
+    if len(raw) > 500:
+        return raw[:500] + "..."
+    return raw
+
+
+def _parse_select_fields(query: str) -> list[str]:
+    """Extract field names from the SELECT clause of a GAQL query."""
+    match = re.search(r"SELECT\s+(.*?)\s+FROM", query, re.IGNORECASE | re.DOTALL)
+    if not match:
+        return []
+    return [f.strip() for f in match.group(1).split(",") if f.strip()]
+
+
+def _extract_field(row: object, field_path: str) -> object:
+    """Walk a dotted field path on a proto-plus GoogleAdsRow."""
+    obj = row
+    for part in field_path.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+    return _to_python(obj)
+
+
+def _to_python(obj: object) -> object:
+    """Convert proto-plus / protobuf values to plain Python types."""
+    if obj is None:
+        return None
+    if isinstance(obj, (str, float, bool)):
+        return obj
+    if isinstance(obj, int):
+        # Proto-plus enums are int subclasses with a .name attribute
+        if type(obj) is not int and hasattr(obj, "name"):
+            return obj.name
+        return obj
+    # Repeated fields (headlines, final_urls, etc.)
+    try:
+        return [_to_python(item) for item in obj]
+    except TypeError:
+        pass
+    # AdTextAsset and similar message types
+    if hasattr(obj, "text") and isinstance(getattr(obj, "text", None), str):
+        return obj.text
+    return str(obj)
+
+
+def _format_table(rows: list[dict], query: str) -> dict:
+    """Format query results as an aligned text table."""
+    if not rows:
+        return {"table": "(no results)", "row_count": 0, "query": query}
+
+    headers = list(rows[0].keys())
+    widths = {h: len(h) for h in headers}
+
+    str_rows = []
+    for row in rows:
+        sr = {}
+        for h in headers:
+            val = row.get(h)
+            if isinstance(val, list):
+                s = ", ".join(str(v) for v in val)
+            else:
+                s = str(val) if val is not None else ""
+            sr[h] = s
+            widths[h] = max(widths[h], len(s))
+        str_rows.append(sr)
+
+    header_line = " | ".join(h.ljust(widths[h]) for h in headers)
+    separator = "-+-".join("-" * widths[h] for h in headers)
+    data_lines = [
+        " | ".join(sr[h].ljust(widths[h]) for h in headers) for sr in str_rows
+    ]
+
+    table = "\n".join([header_line, separator, *data_lines])
+    return {"table": table, "row_count": len(rows), "query": query}
+
+
+def _format_csv(rows: list[dict], query: str) -> dict:
+    """Format query results as CSV."""
+    if not rows:
+        return {"csv": "", "row_count": 0, "query": query}
+
+    import csv
+    import io
+
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=rows[0].keys())
+    writer.writeheader()
+    for row in rows:
+        writer.writerow({k: v if not isinstance(v, list) else "; ".join(str(i) for i in v) for k, v in row.items()})
+
+    return {"csv": output.getvalue(), "row_count": len(rows), "query": query}

adloop/ads/read.py

@@ -0,0 +1,238 @@
+"""Google Ads read tools — campaign, ad, keyword, and search term performance."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+def list_accounts(config: AdLoopConfig) -> dict:
+    """List all accessible Google Ads accounts."""
+    from adloop.ads.gaql import execute_query
+
+    mcc_id = config.ads.login_customer_id
+    if mcc_id:
+        query = """
+            SELECT customer_client.id, customer_client.descriptive_name,
+                   customer_client.status, customer_client.manager
+            FROM customer_client
+        """
+        rows = execute_query(config, mcc_id, query)
+    else:
+        query = """
+            SELECT customer.id, customer.descriptive_name,
+                   customer.status, customer.manager
+            FROM customer
+            LIMIT 1
+        """
+        rows = execute_query(config, config.ads.customer_id, query)
+
+    return {"accounts": rows, "total_accounts": len(rows)}
+
+
+def get_campaign_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get campaign-level performance metrics for the given date range."""
+    from adloop.ads.gaql import execute_query
+
+    date_clause = _date_clause(date_range_start, date_range_end)
+
+    query = f"""
+        SELECT campaign.id, campaign.name, campaign.status,
+               campaign.advertising_channel_type, campaign.bidding_strategy_type,
+               metrics.impressions, metrics.clicks, metrics.cost_micros,
+               metrics.conversions, metrics.conversions_value,
+               metrics.ctr, metrics.average_cpc
+        FROM campaign
+        WHERE campaign.status != 'REMOVED'
+          {date_clause}
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    rows = execute_query(config, customer_id, query)
+    _enrich_cost_fields(rows)
+
+    return {"campaigns": rows, "total_campaigns": len(rows)}
+
+
+def get_ad_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get ad-level performance data including headlines, descriptions, and metrics."""
+    from adloop.ads.gaql import execute_query
+
+    date_clause = _date_clause(date_range_start, date_range_end)
+
+    query = f"""
+        SELECT campaign.name, ad_group.name,
+               ad_group_ad.ad.id, ad_group_ad.ad.type,
+               ad_group_ad.ad.responsive_search_ad.headlines,
+               ad_group_ad.ad.responsive_search_ad.descriptions,
+               ad_group_ad.ad.final_urls,
+               ad_group_ad.status,
+               metrics.impressions, metrics.clicks, metrics.ctr,
+               metrics.conversions, metrics.cost_micros
+        FROM ad_group_ad
+        WHERE ad_group_ad.status != 'REMOVED'
+          {date_clause}
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    rows = execute_query(config, customer_id, query)
+    _enrich_cost_fields(rows)
+
+    return {"ads": rows, "total_ads": len(rows)}
+
+
+def get_keyword_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get keyword metrics including quality scores and competitive data."""
+    from adloop.ads.gaql import execute_query
+
+    date_clause = _date_clause(date_range_start, date_range_end)
+
+    query = f"""
+        SELECT campaign.name, ad_group.name,
+               ad_group_criterion.keyword.text,
+               ad_group_criterion.keyword.match_type,
+               ad_group_criterion.quality_info.quality_score,
+               metrics.impressions, metrics.clicks, metrics.ctr,
+               metrics.average_cpc, metrics.cost_micros,
+               metrics.conversions
+        FROM keyword_view
+        WHERE ad_group_criterion.status != 'REMOVED'
+          {date_clause}
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    rows = execute_query(config, customer_id, query)
+    _enrich_cost_fields(rows)
+
+    return {"keywords": rows, "total_keywords": len(rows)}
+
+
+def get_search_terms(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get search terms report — what users actually typed before clicking ads."""
+    from adloop.ads.gaql import execute_query
+
+    date_clause = _date_clause(date_range_start, date_range_end)
+
+    query = f"""
+        SELECT search_term_view.search_term,
+               campaign.name, ad_group.name,
+               metrics.impressions, metrics.clicks,
+               metrics.cost_micros, metrics.conversions
+        FROM search_term_view
+        WHERE segments.date DURING LAST_30_DAYS
+          {f"AND segments.date BETWEEN '{date_range_start}' AND '{date_range_end}'" if date_range_start and date_range_end else ""}
+        ORDER BY metrics.clicks DESC
+        LIMIT 200
+    """
+    # search_term_view requires an explicit date segment, so we always
+    # include DURING LAST_30_DAYS as baseline and override if dates given.
+    if date_range_start and date_range_end:
+        query = f"""
+            SELECT search_term_view.search_term,
+                   campaign.name, ad_group.name,
+                   metrics.impressions, metrics.clicks,
+                   metrics.cost_micros, metrics.conversions
+            FROM search_term_view
+            WHERE segments.date BETWEEN '{date_range_start}' AND '{date_range_end}'
+            ORDER BY metrics.clicks DESC
+            LIMIT 200
+        """
+    else:
+        query = """
+            SELECT search_term_view.search_term,
+                   campaign.name, ad_group.name,
+                   metrics.impressions, metrics.clicks,
+                   metrics.cost_micros, metrics.conversions
+            FROM search_term_view
+            WHERE segments.date DURING LAST_30_DAYS
+            ORDER BY metrics.clicks DESC
+            LIMIT 200
+        """
+
+    rows = execute_query(config, customer_id, query)
+    _enrich_cost_fields(rows)
+
+    return {"search_terms": rows, "total_search_terms": len(rows)}
+
+
+def get_negative_keywords(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """List negative keywords for a campaign or all campaigns."""
+    from adloop.ads.gaql import execute_query
+
+    campaign_filter = ""
+    if campaign_id:
+        campaign_filter = f"AND campaign.id = {campaign_id}"
+
+    query = f"""
+        SELECT campaign.id, campaign.name,
+               campaign_criterion.keyword.text,
+               campaign_criterion.keyword.match_type,
+               campaign_criterion.negative,
+               campaign_criterion.criterion_id
+        FROM campaign_criterion
+        WHERE campaign_criterion.negative = TRUE
+          AND campaign_criterion.status != 'REMOVED'
+          {campaign_filter}
+        ORDER BY campaign.name
+    """
+
+    rows = execute_query(config, customer_id, query)
+    return {"negative_keywords": rows, "total_negative_keywords": len(rows)}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _date_clause(start: str, end: str) -> str:
+    """Build a GAQL date WHERE fragment."""
+    if start and end:
+        return f"AND segments.date BETWEEN '{start}' AND '{end}'"
+    return "AND segments.date DURING LAST_30_DAYS"
+
+
+def _enrich_cost_fields(rows: list[dict]) -> None:
+    """Add human-readable cost and CPA fields computed from cost_micros."""
+    for row in rows:
+        cost_micros = row.get("metrics.cost_micros", 0) or 0
+        row["metrics.cost"] = round(cost_micros / 1_000_000, 2)
+
+        conversions = row.get("metrics.conversions", 0) or 0
+        if conversions > 0:
+            row["metrics.cpa"] = round(cost_micros / 1_000_000 / conversions, 2)
+
+        avg_cpc_micros = row.get("metrics.average_cpc", 0) or 0
+        if avg_cpc_micros:
+            row["metrics.average_cpc_eur"] = round(avg_cpc_micros / 1_000_000, 2)