adloop 0.1.0__py3-none-any.whl

adloop/server.py

@@ -0,0 +1,778 @@
+"""AdLoop MCP server — FastMCP instance with all tool registrations."""
+
+from __future__ import annotations
+
+import functools
+from typing import Callable
+
+from fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from adloop.config import load_config
+
+_READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False)
+_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False)
+_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
+
+mcp = FastMCP(
+    "AdLoop",
+    instructions=(
+        "AdLoop connects Google Ads and Google Analytics (GA4) data to your "
+        "codebase. Use the read tools to analyze performance, and the write "
+        "tools (with safety confirmation) to manage campaigns."
+    ),
+)
+
+_config = load_config()
+
+
+def _safe(fn: Callable) -> Callable:
+    """Wrap a tool function so exceptions return structured error dicts."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except RuntimeError as e:
+            return {"error": str(e)}
+        except Exception as e:
+            err = str(e).lower()
+            if "invalid_grant" in err or "revoked" in err:
+                return {
+                    "error": "Authentication failed — OAuth token expired or revoked.",
+                    "hint": (
+                        "Delete ~/.adloop/token.json and re-run any tool to "
+                        "trigger re-authorization. If this keeps happening, "
+                        "publish the GCP consent screen to 'In production'."
+                    ),
+                }
+            return {"error": str(e), "tool": fn.__name__}
+
+    return wrapper
+
+# ---------------------------------------------------------------------------
+# Health Check
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def health_check() -> dict:
+    """Test AdLoop connectivity — checks OAuth token, GA4 API, and Google Ads API.
+
+    Run this first if other tools are failing. Returns status for each service
+    and actionable guidance if something is broken.
+    """
+    from adloop.ads.client import GOOGLE_ADS_API_VERSION
+
+    status = {
+        "ga4": "unknown",
+        "ads": "unknown",
+        "config": "ok",
+        "google_ads_api_version": GOOGLE_ADS_API_VERSION,
+    }
+
+    try:
+        from google.ads.googleads.client import _DEFAULT_VERSION
+        if _DEFAULT_VERSION != GOOGLE_ADS_API_VERSION:
+            status["ads_version_note"] = (
+                f"AdLoop is pinned to {GOOGLE_ADS_API_VERSION} but the "
+                f"google-ads library defaults to {_DEFAULT_VERSION}. "
+                f"A newer API version is available — update "
+                f"GOOGLE_ADS_API_VERSION in ads/client.py when ready to migrate."
+            )
+    except ImportError:
+        pass
+
+    try:
+        from adloop.ga4.reports import get_account_summaries as _ga4_test
+
+        result = _ga4_test(_config)
+        status["ga4"] = "ok"
+        status["ga4_properties"] = result.get("total_properties", 0)
+    except Exception as e:
+        status["ga4"] = "error"
+        status["ga4_error"] = str(e)
+
+    try:
+        from adloop.ads.read import list_accounts as _ads_test
+
+        result = _ads_test(_config)
+        status["ads"] = "ok"
+        status["ads_accounts"] = result.get("total_accounts", 0)
+    except Exception as e:
+        status["ads"] = "error"
+        status["ads_error"] = str(e)
+
+    if status["ga4"] == "error" or status["ads"] == "error":
+        any_error = status.get("ga4_error", "") + status.get("ads_error", "")
+        if "invalid_grant" in any_error.lower() or "revoked" in any_error.lower():
+            status["hint"] = (
+                "OAuth token expired or revoked. Delete ~/.adloop/token.json "
+                "and re-run health_check to trigger re-authorization. "
+                "To prevent recurring expiry, publish the GCP consent screen "
+                "from 'Testing' to 'In production'."
+            )
+
+    return status
+
+
+# ---------------------------------------------------------------------------
+# GA4 Read Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_account_summaries() -> dict:
+    """List all GA4 accounts and properties accessible by the authenticated user.
+
+    Use this as the first step to discover which GA4 properties are available.
+    Returns account names, property names, and property IDs.
+    """
+    from adloop.ga4.reports import get_account_summaries as _impl
+
+    return _impl(_config)
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def run_ga4_report(
+    dimensions: list[str] | None = None,
+    metrics: list[str] | None = None,
+    date_range_start: str = "7daysAgo",
+    date_range_end: str = "today",
+    property_id: str = "",
+    limit: int = 100,
+) -> dict:
+    """Run a custom GA4 report with specified dimensions, metrics, and date range.
+
+    Common dimensions: date, pagePath, sessionSource, sessionMedium, country, deviceCategory, eventName
+    Common metrics: sessions, totalUsers, newUsers, screenPageViews, conversions, eventCount, bounceRate
+
+    Date formats: "today", "yesterday", "7daysAgo", "28daysAgo", "90daysAgo", or "YYYY-MM-DD".
+    If property_id is empty, uses the default from config.
+    """
+    from adloop.ga4.reports import run_ga4_report as _impl
+
+    return _impl(
+        _config,
+        property_id=property_id or _config.ga4.property_id,
+        dimensions=dimensions,
+        metrics=metrics,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+        limit=limit,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def run_realtime_report(
+    dimensions: list[str] | None = None,
+    metrics: list[str] | None = None,
+    property_id: str = "",
+) -> dict:
+    """Run a GA4 realtime report showing current active users and events.
+
+    Useful for checking if tracking is firing correctly after code changes.
+    Common dimensions: unifiedScreenName, eventName, country, deviceCategory
+    Common metrics: activeUsers, eventCount
+    """
+    from adloop.ga4.reports import run_realtime_report as _impl
+
+    return _impl(
+        _config,
+        property_id=property_id or _config.ga4.property_id,
+        dimensions=dimensions,
+        metrics=metrics,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_tracking_events(
+    date_range_start: str = "28daysAgo",
+    date_range_end: str = "today",
+    property_id: str = "",
+) -> dict:
+    """List all GA4 events and their volume for the given date range.
+
+    Returns every distinct event name with its total event count.
+    Use this to understand what tracking is configured and active.
+    """
+    from adloop.ga4.tracking import get_tracking_events as _impl
+
+    return _impl(
+        _config,
+        property_id=property_id or _config.ga4.property_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Google Ads Read Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def list_accounts() -> dict:
+    """List all accessible Google Ads accounts.
+
+    Returns account names, IDs, and status. Use this to discover
+    which accounts are available before running performance queries.
+    """
+    from adloop.ads.read import list_accounts as _impl
+
+    return _impl(_config)
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_campaign_performance(
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get campaign-level performance metrics for a date range.
+
+    Returns: campaign name, status, type, impressions, clicks, cost,
+    conversions, CPA, ROAS, CTR for each campaign.
+    Date format: "YYYY-MM-DD". Empty = last 30 days.
+    """
+    from adloop.ads.read import get_campaign_performance as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_ad_performance(
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get ad-level performance data including headlines, descriptions, and metrics.
+
+    Returns: ad type, headlines, descriptions, final URL, impressions,
+    clicks, CTR, conversions, cost for each ad.
+    """
+    from adloop.ads.read import get_ad_performance as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_keyword_performance(
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get keyword metrics including quality scores and competitive data.
+
+    Returns: keyword text, match type, quality score, impressions,
+    clicks, CTR, CPC, conversions for each keyword.
+    """
+    from adloop.ads.read import get_keyword_performance as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_search_terms(
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get search terms report — what users actually typed before clicking your ads.
+
+    Critical for finding negative keyword opportunities and understanding user intent.
+    Returns: search term, campaign, ad group, impressions, clicks, conversions.
+    """
+    from adloop.ads.read import get_search_terms as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_negative_keywords(
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """List existing negative keywords for a campaign or all campaigns.
+
+    Use this before adding negative keywords to check for duplicates.
+    If campaign_id is empty, returns negatives across all campaigns.
+    """
+    from adloop.ads.read import get_negative_keywords as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        campaign_id=campaign_id,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def analyze_campaign_conversions(
+    date_range_start: str = "",
+    date_range_end: str = "",
+    customer_id: str = "",
+    property_id: str = "",
+    campaign_name: str = "",
+) -> dict:
+    """Campaign clicks → GA4 conversions mapping — the real cost-per-conversion.
+
+    Combines Google Ads campaign metrics with GA4 session/conversion data to
+    reveal click-to-session ratios (GDPR indicator), compare Ads-reported vs
+    GA4-reported conversions, and compute cost-per-GA4-conversion.
+
+    Also returns non-paid channel conversion rates for comparison context.
+    Date format: "YYYY-MM-DD". Empty = last 30 days.
+    """
+    from adloop.crossref import analyze_campaign_conversions as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        property_id=property_id or _config.ga4.property_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+        campaign_name=campaign_name,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def landing_page_analysis(
+    date_range_start: str = "",
+    date_range_end: str = "",
+    customer_id: str = "",
+    property_id: str = "",
+) -> dict:
+    """Analyze which landing pages convert and which don't.
+
+    Combines ad final URLs with GA4 page-level data to show paid traffic
+    sessions, conversion rates, bounce rates, and engagement per landing page.
+    Identifies pages that get ad clicks but zero conversions and orphaned URLs.
+    Date format: "YYYY-MM-DD". Empty = last 30 days.
+    """
+    from adloop.crossref import landing_page_analysis as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        property_id=property_id or _config.ga4.property_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def attribution_check(
+    date_range_start: str = "",
+    date_range_end: str = "",
+    customer_id: str = "",
+    property_id: str = "",
+    conversion_events: list[str] | None = None,
+) -> dict:
+    """Compare Ads-reported conversions vs GA4 — find tracking discrepancies.
+
+    Checks whether conversions reported by Google Ads match what GA4 records,
+    diagnoses GDPR consent gaps, attribution model differences, and missing
+    conversion event configuration.
+
+    conversion_events: optional list of GA4 event names to specifically check
+    (e.g. ["sign_up", "purchase"]). If omitted, compares aggregate totals only.
+    Date format: "YYYY-MM-DD". Empty = last 30 days.
+    """
+    from adloop.crossref import attribution_check as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        property_id=property_id or _config.ga4.property_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+        conversion_events=conversion_events,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def run_gaql(
+    query: str,
+    customer_id: str = "",
+    format: str = "table",
+) -> dict:
+    """Execute an arbitrary GAQL (Google Ads Query Language) query.
+
+    Use this for advanced queries not covered by the other tools.
+    See the GAQL reference in the AdLoop cursor rules for syntax help.
+
+    format: "table" (default, readable), "json" (structured), "csv" (exportable)
+    """
+    from adloop.ads.gaql import run_gaql as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        query=query,
+        format=format,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Google Ads Write Tools (Safety Layer)
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def draft_campaign(
+    campaign_name: str,
+    daily_budget: float,
+    bidding_strategy: str,
+    customer_id: str = "",
+    target_cpa: float = 0,
+    target_roas: float = 0,
+    channel_type: str = "SEARCH",
+    ad_group_name: str = "",
+    keywords: list[dict] | None = None,
+) -> dict:
+    """Draft a full campaign structure — returns a PREVIEW, does NOT create anything.
+
+    Creates: CampaignBudget + Campaign (PAUSED) + AdGroup + optional Keywords.
+    Ads are NOT included — use draft_responsive_search_ad after the campaign exists.
+
+    bidding_strategy: MAXIMIZE_CONVERSIONS | TARGET_CPA | TARGET_ROAS |
+                      MAXIMIZE_CONVERSION_VALUE | TARGET_SPEND | MANUAL_CPC
+    target_cpa: required if bidding_strategy is TARGET_CPA (in account currency)
+    target_roas: required if bidding_strategy is TARGET_ROAS
+    keywords: list of {"text": "keyword", "match_type": "EXACT|PHRASE|BROAD"}
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import draft_campaign as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        campaign_name=campaign_name,
+        daily_budget=daily_budget,
+        bidding_strategy=bidding_strategy,
+        target_cpa=target_cpa,
+        target_roas=target_roas,
+        channel_type=channel_type,
+        ad_group_name=ad_group_name,
+        keywords=keywords,
+    )
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def draft_responsive_search_ad(
+    ad_group_id: str,
+    headlines: list[str],
+    descriptions: list[str],
+    final_url: str,
+    customer_id: str = "",
+    path1: str = "",
+    path2: str = "",
+) -> dict:
+    """Draft a Responsive Search Ad — returns a PREVIEW, does NOT create the ad.
+
+    Provide 3-15 headlines (max 30 chars each) and 2-4 descriptions (max 90 chars each).
+    The preview shows exactly what will be created. Call confirm_and_apply to execute.
+    """
+    from adloop.ads.write import draft_responsive_search_ad as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        ad_group_id=ad_group_id,
+        headlines=headlines,
+        descriptions=descriptions,
+        final_url=final_url,
+        path1=path1,
+        path2=path2,
+    )
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def draft_keywords(
+    ad_group_id: str,
+    keywords: list[dict],
+    customer_id: str = "",
+) -> dict:
+    """Draft keyword additions — returns a PREVIEW, does NOT add keywords.
+
+    keywords: list of {"text": "keyword phrase", "match_type": "EXACT|PHRASE|BROAD"}
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import draft_keywords as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        ad_group_id=ad_group_id,
+        keywords=keywords,
+    )
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def add_negative_keywords(
+    campaign_id: str,
+    keywords: list[str],
+    customer_id: str = "",
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft negative keyword additions — returns a PREVIEW.
+
+    Negative keywords prevent your ads from showing for irrelevant searches.
+    match_type: "EXACT", "PHRASE", or "BROAD"
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import add_negative_keywords as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        campaign_id=campaign_id,
+        keywords=keywords,
+        match_type=match_type,
+    )
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def pause_entity(
+    entity_type: str,
+    entity_id: str,
+    customer_id: str = "",
+) -> dict:
+    """Draft pausing a campaign, ad group, ad, or keyword — returns a PREVIEW.
+
+    entity_type: "campaign", "ad_group", "ad", or "keyword"
+    entity_id format by type:
+      - campaign: campaign ID (e.g. "12345678")
+      - ad_group: ad group ID (e.g. "12345678")
+      - ad: "adGroupId~adId" (e.g. "12345678~987654")
+      - keyword: "adGroupId~criterionId" (e.g. "12345678~987654")
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import pause_entity as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        entity_type=entity_type,
+        entity_id=entity_id,
+    )
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+def enable_entity(
+    entity_type: str,
+    entity_id: str,
+    customer_id: str = "",
+) -> dict:
+    """Draft enabling a paused campaign, ad group, ad, or keyword — returns a PREVIEW.
+
+    entity_type: "campaign", "ad_group", "ad", or "keyword"
+    entity_id format by type:
+      - campaign: campaign ID (e.g. "12345678")
+      - ad_group: ad group ID (e.g. "12345678")
+      - ad: "adGroupId~adId" (e.g. "12345678~987654")
+      - keyword: "adGroupId~criterionId" (e.g. "12345678~987654")
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import enable_entity as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        entity_type=entity_type,
+        entity_id=entity_id,
+    )
+
+
+@mcp.tool(annotations=_DESTRUCTIVE)
+@_safe
+def remove_entity(
+    entity_type: str,
+    entity_id: str,
+    customer_id: str = "",
+) -> dict:
+    """Draft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE.
+
+    entity_type: "campaign", "ad_group", "ad", "keyword", or "negative_keyword"
+    entity_id: The resource ID. For keywords use "adGroupId~criterionId".
+               For negative_keywords use the campaign criterion ID.
+
+    WARNING: Removed entities cannot be re-enabled. Use pause_entity instead
+    if you just want to temporarily disable something.
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import remove_entity as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        entity_type=entity_type,
+        entity_id=entity_id,
+    )
+
+
+@mcp.tool(annotations=_DESTRUCTIVE)
+@_safe
+def confirm_and_apply(
+    plan_id: str,
+    dry_run: bool = True,
+) -> dict:
+    """Execute a previously previewed change.
+
+    IMPORTANT: Defaults to dry_run=True. You MUST explicitly pass dry_run=false
+    to make real changes to the Google Ads account.
+
+    The plan_id comes from a prior draft_* or pause/enable tool call.
+    """
+    from adloop.ads.write import confirm_and_apply as _impl
+
+    return _impl(_config, plan_id=plan_id, dry_run=dry_run)
+
+
+# ---------------------------------------------------------------------------
+# Tracking Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def validate_tracking(
+    expected_events: list[str],
+    property_id: str = "",
+    date_range_start: str = "28daysAgo",
+    date_range_end: str = "today",
+) -> dict:
+    """Compare tracking events found in the codebase against actual GA4 data.
+
+    First, search the user's codebase for gtag('event', ...) or dataLayer.push
+    calls and extract event names. Then pass those names here to check which
+    ones actually fire in GA4.
+
+    Returns: matched events, events missing from GA4, unexpected GA4 events,
+    and auto-collected events (page_view, session_start, etc.).
+    """
+    from adloop.tracking import validate_tracking as _impl
+
+    return _impl(
+        _config,
+        expected_events=expected_events,
+        property_id=property_id or _config.ga4.property_id,
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def generate_tracking_code(
+    event_name: str,
+    event_params: dict | None = None,
+    trigger: str = "",
+    property_id: str = "",
+    check_existing: bool = True,
+) -> dict:
+    """Generate a GA4 event tracking JavaScript snippet.
+
+    Produces ready-to-paste gtag code for the specified event. Includes
+    recommended parameters for well-known GA4 events (sign_up, purchase, etc.).
+    Optionally checks GA4 to warn if the event already fires.
+
+    trigger: "form_submit", "button_click", or "page_load" — wraps the gtag
+    call in an appropriate event listener. Empty = bare gtag call.
+    """
+    from adloop.tracking import generate_tracking_code as _impl
+
+    return _impl(
+        _config,
+        event_name=event_name,
+        event_params=event_params,
+        trigger=trigger,
+        property_id=property_id or _config.ga4.property_id,
+        check_existing=check_existing,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Planning Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def estimate_budget(
+    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 Google Ads Keyword Planner to estimate campaign performance without
+    creating anything. Essential for budget planning before launching campaigns.
+
+    keywords: list of {"text": "keyword", "match_type": "EXACT|PHRASE|BROAD", "max_cpc": 1.50}
+        max_cpc is optional (defaults to 1.00 in account currency)
+    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)
+    daily_budget: if provided, insights will show what % of traffic the budget captures
+    forecast_days: forecast horizon in days (default 30)
+    """
+    from adloop.ads.forecast import estimate_budget as _impl
+
+    return _impl(
+        _config,
+        keywords=keywords,
+        daily_budget=daily_budget,
+        geo_target_id=geo_target_id,
+        language_id=language_id,
+        forecast_days=forecast_days,
+        customer_id=customer_id or _config.ads.customer_id,
+    )