adloop 0.19.0__tar.gz → 0.19.2__tar.gz

{adloop-0.19.0 → adloop-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.19.0
+Version: 0.19.2
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -255,7 +255,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_callouts` | Create campaign callout assets from 1-25 character text snippets. |
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
 | `draft_image_assets` | Create campaign image assets from local files or public image URLs (PNG, JPEG, or GIF). |
-| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
+| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — flags BROAD match on campaigns without Smart Bidding as dangerous in the preview. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
@@ -314,8 +314,8 @@ AdLoop manages real ad spend, so safety is not optional.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
-- **Destructive ops require double confirmation.** Removing entities or large budget increases trigger extra warnings.
-- **Broad Match + Manual CPC blocked.** The #1 cause of wasted ad spend is automatically prevented — `draft_keywords` refuses to add BROAD match keywords to campaigns without Smart Bidding.
+- **Destructive ops are flagged for double confirmation.** Removing entities or large budget increases come back with extra warnings, and the AI is instructed to confirm twice.
+- **Broad Match without Smart Bidding caught.** The #1 cause of wasted ad spend: `draft_campaign` refuses BROAD keywords unless the campaign uses Smart Bidding, and `draft_keywords` / `draft_ad_group` mark them as dangerous in the preview, so the AI has to raise it before anything is applied.
 - **Pre-write validation.** Before any write, the AI checks bidding strategy, conversion tracking status, and quality scores. If the campaign is fundamentally broken, AdLoop warns you instead of making things worse.
 - **Structured error handling.** All tools return actionable error messages with hints instead of raw exceptions. Auth errors include specific re-authorization steps.
 - **API version pinning.** The Google Ads API version is pinned to prevent silent breaking changes from library updates. `health_check` warns when a newer version is available.
@@ -578,7 +578,7 @@ What's been shipped and what's next:
 - ~~PyPI package~~ ✓ — `pip install adloop`
 - ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no API access application, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
-- ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Behavioral eval suites~~ ✓ — prompt-and-expectation tests in `tests/evals/` covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**

{adloop-0.19.0 → adloop-0.19.2}/README.md

@@ -228,7 +228,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_callouts` | Create campaign callout assets from 1-25 character text snippets. |
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
 | `draft_image_assets` | Create campaign image assets from local files or public image URLs (PNG, JPEG, or GIF). |
-| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
+| `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — flags BROAD match on campaigns without Smart Bidding as dangerous in the preview. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
@@ -287,8 +287,8 @@ AdLoop manages real ad spend, so safety is not optional.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
-- **Destructive ops require double confirmation.** Removing entities or large budget increases trigger extra warnings.
-- **Broad Match + Manual CPC blocked.** The #1 cause of wasted ad spend is automatically prevented — `draft_keywords` refuses to add BROAD match keywords to campaigns without Smart Bidding.
+- **Destructive ops are flagged for double confirmation.** Removing entities or large budget increases come back with extra warnings, and the AI is instructed to confirm twice.
+- **Broad Match without Smart Bidding caught.** The #1 cause of wasted ad spend: `draft_campaign` refuses BROAD keywords unless the campaign uses Smart Bidding, and `draft_keywords` / `draft_ad_group` mark them as dangerous in the preview, so the AI has to raise it before anything is applied.
 - **Pre-write validation.** Before any write, the AI checks bidding strategy, conversion tracking status, and quality scores. If the campaign is fundamentally broken, AdLoop warns you instead of making things worse.
 - **Structured error handling.** All tools return actionable error messages with hints instead of raw exceptions. Auth errors include specific re-authorization steps.
 - **API version pinning.** The Google Ads API version is pinned to prevent silent breaking changes from library updates. `health_check` warns when a newer version is available.
@@ -551,7 +551,7 @@ What's been shipped and what's next:
 - ~~PyPI package~~ ✓ — `pip install adloop`
 - ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no API access application, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
-- ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Behavioral eval suites~~ ✓ — prompt-and-expectation tests in `tests/evals/` covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**

{adloop-0.19.0 → adloop-0.19.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.19.0"
+version = "0.19.2"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.19.0 → adloop-0.19.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.19.0"
+version = "0.19.2"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.19.0 → adloop-0.19.2}/src/adloop/ads/custom_conversion_goals.py

@@ -537,7 +537,6 @@ def draft_clear_custom_conversion_goal(
 
     Call ``confirm_and_apply`` with the returned plan_id to execute.
     """
-    from adloop.ads.client import normalize_customer_id
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
 
@@ -553,7 +552,6 @@ def draft_clear_custom_conversion_goal(
             "details": ["campaign_id must be a numeric ID"],
         }
 
-    cid = normalize_customer_id(customer_id or config.ads.customer_id)
     state = _custom_goal_state(config, customer_id, campaign_id=campaign_id)
     campaign = find_campaign(state, campaign_id)
     if campaign is None:

{adloop-0.19.0 → adloop-0.19.2}/src/adloop/ads/read.py

@@ -373,7 +373,11 @@ def get_search_terms(
     """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)
+    # search_term_view requires an explicit date segment, so the default is
+    # DURING LAST_30_DAYS and a given range replaces it. ``_date_clause``
+    # prefixes its fragment with AND (the other read tools append it to a
+    # WHERE); here it is the only predicate, so the AND comes off.
+    where = _date_clause(date_range_start, date_range_end).removeprefix("AND ")
 
     query = f"""
         SELECT search_term_view.search_term,
@@ -381,35 +385,10 @@ def get_search_terms(
                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 ""}
+        WHERE {where}
         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)
     currency_code = get_currency_code(config, customer_id)

{adloop-0.19.0 → adloop-0.19.2}/src/adloop/ads/write.py

@@ -2780,7 +2780,27 @@ def confirm_and_apply(
                     "objects an earlier step would create, so Google could "
                     "only validate the step(s) before them."
                 )
-        if forced_by_config:
+        from adloop.runtime import deployment_mode as _deployment_mode
+
+        if forced_by_config and _deployment_mode() == "server":
+            # Hosted: the flag is the workspace's live-changes setting,
+            # switched in the dashboard. There is no config file to edit
+            # and no server for the user to restart.
+            response["dry_run_forced_by"] = "config.safety.require_dry_run"
+            response["remediation"] = (
+                "Live changes are switched off for this workspace (or for "
+                "this client). The workspace owner can switch them on in "
+                "the AdLoop Cloud dashboard under Settings → Safety. Passing "
+                "dry_run=false on this tool will keep being overridden until "
+                "then."
+            )
+            response["message"] = (
+                "dry_run=false was IGNORED because live changes are switched "
+                "off for this workspace. No changes were made. Retrying this "
+                "tool with dry_run=false will not succeed until live changes "
+                "are switched on in the dashboard."
+            )
+        elif forced_by_config:
             # The caller passed dry_run=false but safety.require_dry_run
             # forced it back on. Tell them exactly why and how to unlock
             # real writes — without this, agents (e.g. Claude Code) retry
@@ -3867,7 +3887,6 @@ def _apply_create_campaign(client: object, cid: str, changes: dict) -> dict:
     results = {}
     num_keywords = len(kw_list)
     num_geo = len(changes.get("geo_target_ids") or [])
-    num_lang = len(changes.get("language_ids") or [])
     for i, resp in enumerate(response.mutate_operation_responses):
         rn = _extract_resource_name(resp)
         if rn:

{adloop-0.19.0 → adloop-0.19.2}/src/adloop/server.py

@@ -13,9 +13,11 @@ from pydantic import BeforeValidator
 from adloop import diagnostics
 from adloop.runtime import current_config
 
-_READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False)
-_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False)
-_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
+# openWorldHint: every tool talks to an external service (Google, Reddit,
+# a live web page), which directories such as ChatGPT's require to be said.
+_READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=True)
+_WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=True)
+_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True)
 
 # Toolset taxonomy: every tool carries exactly one of these tags (or "core",
 # which survives every ADLOOP_TOOLSETS selection — health_check and
@@ -308,13 +310,20 @@ def _structured_error(fn_name: str, exc: Exception) -> dict:
         }
 
     if "deleted_client" in err_lower or "invalid_client" in err_lower:
+        from adloop.runtime import deployment_mode
+
         return {
             "error": (
                 "Authentication failed — the OAuth client behind your stored "
                 "credentials no longer exists or is invalid."
             ),
+            # On a hosted server the user never sees an OAuth client: the
+            # fix is reconnecting, and pointing at a product would be an ad.
             "hint": (
-                "If you set up AdLoop before v0.10 with its bundled "
+                "Reconnect Google in your AdLoop Cloud dashboard "
+                "(Settings → Google), then retry."
+                if deployment_mode() == "server"
+                else "If you set up AdLoop before v0.10 with its bundled "
                 "credentials: that shared Google Cloud project has been "
                 "retired. Fastest fix: AdLoop Cloud (https://getadloop.com) — "
                 "connect Google in two clicks, no Google Cloud project "
@@ -552,6 +561,8 @@ def run_ga4_report(
 
     Date formats: "today", "yesterday", "7daysAgo", "28daysAgo", "90daysAgo", or "YYYY-MM-DD".
     If property_id is empty, uses the default from config.
+    Queries the GA4 Data API. Dimensions and metrics:
+    https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema
     """
     from adloop.ga4.reports import run_ga4_report as _impl
 
@@ -648,7 +659,7 @@ def run_gsc_report(
     finding keyword opportunities, and cross-referencing with GA4 and Ads data.
 
     site_url: the GSC property URL (e.g. "https://example.com/" or
-        "sc-domain:example.com"). Defaults to gsc.site_url in config.yaml.
+        "sc-domain:example.com"). Defaults to the configured Search Console site.
     dimensions: one or more of ["query", "page", "country", "device", "date"].
         Defaults to ["query"].
     date_range_start / date_range_end: ISO dates (YYYY-MM-DD) or relative
@@ -660,6 +671,8 @@ def run_gsc_report(
         [{"filters": [{"dimension": "query", "operator": "contains",
                        "expression": "analytics"}]}]
     limit: maximum rows to return (default 100, max 25000).
+    Queries the Search Console API:
+    https://developers.google.com/webmaster-tools/v1/searchanalytics/query
     """
     from adloop.gsc.reports import run_gsc_report as _impl
 
@@ -708,8 +721,9 @@ def analyze_page_speed(url: str, strategy: str = "mobile") -> dict:
 def list_merchant_accounts() -> dict:
     """List Google Merchant Center accounts the connected user can access.
 
-    Call first to discover merchant IDs for get_merchant_feed_health.
-    Distinguishes standalone accounts from aggregator (MCA) accounts.
+    Returns each account's numeric ID, name and whether it is a test
+    account. Call it to find the account_id for get_merchant_feed_health;
+    not needed when merchant.account_id is set in the config.
     """
     from adloop.merchant.read import list_merchant_accounts as _impl
 
@@ -899,9 +913,9 @@ def get_negative_keyword_lists(
 ) -> dict:
     """List all shared negative keyword lists (SharedSets) in the account.
 
-    Returns each list's ID, name, status, and keyword count. Always call
-    this before propose_negative_keyword_list to avoid creating duplicates —
-    a suitable list may already exist and just need attaching to a campaign.
+    Returns each list's ID, name, status, and keyword count. Useful before
+    propose_negative_keyword_list: a suitable list may already exist and
+    just need attaching to a campaign.
     """
     from adloop.ads.read import get_negative_keyword_lists as _impl
 
@@ -1543,7 +1557,8 @@ def run_gaql(
     """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.
+    Queries the Google Ads API. GAQL syntax and fields:
+    https://developers.google.com/google-ads/api/docs/query/overview
 
     format: "table" (default, readable), "json" (structured), "csv" (exportable)
     """
@@ -2125,8 +2140,8 @@ def add_to_negative_keyword_list(
 
     Use this when a suitable list already exists and only needs more keywords
     (instead of propose_negative_keyword_list, which creates a new list).
-    Always call get_negative_keyword_lists first to find the right shared_set_id
-    and get_negative_keyword_list_keywords to avoid duplicating existing terms.
+    The shared_set_id comes from get_negative_keyword_lists;
+    get_negative_keyword_list_keywords shows the terms already in a list.
 
     shared_set_id: numeric ID from get_negative_keyword_lists (shared_set.id).
     keywords: list of keyword strings to append (duplicates in the input list
@@ -2625,14 +2640,12 @@ def confirm_and_apply(
     to make real changes to the ad account (Google Ads or Reddit Ads — the
     plan knows which platform it targets).
 
-    Config override: if 'safety.require_dry_run: true' is set in the user's
-    config file (default ~/.adloop/config.yaml), dry_run=false is IGNORED
-    and this tool will keep returning DRY_RUN_SUCCESS. When that happens the
-    response includes 'dry_run_forced_by', 'config_path', and 'remediation'
-    fields — surface those to the user verbatim and STOP retrying. Calling
-    this tool again with dry_run=false will not change anything until the
-    user edits the config file, sets 'require_dry_run: false', and restarts
-    the AdLoop MCP server.
+    Forced dry runs: when real changes are switched off (live changes off
+    for the workspace in AdLoop Cloud, or safety.require_dry_run in a
+    self-hosted config), dry_run=false is IGNORED and the result is still
+    DRY_RUN_SUCCESS, with 'dry_run_forced_by' and 'remediation' fields.
+    Pass the remediation on to the user and stop retrying: calling again
+    with dry_run=false changes nothing until that setting is changed.
 
     Two-phase apply: if 'safety.two_phase_apply: true' is set (always on
     for AdLoop Cloud tenants), dry_run=false is REFUSED with status
@@ -2815,6 +2828,7 @@ def run_reddit_report(
     (HOUR and DATE cannot be combined). Dates are account-local days.
     filter: Reddit filter expression (e.g. "campaign_id==abc123").
     Microcurrency fields are converted to currency amounts.
+    Queries the Reddit Ads API: https://ads-api.reddit.com/docs/v3/
     """
     from adloop.reddit.read import run_reddit_report as _impl
 
@@ -3734,8 +3748,8 @@ def get_brand_lists(
 ) -> dict:
     """List all brand lists (SharedSets of type BRANDS) in the account.
 
-    Returns each list's ID, name, status, and member count. Call this before
-    propose_brand_list so an existing list can be reused instead of duplicated.
+    Returns each list's ID, name, status, and member count. Useful before
+    propose_brand_list, so an existing list can be reused instead of duplicated.
 
     Args:
         customer_id: Ads account ID. Defaults to the configured account.