adloop 0.19.0__tar.gz → 0.19.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.19.0
+Version: 0.19.1
 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.1}/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.19.0"
+version = "0.19.1"
 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.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.19.0"
+version = "0.19.1"
 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.1}/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.1}/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.1}/src/adloop/ads/write.py

@@ -3867,7 +3867,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.1}/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
@@ -552,6 +554,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
 
@@ -660,6 +664,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 +714,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 +906,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 +1550,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 +2133,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
@@ -2815,6 +2823,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 +3743,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.