adloop 0.15.0__tar.gz → 0.16.0__tar.gz

{adloop-0.15.0 → adloop-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.15.0
+Version: 0.16.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.15.0 → adloop-0.16.0}/pyproject.toml

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

{adloop-0.15.0 → adloop-0.16.0}/pyproject.toml.orig

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

{adloop-0.15.0 → adloop-0.16.0}/src/adloop/ads/conversion_actions.py

@@ -430,6 +430,7 @@ def draft_remove_conversion_action(
         entity_id=str(conversion_action_id),
         customer_id=customer_id,
         changes={"conversion_action_id": str(conversion_action_id)},
+        requires_double_confirm=True,
     )
     store_plan(plan)
     preview = plan.to_preview()

adloop-0.16.0/src/adloop/ads/validate_only.py

@@ -0,0 +1,115 @@
+"""Run a Google Ads plan in validate-only mode for ``confirm_and_apply`` dry runs.
+
+The dry run used to echo the plan back without asking Google anything, so a
+change the API would reject only failed at the real apply. Wrapping the Ads
+client here sends every mutate the plan would send with ``validate_only=True``
+instead: Google checks the full request (field values, policy, references to
+existing entities) and executes nothing.
+
+Validate-only responses carry no results, so each validated call answers the
+apply code with placeholder resource names. A later call that references one
+(a plan whose second step uses what the first would have created) cannot be
+validated meaningfully; it is skipped and counted instead of sent.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+PLACEHOLDER = "adloop-validate-only"
+
+_RESPONSE_FIELD_FOR_SERVICE = "campaign_result"
+
+
+class ValidateOnlyFailure(Exception):
+    """Google rejected part of a validate-only request (partial failure)."""
+
+
+class ValidateOnlyClient:
+    """A GoogleAdsClient stand-in whose services only ever validate.
+
+    Everything except ``get_service`` passes through (enums, ``get_type``),
+    and every service method except ``mutate*`` passes through too, so the
+    reads some apply paths do before mutating still run normally.
+    """
+
+    def __init__(self, client: object) -> None:
+        self._client = client
+        self.validated_calls = 0
+        self.skipped_calls = 0
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(self._client, name)
+
+    def get_service(self, name: str, *args: object, **kwargs: object) -> object:
+        return _ValidateOnlyService(self, name, self._client.get_service(name, *args, **kwargs))
+
+
+class _ValidateOnlyService:
+    def __init__(self, owner: ValidateOnlyClient, name: str, service: object) -> None:
+        self._owner = owner
+        self._name = name
+        self._service = service
+
+    def __getattr__(self, attr: str) -> object:
+        target = getattr(self._service, attr)
+        if not attr.startswith("mutate"):
+            return target
+
+        def validate(request: object = None, **kwargs: object) -> object:
+            if request is None:
+                request = self._build_request(attr, kwargs)
+            request.validate_only = True
+
+            operations = list(_operations_of(request))
+            if PLACEHOLDER in str(request):
+                self._owner.skipped_calls += 1
+            else:
+                response = target(request=request)
+                self._owner.validated_calls += 1
+                failure = getattr(response, "partial_failure_error", None)
+                if failure is not None and getattr(failure, "code", 0):
+                    raise ValidateOnlyFailure(getattr(failure, "message", "") or str(failure))
+
+            return _placeholder_response(request.customer_id, len(operations), attr == "mutate")
+
+        return validate
+
+    def _build_request(self, method: str, kwargs: dict) -> object:
+        request = self._owner._client.get_type(_request_type(self._name, method))
+        for key, value in kwargs.items():
+            if key in ("operations", "mutate_operations"):
+                getattr(request, key).extend(value)
+            else:
+                setattr(request, key, value)
+        return request
+
+
+def _request_type(service_name: str, method: str) -> str:
+    """``mutate_ad_group_criteria`` -> ``MutateAdGroupCriteriaRequest``."""
+    if method == "mutate":
+        return "Mutate" + service_name.removesuffix("Service") + "Request"
+    words = method.removeprefix("mutate_").split("_")
+    return "Mutate" + "".join(word.capitalize() for word in words) + "Request"
+
+
+def _operations_of(request: object) -> object:
+    if hasattr(request, "mutate_operations"):
+        return request.mutate_operations
+    return getattr(request, "operations", [])
+
+
+def _placeholder_response(customer_id: str, count: int, googleads_mutate: bool) -> object:
+    names = [f"customers/{customer_id}/{PLACEHOLDER}/{i}" for i in range(count)]
+    if googleads_mutate:
+        return SimpleNamespace(
+            mutate_operation_responses=[
+                SimpleNamespace(**{_RESPONSE_FIELD_FOR_SERVICE: SimpleNamespace(resource_name=n)})
+                for n in names
+            ],
+            partial_failure_error=None,
+        )
+    return SimpleNamespace(
+        results=[SimpleNamespace(resource_name=n) for n in names],
+        partial_failure_error=None,
+    )

{adloop-0.15.0 → adloop-0.16.0}/src/adloop/ads/write.py

@@ -669,8 +669,13 @@ def update_responsive_search_ad(
     if errors:
         return {"error": "Validation failed", "details": errors}
 
+    url_warnings_found: list[str] = []
     if has_url_change:
-        url_check = _validate_urls([final_url])
+        # _validate_urls returns (errors, warnings) — the same contract the
+        # create path and the sitelink path already unpack. Treating the tuple
+        # as a dict made every URL-only update fail with
+        # "'tuple' object has no attribute 'get'" before a plan existed.
+        url_check, url_warnings = _validate_urls([final_url])
         if url_check.get(final_url):
             return {
                 "error": "URL validation failed",
@@ -679,6 +684,10 @@ def update_responsive_search_ad(
                     f"{url_check[final_url]}. Ads MUST point to working URLs."
                 ],
             }
+        if url_warnings.get(final_url):
+            url_warnings_found.append(
+                f"final_url '{final_url}': {url_warnings[final_url]}"
+            )
 
     changes: dict = {"ad_id": str(ad_id)}
     if has_url_change:
@@ -703,8 +712,10 @@ def update_responsive_search_ad(
     preview = plan.to_preview()
     # Only warn when the creative text is actually being replaced — URL/path
     # edits do not trigger the learning reset or policy re-review.
+    if url_warnings_found:
+        preview.setdefault("warnings", []).extend(url_warnings_found)
     if has_headlines_change or has_descriptions_change:
-        preview["warnings"] = [_RSA_TEXT_UPDATE_WARNING]
+        preview.setdefault("warnings", []).append(_RSA_TEXT_UPDATE_WARNING)
     return preview
 
 
@@ -1232,7 +1243,11 @@ def update_ad_group(
     max_cpc: float = 0,
 ) -> dict:
     """Draft an ad group update for name and manual CPC bid."""
-    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.guards import (
+        SafetyViolation,
+        check_bid_increase,
+        check_blocked_operation,
+    )
     from adloop.safety.preview import ChangePlan, store_plan
 
     try:
@@ -1276,6 +1291,12 @@ def update_ad_group(
                     f"target governs spend under automated bidding. "
                     f"No change made."
                 )
+        else:
+            current_bid = _current_ad_group_cpc_bid(config, customer_id, ad_group_id)
+            try:
+                check_bid_increase(current_bid or 0, max_cpc, config.safety)
+            except SafetyViolation as e:
+                errors.append(str(e))
 
     has_any_change = bool(ad_group_name.strip() or max_cpc)
     if not has_any_change:
@@ -1384,6 +1405,9 @@ def remove_entity(
         entity_id=entity_id,
         customer_id=customer_id,
         changes={"action": "REMOVE"},
+        # Removal is irreversible; the preview asks for a second explicit
+        # confirmation, as Reddit removals already did.
+        requires_double_confirm=True,
     )
     store_plan(plan)
     return plan.to_preview()
@@ -1574,6 +1598,7 @@ def update_campaign(
     """
     from adloop.safety.guards import (
         SafetyViolation,
+        check_bid_increase,
         check_blocked_operation,
         check_budget_cap,
     )
@@ -1628,6 +1653,14 @@ def update_campaign(
             errors.append("campaign_id was not found")
         elif strategy_for_cap != "TARGET_SPEND":
             errors.append("max_cpc requires TARGET_SPEND bidding_strategy")
+        else:
+            # Only a ceiling that already exists has a baseline; a campaign
+            # switching to Maximize Clicks has none to compare against.
+            current_ceiling = _current_campaign_cpc_ceiling(config, customer_id, campaign_id)
+            try:
+                check_bid_increase(current_ceiling or 0, max_cpc, config.safety)
+            except SafetyViolation as e:
+                errors.append(str(e))
 
     has_any_change = any([
         bs,
@@ -1957,14 +1990,23 @@ def _extract_error_message(exc: Exception) -> str:
         if isinstance(exc, GoogleAdsException) and exc.failure:
             parts = []
             for error in exc.failure.errors:
-                error_code = error.error_code
-                code_field = error_code.WhichOneof("error_code")
-                code_value = getattr(error_code, code_field) if code_field else "UNKNOWN"
-                line = f"[{code_field}={code_value.name if hasattr(code_value, 'name') else code_value}]"
-                if error.message:
-                    line += f" {error.message}"
-                if error.trigger and error.trigger.string_value:
-                    line += f" (trigger: {error.trigger.string_value})"
+                # The client returns proto-plus messages, on which WhichOneof
+                # does not exist; read the underlying protobuf instead.
+                pb = type(error).pb(error) if hasattr(type(error), "pb") else error
+                code_field = pb.error_code.WhichOneof("error_code")
+                code_name = "UNKNOWN"
+                if code_field:
+                    number = getattr(pb.error_code, code_field)
+                    enum = pb.error_code.DESCRIPTOR.fields_by_name[code_field].enum_type
+                    value = enum.values_by_number.get(number)
+                    code_name = value.name if value else str(number)
+                line = f"[{code_field}={code_name}]"
+                if pb.message:
+                    line += f" {pb.message}"
+                if pb.HasField("trigger"):
+                    kind = pb.trigger.WhichOneof("value")
+                    if kind:
+                        line += f" (trigger: {getattr(pb.trigger, kind)})"
                 parts.append(line)
             if parts:
                 msg = "; ".join(parts)
@@ -2008,39 +2050,49 @@ def confirm_and_apply(
 
     if dry_run:
         preflight_checks: dict | None = None
-        if is_reddit:
-            # Reddit has no validate-only mode; the dry run re-reads the
-            # target and re-runs the safety caps against live values. A
-            # failed preflight leaves dry_run_result unset so two-phase
-            # apply keeps refusing the real write.
-            from adloop.reddit.write import preflight
+        validation: dict | None = None
+        # Either way a failed check leaves dry_run_result unset, so two-phase
+        # apply keeps refusing the real write.
+        try:
+            if is_reddit:
+                # Reddit has no validate-only mode; the dry run re-reads the
+                # target and re-runs the safety caps against live values.
+                from adloop.reddit.write import preflight
 
-            try:
                 preflight_checks = preflight(config, plan)
-            except Exception as e:
-                error_message = _extract_error_message(e)
-                log_mutation(
-                    config.safety.log_file,
-                    operation=plan.operation,
-                    customer_id=plan.customer_id,
-                    entity_type=plan.entity_type,
-                    entity_id=plan.entity_id,
-                    changes=plan.changes,
-                    dry_run=True,
-                    result="dry_run_failed",
-                    error=error_message,
-                )
-                return {
-                    "status": "DRY_RUN_FAILED",
-                    "plan_id": plan.plan_id,
-                    "operation": plan.operation,
-                    "error": error_message,
-                    "message": (
-                        "The dry run re-checked the target against Reddit and "
-                        "found a problem; nothing was sent. Fix the cause and "
-                        "draft again."
-                    ),
-                }
+            elif plan.operation != "create_key_event":
+                # Google Ads checks the exact mutates with validate_only=True
+                # and executes nothing.
+                validation = _validate_with_google(config, plan)
+        except Exception as e:
+            error_message = _extract_error_message(e)
+            log_mutation(
+                config.safety.log_file,
+                operation=plan.operation,
+                customer_id=plan.customer_id,
+                entity_type=plan.entity_type,
+                entity_id=plan.entity_id,
+                changes=plan.changes,
+                dry_run=True,
+                result="dry_run_failed",
+                error=error_message,
+            )
+            checked_against = (
+                "re-checked the target against Reddit"
+                if is_reddit
+                else "sent the change to Google Ads in validate-only mode"
+            )
+            return {
+                "status": "DRY_RUN_FAILED",
+                "plan_id": plan.plan_id,
+                "operation": plan.operation,
+                "error": error_message,
+                "message": (
+                    f"The dry run {checked_against} and found a problem; "
+                    "nothing was changed. The real apply would fail the same "
+                    "way. Fix the cause and draft again."
+                ),
+            }
         log_mutation(
             config.safety.log_file,
             operation=plan.operation,
@@ -2074,6 +2126,18 @@ def confirm_and_apply(
                 "Reddit Ads has no validate-only mode: the dry run re-read the "
                 "target and re-checked the safety caps; nothing was sent."
             )
+        if validation is not None:
+            response["checks"] = validation
+            response["note"] = (
+                "Google Ads validated this exact change (validate_only) and "
+                "executed nothing."
+            )
+            if validation["skipped_calls"]:
+                response["note"] += (
+                    f" {validation['skipped_calls']} later step(s) build on "
+                    "objects an earlier step would create, so Google could "
+                    "only validate the step(s) before them."
+                )
         if forced_by_config:
             # The caller passed dry_run=false but safety.require_dry_run
             # forced it back on. Tell them exactly why and how to unlock
@@ -2257,6 +2321,38 @@ def _existing_negative_geo_exclusions(
     return ids
 
 
+def _current_ad_group_cpc_bid(
+    config: AdLoopConfig, customer_id: str, ad_group_id: str
+) -> float | None:
+    """The ad group's current manual CPC bid in account currency, or None."""
+    from adloop.ads.gaql import execute_query
+
+    rows = execute_query(config, customer_id, f"""
+        SELECT ad_group.cpc_bid_micros
+        FROM ad_group
+        WHERE ad_group.id = {ad_group_id}
+        LIMIT 1
+    """)
+    micros = rows[0].get("ad_group.cpc_bid_micros") if rows else None
+    return int(micros) / 1_000_000 if micros else None
+
+
+def _current_campaign_cpc_ceiling(
+    config: AdLoopConfig, customer_id: str, campaign_id: str
+) -> float | None:
+    """The campaign's current Maximize Clicks CPC ceiling, or None if unset."""
+    from adloop.ads.gaql import execute_query
+
+    rows = execute_query(config, customer_id, f"""
+        SELECT campaign.target_spend.cpc_bid_ceiling_micros
+        FROM campaign
+        WHERE campaign.id = {campaign_id}
+        LIMIT 1
+    """)
+    micros = rows[0].get("campaign.target_spend.cpc_bid_ceiling_micros") if rows else None
+    return int(micros) / 1_000_000 if micros else None
+
+
 def _ad_group_campaign_bidding_strategy(
     config: AdLoopConfig, customer_id: str, ad_group_id: str
 ) -> str | None:
@@ -2851,8 +2947,20 @@ def _extract_resource_name(resp: object) -> str:
     return ""
 
 
-def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
-    """Dispatch to the right API call based on plan.operation."""
+def _validate_with_google(config: AdLoopConfig, plan: object) -> dict:
+    """Send a Google Ads plan with validate_only=True; raises if Google rejects it."""
+    return _execute_plan(config, plan, validate_only=True)
+
+
+def _execute_plan(
+    config: AdLoopConfig, plan: object, *, validate_only: bool = False
+) -> dict:
+    """Dispatch to the right API call based on plan.operation.
+
+    With ``validate_only`` the plan's Google Ads mutates are sent with
+    ``validate_only=True`` (nothing executes) and the return value reports
+    how many calls Google validated; any rejection raises.
+    """
     from adloop.ads.client import get_ads_client, normalize_customer_id
 
     # Reddit plans have their own executors and never touch Google: the
@@ -2873,6 +2981,25 @@ def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
     client = get_ads_client(config)
     cid = normalize_customer_id(plan.customer_id)
 
+    if validate_only:
+        from adloop.ads.validate_only import ValidateOnlyClient
+
+        validator = ValidateOnlyClient(client)
+        result = _dispatch_ads_plan(validator, cid, plan)
+        # Multi-step applies catch their own errors and report them in the
+        # result instead of raising; in a dry run that is still a failure.
+        if isinstance(result, dict) and result.get("error"):
+            raise ValueError(result["error"])
+        return {
+            "validated_calls": validator.validated_calls,
+            "skipped_calls": validator.skipped_calls,
+        }
+
+    return _dispatch_ads_plan(client, cid, plan)
+
+
+def _dispatch_ads_plan(client: object, cid: str, plan: object) -> dict:
+    """Run a Google Ads plan against ``client`` (real or validate-only)."""
     # Conversion-action CRUD lives in its own module; import lazily so the
     # dispatch table (and this module) don't take the dependency at import time.
     from adloop.ads.conversion_actions import (

{adloop-0.15.0 → adloop-0.16.0}/src/adloop/rules/adloop.md

@@ -244,6 +244,9 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
 - `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.
+- 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.
 - `require_dry_run: true` in config overrides `dry_run=false` — the user must change the config to allow real mutations.
 - `two_phase_apply: true` in config (always on for AdLoop Cloud) refuses `dry_run=false` with status `DRY_RUN_REQUIRED` until that plan_id has completed one `dry_run=true` pass. Run the dry run, show the user, then apply — do not retry `dry_run=false` in a loop.
 - All operations (including dry runs) are logged to `~/.adloop/audit.log`.

{adloop-0.15.0 → adloop-0.16.0}/src/adloop/server.py

@@ -110,8 +110,13 @@ def _build_orchestration_instructions() -> str:
         "`dry_run=false` after the user explicitly approves the preview. "
         "`require_dry_run` in config can override this.\n"
         "- Respect the config's `max_daily_budget` cap.\n"
-        "- New campaigns, ad groups, RSAs and Reddit ads are created PAUSED. "
+        "- New Google Ads campaigns and RSAs, and every new Reddit campaign, "
+        "ad group and ad, are created PAUSED. A new Google Ads ad group is "
+        "enabled but cannot serve until one of its (paused) ads is enabled. "
         "The user must enable them after review.\n"
+        "- A Google Ads dry run sends the exact change to Google with "
+        "validate_only (nothing executes); DRY_RUN_FAILED means the real "
+        "apply would fail the same way.\n"
         "- One change at a time — don't batch unrelated writes.\n\n"
         "PRE-WRITE CHECKS (before any `draft_*`):\n"
         "- BROAD match keywords require Smart Bidding (MAXIMIZE_CONVERSIONS, "
@@ -2273,9 +2278,15 @@ def confirm_and_apply(
     DRY_RUN_REQUIRED until this plan_id has completed one dry_run=true
     pass. Run the dry run, show it to the user, then apply for real.
 
+    Google Ads plans: the dry run sends the exact mutates to Google with
+    validate_only=True, so Google checks the change and executes nothing
+    (`checks` counts the validated calls). Steps that build on an object an
+    earlier step would create cannot be validated and are counted as skipped.
+
     Reddit plans: Reddit has no validate-only mode, so the dry run re-reads
-    the target entity and re-checks the safety caps (returned as `checks`);
-    a DRY_RUN_FAILED result means the real apply would also fail.
+    the target entity and re-checks the safety caps (returned as `checks`).
+
+    Either way, a DRY_RUN_FAILED result means the real apply would also fail.
 
     The plan_id comes from a prior draft_* or pause/enable tool call.
     """