[illia-sapryga]

Rebased onto main (0.41.2, after #134 and #130). The commits are the ChatGPT Ads module, the review fixes, two fixes from the live run, then _PLATFORM_SETUP, health_check and plugin-sync commits that match what main does for Microsoft.

ChatGPT ads went self-serve in OpenAI Ads Manager, and OpenAI published an Advertiser API for it. This adds it as a new toolset, chatgpt_ads, on the same draft → preview → confirm_and_apply gate as Google Ads and Reddit.

Reads: account (reviews, spending limits, account-level blockers), campaigns, ad groups, ads, performance with breakdowns and compact mode, conversions (click-through and view-through, plus every attributed event), a conversion-setup audit with a verdict, change history, chatgpt_attribution_check against GA4, and location search.

Writes: pause / enable / archive, update_chatgpt_campaign / _ad_group / _ad, and draft_chatgpt_campaign / _ad_group / _ad. New entities are created paused.

Connection. An Advertiser API key from Ads Manager → Settings → API keys. There's no OAuth and no developer token. Each key belongs to exactly one ad account, so ad_account_id on a tool only picks which configured key to use. Config is chatgpt_ads.api_key (or OPENAI_ADS_API_KEY) plus an optional chatgpt_ads.accounts map for agencies. CredentialsProvider gains chatgpt_ads_api_key(). A hosted provider without it doesn't get the tools, and health_check leaves chatgpt_ads out there. A local server without a key hides the tools (_PLATFORM_SETUP).

The gate. OpenAI has no validate-only mode for single resources, so the dry run works like Reddit's. It re-reads the target and refuses when a field the plan changes was edited since the preview. It also re-checks:

• max_daily_budget, with a lifetime budget judged by its daily equivalent over the flight, re-computed whenever the budget or either date changes
• max_bid_increase_pct
• the landing page
• that the key still answers for the account the preview named

The real apply runs the same checks first, reading the target by id. Creates send an Idempotency-Key, which OpenAI documents on POST /campaigns, /ad_groups and /ads: "If a matching prior create is visible, the existing object is returned instead of creating a duplicate". Live, replaying each create with the same key and body returned the same object. Images are fetched through image_fetch, so the public-only and redirect checks apply. The draft pins their sha256, and the apply uploads exactly those bytes. A new ad's file id is kept in the plan, so a retry after a lost response sends the same request.

Shared changes are in #134 now: the blocked_operations re-check in confirm_and_apply and the shared draft helpers. The name-based display hiding is gone. Request payloads, snapshots and the image pin live in ChangePlan.apply_only_payload, so changes holds only what a person approves.

Cloud contract. TOOLSETS gains chatgpt_ads, so config/toolsets.php and the runtime filter need the slug too. I updated test_toolset_slugs_match_the_cross_repo_contract.

Review fixes (801acd3, plus two found in the live run: 236bc01 and c97694d) are listed in the review reply below. The live transcript of every write is linked there.

What it does not do:

• The Conversions API (server-side events), pixel setup, or custom audiences.
• An adloop init step. The key goes in the config by hand, as the README says.
• Change a campaign's bidding type or move a daily budget to lifetime. OpenAI refuses both, so the draft refuses them first.

Tested with the full suite plus tests/test_chatgpt_ads.py and tests/test_chatgpt_ads_write.py. The write tests drive the real gate against a stateful fake of the Advertiser API. It enforces the contract details: whole-object updates, status endpoints, and idempotency keys that must come back with the same body. The tests cover lost responses after a successful create, edits made between preview and apply, a key that moves to another account, and private image URLs. Every write tool has also run live against a real ad account: create, update, enable, pause and archive for campaigns, ad groups and ads. The redacted transcript is linked in the review reply.

I also changed the rules files (a tool section and two orchestration patterns), the README and config.yaml.example. I didn't regenerate reference/tools.mdx in the docs repo.

[kLOsk]

Thanks for this, Illia. ChatGPT Ads is welcome in the open-source package. Three decisions first, then the review.

How we'd like to land it

1. Please move the shared changes into their own small PR: the blocked-operations re-check in confirm_and_apply, the approval display change (reworked as below) and safety/outcomes.py from Microsoft Advertising: reads, reports and campaign management #130. We'll merge that first. ChatGPT Ads: reads, campaign management and conversion diagnostics #127 and Microsoft Advertising: reads, reports and campaign management #130 can then both sit on top of it and land independently.
2. ChatGPT Ads goes in as an open-source, community-maintained toolset. It won't be offered on AdLoop Cloud for now. If it ever is, we'll take over maintenance of the module.
3. On our side we'll add a startup step that hides a platform's tools when it isn't configured, so local users without ChatGPT Ads don't get 17 extra tools. Nothing needed from you there.

Must fix

• display_fields hides every top-level before, but Tag Manager update plans keep the values the user approves against under before (gtm/write.py:499, 627, 776). GTM tag, trigger and variable previews would lose them in the dialog and on the card. Please put ChatGPT's request payload and snapshot into ChangePlan.apply_only_payload (never shown or logged) and drop the name-based hiding in both approval.py and approval_card.html.
• Switching a campaign from a lifetime to a daily budget compares the old lifetime total with the new daily amount (chatgpt_ads/write.py:610-617). Lifetime 500 → daily 100 is roughly 6x the daily spend, yet gets no double confirmation, and the warning points the wrong way. Please compare daily equivalents.

Should fix

• Preflight finds the entity by scanning the whole account (find_entity, write.py:185) at draft, dry run and apply. The API has GET /campaigns|ad_groups|ads/{id}: please fetch by id in preflight and keep the scan for parent names at draft only.
• Image ads: preflight checks the image with our fetcher, then /upload sends the URL and OpenAI fetches it again, so the uploaded bytes can differ from the checked ones. Please pin a sha256 at draft, re-check it, and upload the bytes we fetched.
• A request error during a POST is reported as "nothing is known to have changed" (client.py:262). After a timeout the outcome is unknown: please say so, and have preflight recognise "already at the planned value", so a retry isn't refused as "changed since the draft".
• _require_unchanged compares whole creative, targeting and bidding_config objects. Please compare only the subfields the plan sends; a response-only field such as creative.image_url would otherwise break every dry run if it ever changes between reads.
• custom_audience_bid_multipliers: [] is sent on update, but the docs list that field for create requests only.
• Skip BLOCKED plans in _dialog_applies before asking the user, and write an audit entry for BLOCKED refusals.
• _guard, _store and the blocked-operation refusal belong in safety/guards.py rather than a third copy next to Reddit and GTM; reuse the Reddit client helpers where they are identical; drop the dead code (_Refusal, is_chatgpt_plan, _IMAGE_TYPES).
• Context hints in the ad group read have no compact mode or cap (up to 2,000 per ad group).
• Small: chatgpt_attribution_check also needs GA4 but is only tagged chatgpt_ads, and the confirm_and_apply docstring doesn't mention ChatGPT plans.

Before merge
The tests drive the real gate against a fake that encodes your reading of the API. Could you attach a redacted transcript of each write operation against a real ad account (create a paused campaign, ad group and ad; update; pause, enable, archive)? And which create endpoints actually honor Idempotency-Key? The docs say "supported create endpoints", while the tool descriptions promise no duplicates unconditionally.

[illia-sapryga]

Thanks, Daniel. All done; the branch is force-pushed.

Landing

• The shared changes are in Write gate: blocked operations re-checked at apply, partial applies retired, shared draft helpers #134: the blocked-operations re-check (with an audit entry, and no dialog for a blocked plan), safety/outcomes.py, the blocked_operation_error / store_draft / blocked_plan_refusal helpers in safety/guards.py (Reddit and Tag Manager use them too), and the card labels.
• This PR is rebased onto Write gate: blocked operations re-checked at apply, partial applies retired, shared draft helpers #134 and 0.40.1. The module is one commit, then the review fixes (988f34e), then two fixes the live run found (91dfad9, 0d2b24b).
• Community-maintained and not on Cloud: understood. The same goes for hiding unconfigured platforms at startup.

Must fix

• Payloads.
  • The request body, snapshot, account selector, status action and image pin are now in ChangePlan.apply_only_payload. The name-based hiding is gone from approval.py and the card.
  • changes keeps only what the user approves. Empty values are dropped, and updates show before → after under display, which the new dialog puts on its summary line.
  • If a plan store drops the payload, the apply refuses and sends nothing.
  • Tests cover the preview, the dialog, the dry run, the audit log and the apply.
• Lifetime → daily budget. Both sides are compared as daily amounts. Lifetime 500 over a 31-day flight → daily 100 is about 6.2x. It gets the double confirmation, and the warning says which way it goes. Shortening a lifetime flight also counts as a raise.

Should fix

• Lookups.
  • Preflight and apply read the target with GET /campaigns|ad_groups|ads/{id}.
  • Drafts still scan the account for parent names, since ad groups and ads carry no parent id. They now read the entity itself by id first.
  • Live, a campaign created a moment earlier was missing from GET /campaigns, and drafting its ad group answered "not found" (0d2b24b). A scan that misses now only leaves the parent names unknown, and the preview says so.
• Images. The draft pins the sha256 of the bytes it fetched through image_fetch. The dry run and apply re-read them and refuse bytes that changed, and the apply uploads exactly those bytes as multipart.
• Lost answers.
  • A timeout, dropped connection or 5xx on a write raises ChatGPTAdsOutcomeUnknown ("whether it changed anything is unknown").
  • A request that never connected says nothing changed.
  • Preflight counts a field already at the planned value as done, so a retry sends nothing, or only what's still missing.
  • Creates keep the plan and resend the same key and body (see Idempotency-Key below).
• _require_unchanged compares only what the plan sends: budget limits, the sent bidding_config keys, the sent creative keys, and targeting in its writable form.
• custom_audience_bid_multipliers: []. OpenAI's bidding guide sends it on update to clear multipliers when an ad group moves to automatic bidding. It's now sent only in that case and left out otherwise.
• Shared helpers.
  • _guard / _store now use the guards.py helpers.
  • _Refusal, is_chatgpt_plan and _IMAGE_TYPES are deleted.
  • The micros conversions are Reddit's from_micro / to_micro. Nothing else in the two clients was identical.
• Context hints. Previews list 20 and count the rest. get_chatgpt_ad_groups lists 50 per ad group with context_hint_count, and has a compact mode.
• Small items.
  • chatgpt_attribution_check is tagged chatgpt_ads and ga4. The one-tag test allows the tools listed in a new CROSS_PLATFORM_TOOLS in server.py. Happy to do it another way if your startup filter wants something else.
  • The confirm_and_apply docstring describes ChatGPT plans.

Before merge

• Live transcript (redacted): https://gist.github.com/illia-sapryga/6071e4aed3b7a660ebbbe01a9c0beab9
  • It covers a paused campaign, ad group and ad, each create replayed with the same Idempotency-Key, an update of each, and the ad enabled (its campaign stayed paused) and paused again. All three were then archived.
  • Every step goes draft → dry run → apply and lists each HTTP request with its body and answer.
• One more gap the run found. OpenAI refuses daily budgets under 25 ("Daily campaign budget must be at least 25000000 micros"), although the spec's minimum is 1,000,000. The draft and the update now refuse them (91dfad9).
• Idempotency-Key.
  • The OpenAPI spec documents the header on POST /campaigns, /ad_groups and /ads: "If a matching prior create is visible, the existing object is returned instead of creating a duplicate." /upload has none.
  • Live, all three replays returned the original object.
  • The tool descriptions, rules and README now claim only that. After a lost create, the error tells the user to check the account and wait a minute before confirming again.

Full suite: 2162 passed, 2 skipped.

[kLOsk]

Thanks, Illia. #134 and #130 are merged, so this one now conflicts with main where both platforms plug in: TOOLSETS, confirm_and_apply, auth, config, the rules, the README and the tests. Could you rebase it onto main?

While you're at it, please add chatgpt_ads to _PLATFORM_SETUP in server.py, next to Reddit and Microsoft, so a local server hides the ChatGPT Ads tools when no key is set up. The check needs to cover chatgpt_ads.api_key, chatgpt_ads.accounts and OPENAI_ADS_API_KEY.

The review fixes look right from what I've read so far. I'll do a last pass after the rebase, then merge.

[illia-sapryga]

Thanks, Daniel. Rebased onto main (0.41.2). ChatGPT Ads now sits next to Microsoft in TOOLSETS, confirm_and_apply, auth, config, the rules, the README and the tests. The #134 commits are gone; the module and its tests are unchanged.

• 770db9c: chatgpt_ads is in _PLATFORM_SETUP. A local server hides the tools unless there's a key in chatgpt_ads.api_key, chatgpt_ads.accounts or OPENAI_ADS_API_KEY, using the same lookup as the client, so a blank env var counts as no key. chatgpt_attribution_check is hidden with them; the GA4 tools stay.
• Following what you did for Microsoft: 0bf2884 makes health_check report chatgpt_ads only where its tools are offered, and 448b718 makes the plugin sync drop the ChatGPT sections, so the Cloud files come out the same as from main. Both are separate commits, so either can be dropped.

The full suite passes locally (2,423 tests), and the description is updated.

[kLOsk]

Thanks, Illia. The rebase is clean against main (0.41.4), and the earlier points check out in the code: the apply-only payload, the image checksum, the unknown-outcome handling, the account pin at apply, and the tools hidden without a key. Two things from the last pass, one of them before merge.

Must fix

• _daily_equivalent (chatgpt_ads/write.py) spreads a lifetime budget over the whole flight, from start_time, even when the start is in the past. A budget is spent in the days that are left, so days that have passed thin out the per-day share and the max_daily_budget check passes amounts it should refuse:

  • draft_chatgpt_campaign with start_date a year ago, end_date next week and lifetime_budget 3500 comes out at about 9 a day instead of 500.
  • A campaign 60 days into a 62-day flight: raising the lifetime budget from 620 to 3000 counts as about 48 a day, while up to 2400 can be spent in the last two days.

  Please count from now when the flight has already started (max(start, now)), in the draft, the update and the preflight, which all go through this function. Reddit got the same change in 0.41.3 (_days_between in reddit/write.py). Tests for a past start on create and for a late-flight raise would pin it.

Should fix

• campaign_id, ad_group_id, ad_id and entity_id go into the request path as given (_get, the status actions, the update POST). An id with /, .. or ? in it turns into a different path than the preview describes. Each key only reaches its own account, so the reach is small, but please refuse anything that isn't a plain id before the first request, as Reddit does with _ENTITY_ID.

#121 and #122 are merged, thanks for both. They touch server.py, the rules and ads/write.py, so this one may need another small rebase. With the budget fix in, I'll merge.