adloop 0.31.0__tar.gz → 0.32.0__tar.gz

{adloop-0.31.0 → adloop-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.31.0
+Version: 0.32.0
 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

{adloop-0.31.0 → adloop-0.32.0}/pyproject.toml

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

{adloop-0.31.0 → adloop-0.32.0}/pyproject.toml.orig

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

{adloop-0.31.0 → adloop-0.32.0}/src/adloop/ads/write.py

@@ -550,9 +550,10 @@ def draft_responsive_search_ad(
         headlines:    HEADLINE_1, HEADLINE_2, HEADLINE_3
         descriptions: DESCRIPTION_1, DESCRIPTION_2
 
-    Google caps: at most 2 headlines per pin slot, at most 1 description per
-    pin slot. Mixed plain-string and dict entries are allowed within a single
-    call (e.g. brand pinned to HEADLINE_1, the rest unpinned).
+    Several assets may pin to the same position (Google rotates them there),
+    as long as every position stays fillable: by an asset pinned to it or by
+    a distinct unpinned asset. Mixed plain-string and dict entries are allowed
+    within a single call (e.g. brand pinned to HEADLINE_1, the rest unpinned).
     """
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
@@ -2055,12 +2056,19 @@ def remove_entity(
     if entity_type in ("campaign_asset", "customer_asset"):
         entity_id = entity_id.replace(",", "~")
 
+    names, not_found = _describe_target(config, customer_id, entity_type, entity_id)
+    if not_found:
+        return {"error": not_found}
+
     plan = ChangePlan(
         operation="remove_entity",
         entity_type=entity_type,
         entity_id=entity_id,
         customer_id=customer_id,
-        changes={"action": "REMOVE"},
+        changes={"action": "REMOVE", **names, **(
+            {"warnings": ["This entity is already REMOVED; applying changes nothing."]}
+            if names.get("current_status") == "REMOVED" else {}
+        )},
         # Removal is irreversible; the preview asks for a second explicit
         # confirmation, as Reddit removals already did.
         requires_double_confirm=True,
@@ -3457,7 +3465,6 @@ def _validate_rsa_assets(
         if len(descriptions) > 4:
             errors.append(f"Maximum 4 descriptions, got {len(descriptions)}")
 
-    headline_pin_counts: dict[str, int] = {}
     for i, h in enumerate(headlines):
         text = h["text"]
         pin = h["pinned_field"]
@@ -3472,13 +3479,8 @@ def _validate_rsa_assets(
                     f"Headline {i + 1} pinned_field '{pin}' invalid; "
                     f"must be one of {sorted(_VALID_HEADLINE_PINS)} or null"
                 )
-            else:
-                headline_pin_counts[pin] = headline_pin_counts.get(pin, 0) + 1
-    for pin, count in headline_pin_counts.items():
-        if count > 2:
-            errors.append(f"At most 2 headlines may pin to {pin}; got {count}")
+    errors.extend(_pin_fill_errors("headline", headlines, _VALID_HEADLINE_PINS))
 
-    description_pin_counts: dict[str, int] = {}
     for i, d in enumerate(descriptions):
         text = d["text"]
         pin = d["pinned_field"]
@@ -3493,15 +3495,37 @@ def _validate_rsa_assets(
                     f"Description {i + 1} pinned_field '{pin}' invalid; "
                     f"must be one of {sorted(_VALID_DESCRIPTION_PINS)} or null"
                 )
-            else:
-                description_pin_counts[pin] = description_pin_counts.get(pin, 0) + 1
-    for pin, count in description_pin_counts.items():
-        if count > 1:
-            errors.append(f"At most 1 description may pin to {pin}; got {count}")
+    errors.extend(_pin_fill_errors("description", descriptions, _VALID_DESCRIPTION_PINS))
 
     return errors
 
 
+def _pin_fill_errors(kind: str, assets: list[dict], positions: set[str]) -> list[str]:
+    """Google's pinning rule: every position must be fillable, either by an
+    asset pinned to it or by a distinct unpinned asset.
+
+    Google sets no cap on how many assets pin to one position (they rotate
+    there), so several headlines pinned to HEADLINE_1 are fine as long as the
+    other positions can still be filled. Breaking the rule fails at Google with
+    NOT_ENOUGH_AVAILABLE_ASSET_LINKS_FOR_VALID_COMBINATION.
+    """
+    if not assets:
+        return []
+    pinned = {a["pinned_field"] for a in assets if a.get("pinned_field") in positions}
+    if not pinned:
+        return []
+    empty = sorted(positions - pinned)
+    unpinned = sum(1 for a in assets if not a.get("pinned_field"))
+    if unpinned >= len(empty):
+        return []
+    return [
+        f"Pinning leaves {', '.join(empty)} without enough {kind}s: "
+        f"{len(empty)} position(s) have no pinned {kind} and need one distinct "
+        f"unpinned {kind} each, but only {unpinned} {kind}(s) are unpinned. "
+        f"Unpin a {kind}, add more unpinned ones, or pin one to each empty position."
+    ]
+
+
 def _validate_rsa(
     ad_group_id: str,
     headlines: list[dict],
@@ -3815,6 +3839,98 @@ def _preflight_ad_group_checks(
     return errors, warnings
 
 
+# What the preview of a pause, enable or remove names besides the IDs:
+# (query resource, id fields, name field, extra fields) per entity type. The
+# names reach the approval card and the confirmation dialog, where an ID alone
+# is hard to check, and a lookup that finds nothing exposes a mistyped ID.
+_TARGET_LOOKUPS: dict[str, tuple[str, tuple[str, ...], str, dict[str, str]]] = {
+    "campaign": ("campaign", ("campaign.id",), "campaign.name",
+                 {"current_status": "campaign.status"}),
+    "ad_group": ("ad_group", ("ad_group.id",), "ad_group.name",
+                 {"campaign_name": "campaign.name", "current_status": "ad_group.status"}),
+    "ad": ("ad_group_ad", ("ad_group_ad.ad.id",), "ad_group_ad.ad.name",
+           {"ad_group_name": "ad_group.name", "campaign_name": "campaign.name",
+            "current_status": "ad_group_ad.status"}),
+    "keyword": ("ad_group_criterion", ("ad_group.id", "ad_group_criterion.criterion_id"),
+                "ad_group_criterion.keyword.text",
+                {"match_type": "ad_group_criterion.keyword.match_type",
+                 "ad_group_name": "ad_group.name", "campaign_name": "campaign.name",
+                 "current_status": "ad_group_criterion.status"}),
+    "asset_group": ("asset_group", ("asset_group.id",), "asset_group.name",
+                    {"campaign_name": "campaign.name", "current_status": "asset_group.status"}),
+    "negative_keyword": ("campaign_criterion", ("campaign.id", "campaign_criterion.criterion_id"),
+                         "campaign_criterion.keyword.text", {"campaign_name": "campaign.name"}),
+    "campaign_criterion": ("campaign_criterion", ("campaign.id", "campaign_criterion.criterion_id"),
+                           "campaign_criterion.type", {"campaign_name": "campaign.name"}),
+    "ad_group_criterion": ("ad_group_criterion", ("ad_group.id", "ad_group_criterion.criterion_id"),
+                           "ad_group_criterion.type",
+                           {"ad_group_name": "ad_group.name", "campaign_name": "campaign.name"}),
+}
+
+
+def _format_customer(customer_id: object) -> str:
+    digits = str(customer_id or "").replace("-", "")
+    return f"{digits[:3]}-{digits[3:6]}-{digits[6:]}" if len(digits) == 10 else digits
+
+
+def _describe_target(
+    config: AdLoopConfig, customer_id: str, entity_type: str, entity_id: str
+) -> tuple[dict, str | None]:
+    """Names for a status change or removal preview: ``({names}, error)``.
+
+    One GAQL query reads the account name and, for the entity types above,
+    the entity's name, its campaign or ad group and its current status. A
+    failed lookup (API error, an ID format this does not know) returns no
+    names and no error, so the preview falls back to the IDs. A lookup that
+    succeeds but finds no such entity returns an error: the ID is wrong.
+    """
+    from adloop.ads.gaql import execute_query
+
+    spec = _TARGET_LOOKUPS.get(entity_type)
+    parts = entity_id.split("~")
+    if entity_type == "ad" and len(parts) == 2:
+        parts = parts[1:]  # adGroupId~adId: the ad id alone identifies it
+    if spec and (len(parts) != len(spec[1]) or not all(p.isdigit() for p in parts)):
+        spec = None
+    try:
+        if spec:
+            resource, id_fields, name_field, extra = spec
+            fields = ["customer.descriptive_name", "customer.id", name_field, *extra.values()]
+            where = " AND ".join(f"{f} = {v}" for f, v in zip(id_fields, parts))
+            rows = execute_query(
+                config, customer_id,
+                f"SELECT {', '.join(fields)} FROM {resource} WHERE {where} LIMIT 1",
+            )
+        else:
+            rows = execute_query(
+                config, customer_id, "SELECT customer.descriptive_name, customer.id FROM customer LIMIT 1"
+            )
+    except Exception:
+        return {}, None
+    if not rows:
+        if spec:
+            return {}, (
+                f"No {entity_type.replace('_', ' ')} with ID {entity_id} in account "
+                f"{_format_customer(customer_id) or 'the default account'}. Check the ID "
+                "with a read tool (get_campaign_performance, get_ad_performance, ...)."
+            )
+        return {}, None
+    row = rows[0]
+    names: dict = {}
+    account = row.get("customer.descriptive_name") or ""
+    cid = _format_customer(row.get("customer.id"))
+    if account or cid:
+        names["account"] = f"{account} ({cid})" if account and cid else account or cid
+    if spec:
+        name = row.get(spec[2])
+        if name:
+            names["entity_name"] = str(name)
+        for key, field_name in spec[3].items():
+            if row.get(field_name) not in (None, ""):
+                names[key] = str(row[field_name])
+    return names, None
+
+
 def _draft_status_change(
     config: AdLoopConfig,
     operation: str,
@@ -3841,12 +3957,21 @@ def _draft_status_change(
     if errors:
         return {"error": "Validation failed", "details": errors}
 
+    names, not_found = _describe_target(config, customer_id, entity_type, entity_id)
+    if not_found:
+        return {"error": not_found}
+    changes: dict = {"target_status": target_status, **names}
+    if names.get("current_status") == target_status:
+        changes["warnings"] = [
+            f"This {entity_type.replace('_', ' ')} is already {target_status}; applying changes nothing."
+        ]
+
     plan = ChangePlan(
         operation=operation,
         entity_type=entity_type,
         entity_id=entity_id,
         customer_id=customer_id,
-        changes={"target_status": target_status},
+        changes=changes,
     )
     store_plan(plan)
     return plan.to_preview()

{adloop-0.31.0 → adloop-0.32.0}/src/adloop/rules/adloop.md

@@ -270,7 +270,7 @@ For images that have no public URL: a file on the user's computer, or an image t
 | `draft_ad_group` | Create a new ad group within an existing campaign (does NOT publish) | `campaign_id` (REQUIRED), `ad_group_name` (REQUIRED), `keywords` (optional list of {text, match_type}), `cpc_bid_micros` (optional) |
 | `update_campaign` | Modify existing campaign settings — bid strategy, budget, geo targets, language targets, Search partners, display expansion | `campaign_id` (REQUIRED), plus any of: `bidding_strategy`, `daily_budget`, `geo_target_ids`, `language_ids`, `search_partners_enabled`, `display_network_enabled`, TARGET_SPEND `max_cpc` |
 | `update_ad_group` | Update ad group name and/or MANUAL_CPC `max_cpc` | `ad_group_id`, optional `ad_group_name`, optional `max_cpc` |
-| `draft_responsive_search_ad` | Create RSA preview (does NOT publish) | 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), final_url required, path1/path2 (≤15 chars each). Each headline/description may be a plain string (unpinned) or `{"text": "...", "pinned_field": "HEADLINE_1"}` (pinned). Valid pin slots: `HEADLINE_1/2/3`, `DESCRIPTION_1/2`. Google permits ≤2 headlines per slot, ≤1 description per slot. |
+| `draft_responsive_search_ad` | Create RSA preview (does NOT publish) | 3-15 headlines (≤30 chars), 2-4 descriptions (≤90 chars), final_url required, path1/path2 (≤15 chars each). Each headline/description may be a plain string (unpinned) or `{"text": "...", "pinned_field": "HEADLINE_1"}` (pinned). Valid pin slots: `HEADLINE_1/2/3`, `DESCRIPTION_1/2`. Several assets may pin to one slot (they rotate there), but every slot must stay fillable: by an asset pinned to it or by a distinct unpinned asset. |
 | `draft_callouts` | Create callout assets for a campaign (does NOT publish) | `campaign_id`, `callouts` list with 1-25 chars each |
 | `draft_structured_snippets` | Create structured snippet assets for a campaign (does NOT publish) | `campaign_id`, `snippets` list of `{header, values}` with official header values and 3-10 values |
 | `draft_image_assets` | Create image assets for a campaign from local files, public image URLs or uploads (does NOT publish) | `campaign_id`, `image_paths` (local PNG/JPEG/GIF files; not on a hosted server), `image_urls` (public http(s) image links, ≤5120 KB; re-checked at apply — if the image changed since the preview, draft again) and/or `upload_ids` (`up_...` from `upload_images` / `list_uploads`) |
@@ -427,7 +427,7 @@ Most websites (especially in the EU) use a GDPR cookie consent banner. This has
 7. **Pinning (use sparingly).** By default, pass headlines and descriptions as plain strings — Google rotates them for you and ad strength benefits from the diversity. Only switch to the dict shape `{"text": "...", "pinned_field": "HEADLINE_1"}` when the user has a concrete brand-safety, compliance, or messaging requirement (e.g. "the brand name must always appear", "the disclaimer must always show"). Trade-offs to flag before pinning:
    - Each pin reduces Google's ability to optimize headline order, which usually drops ad strength one notch.
    - Phone numbers should generally use a **call asset at the campaign level** (separate tool/manual setup) rather than a pinned headline — call assets are clickable on mobile and don't burn a headline slot. If the user asks to pin a phone number, suggest the call-asset path first.
-   - Valid pin slots: `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3` for headlines; `DESCRIPTION_1`, `DESCRIPTION_2` for descriptions. Google permits at most 2 headlines per slot and 1 description per slot — the draft tool enforces these caps.
+   - Valid pin slots: `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3` for headlines; `DESCRIPTION_1`, `DESCRIPTION_2` for descriptions. Several assets may pin to the same slot and rotate there (Google suggests 2 or 3 unique ones per pinned slot), but every slot must stay fillable: by an asset pinned to it or by a distinct unpinned asset. Pinning 3 keyword headlines to `HEADLINE_1` with 10 unpinned headlines is fine; pinning all 3 headlines of a 3-headline ad to `HEADLINE_1` is refused.
    - You can mix pinned dict entries with plain-string entries in a single call (e.g. brand pinned to `HEADLINE_1`, the rest unpinned).
 8. **Always set display paths** (`path1`, `path2`, max 15 chars each). These appear in the display URL (e.g. `example.com/Products/Pricing`) and significantly improve ad relevance. Derive them from the landing page URL structure or the ad's value proposition.
 9. Present the complete preview to the user — include any warnings from the pre-write checks, and explicitly call out which assets (if any) are pinned and the trade-off.
@@ -576,7 +576,7 @@ Reddit's structure is campaign → ad group (budget, bid, pixel, targeting) →
 
 1. Call the appropriate read tool to confirm the entity exists and get its current status
 2. Call `pause_entity` or `enable_entity` (Google) or `pause_reddit_entity` / `enable_reddit_entity` (Reddit) with the entity type and ID
-3. Present the preview with a clear warning about impact (e.g. "This will stop all ads in this campaign")
+3. Present the preview with a clear warning about impact (e.g. "This will stop all ads in this campaign"). Google Ads previews of pause, enable and remove name the target: `entity_name`, `account`, the parent `campaign_name` / `ad_group_name` and `current_status`. Repeat the names to the user, because a wrong account is the costly mistake; an ID that matches nothing is refused at draft time
 4. Wait for confirmation
 
 ### When user asks about landing page performance

{adloop-0.31.0 → adloop-0.32.0}/src/adloop/safety/approval_card.html

@@ -203,15 +203,25 @@
     const p = plan.preview;
     $("platform").textContent = PLATFORMS[platformOf(p)];
     $("title").textContent = humanize(p.operation);
+    // Names resolved at draft time (pause, enable, remove) sit in changes;
+    // the IDs stay visible next to them, and the card falls back to IDs.
+    const ch = p.changes || {};
     const sub = [];
-    if (p.entity_type) sub.push(String(p.entity_type).replace(/_/g, " ") + (p.entity_id ? " " + p.entity_id : ""));
-    if (p.customer_id) sub.push(String(p.customer_id));
+    if (p.entity_type) {
+      let target = String(p.entity_type).replace(/_/g, " ");
+      if (ch.entity_name) target += " \u201c" + ch.entity_name + "\u201d" + (p.entity_id ? " (" + p.entity_id + ")" : "");
+      else if (p.entity_id) target += " " + p.entity_id;
+      sub.push(target);
+    }
+    if (ch.account) sub.push(String(ch.account));
+    else if (p.customer_id) sub.push(String(p.customer_id));
     sub.push("plan " + plan.planId);
     $("subtitle").textContent = sub.join(" · ");
 
     const dl = $("changes");
     dl.replaceChildren();
-    const entries = Object.entries(p.changes || {});
+    const SHOWN_ELSEWHERE = new Set(["account", "entity_name", "warnings"]);
+    const entries = Object.entries(ch).filter(([k]) => !SHOWN_ELSEWHERE.has(k));
     entries.slice(0, MAX_ROWS).forEach(([k, v]) => row(dl, k, v));
     if (entries.length > MAX_ROWS) {
       const more = document.createElement("div");

{adloop-0.31.0 → adloop-0.32.0}/src/adloop/server.py

@@ -3406,10 +3406,11 @@ def draft_responsive_search_ad(
 
     The preview shows exactly what will be created; confirm_and_apply executes
     the returned plan_id. The ad is created PAUSED. final_url is checked for
-    reachability first and an unreachable URL is refused. Google caps: at most
-    2 headlines per pin slot, at most 1 description per pin slot. Mixed
-    plain-string and dict entries are allowed within a single call (e.g. brand
-    pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8
+    reachability first and an unreachable URL is refused. Several headlines
+    may pin to the same position (Google rotates them there) as long as every
+    position stays fillable, by an asset pinned to it or by a distinct
+    unpinned one. Mixed plain-string and dict entries are allowed within a
+    single call (e.g. brand pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8
     headlines or 3 descriptions.
 
     Args:
@@ -3483,15 +3484,15 @@ def update_responsive_search_ad(
             uses the configured default account.
         headlines: LIST-REPLACE: None or [] means no change; a non-empty list
             fully swaps in for the existing headlines. Google's RSA constraints
-            apply: 3-15 headlines, max 30 chars each, at most 2 per pin slot.
+            apply: 3-15 headlines, max 30 chars each, every pin position fillable.
             Each entry is a plain string (unpinned) or {"text": "...",
             "pinned_field": "HEADLINE_1"} (HEADLINE_1-3). Insertion tags such as
             {KeyWord:Clogged Drain Service} count as their default text, which
             is required.
         descriptions: LIST-REPLACE: None or [] means no change; a non-empty list
-            fully swaps in. 2-4 descriptions, max 90 chars each, at most 1 per
-            pin slot (DESCRIPTION_1, DESCRIPTION_2). Same entry format and
-            insertion-tag counting as headlines.
+            fully swaps in. 2-4 descriptions, max 90 chars each, pins to
+            DESCRIPTION_1 or DESCRIPTION_2 with every position fillable. Same
+            entry format and insertion-tag counting as headlines.
         final_url: Empty means no change; non-empty replaces the final URL and
             is checked for reachability.
         path1: Empty means no change; non-empty sets the first display path