Integrate Meta Ads (#87)

* fix buyer booking flow with seller

* meta ad booking flow using graph api

* GAM and Meta Reporting Integration

* naming refactor

* docs for meta ads and Reporting

* fallback allocation if llm fails

* Access GAM report via seller agent

* lint formatting and unit test fixes

* replace cli with api

* Fix lint (ruff format + E501 + I001) and CrewAI >=1.14 Flow.__init__ state kwargs

* Fix 7 test failures introduced by Meta integration merge

- test_deal_library_agent_has_memory / test_linear_tv_agent_has_memory:
  patch settings.crew_memory_enabled=True inside each test so the assertion
  holds regardless of the .env default (CREW_MEMORY_ENABLED=false)

- test_approve_specific_recommendations / test_approve_all_recommendations:
  mock _book_via_seller_api — this method now makes real HTTP calls after the
  Meta integration added it to _execute_bookings; integration tests must not
  reach out to a live seller URL

- test_execute_bookings_no_store / test_execute_bookings_persists_records:
  same mock for the same reason

- test_crew_with_memory_true: skipif crewai[bedrock] not installed locally;
  crewai[bedrock] is in core deps so CI runs the test normally

* Fix DealBookingFlow.__init__ state kwargs for crewai >=1.15

crewai 1.15 restructured Flow as a BaseModel — extra kwargs passed to
super().__init__() are silently dropped by pydantic instead of being
forwarded to _initialize_state. Fix: call super().__init__() with no
kwargs, then apply state_kwargs directly via setattr on self.state.
This works across all crewai versions.

* fix channel allocation: add social to BudgetAllocationOutput and restore LLM-driven split with equal-split fallback

* restore crew_memory_enabled=True to match main branch default

* Fix booking mock and ruff format drift exposed by PR #110 merge

test_spend_ceiling.py's budget-ceiling tests used a bare MagicMock
client, which broke once DealBookingFlow's booking path (from the
Meta integration work) started reading a real base_url and issuing
HTTP calls via _book_via_seller_api. Mock that call the same way the
rest of the suite does. Also applies a ruff-format-only fix to
helpers.py that was already failing `ruff format --check` on main.

* Fix get_latest_pacing_snapshot to order by insertion time, not business time

PacingStore.get_latest_pacing_snapshot() ordered by the timestamp
column, which is caller-supplied business/simulated time and not
guaranteed to be monotonic with write order. The campaign demo's
READY-stage snapshot is stamped with real wall-clock time while its
later ACTIVE-stage snapshot uses a simulated "35% through flight"
timestamp — once real time passes that simulated point, the stale
zero-value READY snapshot outranks the real one, and every reporting
consumer (campaign_report.py, mcp_server.py) reads zero spend for an
active campaign. created_at already records true insertion order and
is the correct column to sort by.

Author: Sirajmx

.env.example

@@ -44,6 +44,28 @@ POSTGRES_POOL_MAX=10
 ENVIRONMENT=development
 LOG_LEVEL=INFO
 
+# CrewAI
+CREW_MEMORY_ENABLED=true
+
+# =============================================================================
+# Meta Ads API Integration
+# =============================================================================
+# System user access token — generate in Meta Business Manager:
+#   Business Settings → System Users → <your system user> → Generate Token
+#   Required scopes: ads_management, ads_read, business_management
+META_ACCESS_TOKEN=
+
+# Ad account ID — assign system user to ad account first:
+#   Business Settings → System Users → Add Assets → Ad Accounts
+#   Format: act_XXXXXXXXX
+META_AD_ACCOUNT_ID=
+
+# Facebook Page ID — Business Manager → Pages → click page → copy ID from URL
+META_PAGE_ID=
+
+# Graph API version (for reach estimates)
+META_API_VERSION=v21.0
+
 # IAB Diligence Platform Integration (via SafeGuard Privacy)
 # optional; inert when SGP_API_KEY is empty
 SGP_API_KEY=

docs/integration/meta-ads.md

@@ -0,0 +1,241 @@
+# Meta Ads Integration
+
+The buyer agent integrates with the Meta Marketing API to book and report on social channel campaigns across Facebook and Instagram. This page covers authentication setup, the booking flow, and reporting endpoints.
+
+The buyer agent calls `graph.facebook.com` directly using a system user access token. This is the same endpoint used by the official Meta Marketing API SDKs — no browser OAuth is required.
+
+## Configuration
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `META_ACCESS_TOKEN` | `str` | `""` | System user access token from Meta Business Manager |
+| `META_AD_ACCOUNT_ID` | `str` | `""` | Ad account ID — format `act_XXXXXXXXX` |
+| `META_PAGE_ID` | `str` | `""` | Facebook Page ID — required for ad creative creation |
+| `META_API_VERSION` | `str` | `v21.0` | Meta Graph API version |
+
+Add these to your `.env` file:
+
+```bash
+META_ACCESS_TOKEN=your-system-user-token
+META_AD_ACCOUNT_ID=act_XXXXXXXXX
+META_PAGE_ID=XXXXXXXXX
+META_API_VERSION=v21.0
+```
+
+### Generating a System User Token
+
+1. Open **Meta Business Manager → Business Settings → System Users**
+2. Create or select a system user
+3. Click **Generate Token** → select your app
+4. Required scopes: `ads_management`, `ads_read`, `business_management`
+5. Assign the system user to your ad account: **Business Settings → System Users → Add Assets → Ad Accounts**
+
+### Installation
+
+```bash
+pip install -e ".[meta]"
+```
+
+!!! note "Sandbox accounts"
+    Meta provides sandbox ad accounts for development. Campaigns created in a sandbox account are API-only and not visible in the Ads Manager UI. They are created in `PAUSED` state and never serve impressions.
+
+---
+
+## Booking Flow
+
+When a booking brief includes `"channels": ["social"]` or `"channels": ["meta"]`, the buyer agent routes through the Meta booking path.
+
+```mermaid
+sequenceDiagram
+    participant Buyer as Buyer Agent
+    participant Meta as graph.facebook.com
+
+    Buyer->>Meta: GET /{account}/reachestimate
+    Meta-->>Buyer: Reach + CPM estimates
+
+    Note over Buyer: Awaiting approval
+
+    loop Per placement (Instagram Reels, Facebook Feed, etc.)
+        Buyer->>Meta: POST /act_{id}/campaigns
+        Meta-->>Buyer: campaign_id (PAUSED)
+
+        Buyer->>Meta: POST /act_{id}/adsets
+        Meta-->>Buyer: ad_set_id (PAUSED)
+    end
+```
+
+### Research Phase
+
+The `SocialCrew` uses `MetaInventoryTool` to call `GET /{account}/reachestimate` and estimate reach and CPM for four placements:
+
+- Instagram Reels
+- Facebook Video Feeds
+- Instagram Feed
+- Facebook Feed
+
+If the reach estimate API returns an error, the tool falls back to static estimates.
+
+### Booking Phase
+
+After the user approves recommendations, the buyer agent creates two resources per placement:
+
+| Step | API Call | Status |
+|---|---|---|
+| 1 | `POST /act_{id}/campaigns` | PAUSED |
+| 2 | `POST /act_{id}/adsets` | PAUSED |
+
+!!! note "Creative step"
+    Ad creative creation (step 3) requires an uploaded image asset. This step is skipped — campaign and ad set creation is sufficient to confirm booking.
+
+### Objective Mapping
+
+| IAB Objective | Meta Objective |
+|---|---|
+| `brand_awareness`, `reach` | `OUTCOME_AWARENESS` |
+| `traffic` | `OUTCOME_TRAFFIC` |
+| `conversions` | `OUTCOME_SALES` |
+| `video_views` | `OUTCOME_ENGAGEMENT` |
+| `lead_generation` | `OUTCOME_LEADS` |
+
+### Budget Allocation
+
+The `PortfolioCrew` LLM allocates budget across channels based on campaign objectives, audience fit, and KPIs. If `channels` is specified in the brief, the LLM is instructed to allocate only to those channels:
+
+```json
+{
+  "channels": ["branding", "ctv", "social"],
+  "budget": 15000
+}
+```
+
+The LLM will distribute the `$15,000` across `branding`, `ctv`, and `social` based on which best fits the campaign objectives.
+
+### Example Booking Request
+
+```
+POST /bookings
+Content-Type: application/json
+```
+
+```json
+{
+  "brief": {
+    "name": "Summer Campaign 2026",
+    "objectives": ["brand_awareness", "reach"],
+    "budget": 5000,
+    "start_date": "2026-06-01",
+    "end_date": "2026-06-30",
+    "channels": ["social"],
+    "target_audience": {
+      "demographics": {"age": "18-45"},
+      "interests": ["technology", "gaming"]
+    }
+  },
+  "auto_approve": false
+}
+```
+
+Poll `GET /bookings/{job_id}` until `status: awaiting_approval`, then approve:
+
+```
+POST /bookings/{job_id}/approve-all
+```
+
+Booked lines for the social channel will have `booking_status: "paused"`.
+
+---
+
+## Reporting
+
+### List Campaigns
+
+Returns all campaigns in the ad account — no booking job ID required.
+
+```
+GET /meta/campaigns?limit=10
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `limit` | `int` | `10` | Number of campaigns to return |
+
+```json
+{
+  "ad_account_id": "act_XXXXXXXXX",
+  "campaigns": [
+    {
+      "id": "23856xxxxxxxxx",
+      "name": "Summer Campaign 2026 — Instagram Reels",
+      "effective_status": "PAUSED",
+      "objective": "OUTCOME_AWARENESS",
+      "daily_budget": "125000",
+      "created_time": "2026-05-11T15:35:59+0530"
+    }
+  ],
+  "count": 10
+}
+```
+
+### Campaign Report
+
+Returns campaign details combined with delivery insights for one or more campaign IDs.
+
+```
+GET /meta/report?campaign_ids=CAMPAIGN_ID_1,CAMPAIGN_ID_2&date_preset=last_30d
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `campaign_ids` | `string` | required | Comma-separated Meta campaign IDs |
+| `date_preset` | `string` | `last_30d` | `last_7d` / `last_14d` / `last_30d` / `last_90d` |
+
+```json
+{
+  "ad_account_id": "act_XXXXXXXXX",
+  "date_preset": "last_30d",
+  "campaigns": [
+    {
+      "campaign_id":   "23856xxxxxxxxx",
+      "campaign_name": "Summer Campaign 2026 — Instagram Reels",
+      "status":        "PAUSED",
+      "objective":     "OUTCOME_AWARENESS",
+      "daily_budget":  "125000",
+      "created_time":  "2026-05-11T15:35:59+0530",
+      "spend":         0.0,
+      "impressions":   0,
+      "reach":         0,
+      "frequency":     0.0,
+      "clicks":        0,
+      "ctr":           0.0,
+      "cpm":           0.0
+    }
+  ],
+  "summary": {
+    "total_spend": 0.0,
+    "total_impressions": 0,
+    "total_clicks": 0,
+    "total_reach": 0
+  }
+}
+```
+
+### Job-Scoped Report
+
+To report on all campaigns booked within a specific job:
+
+```
+GET /reports/{job_id}?date_range=last_30d
+```
+
+The buyer agent automatically identifies Meta campaign IDs from `booked_lines` and pulls insights for each. IAB OpenDirect order IDs in the same job are routed to the seller agent's delivery performance endpoint. See [Bookings API](../api/bookings.md) for details.
+
+!!! tip "Access token security"
+    The Meta access token is never exposed in API error responses. It is automatically redacted to `***` before any error message reaches the HTTP response.
+
+---
+
+## Related
+
+- [Seller Agent Integration](seller-agent.md) --- How buyer and seller agents communicate
+- [Bookings API](../api/bookings.md) --- Full booking flow reference
+- [Configuration Reference](../guides/configuration.md) --- All environment variables

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
   - Integration:
       - Seller Agent Guide: integration/seller-agent.md
       - OpenDirect Protocol: integration/opendirect.md
+      - Meta Ads: integration/meta-ads.md
       - IAB Diligence Platform Approval: integration/iab-diligence-platform.md
   - AI Assistant Setup:
       - Claude (Desktop & Web): claude-desktop-setup.md

pyproject.toml

@@ -22,6 +22,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+meta = [
+    "meta-ads-cli>=0.1.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.24.0",

src/ad_buyer/agents/level2/social_agent.py

@@ -0,0 +1,31 @@
+# Author: Green Mountain Systems AI Inc.
+# Donated to IAB Tech Lab
+
+"""Social media channel specialist agent (Meta Ads)."""
+
+from crewai import Agent
+
+from ...config.settings import settings
+
+
+def create_social_agent() -> Agent:
+    """Create the Social Media Specialist agent for Meta Ads campaigns."""
+    return Agent(
+        role="Social Media Advertising Specialist",
+        goal=(
+            "Identify the best Meta Ads placements (Facebook, Instagram, Audience Network) "
+            "for campaigns targeting social media audiences. Evaluate reach, CPM, and "
+            "audience alignment. Only recommend placements actually returned by the "
+            "search_meta_placements tool."
+        ),
+        backstory=(
+            "Expert in Meta Ads ecosystem with deep knowledge of Facebook Feed, Instagram Reels, "
+            "Stories, and Audience Network inventory. Skilled at matching campaign objectives "
+            "(brand awareness, reach, conversions) to optimal Meta placements "
+            "and bidding strategies."
+        ),
+        llm=settings.manager_llm_model,
+        verbose=settings.crew_verbose,
+        allow_delegation=False,
+        max_iter=settings.crew_max_iterations,
+    )

src/ad_buyer/clients/meta_ads_api_client.py

@@ -0,0 +1,76 @@
+# Author: Green Mountain Systems AI Inc.
+# Donated to IAB Tech Lab
+
+"""Meta Ads reach-estimate client — Graph API reach estimates only.
+
+Used in the research phase to estimate audience reach + CPM before booking.
+All other operations (booking, reporting, lifecycle) use MetaAdsClient
+(meta_ads_client.py).
+"""
+
+import json
+
+import httpx
+
+
+class MetaAdsAPIClient:
+    """Graph API httpx client scoped to reach estimation.
+
+    Calls graph.facebook.com/v{version}/{account}/reachestimate
+    directly using a system user access token.
+    """
+
+    def __init__(
+        self,
+        access_token: str,
+        ad_account_id: str,
+        api_version: str = "v21.0",
+    ):
+        self._token = access_token
+        self._account_id = (
+            ad_account_id if ad_account_id.startswith("act_") else f"act_{ad_account_id}"
+        )
+        self._base = f"https://graph.facebook.com/{api_version}"
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        all_params = {"access_token": self._token, **(params or {})}
+        r = httpx.get(f"{self._base}/{path}", params=all_params, timeout=30.0)
+        r.raise_for_status()
+        return r.json()
+
+    def get_reach_estimate(
+        self,
+        targeting: dict,
+        daily_budget: float,
+        optimize_for: str = "REACH",
+    ) -> dict:
+        """Estimate reach for a targeting + daily budget combination.
+
+        Args:
+            targeting: Graph API targeting spec:
+                {
+                    "geo_locations": {"countries": ["US"]},
+                    "age_min": 25, "age_max": 54
+                }
+            daily_budget: Daily budget in USD (converted to cents internally)
+            optimize_for: REACH | IMPRESSIONS | LINK_CLICKS
+
+        Returns:
+            { "users_lower_bound": int, "users_upper_bound": int,
+              "estimate_ready": bool }
+        """
+        return self._get(
+            f"{self._account_id}/reachestimate",
+            {
+                "targeting_spec": json.dumps(targeting),
+                "optimize_for": optimize_for,
+                "daily_budget": int(daily_budget * 100),
+            },
+        )
+
+    def get_ad_account(self) -> dict:
+        """Get ad account metadata — name, currency, timezone."""
+        return self._get(
+            self._account_id,
+            {"fields": "id,name,currency,timezone_name,account_status"},
+        )