adloop 0.2.0__tar.gz → 0.4.0__tar.gz

{adloop-0.2.0 → adloop-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.2.0
-Summary: MCP server connecting Google Ads + GA4 + codebase into one AI-driven feedback loop
+Version: 0.4.0
+Summary: Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
 Author-email: Daniel Klose <info@daniel-klose.com>
@@ -66,7 +66,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 33 Tools
+## All 38 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
 
@@ -95,6 +95,11 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_keyword_performance` | Keywords — quality scores, competitive metrics |
 | `get_search_terms` | What users actually searched before clicking |
 | `get_negative_keywords` | List existing negative keywords for a campaign or all campaigns |
+| `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
+| `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
+| `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 |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
 ### Cross-Reference Tools (GA4 + Ads Combined)
@@ -204,28 +209,32 @@ uv sync
 uv run adloop init
 ```
 
-The `adloop init` wizard walks you through everything:
+The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
 
-1. **Google Cloud checklist** with clickable links to each setup page
-2. **Credentials** — prompts for your OAuth JSON path, validates the file exists
-3. **GA4 Property ID** — validates numeric format
-4. **Developer Token** — from your Google Ads MCC API Center
-5. **Customer IDs** — auto-formats `1234567890` → `123-456-7890`
-6. **Safety defaults** — budget cap and dry-run preference
-7. **OAuth authorization** — optionally opens your browser to complete auth immediately
-8. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+The wizard:
+
+1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
+2. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
+3. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
+4. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
+5. **Safety defaults** — budget cap and dry-run preference
+6. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
 ### Requirements
 
 - Python 3.11+
-- [uv](https://docs.astral.sh/uv/) for package management
-- A Google Cloud project (free tier works)
 - A Google Ads account with an MCC (Manager Account)
 
-### Manual Setup (If Not Using the Wizard)
+### Headless Servers
+
+Running on a server without a browser (VMs, Docker, SSH)? The wizard automatically detects this and falls back to a manual flow: it prints an authorization URL you can open on any device, then you paste the redirect URL back into the terminal.
+
+### Advanced Setup (Custom Google Cloud Project)
 
 <details>
-<summary>Click to expand manual setup steps</summary>
+<summary>Click to expand — only needed if you want to use your own GCP project instead of AdLoop's built-in credentials</summary>
+
+When you run `adloop init`, choose "No" when asked about built-in credentials. The wizard will guide you through:
 
 #### Step 1 — Google Cloud Project
 
@@ -242,8 +251,6 @@ The `adloop init` wizard walks you through everything:
 3. Select **Desktop app** as the application type, give it any name
 4. Download the JSON file and save it as `~/.adloop/credentials.json`
 
-On first run, AdLoop opens a browser window where you sign in with your Google account and grant access. The resulting token is saved to `~/.adloop/token.json` and refreshed automatically.
-
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
 #### Step 3 — Google Ads Developer Token
@@ -256,28 +263,7 @@ Access levels:
 - **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
 - **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
 
-#### Step 4 — Find Your IDs
-
-| ID | Where to Find It |
-|----|-------------------|
-| **GA4 Property ID** | GA4 → Admin → Property Settings (numeric, e.g. `123456789`) |
-| **Google Ads Customer ID** | Google Ads UI → top bar (e.g. `123-456-7890`) |
-| **MCC Account ID** | MCC UI → top bar (e.g. `123-456-7890`) |
-
-#### Step 5 — Install and Configure
-
-```bash
-git clone https://github.com/kLOsk/adloop.git
-cd adloop
-uv sync
-
-mkdir -p ~/.adloop
-cp config.yaml.example ~/.adloop/config.yaml
-```
-
-Edit `~/.adloop/config.yaml` and fill in the values from the previous steps. See [`config.yaml.example`](config.yaml.example) for a fully documented template.
-
-#### Step 6 — Connect to Your Editor
+#### Step 4 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 
@@ -336,12 +322,12 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
-| `google` | `project_id` | — | Your Google Cloud project ID |
-| `google` | `credentials_path` | `~/.adloop/credentials.json` | Path to OAuth client JSON or service account key |
+| `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
+| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
-| `ga4` | `property_id` | — | Your GA4 property ID (found in GA4 Admin → Property Settings) |
+| `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
-| `ads` | `customer_id` | — | Default Google Ads customer ID |
+| `ads` | `customer_id` | — | Default Google Ads customer ID (auto-discovered by `adloop init`) |
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
@@ -352,9 +338,9 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 26 tool registrations with safety annotations
+├── server.py          # FastMCP server — 38 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 Desktop flow + service account support + token refresh handling
+├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
 ├── cli.py             # Interactive 'adloop init' setup wizard
 ├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
@@ -365,7 +351,8 @@ src/adloop/
 ├── ads/
 │   ├── client.py      # Google Ads API client (version-pinned)
 │   ├── gaql.py        # GAQL query execution with human-readable error parsing
-│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword reads
+│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, recommendations, audience reads
+│   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
 │   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
 │   └── forecast.py    # Budget estimation via Keyword Planner API
 └── safety/
@@ -386,6 +373,8 @@ What's been shipped and what's next:
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts
+- ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**
 

{adloop-0.2.0 → adloop-0.4.0}/README.md

@@ -42,7 +42,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 33 Tools
+## All 38 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
 
@@ -71,6 +71,11 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_keyword_performance` | Keywords — quality scores, competitive metrics |
 | `get_search_terms` | What users actually searched before clicking |
 | `get_negative_keywords` | List existing negative keywords for a campaign or all campaigns |
+| `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
+| `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
+| `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 |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
 ### Cross-Reference Tools (GA4 + Ads Combined)
@@ -180,28 +185,32 @@ uv sync
 uv run adloop init
 ```
 
-The `adloop init` wizard walks you through everything:
+The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
 
-1. **Google Cloud checklist** with clickable links to each setup page
-2. **Credentials** — prompts for your OAuth JSON path, validates the file exists
-3. **GA4 Property ID** — validates numeric format
-4. **Developer Token** — from your Google Ads MCC API Center
-5. **Customer IDs** — auto-formats `1234567890` → `123-456-7890`
-6. **Safety defaults** — budget cap and dry-run preference
-7. **OAuth authorization** — optionally opens your browser to complete auth immediately
-8. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+The wizard:
+
+1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
+2. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
+3. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
+4. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
+5. **Safety defaults** — budget cap and dry-run preference
+6. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
 ### Requirements
 
 - Python 3.11+
-- [uv](https://docs.astral.sh/uv/) for package management
-- A Google Cloud project (free tier works)
 - A Google Ads account with an MCC (Manager Account)
 
-### Manual Setup (If Not Using the Wizard)
+### Headless Servers
+
+Running on a server without a browser (VMs, Docker, SSH)? The wizard automatically detects this and falls back to a manual flow: it prints an authorization URL you can open on any device, then you paste the redirect URL back into the terminal.
+
+### Advanced Setup (Custom Google Cloud Project)
 
 <details>
-<summary>Click to expand manual setup steps</summary>
+<summary>Click to expand — only needed if you want to use your own GCP project instead of AdLoop's built-in credentials</summary>
+
+When you run `adloop init`, choose "No" when asked about built-in credentials. The wizard will guide you through:
 
 #### Step 1 — Google Cloud Project
 
@@ -218,8 +227,6 @@ The `adloop init` wizard walks you through everything:
 3. Select **Desktop app** as the application type, give it any name
 4. Download the JSON file and save it as `~/.adloop/credentials.json`
 
-On first run, AdLoop opens a browser window where you sign in with your Google account and grant access. The resulting token is saved to `~/.adloop/token.json` and refreshed automatically.
-
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
 #### Step 3 — Google Ads Developer Token
@@ -232,28 +239,7 @@ Access levels:
 - **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
 - **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
 
-#### Step 4 — Find Your IDs
-
-| ID | Where to Find It |
-|----|-------------------|
-| **GA4 Property ID** | GA4 → Admin → Property Settings (numeric, e.g. `123456789`) |
-| **Google Ads Customer ID** | Google Ads UI → top bar (e.g. `123-456-7890`) |
-| **MCC Account ID** | MCC UI → top bar (e.g. `123-456-7890`) |
-
-#### Step 5 — Install and Configure
-
-```bash
-git clone https://github.com/kLOsk/adloop.git
-cd adloop
-uv sync
-
-mkdir -p ~/.adloop
-cp config.yaml.example ~/.adloop/config.yaml
-```
-
-Edit `~/.adloop/config.yaml` and fill in the values from the previous steps. See [`config.yaml.example`](config.yaml.example) for a fully documented template.
-
-#### Step 6 — Connect to Your Editor
+#### Step 4 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 
@@ -312,12 +298,12 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
-| `google` | `project_id` | — | Your Google Cloud project ID |
-| `google` | `credentials_path` | `~/.adloop/credentials.json` | Path to OAuth client JSON or service account key |
+| `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
+| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
-| `ga4` | `property_id` | — | Your GA4 property ID (found in GA4 Admin → Property Settings) |
+| `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
-| `ads` | `customer_id` | — | Default Google Ads customer ID |
+| `ads` | `customer_id` | — | Default Google Ads customer ID (auto-discovered by `adloop init`) |
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
@@ -328,9 +314,9 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 26 tool registrations with safety annotations
+├── server.py          # FastMCP server — 38 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 Desktop flow + service account support + token refresh handling
+├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
 ├── cli.py             # Interactive 'adloop init' setup wizard
 ├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
@@ -341,7 +327,8 @@ src/adloop/
 ├── ads/
 │   ├── client.py      # Google Ads API client (version-pinned)
 │   ├── gaql.py        # GAQL query execution with human-readable error parsing
-│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword reads
+│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, recommendations, audience reads
+│   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
 │   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
 │   └── forecast.py    # Budget estimation via Keyword Planner API
 └── safety/
@@ -362,6 +349,8 @@ What's been shipped and what's next:
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts
+- ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**
 

{adloop-0.2.0 → adloop-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "adloop"
-version = "0.2.0"
-description = "MCP server connecting Google Ads + GA4 + codebase into one AI-driven feedback loop"
+version = "0.4.0"
+description = "Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped."
 readme = "README.md"
 authors = [
     { name = "Daniel Klose", email = "info@daniel-klose.com" }

{adloop-0.2.0 → adloop-0.4.0}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 
 def main() -> None:

adloop-0.4.0/src/adloop/ads/pmax.py

@@ -0,0 +1,257 @@
+"""Performance Max read tools — campaign, asset group, and asset performance."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from adloop.ads.currency import get_currency_code
+from adloop.ads.read import _date_clause, _enrich_cost_fields
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+def get_pmax_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    date_range_start: str = "",
+    date_range_end: str = "",
+) -> dict:
+    """Get Performance Max campaign metrics with network breakdown and asset group ad strength."""
+    from adloop.ads.gaql import execute_query
+
+    date_clause = _date_clause(date_range_start, date_range_end)
+
+    campaign_query = f"""
+        SELECT campaign.id, campaign.name, campaign.status,
+               campaign.bidding_strategy_type,
+               metrics.impressions, metrics.clicks, metrics.cost_micros,
+               metrics.conversions, metrics.conversions_value,
+               metrics.ctr, metrics.average_cpc,
+               segments.ad_network_type
+        FROM campaign
+        WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'
+          AND campaign.status != 'REMOVED'
+          {date_clause}
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    campaigns = execute_query(config, customer_id, campaign_query)
+    currency_code = get_currency_code(config, customer_id)
+    _enrich_cost_fields(campaigns, currency_code)
+
+    asset_group_query = f"""
+        SELECT asset_group.id, asset_group.name, asset_group.status,
+               asset_group.ad_strength, asset_group.campaign,
+               metrics.impressions, metrics.clicks, metrics.cost_micros,
+               metrics.conversions, metrics.conversions_value
+        FROM asset_group
+        WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'
+          {date_clause}
+        ORDER BY metrics.cost_micros DESC
+    """
+
+    asset_groups = execute_query(config, customer_id, asset_group_query)
+    _enrich_cost_fields(asset_groups, currency_code)
+
+    insights: list[str] = []
+
+    poor_strength = [
+        ag for ag in asset_groups
+        if ag.get("asset_group.ad_strength") in ("POOR", "AVERAGE")
+    ]
+    if poor_strength:
+        names = ", ".join(
+            ag.get("asset_group.name", "?") for ag in poor_strength[:5]
+        )
+        insights.append(
+            f"{len(poor_strength)} asset group(s) have POOR or AVERAGE ad strength: "
+            f"{names}. Add more diverse assets (headlines, descriptions, images) to improve."
+        )
+
+    zero_conv_groups = [
+        ag for ag in asset_groups
+        if (ag.get("metrics.clicks", 0) or 0) > 10
+        and (ag.get("metrics.conversions", 0) or 0) == 0
+    ]
+    if zero_conv_groups:
+        names = ", ".join(
+            ag.get("asset_group.name", "?") for ag in zero_conv_groups[:5]
+        )
+        insights.append(
+            f"{len(zero_conv_groups)} asset group(s) have clicks but zero conversions: {names}."
+        )
+
+    network_counts: dict[str, int] = {}
+    for c in campaigns:
+        net = c.get("segments.ad_network_type", "UNKNOWN")
+        network_counts[net] = network_counts.get(net, 0) + (
+            c.get("metrics.impressions", 0) or 0
+        )
+    if network_counts:
+        total_impr = sum(network_counts.values()) or 1
+        dist = {
+            k: f"{round(v / total_impr * 100, 1)}%"
+            for k, v in sorted(network_counts.items(), key=lambda x: -x[1])
+        }
+        insights.append(f"PMax network distribution by impressions: {dist}")
+
+    if not campaigns:
+        insights.append("No Performance Max campaigns found in this account.")
+
+    return {
+        "campaigns": campaigns,
+        "asset_groups": asset_groups,
+        "total_campaigns": len(campaigns),
+        "total_asset_groups": len(asset_groups),
+        "insights": insights,
+    }
+
+
+def get_asset_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """Get per-asset details for Performance Max asset groups.
+
+    Returns each asset's field type, status, primary serving status, and
+    content. ``primary_status`` shows whether the asset is eligible to serve
+    (ELIGIBLE, NOT_ELIGIBLE, PAUSED, PENDING).
+
+    Note: the Google Ads API v23 does not expose per-asset performance labels
+    (BEST/GOOD/LOW) for PMax assets via GAQL. Use ``get_detailed_asset_performance``
+    to see which asset *combinations* Google selects most — that's the closest
+    proxy for individual asset quality.
+    """
+    from adloop.ads.gaql import execute_query
+
+    campaign_filter = ""
+    if campaign_id:
+        campaign_filter = f"AND campaign.id = {campaign_id}"
+
+    query = f"""
+        SELECT asset_group_asset.asset, asset_group_asset.field_type,
+               asset_group_asset.status, asset_group_asset.primary_status,
+               asset_group.id, asset_group.name,
+               campaign.id, campaign.name,
+               asset.name, asset.type,
+               asset.text_asset.text,
+               asset.image_asset.full_size.url
+        FROM asset_group_asset
+        WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'
+          {campaign_filter}
+    """
+
+    rows = execute_query(config, customer_id, query)
+
+    status_counts: dict[str, int] = {}
+    field_type_counts: dict[str, int] = {}
+    for row in rows:
+        status = row.get("asset_group_asset.primary_status", "UNSPECIFIED")
+        status_counts[status] = status_counts.get(status, 0) + 1
+        ftype = row.get("asset_group_asset.field_type", "UNSPECIFIED")
+        field_type_counts[ftype] = field_type_counts.get(ftype, 0) + 1
+
+    insights: list[str] = []
+    if not rows:
+        insights.append(
+            "No PMax assets found. This account has no Performance Max campaigns, "
+            "or the specified campaign_id does not match a PMax campaign."
+        )
+    else:
+        not_eligible = [
+            r for r in rows
+            if r.get("asset_group_asset.primary_status") == "NOT_ELIGIBLE"
+        ]
+        if not_eligible:
+            insights.append(
+                f"{len(not_eligible)} asset(s) are NOT_ELIGIBLE to serve — "
+                f"check policy status or asset quality."
+            )
+
+    return {
+        "assets": rows,
+        "total_assets": len(rows),
+        "by_status": status_counts,
+        "by_field_type": field_type_counts,
+        "insights": insights,
+    }
+
+
+def get_detailed_asset_performance(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """Get top-performing asset combinations for Performance Max campaigns.
+
+    Uses the ``asset_group_top_combination_view`` resource directly (not
+    ``execute_query``) because the nested proto structure requires custom
+    extraction.
+    """
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+
+    client = get_ads_client(config)
+    service = client.get_service("GoogleAdsService")
+    cid = normalize_customer_id(customer_id)
+
+    campaign_filter = ""
+    if campaign_id:
+        campaign_filter = f"AND campaign.id = {campaign_id}"
+
+    query = f"""
+        SELECT asset_group_top_combination_view.asset_group_top_combinations,
+               campaign.id, campaign.name,
+               asset_group.id, asset_group.name
+        FROM asset_group_top_combination_view
+        WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'
+          {campaign_filter}
+    """
+
+    combinations: list[dict] = []
+    for row in service.search(customer_id=cid, query=query):
+        campaign_name = row.campaign.name
+        campaign_id_val = row.campaign.id
+        ag_name = row.asset_group.name
+        ag_id = row.asset_group.id
+
+        top_combos = row.asset_group_top_combination_view.asset_group_top_combinations
+        for combo in top_combos:
+            assets_in_combo: list[dict] = []
+            for served_info in getattr(combo, "asset_combination_serving_infos", []):
+                for asset_usage in getattr(served_info, "served_assets", []):
+                    field_type = getattr(asset_usage, "served_asset_field_type", None)
+                    assets_in_combo.append({
+                        "asset": getattr(asset_usage, "asset", ""),
+                        "field_type": (
+                            field_type.name
+                            if hasattr(field_type, "name")
+                            else str(field_type)
+                        ),
+                    })
+
+            if assets_in_combo:
+                combinations.append({
+                    "campaign.id": campaign_id_val,
+                    "campaign.name": campaign_name,
+                    "asset_group.id": ag_id,
+                    "asset_group.name": ag_name,
+                    "assets": assets_in_combo,
+                })
+
+    insights: list[str] = []
+    if not combinations:
+        insights.append(
+            "No top asset combinations found. This account has no Performance Max "
+            "campaigns, or the specified campaign_id does not match a PMax campaign."
+        )
+
+    return {
+        "top_combinations": combinations,
+        "total_combinations": len(combinations),
+        "insights": insights,
+    }