adloop 0.28.0__tar.gz → 0.29.0__tar.gz

{adloop-0.28.0 → adloop-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.28.0
+Version: 0.29.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
@@ -138,6 +138,9 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
 | `get_change_history` | What changed before the drop: who changed what and when, through which client (UI, API, scripts, auto-applied recommendations), last 30 days |
 | `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `get_audience_lists` | The account's remarketing and customer lists (size, eligibility, open/closed), custom and combined segments |
+| `search_audience_segments` | Find Google's in-market and affinity segments by name |
+| `get_audience_targeting` | Audiences and audience exclusions on a campaign or ad group, plus the audience mode (observation or targeting) |
 | `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 |
@@ -308,6 +311,7 @@ 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_delete_key_event` | Remove a GA4 key event. The event keeps firing but no longer counts as a conversion, for future data only |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
+| `draft_audience_attachment` | Attach audiences as observation (default), targeting (double confirmation) or exclusion; refuses pairings Google doesn't allow and Search lists too small to target |
 | `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 |

{adloop-0.28.0 → adloop-0.29.0}/README.md

@@ -110,6 +110,9 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
 | `get_change_history` | What changed before the drop: who changed what and when, through which client (UI, API, scripts, auto-applied recommendations), last 30 days |
 | `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
+| `get_audience_lists` | The account's remarketing and customer lists (size, eligibility, open/closed), custom and combined segments |
+| `search_audience_segments` | Find Google's in-market and affinity segments by name |
+| `get_audience_targeting` | Audiences and audience exclusions on a campaign or ad group, plus the audience mode (observation or targeting) |
 | `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 |
@@ -280,6 +283,7 @@ 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_delete_key_event` | Remove a GA4 key event. The event keeps firing but no longer counts as a conversion, for future data only |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
+| `draft_audience_attachment` | Attach audiences as observation (default), targeting (double confirmation) or exclusion; refuses pairings Google doesn't allow and Search lists too small to target |
 | `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 |

{adloop-0.28.0 → adloop-0.29.0}/pyproject.toml

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

{adloop-0.28.0 → adloop-0.29.0}/pyproject.toml.orig

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

adloop-0.29.0/src/adloop/ads/audiences.py

@@ -0,0 +1,547 @@
+"""Google Ads audiences: list them, see what is attached, attach them (#48).
+
+Reads cover the account's own audiences (remarketing/customer lists, custom
+segments, combined segments), Google's segment catalog (in-market and
+affinity), and the audiences attached to one campaign or ad group together
+with its audience mode.
+
+``draft_audience_attachment`` attaches audiences in one atomic
+GoogleAdsService.Mutate. Observation is the default: the audiences only
+adjust bids and report, reach stays the same. Targeting narrows serving to
+the audiences, so it has to be asked for explicitly and needs a double
+confirmation. The mode is the entity's AUDIENCE target restriction
+(``bid_only``); it is always written explicitly with the attachment, so the
+result never depends on Google's default for the campaign type. Exclusions
+(``exclude=True``) are negative criteria and leave the mode alone.
+
+Performance Max takes audiences only as asset group signals
+(draft_asset_group_signals) and is refused here with that pointer. Creating
+audiences is out of scope.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+# Audience kinds a criterion can point at: (criterion type in GAQL,
+# criterion field, resource collection).
+_KINDS = {
+    "user_list": ("USER_LIST", "user_list.user_list", "userLists"),
+    "segment": ("USER_INTEREST", "user_interest.user_interest_category", "userInterests"),
+    "custom_audience": ("CUSTOM_AUDIENCE", "custom_audience.custom_audience", "customAudiences"),
+    "combined_audience": ("COMBINED_AUDIENCE", "combined_audience.combined_audience", "combinedAudiences"),
+}
+_TYPE_TO_KIND = {v[0]: k for k, v in _KINDS.items()}
+
+# Which kinds each campaign type accepts. Custom segments cannot be attached
+# to Search; combined segments are Search-only. Google's dry run checks the
+# rest (e.g. level rules) against the live account.
+_COMPATIBLE = {
+    "SEARCH": {"user_list", "segment", "combined_audience"},
+    "DISPLAY": {"user_list", "segment", "custom_audience"},
+    "VIDEO": {"user_list", "segment", "custom_audience"},
+    "SHOPPING": {"user_list", "segment"},
+}
+_KIND_LABELS = {
+    "user_list": "remarketing or customer lists",
+    "segment": "in-market and affinity segments",
+    "custom_audience": "custom segments",
+    "combined_audience": "combined segments",
+}
+# Search shows ads to a remarketing list once it has this many active users.
+_SEARCH_MIN_SIZE = 1000
+_MAX_PER_DRAFT = 50
+
+
+def _id(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _last(resource: str | None) -> str:
+    return str(resource or "").rsplit("/", 1)[-1]
+
+
+def get_audience_lists(config: AdLoopConfig, *, customer_id: str = "") -> dict:
+    """The account's own audiences: remarketing/customer lists, custom and combined segments."""
+    from adloop.ads.gaql import execute_query
+
+    lists = execute_query(
+        config,
+        customer_id,
+        "SELECT user_list.id, user_list.name, user_list.type, user_list.membership_status, "
+        "user_list.size_for_search, user_list.size_for_display, user_list.eligible_for_search, "
+        "user_list.eligible_for_display, user_list.membership_life_span, "
+        "user_list.account_user_list_status FROM user_list",
+    )
+    custom = execute_query(
+        config,
+        customer_id,
+        "SELECT custom_audience.id, custom_audience.name, custom_audience.type, custom_audience.description "
+        "FROM custom_audience WHERE custom_audience.status = 'ENABLED'",
+    )
+    combined = execute_query(
+        config,
+        customer_id,
+        "SELECT combined_audience.id, combined_audience.name, combined_audience.description "
+        "FROM combined_audience WHERE combined_audience.status = 'ENABLED'",
+    )
+    user_lists = []
+    for row in lists:
+        if row.get("user_list.account_user_list_status") == "CLOSED":
+            continue
+        user_lists.append({
+            "user_list_id": str(row.get("user_list.id")),
+            "name": row.get("user_list.name"),
+            "type": row.get("user_list.type"),
+            "membership_status": row.get("user_list.membership_status"),
+            "size_for_search": row.get("user_list.size_for_search"),
+            "size_for_display": row.get("user_list.size_for_display"),
+            "eligible_for_search": row.get("user_list.eligible_for_search"),
+            "eligible_for_display": row.get("user_list.eligible_for_display"),
+            "membership_life_span_days": row.get("user_list.membership_life_span"),
+        })
+    insights = []
+    small = [u["name"] for u in user_lists if (u["size_for_search"] or 0) < _SEARCH_MIN_SIZE and u["eligible_for_search"]]
+    if small:
+        insights.append(
+            f"Below {_SEARCH_MIN_SIZE:,} users for Search (attachable, but they adjust nothing there until they grow): "
+            + ", ".join(small[:10])
+        )
+    closed = [u["name"] for u in user_lists if u["membership_status"] == "CLOSED"]
+    if closed:
+        insights.append("Closed lists no longer add members and shrink over time: " + ", ".join(closed[:10]))
+    if not user_lists and not custom and not combined:
+        insights.append(
+            "No audiences of your own yet. In-market and affinity segments (search_audience_segments) work without any."
+        )
+    return {
+        "user_lists": user_lists,
+        "custom_segments": [
+            {"custom_audience_id": str(r.get("custom_audience.id")), "name": r.get("custom_audience.name"),
+             "type": r.get("custom_audience.type"), "description": r.get("custom_audience.description")}
+            for r in custom
+        ],
+        "combined_segments": [
+            {"combined_audience_id": str(r.get("combined_audience.id")), "name": r.get("combined_audience.name"),
+             "description": r.get("combined_audience.description")}
+            for r in combined
+        ],
+        "insights": insights,
+    }
+
+
+def search_audience_segments(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    query: str = "",
+    kind: str = "all",
+    limit: int = 25,
+) -> dict:
+    """Google's in-market and affinity segments whose name matches ``query``."""
+    from adloop.ads.gaql import execute_query
+
+    query = str(query or "").strip()
+    if len(query) < 2:
+        return {"error": "query needs at least 2 characters, e.g. 'running' or 'insurance'"}
+    taxonomies = {"in_market": ["IN_MARKET"], "affinity": ["AFFINITY"], "all": ["IN_MARKET", "AFFINITY"]}
+    if kind not in taxonomies:
+        return {"error": "kind must be in_market, affinity or all"}
+    limit = max(1, min(int(limit or 25), 100))
+    # GAQL's LIKE is case-sensitive and the catalog is small (about 1,500
+    # segments), so match here instead. launched_to_all is False for most
+    # segments ("not in every channel and locale"), so it is no filter.
+    rows = execute_query(
+        config,
+        customer_id,
+        "SELECT user_interest.user_interest_id, user_interest.name, user_interest.taxonomy_type FROM user_interest "
+        f"WHERE user_interest.taxonomy_type IN ({', '.join(repr(t) for t in taxonomies[kind])})",
+    )
+    needle = query.lower()
+    matches = [r for r in rows if needle in str(r.get("user_interest.name") or "").lower()]
+    # Names that start with the query first, then the rest alphabetically.
+    matches.sort(key=lambda r: (not str(r.get("user_interest.name")).lower().startswith(needle), str(r.get("user_interest.name"))))
+    segments = [
+        {
+            "segment_id": str(r.get("user_interest.user_interest_id")),
+            "name": r.get("user_interest.name"),
+            "kind": "in_market" if r.get("user_interest.taxonomy_type") == "IN_MARKET" else "affinity",
+        }
+        for r in matches[:limit]
+    ]
+    return {"query": query, "segments": segments, "count": len(segments)}
+
+
+def _entity_context(config: AdLoopConfig, customer_id: str, campaign_id: str, ad_group_id: str) -> dict:
+    """Channel, names, the AUDIENCE mode and the audience criteria at both levels."""
+    from adloop.ads.gaql import execute_query
+
+    if ad_group_id:
+        rows = execute_query(
+            config,
+            customer_id,
+            "SELECT ad_group.id, ad_group.name, ad_group.targeting_setting.target_restrictions, campaign.id, "
+            "campaign.name, campaign.advertising_channel_type FROM ad_group "
+            f"WHERE ad_group.id = {int(ad_group_id)}",
+        )
+        if not rows:
+            raise ValueError(f"ad group {ad_group_id} was not found")
+        row = rows[0]
+        restrictions = row.get("ad_group.targeting_setting.target_restrictions") or []
+        campaign_id = str(row.get("campaign.id"))
+        entity_name = row.get("ad_group.name")
+    else:
+        rows = execute_query(
+            config,
+            customer_id,
+            "SELECT campaign.id, campaign.name, campaign.advertising_channel_type, "
+            "campaign.targeting_setting.target_restrictions FROM campaign "
+            f"WHERE campaign.id = {int(campaign_id)}",
+        )
+        if not rows:
+            raise ValueError(f"campaign {campaign_id} was not found")
+        row = rows[0]
+        restrictions = row.get("campaign.targeting_setting.target_restrictions") or []
+        entity_name = row.get("campaign.name")
+
+    types = ", ".join(f"'{t}'" for t, _f, _c in _KINDS.values())
+    campaign_criteria = execute_query(
+        config,
+        customer_id,
+        "SELECT campaign_criterion.criterion_id, campaign_criterion.type, campaign_criterion.negative, "
+        "campaign_criterion.user_list.user_list, campaign_criterion.user_interest.user_interest_category, "
+        "campaign_criterion.custom_audience.custom_audience, campaign_criterion.combined_audience.combined_audience "
+        f"FROM campaign_criterion WHERE campaign.id = {int(campaign_id)} AND campaign_criterion.type IN ({types}) "
+        "AND campaign_criterion.status != 'REMOVED'",
+    )
+    ad_group_criteria = execute_query(
+        config,
+        customer_id,
+        "SELECT ad_group.id, ad_group_criterion.criterion_id, ad_group_criterion.type, ad_group_criterion.negative, "
+        "ad_group_criterion.user_list.user_list, ad_group_criterion.user_interest.user_interest_category, "
+        "ad_group_criterion.custom_audience.custom_audience, ad_group_criterion.combined_audience.combined_audience "
+        f"FROM ad_group_criterion WHERE campaign.id = {int(campaign_id)} AND ad_group_criterion.type IN ({types}) "
+        "AND ad_group_criterion.status != 'REMOVED'",
+    )
+
+    def criteria(rows: list[dict], prefix: str, owner: str) -> list[dict]:
+        out = []
+        for r in rows:
+            kind = _TYPE_TO_KIND.get(str(r.get(f"{prefix}.type") or ""))
+            if not kind:
+                continue
+            out.append({
+                "kind": kind,
+                "audience_id": _last(r.get(f"{prefix}.{_KINDS[kind][1]}")),
+                "negative": bool(r.get(f"{prefix}.negative")),
+                "remove_id": f"{owner if owner else r.get('ad_group.id')}~{r.get(f'{prefix}.criterion_id')}",
+                "ad_group_id": str(r.get("ad_group.id")) if not owner else None,
+            })
+        return out
+
+    mode = None
+    for restriction in restrictions:
+        if isinstance(restriction, dict) and restriction.get("targeting_dimension") == "AUDIENCE":
+            mode = "observation" if restriction.get("bid_only") else "targeting"
+    return {
+        "campaign_id": campaign_id,
+        "channel": str(row.get("campaign.advertising_channel_type") or ""),
+        "campaign_name": row.get("campaign.name"),
+        "entity_name": entity_name,
+        "mode": mode,
+        "restrictions": [r for r in restrictions if isinstance(r, dict)],
+        "campaign_criteria": criteria(campaign_criteria, "campaign_criterion", campaign_id),
+        "ad_group_criteria": criteria(ad_group_criteria, "ad_group_criterion", ""),
+    }
+
+
+def _names(config: AdLoopConfig, customer_id: str, entries: list[dict], lists: dict | None = None) -> None:
+    """Fill in ``name`` for criteria entries (lists from get_audience_lists, segments by id)."""
+    from adloop.ads.gaql import execute_query
+
+    lists = lists or get_audience_lists(config, customer_id=customer_id)
+    names = {("user_list", u["user_list_id"]): u["name"] for u in lists["user_lists"]}
+    names |= {("custom_audience", c["custom_audience_id"]): c["name"] for c in lists["custom_segments"]}
+    names |= {("combined_audience", c["combined_audience_id"]): c["name"] for c in lists["combined_segments"]}
+    segment_ids = sorted({e["audience_id"] for e in entries if e["kind"] == "segment" and e["audience_id"].isdigit()})
+    if segment_ids:
+        rows = execute_query(
+            config,
+            customer_id,
+            "SELECT user_interest.user_interest_id, user_interest.name, user_interest.taxonomy_type FROM user_interest "
+            f"WHERE user_interest.user_interest_id IN ({', '.join(segment_ids)})",
+        )
+        names |= {("segment", str(r.get("user_interest.user_interest_id"))): r.get("user_interest.name") for r in rows}
+    for entry in entries:
+        entry["name"] = names.get((entry["kind"], entry["audience_id"]))
+
+
+def get_audience_targeting(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+    ad_group_id: str = "",
+) -> dict:
+    """Audiences attached to one campaign or ad group, with the audience mode."""
+    campaign_id, ad_group_id = _id(campaign_id), _id(ad_group_id)
+    if bool(campaign_id) == bool(ad_group_id):
+        return {"error": "Provide exactly one of campaign_id or ad_group_id"}
+    if not (campaign_id or ad_group_id).isdigit():
+        return {"error": "campaign_id / ad_group_id must be a numeric Google Ads id"}
+    try:
+        ctx = _entity_context(config, customer_id, campaign_id, ad_group_id)
+    except ValueError as e:
+        return {"error": str(e)}
+    if ad_group_id:
+        attached = [c for c in ctx["ad_group_criteria"] if c["ad_group_id"] == ad_group_id]
+    else:
+        attached = list(ctx["campaign_criteria"])
+    _names(config, customer_id, attached)
+    for entry in attached:
+        entry.pop("ad_group_id", None)
+    insights = []
+    if ctx["mode"] == "targeting" and any(not c["negative"] for c in attached):
+        insights.append("Targeting mode: ads only reach people in the attached audiences.")
+    if ad_group_id and any(not c["negative"] for c in ctx["campaign_criteria"]):
+        insights.append("The campaign has audiences of its own; Google does not allow audiences at both levels.")
+    return {
+        "level": "ad_group" if ad_group_id else "campaign",
+        "campaign_id": ctx["campaign_id"],
+        "campaign_name": ctx["campaign_name"],
+        "channel": ctx["channel"],
+        "audience_mode": ctx["mode"] or "not set",
+        "audiences": [c for c in attached if not c["negative"]],
+        "exclusions": [c for c in attached if c["negative"]],
+        "insights": insights,
+    }
+
+
+def draft_audience_attachment(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+    ad_group_id: str = "",
+    user_list_ids: list[str] | None = None,
+    segment_ids: list[str] | None = None,
+    custom_audience_ids: list[str] | None = None,
+    combined_audience_ids: list[str] | None = None,
+    mode: str = "observation",
+    exclude: bool = False,
+) -> dict:
+    """Draft attaching audiences to a campaign or ad group: returns a preview."""
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("add_audience_criteria", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    campaign_id, ad_group_id = _id(campaign_id), _id(ad_group_id)
+    requested = {
+        "user_list": user_list_ids,
+        "segment": segment_ids,
+        "custom_audience": custom_audience_ids,
+        "combined_audience": combined_audience_ids,
+    }
+    wanted = [
+        {"kind": kind, "audience_id": _id(value)}
+        for kind, values in requested.items()
+        for value in dict.fromkeys(values or [])
+        if _id(value)
+    ]
+    errors = []
+    if bool(campaign_id) == bool(ad_group_id):
+        errors.append("Provide exactly one of campaign_id or ad_group_id")
+    elif not (campaign_id or ad_group_id).isdigit():
+        errors.append("campaign_id / ad_group_id must be a numeric Google Ads id")
+    if not wanted:
+        errors.append("Pass at least one of user_list_ids, segment_ids, custom_audience_ids, combined_audience_ids")
+    bad = [w["audience_id"] for w in wanted if not w["audience_id"].isdigit()]
+    if bad:
+        errors.append(f"audience ids must be numeric: {', '.join(bad)}")
+    if len(wanted) > _MAX_PER_DRAFT:
+        errors.append(f"at most {_MAX_PER_DRAFT} audiences per draft")
+    if mode not in ("observation", "targeting"):
+        errors.append("mode must be 'observation' (default, bids and reporting only) or 'targeting'")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    try:
+        ctx = _entity_context(config, customer_id, campaign_id, ad_group_id)
+    except ValueError as e:
+        return {"error": str(e)}
+    channel = ctx["channel"]
+    if channel == "PERFORMANCE_MAX":
+        return {"error": (
+            "Performance Max takes audiences only as asset group signals, not as targeting. "
+            "Use get_asset_group_signals and draft_asset_group_signals instead."
+        )}
+    allowed = _COMPATIBLE.get(channel)
+    if allowed is None:
+        return {"error": f"Attaching audiences to {channel or 'this'} campaigns is not supported yet; use the Google Ads interface."}
+    for kind in {w["kind"] for w in wanted} - allowed:
+        errors.append(
+            f"{_KIND_LABELS[kind].capitalize()} cannot be attached to {channel} campaigns"
+            + (" (custom segments work on Display and Video)" if kind == "custom_audience" else "")
+            + (" (combined segments are Search-only)" if kind == "combined_audience" else "")
+        )
+
+    lists = get_audience_lists(config, customer_id=customer_id)
+    known = {
+        "user_list": {u["user_list_id"]: u for u in lists["user_lists"]},
+        "custom_audience": {c["custom_audience_id"]: c for c in lists["custom_segments"]},
+        "combined_audience": {c["combined_audience_id"]: c for c in lists["combined_segments"]},
+    }
+    _names(config, customer_id, wanted, lists)
+    warnings = []
+    for w in wanted:
+        if w["kind"] == "segment":
+            if not w["name"]:
+                errors.append(f"segment {w['audience_id']} was not found (see search_audience_segments)")
+            continue
+        info = known[w["kind"]].get(w["audience_id"])
+        if not info:
+            errors.append(f"{w['kind'].replace('_', ' ')} {w['audience_id']} is not an audience of this account (see get_audience_lists)")
+            continue
+        if w["kind"] == "user_list":
+            if channel == "SEARCH" and info.get("eligible_for_search") is False:
+                errors.append(f"list '{info['name']}' is not eligible for Search")
+            elif channel == "SEARCH" and (info.get("size_for_search") or 0) < _SEARCH_MIN_SIZE:
+                size = info.get("size_for_search") or 0
+                if mode == "targeting" and not exclude:
+                    errors.append(
+                        f"list '{info['name']}' has {size:,} Search users; with targeting the ads would not serve "
+                        f"until it reaches {_SEARCH_MIN_SIZE:,}. Use observation, or wait for the list to grow."
+                    )
+                else:
+                    warnings.append(f"list '{info['name']}' has {size:,} Search users; it takes effect from {_SEARCH_MIN_SIZE:,}")
+            if info.get("membership_status") == "CLOSED":
+                warnings.append(f"list '{info['name']}' is closed: it no longer adds members")
+
+    # Google keeps audiences at one level per campaign.
+    if not exclude:
+        if ad_group_id and any(not c["negative"] for c in ctx["campaign_criteria"]):
+            errors.append("The campaign already has audiences; Google does not allow audiences at both campaign and ad group level. Attach at the campaign instead.")
+        if campaign_id and any(not c["negative"] for c in ctx["ad_group_criteria"]):
+            errors.append("Ad groups of this campaign already have audiences; Google does not allow both levels. Attach at those ad groups instead.")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    existing = ctx["ad_group_criteria"] if ad_group_id else ctx["campaign_criteria"]
+    present = {
+        (c["kind"], c["audience_id"], c["negative"])
+        for c in existing
+        if not ad_group_id or c["ad_group_id"] == ad_group_id
+    }
+    duplicates = [w for w in wanted if (w["kind"], w["audience_id"], exclude) in present]
+    for w in duplicates:
+        warnings.append(f"'{w['name'] or w['audience_id']}' is already attached; skipped")
+    wanted = [w for w in wanted if w not in duplicates]
+    if not wanted:
+        return {"error": "Nothing to attach: every audience is already there", "warnings": warnings}
+
+    set_mode = None
+    double_confirm = False
+    if not exclude and ctx["mode"] != mode:
+        set_mode = mode
+        others = [c for c in existing if not c["negative"] and (not ad_group_id or c["ad_group_id"] == ad_group_id)]
+        if mode == "targeting":
+            double_confirm = True
+            warnings.insert(0, (
+                "TARGETING narrows delivery: from now on the ads only reach people in the attached audiences"
+                + (" (including the ones already attached)" if others else "")
+                + ". Impressions and clicks usually drop sharply. Observation keeps the reach and only adjusts bids."
+            ))
+        elif ctx["mode"] == "targeting" and others:
+            warnings.insert(0, "Switches from targeting to observation: the audiences already attached stop restricting delivery, so reach grows.")
+    elif mode == "targeting" and not exclude:
+        warnings.insert(0, "The audience mode is already targeting: the ads only reach people in the attached audiences.")
+    if exclude:
+        warnings.append("Exclusions keep these people from seeing the ads; the audience mode is unchanged.")
+
+    plan = ChangePlan(
+        operation="add_audience_criteria",
+        entity_type="ad_group" if ad_group_id else "campaign",
+        entity_id=ad_group_id or campaign_id,
+        customer_id=customer_id,
+        requires_double_confirm=double_confirm,
+        changes={
+            "level": "ad_group" if ad_group_id else "campaign",
+            "campaign_id": ctx["campaign_id"],
+            "ad_group_id": ad_group_id or None,
+            "name": ctx["entity_name"],
+            "channel": channel,
+            "exclude": bool(exclude),
+            "audiences": [{"kind": w["kind"], "audience_id": w["audience_id"], "name": w["name"]} for w in wanted],
+            "audience_mode_before": ctx["mode"] or "not set",
+            "set_audience_mode": set_mode,
+            "target_restrictions": ctx["restrictions"],
+        },
+    )
+    store_plan(plan)
+    preview = plan.to_preview()
+    preview["warnings"] = warnings
+    return preview
+
+
+def apply_audience_criteria(client: object, cid: str, changes: dict) -> dict:
+    """One mutate: the audience mode (if it changes), then the criteria."""
+    service = client.get_service("GoogleAdsService")
+    at_ad_group = changes["level"] == "ad_group"
+    operations = []
+
+    if changes.get("set_audience_mode"):
+        op = client.get_type("MutateOperation")
+        if at_ad_group:
+            entity = op.ad_group_operation.update
+            entity.resource_name = service.ad_group_path(cid, changes["ad_group_id"])
+            mask = op.ad_group_operation.update_mask
+        else:
+            entity = op.campaign_operation.update
+            entity.resource_name = service.campaign_path(cid, changes["campaign_id"])
+            mask = op.campaign_operation.update_mask
+        dimension = client.enums.TargetingDimensionEnum
+        # The mask replaces the whole list: keep the other dimensions as they are.
+        for existing in changes.get("target_restrictions") or []:
+            if existing.get("targeting_dimension") == "AUDIENCE":
+                continue
+            kept = client.get_type("TargetRestriction")
+            kept.targeting_dimension = getattr(dimension, existing["targeting_dimension"])
+            kept.bid_only = bool(existing.get("bid_only"))
+            entity.targeting_setting.target_restrictions.append(kept)
+        audience = client.get_type("TargetRestriction")
+        audience.targeting_dimension = dimension.AUDIENCE
+        audience.bid_only = changes["set_audience_mode"] == "observation"
+        entity.targeting_setting.target_restrictions.append(audience)
+        mask.paths.append("targeting_setting.target_restrictions")
+        operations.append(op)
+
+    for entry in changes["audiences"]:
+        _type, field, collection = _KINDS[entry["kind"]]
+        op = client.get_type("MutateOperation")
+        if at_ad_group:
+            criterion = op.ad_group_criterion_operation.create
+            criterion.ad_group = service.ad_group_path(cid, changes["ad_group_id"])
+        else:
+            criterion = op.campaign_criterion_operation.create
+            criterion.campaign = service.campaign_path(cid, changes["campaign_id"])
+        message, attribute = field.split(".")
+        setattr(getattr(criterion, message), attribute, f"customers/{cid}/{collection}/{entry['audience_id']}")
+        if changes.get("exclude"):
+            criterion.negative = True
+        operations.append(op)
+
+    service.mutate(customer_id=cid, mutate_operations=operations)
+    return {
+        "level": changes["level"],
+        "entity_id": changes.get("ad_group_id") or changes["campaign_id"],
+        "audiences_attached": len(changes["audiences"]),
+        "excluded": bool(changes.get("exclude")),
+        "audience_mode": changes.get("set_audience_mode") or changes.get("audience_mode_before"),
+    }

{adloop-0.28.0 → adloop-0.29.0}/src/adloop/ads/write.py

@@ -3976,6 +3976,7 @@ def _dispatch_ads_plan(client: object, cid: str, plan: object) -> dict:
         _apply_upload_call_conversions,
         _apply_upload_enhanced_conversions_for_leads,
     )
+    from adloop.ads.audiences import apply_audience_criteria as _apply_audience_criteria
     from adloop.ads.shopping import apply_create_shopping_campaign as _apply_create_shopping_campaign
     from adloop.ads.pmax import apply_asset_group_assets as _apply_asset_group_assets
     from adloop.ads.pmax import apply_asset_group_signals as _apply_asset_group_signals
@@ -4007,6 +4008,7 @@ def _dispatch_ads_plan(client: object, cid: str, plan: object) -> dict:
         "attach_shared_set_to_campaigns": _apply_attach_shared_set_to_campaigns,
         "detach_shared_set_from_campaigns": _apply_detach_shared_set_from_campaigns,
         "add_demographic_criteria": _apply_add_demographic_criteria,
+        "add_audience_criteria": _apply_audience_criteria,
         "create_brand_list": _apply_create_brand_list,
         "add_to_brand_list": _apply_add_to_brand_list,
         "remove_from_brand_list": _apply_remove_from_brand_list,

{adloop-0.28.0 → adloop-0.29.0}/src/adloop/rules/adloop.md

@@ -60,6 +60,9 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 | `get_audience_performance` | Audience segment metrics — remarketing, in-market, affinity, demographics | `date_range_start`, `date_range_end`, `campaign_id` (optional) |
 | `get_change_history` | What changed in the account and who changed it: time, user email, client (UI, API, scripts, Editor, auto-applied recommendations), resource type, operation, changed fields, campaign/ad group. The first stop for "what changed before the drop?" (30 days of history) | `date_range_start`, `date_range_end`, `campaign_id` (optional), `resource_types` (optional), `limit` (optional, max 10000) |
 | `get_demographic_targeting` | List current demographic criteria (age/gender/parental status/income) on an ad group or campaign — returns each criterion's `remove_id` for use with `remove_entity` | exactly one of `ad_group_id` or `campaign_id` |
+| `get_audience_lists` | The account's own audiences: remarketing and customer lists (type, OPEN/CLOSED, size for Search and Display, eligibility), custom segments, combined segments | (none) |
+| `search_audience_segments` | Find Google's in-market and affinity segments by name (case-insensitive, English names) and get the `segment_id` to attach | `query`, `kind` (in_market/affinity/all), `limit` |
+| `get_audience_targeting` | Audiences and audience exclusions attached to one campaign or ad group, the audience mode (observation/targeting/not set), and each one's `remove_id` | exactly one of `campaign_id` or `ad_group_id` |
 | `suggest_brands` | Resolve one brand name to the brands Google recognizes — brand ID, name, state, URLs. The ID is what brand criteria target, so resolve here before building any brand list | `brand_prefix` (required), `selected_brand_ids` (optional, IDs already picked) |
 | `check_brand_names` | Triage a shortlist of brand names at once: matched vs. unknown, plus each brand's ID | `brand_names` (required, max 25 per call) |
 | `get_brand_lists` | List brand lists (SharedSets of type BRANDS) before creating a new one — reuse beats duplication | (none) |
@@ -79,6 +82,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 - PMax tools: `get_pmax_performance` returns `insights[]` flagging weak ad strength and zero-conversion asset groups. `segments.ad_network_type` includes MIXED — a Google catch-all for most PMax traffic. Full channel splits (Search vs YouTube vs Display vs Discover) are not available via the API.
 - `get_pmax_assets` returns `by_status` and `by_field_type` summaries. Note: per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. Use `get_detailed_asset_performance` for quality signals via top combinations.
 - `get_audience_performance` works for campaigns with explicit audience targeting. PMax audience targeting is automatic and may not appear in this report. When the results include SEARCH campaigns, `insights[]` reminds you that custom segments cannot be attached to them (see the compatibility matrix below) — relay that constraint instead of proposing impossible pairings.
+- `get_audience_lists` flags lists below 1,000 users (Search ignores them until they grow) and closed lists. `get_audience_targeting`'s `audience_mode` is the entity's AUDIENCE setting: `observation` means the audiences only adjust bids and report, `targeting` means the ads only reach them, `not set` means none was written yet.
 - `get_demographic_targeting` returns an empty list when no demographics have been excluded or narrowed — that is the DEFAULT state (Google serves to all segments). Each criterion includes a composite `remove_id` (`adGroupId~criterionId` or `campaignId~criterionId`) that can be passed straight to `remove_entity`.
 - **Compact mode for audits**: `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`, returning account totals, breakdowns, the top-10 rows, and pre-computed offender lists (zero-conversion spenders, budget-limited converters, low-QS keywords, negative-keyword waste candidates, thin RSAs, single-ad ad groups, disapproved or limited ads) instead of every row; compact `get_ad_performance` keeps `final_urls` on its rows and adds `landing_pages` (every final URL across all ads with its ad count), so landing-page checks need no extra GAQL — roughly 90% smaller. Use it for account audits and overviews so raw tables don't flood the context; use the default full mode when you need a specific entity's exact rows before drafting a change. In harnesses with subagents, heavy multi-tool audits can additionally be delegated to a subagent that returns only the summary.
 
@@ -285,6 +289,7 @@ For images that have no public URL: a file on the user's computer, or an image t
 | `attach_shared_set_to_campaigns` | Attach an EXISTING shared set (e.g. shared negative keyword list) to one or more campaigns. Use after creating a campaign to inherit pre-built negatives. | `shared_set_id` (from `get_negative_keyword_lists`), `campaign_ids` list |
 | `detach_shared_set_from_campaigns` | Detach a shared set from one or more campaigns. Removes only the linkage; the shared set and its keywords stay intact. | `shared_set_id`, `campaign_ids` list |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income range) at ad group or campaign level. Defaults to EXCLUSION (`negative=True`). | exactly one of `ad_group_id` or `campaign_id`, at least one of `age_ranges`/`genders`/`parental_statuses`/`income_ranges`, optional `negative` (default True) |
+| `draft_audience_attachment` | Attach audiences to a campaign or ad group as OBSERVATION (default: bids and reporting, reach unchanged), TARGETING (ads only reach the audiences; double confirmation) or exclusion. Refuses incompatible pairings, Search lists too small to target, audiences at both campaign and ad group level, and Performance Max | exactly one of `campaign_id` or `ad_group_id`; any of `user_list_ids`, `segment_ids`, `custom_audience_ids`, `combined_audience_ids`; `mode` observation/targeting; `exclude` |
 | `draft_ai_max_settings` | Draft AI Max controls for one Search campaign: `enable_ai_max`, per-ad-group `disable_search_term_matching`, text and final-URL asset automation. Refuses a plan that would switch AI Max on while an automation it was never told about keeps running; an explicitly requested automation asks for a double confirmation. | `campaign_id`, optional `enable_ai_max`, optional `disable_search_term_matching`, optional `ad_group_ids`, optional `include_paused_ad_groups`, optional `text_asset_automation`, optional `final_url_expansion` |
 | `draft_prepare_brand_exclusions` | Draft the whole safe state for a brand exclusion in one step: AI Max on, search term matching off on every non-removed ad group, text and final-URL automation opted out. Touches nothing else. | `campaign_id`, optional `include_paused_ad_groups` |
 | `pause_entity` | Propose pausing campaign/ad group/ad/keyword/asset group | `entity_type` (incl. `asset_group` for PMax), `entity_id` |
@@ -331,7 +336,7 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
 - Ad-group pause/enable is already handled by `pause_entity` / `enable_entity` with `entity_type="ad_group"`; do not invent a separate pause tool.
 - `update_campaign` replaces POSITIVE geo/language targets entirely (not append). Pass the full desired list. NEGATIVE geo exclusions (criteria with `negative=TRUE`) are **preserved** across a positive-geo replacement — they survive the swap. The preview surfaces preserved negative geo IDs in `preserved_negative_geo_target_ids` so the change is auditable. To ADD negative geo exclusions (e.g. exclude a city inside a targeted state), use `add_negative_locations` — do not try to express exclusions through `geo_target_ids`. To remove a negative geo exclusion explicitly, use `remove_entity` with `entity_type="campaign_criterion"`.
 - `remove_entity` is IRREVERSIBLE — always prefer `pause_entity` unless the user explicitly wants permanent removal. Removal triggers double confirmation in the safety layer.
-- `remove_entity` supports `entity_type` values: "campaign", "ad_group", "ad", "keyword", "negative_keyword", "shared_criterion", "ad_group_criterion", "campaign_criterion", "campaign_asset", "asset", "customer_asset". Use "negative_keyword" to remove campaign-level negative keywords. Use "shared_criterion" to remove a keyword from a shared negative keyword list — the `entity_id` format is "sharedSetId~criterionId" (use the `resource_id` field from `get_negative_keyword_list_keywords`). Use "ad_group_criterion" or "campaign_criterion" to remove demographic targeting (age/gender/parental/income) — pass the `remove_id` returned by `get_demographic_targeting`. Use "campaign_asset" to remove sitelinks and other asset links from a campaign. Use "asset" to remove a standalone asset. Use "customer_asset" to remove a customer-level asset link.
+- `remove_entity` supports `entity_type` values: "campaign", "ad_group", "ad", "keyword", "negative_keyword", "shared_criterion", "ad_group_criterion", "campaign_criterion", "campaign_asset", "asset", "customer_asset". Use "negative_keyword" to remove campaign-level negative keywords. Use "shared_criterion" to remove a keyword from a shared negative keyword list — the `entity_id` format is "sharedSetId~criterionId" (use the `resource_id` field from `get_negative_keyword_list_keywords`). Use "ad_group_criterion" or "campaign_criterion" to remove demographic targeting (age/gender/parental/income) or an attached audience or audience exclusion — pass the `remove_id` returned by `get_demographic_targeting` or `get_audience_targeting`. Use "campaign_asset" to remove sitelinks and other asset links from a campaign. Use "asset" to remove a standalone asset. Use "customer_asset" to remove a customer-level asset link.
 - A Google Ads `dry_run=true` sends the exact change to Google with `validate_only` — Google checks it and executes nothing. `DRY_RUN_FAILED` carries Google's error and means the real apply would fail the same way; fix the cause and draft again. Steps that build on an object an earlier step would create (e.g. keywords for a new negative list) are counted in `checks.skipped_calls` instead of validated.
 - `max_bid_increase_pct` (default 100) applies to Google Ads bid raises too: `update_ad_group` max_cpc on MANUAL_CPC and `update_campaign` max_cpc on an existing Maximize Clicks ceiling. A first-time ceiling has no baseline and is not capped.
 - New Google Ads ad groups are created enabled; they cannot serve until one of their ads (created PAUSED) is enabled.
@@ -640,6 +645,17 @@ Reddit's structure is campaign → ad group (budget, bid, pixel, targeting) →
 
 - **Custom segments cannot be attached to Search campaigns.** A GAQL join of `custom_audience` against Search campaigns will always come back empty — that is expected, not missing data. Don't propose custom segments for Search; suggest in-market/affinity or remarketing lists instead.
 - **PMax never takes hard audience targeting.** Every audience there is an asset-group-level signal — a hint to the algorithm, not a filter.
+- Shopping campaigns take remarketing lists and in-market/affinity segments.
+
+### When user wants to add, observe or exclude an audience ("add my remarketing list", "bid up for in-market software buyers", "exclude converters")
+
+1. Find the audience: the account's own lists and segments with `get_audience_lists`; Google's in-market and affinity segments with `search_audience_segments` (English names: "software", not "Software-Käufer").
+2. Check the campaign or ad group with `get_audience_targeting`: what is attached, and the current audience mode. Audiences live at one level per campaign: if the campaign has audiences, attach at the campaign; if its ad groups have them, attach there.
+3. Default to **observation**. It keeps the reach and lets the audience adjust bids and show in reports, which is what "add an audience" almost always means. Only use `mode="targeting"` when the user explicitly wants to restrict who sees the ads, and say clearly that impressions and clicks will drop. The draft needs a double confirmation then.
+4. Exclusions (`exclude=True`) are the safe way to keep people out, e.g. a list of recent buyers on a prospecting campaign. They don't change the mode.
+5. Call `draft_audience_attachment`, show the preview with its warnings (mode changes, small lists), wait for approval, then `confirm_and_apply`.
+6. To remove one, use `remove_entity` with the `remove_id` from `get_audience_targeting` (`entity_type` "campaign_criterion" or "ad_group_criterion").
+7. Creating audiences (building remarketing lists or custom segments) is not supported; that happens in the Google Ads interface. Performance Max takes audiences as asset group signals (`draft_asset_group_signals`).
 
 ### When user asks to exclude or include demographics ("exclude ages 25-34", "exclude women", "only show to parents")
 
@@ -659,7 +675,7 @@ Reddit's structure is campaign → ad group (budget, bid, pixel, targeting) →
 8. **To remove an existing demographic exclusion**, call `get_demographic_targeting` to find the criterion's `remove_id`, then use `remove_entity` with `entity_type="ad_group_criterion"` or `entity_type="campaign_criterion"`.
 
 **Common pitfalls:**
-- "Audiences" and "demographics" mean different things in Google Ads. Audiences are user lists (remarketing, in-market, affinity) — use `get_audience_performance` and audience-targeting tools. Demographics are age/gender/parental/income — use `get_demographic_targeting` and `draft_demographic_targeting`. If the user says "exclude audiences" but describes ages, they mean demographics.
+- "Audiences" and "demographics" mean different things in Google Ads. Audiences are user lists (remarketing, in-market, affinity) — use `get_audience_lists`, `get_audience_targeting`, `draft_audience_attachment` and `get_audience_performance`. Demographics are age/gender/parental/income — use `get_demographic_targeting` and `draft_demographic_targeting`. If the user says "exclude audiences" but describes ages, they mean demographics.
 - Excluding many segments within a single dimension drastically reduces reach. The tool will warn when you exclude nearly all values in one dimension.
 - **Excluding UNDETERMINED is almost never what the user wants.** Google cannot classify a large share of users (often 30%+, more under EU consent restrictions); excluding UNDETERMINED blocks all of them, far beyond the named segment. The tool warns — surface that warning prominently and confirm intent before applying.
 - Campaign-level demographic criteria can only be EXCLUSIONS. Positive (narrowing) demographic targeting must go on an ad group — the tool rejects `campaign_id` + `negative=False`.

{adloop-0.28.0 → adloop-0.29.0}/src/adloop/server.py

@@ -2668,6 +2668,131 @@ def run_gaql(
 # ---------------------------------------------------------------------------
 
 
+@_tool(title="Audience lists", annotations=_READONLY, tags={"ads"})
+@_safe
+def get_audience_lists(customer_id: str = "") -> dict:
+    """The account's own audiences: remarketing and customer lists, custom segments, combined segments.
+
+    Each user list comes with its type, membership status (OPEN or CLOSED),
+    size for Search and Display, eligibility and membership duration;
+    custom and combined segments with their id and description. Insights
+    flag lists below the 1,000 users Search needs and closed lists. Use the
+    ids with draft_audience_attachment; for Google's in-market and affinity
+    segments use search_audience_segments.
+
+    Args:
+        customer_id: Google Ads customer ID (digits, dashes optional).
+            Defaults to the configured account.
+    """
+    from adloop.ads.audiences import get_audience_lists as _impl
+
+    return _impl(current_config(), customer_id=customer_id or current_config().ads.customer_id)
+
+
+@_tool(title="Search audience segments", annotations=_READONLY, tags={"ads"})
+@_safe
+def search_audience_segments(query: str, kind: str = "all", limit: int = 25, customer_id: str = "") -> dict:
+    """Find Google's in-market and affinity segments by name, with the segment_id to attach.
+
+    In-market segments are people actively researching a purchase; affinity
+    segments are long-term interests. Matching is on the segment name, in
+    English, e.g. "running", "insurance", "travel".
+
+    Args:
+        query: Part of the segment name to look for (at least 2 characters).
+        kind: "in_market", "affinity" or "all" (default).
+        limit: Maximum number of segments to return (1-100, default 25).
+        customer_id: Google Ads customer ID (digits, dashes optional).
+            Defaults to the configured account.
+    """
+    from adloop.ads.audiences import search_audience_segments as _impl
+
+    return _impl(current_config(), customer_id=customer_id or current_config().ads.customer_id, query=query, kind=kind, limit=limit)
+
+
+@_tool(title="Audience targeting", annotations=_READONLY, tags={"ads"})
+@_safe
+def get_audience_targeting(campaign_id: str = "", ad_group_id: str = "", customer_id: str = "") -> dict:
+    """Audiences attached to one campaign or ad group, its exclusions, and the audience mode.
+
+    audience_mode is "observation" (audiences only adjust bids and report),
+    "targeting" (ads only reach the audiences) or "not set". Every audience
+    and exclusion carries a remove_id for remove_entity (entity_type
+    "campaign_criterion" or "ad_group_criterion").
+
+    Args:
+        campaign_id: Numeric campaign id. Pass this or ad_group_id.
+        ad_group_id: Numeric ad group id. Pass this or campaign_id.
+        customer_id: Google Ads customer ID (digits, dashes optional).
+            Defaults to the configured account.
+    """
+    from adloop.ads.audiences import get_audience_targeting as _impl
+
+    return _impl(
+        current_config(),
+        customer_id=customer_id or current_config().ads.customer_id,
+        campaign_id=campaign_id,
+        ad_group_id=ad_group_id,
+    )
+
+
+@_tool(title="Draft audience attachment", annotations=_WRITE, tags={"ads"})
+@_safe
+def draft_audience_attachment(
+    campaign_id: str = "",
+    ad_group_id: str = "",
+    user_list_ids: _StrList = [],  # noqa: B006
+    segment_ids: _StrList = [],  # noqa: B006
+    custom_audience_ids: _StrList = [],  # noqa: B006
+    combined_audience_ids: _StrList = [],  # noqa: B006
+    mode: str = "observation",
+    exclude: bool = False,
+    customer_id: str = "",
+) -> dict:
+    """Draft attaching audiences to a campaign or ad group as observation, targeting or exclusion: returns a PREVIEW.
+
+    Observation (the default) keeps the reach: the audiences adjust bids and
+    show up in reports. Targeting narrows delivery to the audiences and needs
+    a double confirmation. Exclusions keep the people out and leave the mode
+    alone. The draft refuses combinations Google does not allow (custom
+    segments on Search, combined segments outside Search, audiences at both
+    campaign and ad group level) and lists that cannot serve; Performance Max
+    is refused with a pointer to draft_asset_group_signals. Nothing changes
+    until confirm_and_apply applies the plan_id; a dry run has Google
+    validate it.
+
+    Args:
+        campaign_id: Numeric campaign id. Pass this or ad_group_id.
+        ad_group_id: Numeric ad group id. Pass this or campaign_id.
+        user_list_ids: Remarketing or customer lists (user_list_id from
+            get_audience_lists).
+        segment_ids: In-market or affinity segments (segment_id from
+            search_audience_segments).
+        custom_audience_ids: Custom segments (custom_audience_id from
+            get_audience_lists); Display and Video only.
+        combined_audience_ids: Combined segments (combined_audience_id from
+            get_audience_lists); Search only.
+        mode: "observation" (default) or "targeting". Ignored for exclusions.
+        exclude: True to exclude the audiences instead of adding them.
+        customer_id: Google Ads customer ID (digits, dashes optional).
+            Defaults to the configured account.
+    """
+    from adloop.ads.audiences import draft_audience_attachment as _impl
+
+    return _impl(
+        current_config(),
+        customer_id=customer_id or current_config().ads.customer_id,
+        campaign_id=campaign_id,
+        ad_group_id=ad_group_id,
+        user_list_ids=user_list_ids,
+        segment_ids=segment_ids,
+        custom_audience_ids=custom_audience_ids,
+        combined_audience_ids=combined_audience_ids,
+        mode=mode,
+        exclude=exclude,
+    )
+
+
 @_tool(title="Asset group signals", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_asset_group_signals(asset_group_id: str, customer_id: str = "") -> dict: