adloop 0.16.1__tar.gz → 0.18.0__tar.gz

{adloop-0.16.1 → adloop-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.16.1
+Version: 0.18.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
@@ -132,8 +132,23 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_detailed_asset_performance` | Top-performing asset combinations — which headline+description+image combos Google selects most |
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
 | `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `suggest_brands` | Resolve a brand name to the brands Google recognizes — brand ID, name, state, URLs |
+| `check_brand_names` | Check a shortlist of brand names against Google's brand knowledge graph (max 25 per call) |
+| `get_brand_lists` | List brand lists (SharedSets of type BRANDS) — ID, name, status, member count |
+| `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
+| `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
+| `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Brand lists** — a list is a `SharedSet` of type `BRANDS`; attaching it to a campaign is a `CampaignCriterion.brand_list` (`negative=true` excludes, `false` restricts), **not** a `CampaignSharedSet` like negative keyword lists. `remove_from_brand_list` and `detach_brand_list_from_campaigns` remove for real — `SharedCriterion` has no status field.
+
+> **Brand targeting** — brand criteria (brand lists, brand exclusions) target a brand's **Commercial Knowledge Graph ID**, not its display name. Use `suggest_brands` for a single name or `check_brand_names` for a shortlist to get the ID; `exact_match` marks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.
+
+> **AI Max is the container for Search brand exclusions** — Google rejects a brand list on a plain Search campaign with *"For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns."* `draft_prepare_brand_exclusions` sets the state that makes the exclusion usable **without** handing Google the automations: AI Max on, search term matching off per ad group, text and final-URL automation opted out. `draft_ai_max_settings` is the general form when only parts of that state should change — it refuses a plan that would leave an automation on unnoticed, and asks for a second confirmation when that automation was requested explicitly.
+
+> **Custom conversion goals** — a named set of conversion actions that a campaign can be pointed at. `get_custom_conversion_goals` shows the goals with their actions and a campaign's current goal config; `draft_custom_conversion_goal` creates a set, `draft_update_custom_conversion_goal` renames or replaces its actions, `draft_assign_custom_conversion_goal` points a campaign at it and `draft_clear_custom_conversion_goal` puts the campaign back on the account-level goals. Only the goal and the campaign's goal config are touched — conversion actions, bidding and budgets stay as they are.
+
 > **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.
 
 ### Cross-Reference Tools (GA4 + Ads Combined)
@@ -246,6 +261,17 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
+| `propose_brand_list` | Draft a brand list (SharedSet of type BRANDS) from Commercial KG MIDs and optionally attach it to campaigns — `negative=true` (default) excludes the brands, `false` restricts targeting to them |
+| `add_to_brand_list` | Draft adding brands to an existing brand list |
+| `remove_from_brand_list` | Draft removing brands from a list (SharedCriteria have no status — removal is the only way; asks for a second confirmation) |
+| `attach_brand_list_to_campaigns` | Draft attaching an existing brand list to campaigns as `CampaignCriterion.brand_list` |
+| `detach_brand_list_from_campaigns` | Draft detaching a brand list from campaigns (removes only the criterion, the list stays) |
+| `draft_ai_max_settings` | Draft AI Max controls for a Search campaign: `enable_ai_max`, per-ad-group `disable_search_term_matching`, plus text and final-URL asset automation (each `OPTED_IN` / `OPTED_OUT` / `UNCHANGED`) |
+| `draft_prepare_brand_exclusions` | Draft the safe standard state in one step: AI Max on, search term matching off for every non-removed ad group, text and final-URL automation opted out. Touches nothing else |
+| `draft_custom_conversion_goal` | Create a custom conversion goal (a named set of conversion actions) |
+| `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
+| `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
+| `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |

{adloop-0.16.1 → adloop-0.18.0}/README.md

@@ -105,8 +105,23 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_detailed_asset_performance` | Top-performing asset combinations — which headline+description+image combos Google selects most |
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
 | `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `suggest_brands` | Resolve a brand name to the brands Google recognizes — brand ID, name, state, URLs |
+| `check_brand_names` | Check a shortlist of brand names against Google's brand knowledge graph (max 25 per call) |
+| `get_brand_lists` | List brand lists (SharedSets of type BRANDS) — ID, name, status, member count |
+| `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
+| `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
+| `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Brand lists** — a list is a `SharedSet` of type `BRANDS`; attaching it to a campaign is a `CampaignCriterion.brand_list` (`negative=true` excludes, `false` restricts), **not** a `CampaignSharedSet` like negative keyword lists. `remove_from_brand_list` and `detach_brand_list_from_campaigns` remove for real — `SharedCriterion` has no status field.
+
+> **Brand targeting** — brand criteria (brand lists, brand exclusions) target a brand's **Commercial Knowledge Graph ID**, not its display name. Use `suggest_brands` for a single name or `check_brand_names` for a shortlist to get the ID; `exact_match` marks a candidate whose name matches apart from case and punctuation, everything else is a Google suggestion.
+
+> **AI Max is the container for Search brand exclusions** — Google rejects a brand list on a plain Search campaign with *"For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns."* `draft_prepare_brand_exclusions` sets the state that makes the exclusion usable **without** handing Google the automations: AI Max on, search term matching off per ad group, text and final-URL automation opted out. `draft_ai_max_settings` is the general form when only parts of that state should change — it refuses a plan that would leave an automation on unnoticed, and asks for a second confirmation when that automation was requested explicitly.
+
+> **Custom conversion goals** — a named set of conversion actions that a campaign can be pointed at. `get_custom_conversion_goals` shows the goals with their actions and a campaign's current goal config; `draft_custom_conversion_goal` creates a set, `draft_update_custom_conversion_goal` renames or replaces its actions, `draft_assign_custom_conversion_goal` points a campaign at it and `draft_clear_custom_conversion_goal` puts the campaign back on the account-level goals. Only the goal and the campaign's goal config are touched — conversion actions, bidding and budgets stay as they are.
+
 > **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.
 
 ### Cross-Reference Tools (GA4 + Ads Combined)
@@ -219,6 +234,17 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
+| `propose_brand_list` | Draft a brand list (SharedSet of type BRANDS) from Commercial KG MIDs and optionally attach it to campaigns — `negative=true` (default) excludes the brands, `false` restricts targeting to them |
+| `add_to_brand_list` | Draft adding brands to an existing brand list |
+| `remove_from_brand_list` | Draft removing brands from a list (SharedCriteria have no status — removal is the only way; asks for a second confirmation) |
+| `attach_brand_list_to_campaigns` | Draft attaching an existing brand list to campaigns as `CampaignCriterion.brand_list` |
+| `detach_brand_list_from_campaigns` | Draft detaching a brand list from campaigns (removes only the criterion, the list stays) |
+| `draft_ai_max_settings` | Draft AI Max controls for a Search campaign: `enable_ai_max`, per-ad-group `disable_search_term_matching`, plus text and final-URL asset automation (each `OPTED_IN` / `OPTED_OUT` / `UNCHANGED`) |
+| `draft_prepare_brand_exclusions` | Draft the safe standard state in one step: AI Max on, search term matching off for every non-removed ad group, text and final-URL automation opted out. Touches nothing else |
+| `draft_custom_conversion_goal` | Create a custom conversion goal (a named set of conversion actions) |
+| `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
+| `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
+| `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |

{adloop-0.16.1 → adloop-0.18.0}/pyproject.toml

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

{adloop-0.16.1 → adloop-0.18.0}/pyproject.toml.orig

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

adloop-0.18.0/src/adloop/ads/ai_max.py

@@ -0,0 +1,555 @@
+"""AI Max controls — the container that makes brand exclusions usable in Search.
+
+Google Ads API v25 fields this module touches (verified against the SDK, not
+guessed):
+
+    campaign.ai_max_setting.enable_ai_max                            bool, writable
+    campaign.ai_max_setting.bundling_required                        output only
+    campaign.asset_automation_settings[]                             repeated
+        .asset_automation_type    AssetAutomationTypeEnum
+        .asset_automation_status  AssetAutomationStatusEnum (OPTED_IN / OPTED_OUT)
+    ad_group.ai_max_ad_group_setting.disable_search_term_matching     bool, writable
+
+Why this exists: attaching a brand list to a plain Search campaign is rejected
+with
+
+    For search advertising channel, brand lists can only be applied to
+    exclusive targeting, broad match campaigns for inclusive targeting or
+    PMax generated campaigns.
+
+Search campaigns therefore need AI Max as the container for brand exclusions —
+while everything AI Max would otherwise automate stays switched off: search
+term matching per ad group, and the text/URL asset automations at campaign
+level. ``enable_ai_max`` alone is not a safe state, which is why the apply
+order below matters.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+# AssetAutomationTypeEnum members we expose by name in the tool interface.
+# v25 has no plain "FINAL_URL_EXPANSION": the URL knob is modelled as
+# FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION.
+TEXT_ASSET_AUTOMATION = "TEXT_ASSET_AUTOMATION"
+FINAL_URL_EXPANSION = "FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION"
+
+AUTOMATION_CHOICES = ("OPTED_IN", "OPTED_OUT", "UNCHANGED")
+
+_CAMPAIGN_SELECT = """
+    SELECT campaign.id, campaign.name, campaign.status,
+           campaign.advertising_channel_type,
+           campaign.ai_max_setting.enable_ai_max,
+           campaign.ai_max_setting.bundling_required,
+           campaign.asset_automation_settings
+    FROM campaign
+    WHERE {where}
+    ORDER BY campaign.name
+"""
+
+_CAMPAIGN_WHERE_ALL = (
+    "campaign.status != 'REMOVED' AND campaign.advertising_channel_type = 'SEARCH'"
+)
+
+_AD_GROUP_SELECT = """
+    SELECT campaign.id, ad_group.id, ad_group.name, ad_group.status,
+           ad_group.ai_max_ad_group_setting.disable_search_term_matching
+    FROM ad_group
+    WHERE {where}
+    ORDER BY campaign.id, ad_group.name
+"""
+
+_AD_GROUP_WHERE_ALL = (
+    "ad_group.status != 'REMOVED' AND campaign.status != 'REMOVED' "
+    "AND campaign.advertising_channel_type = 'SEARCH'"
+)
+
+
+def get_ai_max_settings(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """Read-only view of the AI Max knobs, per campaign and per ad group.
+
+    Without ``campaign_id`` every non-removed Search campaign is returned.
+    """
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+
+    campaign_id = str(campaign_id or "").strip()
+    if campaign_id and not campaign_id.isdigit():
+        return {"error": "campaign_id must be a numeric ID"}
+
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    client = get_ads_client(config)
+    return read_ai_max_state(client, cid, campaign_id=campaign_id)
+
+
+def read_ai_max_state(client: object, cid: str, *, campaign_id: str = "") -> dict:
+    """Query the campaign settings and ad group switches; return a nested view."""
+    service = client.get_service("GoogleAdsService")
+
+    # The WHERE clause is assembled explicitly — no string surgery on an
+    # indented query, which could silently widen the result set.
+    if campaign_id:
+        if not str(campaign_id).isdigit():
+            raise ValueError("campaign_id must be a numeric ID")
+        campaign_where = f"campaign.id = {campaign_id}"
+        ad_group_where = (
+            f"ad_group.status != 'REMOVED' AND campaign.id = {campaign_id}"
+        )
+    else:
+        campaign_where = _CAMPAIGN_WHERE_ALL
+        ad_group_where = _AD_GROUP_WHERE_ALL
+    campaign_query = _CAMPAIGN_SELECT.format(where=campaign_where)
+    ad_group_query = _AD_GROUP_SELECT.format(where=ad_group_where)
+
+    campaign_rows = _search(service, cid, campaign_query)
+    ad_group_rows = _search(service, cid, ad_group_query)
+
+    campaigns = _normalize_campaign_rows(campaign_rows)
+    if campaign_id:
+        # Never let a row for another campaign through: the draft plans on
+        # campaigns[0], so a wider result set would silently plan the wrong one.
+        campaigns = [
+            campaign
+            for campaign in campaigns
+            if campaign["campaign_id"] == str(campaign_id)
+        ]
+    by_id = {campaign["campaign_id"]: campaign for campaign in campaigns}
+    for row in ad_group_rows:
+        campaign_key = str(row.get("campaign.id", ""))
+        campaign = by_id.get(campaign_key)
+        if campaign is None:
+            continue
+        campaign["ad_groups"].append(
+            {
+                "ad_group_id": str(row.get("ad_group.id", "")),
+                "ad_group_name": row.get("ad_group.name"),
+                "status": row.get("ad_group.status"),
+                "disable_search_term_matching": row.get(
+                    "ad_group.ai_max_ad_group_setting.disable_search_term_matching"
+                ),
+            }
+        )
+
+    return {
+        "campaigns": campaigns,
+        "total_campaigns": len(campaigns),
+        "total_ad_groups": sum(len(c["ad_groups"]) for c in campaigns),
+    }
+
+
+def _search(service: object, cid: str, query: str) -> list[dict]:
+    """Run a GAQL query and flatten each row into {field_path: value}."""
+    from adloop.ads.gaql import _extract_field, _parse_select_fields
+
+    fields = _parse_select_fields(query)
+    return [
+        {field: _extract_field(row, field) for field in fields}
+        for row in service.search(customer_id=cid, query=query)
+    ]
+
+
+def _normalize_campaign_rows(rows: list[dict]) -> list[dict]:
+    """Collapse GAQL rows into one entry per campaign.
+
+    GAQL may return one row per repeated ``asset_automation_settings`` element
+    or a single row with parallel lists, depending on how the field is
+    expanded. Both shapes are handled instead of assuming one.
+    """
+    campaigns: dict[str, dict] = {}
+    for row in rows:
+        key = str(row.get("campaign.id", ""))
+        if not key:
+            continue
+        entry = campaigns.setdefault(
+            key,
+            {
+                "campaign_id": key,
+                "campaign_name": row.get("campaign.name"),
+                "status": row.get("campaign.status"),
+                "advertising_channel_type": row.get("campaign.advertising_channel_type"),
+                "enable_ai_max": row.get("campaign.ai_max_setting.enable_ai_max"),
+                "bundling_required": row.get(
+                    "campaign.ai_max_setting.bundling_required"
+                ),
+                "asset_automation_settings": [],
+                "ad_groups": [],
+            },
+        )
+        for pair in _asset_automation_pairs(row):
+            existing = {
+                item["asset_automation_type"]: item
+                for item in entry["asset_automation_settings"]
+            }
+            existing[pair["asset_automation_type"]] = pair
+            entry["asset_automation_settings"] = list(existing.values())
+    return list(campaigns.values())
+
+
+def _asset_automation_pairs(row: dict) -> list[dict]:
+    """Normalize the asset automation settings of one GAQL row.
+
+    The whole message field is selected (``campaign.asset_automation_settings``,
+    not its sub-fields — GAQL answers those with PROHIBITED_FIELD_IN_SELECT_CLAUSE),
+    so the common shape is a list of dicts. The parallel-list shape is still
+    handled because it is what a sub-field select would have produced.
+    """
+    value = row.get("campaign.asset_automation_settings")
+    pairs: list[dict] = []
+
+    if isinstance(value, dict):
+        entries: list[object] = [value]
+    elif isinstance(value, list):
+        entries = value
+    else:
+        entries = []
+
+    for entry in entries:
+        if isinstance(entry, dict):
+            asset_type = entry.get("asset_automation_type")
+            if not asset_type:
+                continue
+            normalized = {"asset_automation_type": asset_type}
+            if entry.get("asset_automation_status"):
+                normalized["asset_automation_status"] = entry["asset_automation_status"]
+            # AUTOMATED_VIDEO_CRAWL carries its configuration in a nested
+            # setting instead of a status; keep it so a later write can send it
+            # back unchanged.
+            if entry.get("automated_video_crawl_setting"):
+                normalized["automated_video_crawl_setting"] = entry[
+                    "automated_video_crawl_setting"
+                ]
+            pairs.append(normalized)
+
+    if pairs:
+        return pairs
+
+    # Fallback: sub-field selection shape (parallel lists in one row).
+    types = row.get("campaign.asset_automation_settings.asset_automation_type")
+    statuses = row.get("campaign.asset_automation_settings.asset_automation_status")
+    if isinstance(types, list):
+        for index, asset_type in enumerate(types):
+            status = (
+                statuses[index]
+                if isinstance(statuses, list) and index < len(statuses)
+                else None
+            )
+            if asset_type:
+                pairs.append(
+                    {"asset_automation_type": asset_type, "asset_automation_status": status}
+                )
+    elif types:
+        pairs.append(
+            {"asset_automation_type": types, "asset_automation_status": statuses}
+        )
+    return pairs
+
+
+def merge_asset_automation(
+    current: list[dict], updates: dict[str, str]
+) -> list[dict]:
+    """Return the complete settings list with ``updates`` applied per type.
+
+    Google documents the field only as "the opt-in/out status of each
+    AssetAutomationType" — not whether an update replaces or merges the list.
+    Sending the complete merged list is correct either way, and preserving the
+    untouched types is what keeps this from silently switching other
+    automations on or off.
+    """
+    merged: dict[str, dict] = {}
+    for item in current:
+        asset_type = item.get("asset_automation_type")
+        if asset_type:
+            merged[asset_type] = dict(item)
+    for asset_type, status in updates.items():
+        if status == "UNCHANGED":
+            continue
+        entry = merged.setdefault(
+            asset_type,
+            {"asset_automation_type": asset_type, "asset_automation_status": None},
+        )
+        entry["asset_automation_status"] = status
+    return list(merged.values())
+
+
+def plan_targets(
+    state: dict,
+    *,
+    disable_search_term_matching: bool,
+    ad_group_ids: list[str] | None,
+    include_paused_ad_groups: bool,
+) -> tuple[list[dict], list[str]]:
+    """Resolve which ad groups the plan touches. Returns (targets, warnings)."""
+    groups = state.get("ad_groups", [])
+    warnings: list[str] = []
+
+    if ad_group_ids:
+        wanted = [str(g) for g in ad_group_ids]
+        known = {group["ad_group_id"]: group for group in groups}
+        unknown = [g for g in wanted if g not in known]
+        if unknown:
+            warnings.append(
+                "ad_group_ids not found in this campaign (or removed): "
+                + ", ".join(unknown)
+            )
+        targets = [known[g] for g in wanted if g in known]
+    else:
+        targets = list(groups)
+        if not include_paused_ad_groups:
+            skipped = [g for g in targets if g.get("status") != "ENABLED"]
+            targets = [g for g in targets if g.get("status") == "ENABLED"]
+            if skipped:
+                warnings.append(
+                    f"{len(skipped)} paused ad group(s) skipped "
+                    "(include_paused_ad_groups=false)"
+                )
+
+    for group in targets:
+        if group.get("status") == "REMOVED":
+            warnings.append(
+                f"ad group {group['ad_group_id']} is REMOVED and must never be mutated"
+            )
+    targets = [g for g in targets if g.get("status") != "REMOVED"]
+    return targets, warnings
+
+
+def plan_risks(
+    campaign: dict,
+    *,
+    enable_ai_max: bool | None,
+    disable_search_term_matching: bool | None,
+    automation_updates: dict[str, str],
+    targeted_ad_group_ids: set[str],
+) -> dict[str, list[str]]:
+    """Classify the automations still running in the planned AI Max state.
+
+    This module's rule is that AI Max only ever runs as a container with its
+    automations off. A plan can nevertheless end in the automat*on* state in two
+    ways, and they must not be treated the same:
+
+    ``implicit``
+        The automation keeps running because the caller never mentioned it — an
+        unchanged campaign setting or an untouched ad group switch. That is the
+        trap this module exists to prevent, and it should be refused.
+    ``explicit``
+        The caller named the automation in the arguments
+        (``disable_search_term_matching=false``, ``text_asset_automation=
+        OPTED_IN``), or deliberately narrowed the ad group selection. Switching
+        to AI Max with its automations is a legitimate Google Ads configuration,
+        so it must stay expressible — but it deserves a second confirmation and
+        a warning that names what stays automated.
+
+    Returns ``{"implicit": [...], "explicit": [...]}``, both empty when the
+    resulting state has AI Max off or nothing left to automate.
+    """
+    resulting_ai_max = (
+        bool(campaign.get("enable_ai_max"))
+        if enable_ai_max is None
+        else bool(enable_ai_max)
+    )
+    if not resulting_ai_max:
+        return {"implicit": [], "explicit": []}
+
+    inherited: list[str] = []
+    chosen: list[str] = []
+
+    never_mentioned: list[str] = []
+    outside_selection: list[str] = []
+    switched_on: list[str] = []
+    for group in campaign.get("ad_groups", []):
+        if group.get("status") == "REMOVED":
+            continue
+        targeted = group.get("ad_group_id") in targeted_ad_group_ids
+        if disable_search_term_matching is None or not targeted:
+            after = group.get("disable_search_term_matching") is True
+        else:
+            after = bool(disable_search_term_matching)
+        if after:
+            continue
+        name = group.get("ad_group_name") or group["ad_group_id"]
+        if disable_search_term_matching is None:
+            never_mentioned.append(name)
+        elif targeted:
+            switched_on.append(name)
+        else:
+            outside_selection.append(name)
+
+    def _list(names: list[str]) -> str:
+        shown = ", ".join(names[:5])
+        more = "" if len(names) <= 5 else f" (+{len(names) - 5} more)"
+        return f"{shown}{more}"
+
+    if never_mentioned:
+        inherited.append(
+            f"search term matching would stay on for {len(never_mentioned)} ad "
+            f"group(s): {_list(never_mentioned)} — pass "
+            "disable_search_term_matching=true to switch it off"
+        )
+    if outside_selection:
+        # The caller chose the selection (include_paused_ad_groups=false or
+        # ad_group_ids), so this is a decision, not an accident — but it still
+        # deserves the second confirmation and a warning that names the groups.
+        chosen.append(
+            f"search term matching stays on for {len(outside_selection)} ad "
+            f"group(s) outside the selection: {_list(outside_selection)} — pass "
+            "include_paused_ad_groups=true or list them in ad_group_ids to "
+            "switch it off as well"
+        )
+    if switched_on:
+        chosen.append(
+            f"search term matching stays on for {len(switched_on)} ad group(s) "
+            f"— requested with disable_search_term_matching=false: "
+            f"{_list(switched_on)}"
+        )
+
+    for asset_type, status in automation_updates.items():
+        if status == "OPTED_IN":
+            chosen.append(f"{asset_type} is requested as OPTED_IN")
+
+    if automation_updates.get(TEXT_ASSET_AUTOMATION, "UNCHANGED") == "UNCHANGED":
+        if _current_status(campaign, TEXT_ASSET_AUTOMATION) == "OPTED_IN":
+            inherited.append(
+                f"{TEXT_ASSET_AUTOMATION} is OPTED_IN in the campaign and left "
+                "unchanged — pass text_asset_automation to switch it off"
+            )
+    if automation_updates.get(FINAL_URL_EXPANSION, "UNCHANGED") == "UNCHANGED":
+        if _current_status(campaign, FINAL_URL_EXPANSION) == "OPTED_IN":
+            inherited.append(
+                f"{FINAL_URL_EXPANSION} is OPTED_IN in the campaign and left "
+                "unchanged — pass final_url_expansion to switch it off"
+            )
+
+    return {"implicit": inherited, "explicit": chosen}
+
+
+def _current_status(campaign: dict, asset_type: str) -> str | None:
+    for item in campaign.get("asset_automation_settings") or []:
+        if item.get("asset_automation_type") == asset_type:
+            return item.get("asset_automation_status")
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Mutation primitives (all called from the write applier)
+# ---------------------------------------------------------------------------
+
+
+def mutate_ad_group_search_term_matching(
+    client: object, cid: str, ad_groups: list[dict], disable: bool
+) -> dict:
+    """Set ``disable_search_term_matching`` on the given ad groups in one request."""
+    from google.protobuf import field_mask_pb2
+
+    service = client.get_service("AdGroupService")
+    operations = []
+    for group in ad_groups:
+        operation = client.get_type("AdGroupOperation")
+        update = operation.update
+        update.resource_name = service.ad_group_path(cid, group["ad_group_id"])
+        update.ai_max_ad_group_setting.disable_search_term_matching = bool(disable)
+        operation.update_mask = field_mask_pb2.FieldMask(
+            paths=["ai_max_ad_group_setting.disable_search_term_matching"]
+        )
+        operations.append(operation)
+
+    request = client.get_type("MutateAdGroupsRequest")
+    request.customer_id = cid
+    request.operations.extend(operations)
+    request.partial_failure = True
+    response = service.mutate_ad_groups(request=request)
+    return _split_partial_failure(
+        client, response, ad_groups, key="ad_group_id", partial_key="failed_ad_groups"
+    )
+
+
+def mutate_campaign_ai_max(client: object, cid: str, changes: dict) -> dict:
+    """Update campaign-level AI Max settings in a single operation."""
+    from google.protobuf import field_mask_pb2
+
+    service = client.get_service("CampaignService")
+    operation = client.get_type("CampaignOperation")
+    campaign = operation.update
+    campaign.resource_name = service.campaign_path(cid, changes["campaign_id"])
+
+    paths: list[str] = []
+    if changes.get("enable_ai_max") is not None:
+        campaign.ai_max_setting.enable_ai_max = bool(changes["enable_ai_max"])
+        paths.append("ai_max_setting.enable_ai_max")
+
+    settings = changes.get("asset_automation_settings") or []
+    if settings:
+        # proto-plus repeated message fields have no ``add()`` and the nested
+        # message classes are not reachable by attribute — but ``append`` takes
+        # a plain dict and maps enum names and nested messages itself. Settings
+        # read back from the account travel through unchanged, so an update that
+        # replaces the list cannot silently drop a configuration we never
+        # touched (AUTOMATED_VIDEO_CRAWL carries its own nested setting).
+        for item in settings:
+            entry = {"asset_automation_type": item["asset_automation_type"]}
+            if item.get("asset_automation_status"):
+                entry["asset_automation_status"] = item["asset_automation_status"]
+            if item.get("automated_video_crawl_setting"):
+                entry["automated_video_crawl_setting"] = item[
+                    "automated_video_crawl_setting"
+                ]
+            campaign.asset_automation_settings.append(entry)
+        paths.append("asset_automation_settings")
+
+    if not paths:
+        return {"attempted": False, "reason": "no campaign-level change requested"}
+
+    operation.update_mask = field_mask_pb2.FieldMask(paths=paths)
+    response = service.mutate_campaigns(customer_id=cid, operations=[operation])
+    return {
+        "attempted": True,
+        "update_mask": paths,
+        "resource_name": response.results[0].resource_name
+        if response.results
+        else None,
+    }
+
+
+def _split_partial_failure(
+    client: object, response: object, targets: list[dict], *, key: str, partial_key: str
+) -> dict:
+    """Split a partial-failure mutate response into succeeded/failed entries."""
+    from adloop.ads.write import _parse_partial_failure_per_op
+
+    pf_error = getattr(response, "partial_failure_error", None)
+    per_op_errors = _parse_partial_failure_per_op(client, pf_error)
+
+    succeeded: list[str] = []
+    failed: list[dict] = []
+    for index, result in enumerate(response.results):
+        target = targets[index] if index < len(targets) else {}
+        if getattr(result, "resource_name", ""):
+            succeeded.append(str(target.get(key, "")))
+        else:
+            failed.append(
+                {
+                    key: str(target.get(key, "")),
+                    "operation_index": index,
+                    "error": per_op_errors.get(
+                        index, "Unknown error (see partial_failure_message)"
+                    ),
+                }
+            )
+
+    out: dict[str, Any] = {
+        "succeeded": succeeded,
+        "failed": failed,
+        "count": len(succeeded),
+    }
+    if failed:
+        out["partial_failure"] = True
+        out[partial_key] = failed
+        message = getattr(pf_error, "message", "") if pf_error is not None else ""
+        if message:
+            out["partial_failure_message"] = message
+    return out