Repository navigation
Description
Context
The TypeScript SDK has made canonical creatives the primary contract in adcontextprotocol/adcp-client#2391. The reference implementation is merged and published as @adcp/sdk@13.0.0-rc.3; Python implementation is no longer gated on waiting for a TypeScript RC.
This is broader than the v1↔v2 projection layer completed in #741 and the comparison helpers completed in #885. Adopting the modern Python SDK must mean application code uses format_kind, format_options, and format_option_refs, while {agent_url, id} creative identity is confined to wire adapters and explicitly named migration APIs.
Target release
- Target Python SDK 7.0.0-rc before GA.
- Treat the public-surface changes as semver-major.
- Keep negotiated AdCP protocol versions distinct from the Python package version in code, docs, and diagnostics.
Required public contract
- Make canonical creative-bearing models the unqualified/default public types for products, packages, creatives, media-buy requests/responses, delivery responses, and server handler payloads.
- Move raw
{agent_url, id}shapes behindLegacy*model names and explicitly named legacy client/server methods. Follow the cross-SDKLegacy*convention; do not introduceAgentUrl*names. - Make
list_creative_formatslegacy-only. Canonical discovery is through productformat_optionsand canonical declarations. - Remove
format_idsfrom canonicalProductand creative-filter models. - Make generic
execute_task, multi-agent APIs, callbacks, response builders, server helpers, and asset helpers canonical by default. Any raw-format variant must be explicit and legacy-named. - Root
Formatmust mean a canonical format declaration, not the generated named-format model. FormatIdmust not be available from the normaladcproot import. Expose legacy identity only asLegacyFormatIdor through an explicit legacy/raw module.- Primary discovery and write methods must be canonical across
get_products,create_media_buy,update_media_buy,sync_creatives,list_creatives, media-buy reads, and creative-delivery reads. - Preserve raw wire access for migration/conformance tooling through conspicuous legacy methods, hard-deprecated for removal with AdCP 4.0.
- Generated/raw protocol modules may remain available for wire tooling, but must not be primary application-facing imports.
Runtime Pydantic invariants
These are runtime requirements, not typing-only or documentation-only constraints:
- For every primary model,
model_json_schema()must recursively contain no property namedformat_id,format_ids, or format-scopedagent_url, including nested definitions, unions, aliases, request/response containers, callback payloads, and server payloads. - For every primary model,
model_dump()and JSON serialization must be incapable of emitting those fields at any nesting depth, including when input was constructed from legacy/raw objects, aliases, extras, or nested generated models. - Tests must walk the complete primary schema and serialized value recursively. A top-level assertion or static type check is insufficient.
Wire negotiation and lifecycle boundaries
- Apply one capability matrix consistently:
- AdCP 3.0: legacy wire; upgrade reads and downgrade writes.
- AdCP 3.1: the version alone is not canonical evidence; use
media_buy.features.canonical_creatives, then request-local schema evidence where available, otherwise fail closed unless an unambiguous legacy projection exists. - AdCP 3.2+: canonical by contract;
canonical_creatives: falseis a capability error.
- Use the same effective converter and canonical response boundary for polling, task continuation, input-required flows, async completion, callbacks, and webhooks.
- For server/framework APIs, normalize legacy inbound requests before adopter handlers and project responses back to the caller's captured negotiated dialect.
- Keep network resolution outside the pure projector. Feed it validated, cached catalog snapshots in precedence order (publisher → approved community mirror → agent-derived/configured).
- Keep catalog lookup URL-sensitive, including explicit historical AAO aliases and AdCP URL canonicalization while preserving path/query scope.
- Snap's canonical mirror declarations remain canonical-only unless an exact owner-sensitive
v1_format_refauthorizes a legacy route; public availability or a matching ID alone does not create one. - Canonical
Productrequires at least oneformat_optionsentry. Retain partially mapped products with mapped options and sanitizedFORMAT_PROJECTION_FAILEDentries; omit wholly unmappable products from the canonical list while retaining the non-fatal error in portableerrors[]and SDK diagnostics. Never emitformat_options: []for a mapped canonical product.
Cross-language golden parity
Pin validation to the exact inputs, outputs, diagnostics, and transition behavior shipped in TypeScript RC3—not merely equivalent high-level behavior. The fixture is currently repository-local rather than a genuinely shared fixture package, so Python must vendor a versioned copy of the RC3 golden corpus until a shared package exists.
RC3 reference corpus:
test/lib/v2-projection-fixturestest/lib/v1-to-v2-projection.test.jstest/lib/catalog-unique-id.test.jstest/lib/creative-format-projection.test.jstest/lib/projection-catalog-adapters.test.jstest/canonical-creatives-mcp-server-e2e.test.js
The stable migrated option-ID algorithm is normative:
identity = compact JSON([agent_url, id, width_or_null, height_or_null, duration_ms_or_null])
format_option_id = "migrated_" + HMAC-SHA256(key=b"", message=UTF8(identity)).hex()[0:32]
The complete legacy tuple and field order are part of the contract. Tests must assert exact IDs and stability under seller-array reordering.
Compatibility and release work
- Add inbound
legacy_format_convertersupport for seller-owned formats and a separate canonical-to-legacy resolver for persisted canonical custom formats. - Include a migration guide with canonical replacements and explicit legacy escape hatches.
- Audit examples and all root/alias re-exports so old shapes are not silently retained by convenience imports.
- Add transition tests for discovery → selection → serialization → create/update/sync → async/callback/webhook response.
Acceptance criteria
Primary model boundary
- A normal Python client/server integration completes the creative lifecycle without importing or handling
agent_url,format_id, orformat_ids. - Recursive
model_json_schema()tests prove those legacy fields are absent from every primary model. - Recursive
model_dump()/JSON tests prove primary models cannot emit those legacy fields. - Root imports and all generic helpers expose the canonical surfaces described above; only explicit
Legacy*/raw paths expose legacy identity.
Projection precedence and safety
- Resolve exact owner + ID catalog identity first.
- If exact lookup misses, allow a bare-ID fallback only when that ID has exactly one meaning in the bundled AAO catalog and the supplied owner is a valid public HTTPS owner.
- Preserve the complete original legacy tuple for same-process legacy delivery; do not rewrite it to the AAO owner.
- An explicit custom converter overrides compatibility inference, including intentional AAO-slug reuse.
- Reject ambiguous/colliding IDs, unsafe or invalid owners, invalid parameters, catalog conflicts, and contradictory dimensions/duration.
- Never reverse-guess after a process boundary. Persisted canonical selections require rediscovery/readback or an explicit durable canonical-to-legacy resolver backed by adopter storage.
- Preserve exact owner-sensitive
v1_format_refroutes, including dimensional discriminators, for legacy delivery.
Interoperability and fixtures
- Legacy AdCP 3.0/3.1 peers interoperate through deterministic adapters or receive actionable projection errors.
- Seller-specific custom formats have tested bidirectional conversion hooks.
- Python vendors and passes the exact TypeScript RC3 golden inputs/outputs, including all 16 observed Vox, Triton, and OpenAds refs; historical aliases; unique bare-ID and collision cases; unsafe owners; contradictory parameters; original-tuple round trips; persistence boundaries; and all-unmappable discovery.
- Migrated option IDs exactly match the normative empty-key HMAC algorithm above.
- Public documentation clearly distinguishes Python SDK 7.0.0 from the negotiated AdCP protocol version.
References
- TypeScript canonical boundary and reference implementation: feat: enforce canonical creative SDK boundaries adcp-client#2391
- TypeScript reference release:
@adcp/sdk@13.0.0-rc.3 - Existing Python projection layer: feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741
- Existing Python canonical compatibility helpers: Add canonical creative format compatibility helpers #885
- Authoritative catalog aliases: fix(creative): publish deployed legacy format aliases adcp#6028
- AAO deployed-format catalog gaps: fix: publish canonical mappings for deployed AAO legacy format IDs adcp#6025
Activity
bokelley commentedon Jul 26, 2026
Triage
Classification: Feature request (major, breaking)
Bucket(s): client, handlers (no matching repo labels found — flagging the gap)
Status: ready-for-human
Milestone: omitted (epic-shaped; no target version named in issue)
What the experts said:
format_option_refswire semantics on the buy side are unspecified in anything cited; feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741 and Add canonical creative format compatibility helpers #885 cover seller-side projection only. (2) Python work must gate on TypeScript #2391 RC closing the cross-language fixture contract before Python can implement without diverging. Rename ofFormatId({agent_url, id})is a semver-major event that cannot ship as a minor under the currentaliases.pyimport-layering contract.{agent_url, id}as internal plumbing. Blocker: Python RC validation is hollow without a frozen cross-language fixture set ratified against TS, Go, and Java simultaneously. Concern: the scope (six handler methods, new converter hook, three-version capability matrix, async/webhook normalization, RC cycle) is at minimum four to five PRs — needs explicit task breakdown before work starts.AdapterPairshims withDeprecationWarningfirst, then hardened at 4.0; the same pattern should apply here. Concern —Legacy*naming collides with existingV1Canonical*convention inaliases.py;AgentUrl*would be self-documenting and conflict-free. Three migration guide gaps:AdapterPair/is_legacy_shapebridge compat, example updates (hello_seller_creative.pyuses the old shape directly), and ~30aliases.pycross-module aliases that silently re-export the wrong type after a rename.My take: Experts converge on direction but surface two hard blockers and a structural concern. This is a semver-major, epic-shaped change that needs the TypeScript reference (#2391) to reach RC before Python implementation can begin, a phased rollout strategy (3.x shims → 4.0 hardening) rather than a single big-bang break, and an explicit task breakdown before any PRs are opened. Recommend @bokelley convert this to an epic with a task list once TS #2391 reaches RC.
Suggested task structure (not authoritative — human owns decomposition):
format_option_refswire semantics on buy-side creative manifestsAgentUrl*shim layer in 3.x minor withDeprecationWarningacross all public typeslegacy_format_converter/ canonical-to-legacy resolveraliases.pyauditTriaged by Claude Code. Session: https://claude.ai/code/session_01EhaQ2hZVwqtt8pcaaCGjge
Generated by Claude Code
bokelley commentedon Jul 26, 2026
Implementation clarification from the TypeScript RC work:
https://snapchat.com/.well-known/adagents.jsoncurrently returns 404, sopublisher_domain: "snapchat.com"discovery must fall back to that community mirror and reportsource: "aao_mirror".canonical_formats_only: trueand carry nov1_format_ref; they therefore do not authorize any{agent_url, id}legacy pairing. Seller/community catalogs participate in legacy projection only through an exact, owner-sensitivev1_format_ref(including dimensional discriminators). Public availability alone is insufficient.format_optionsentry. For partial projection, retain the product with mapped options and add sanitizedFORMAT_PROJECTION_FAILEDentries. If no option maps, omit the product from the canonical list and retain the non-fatal error in the standarderrors[]; never emitformat_options: [].errors[]is the portable multi-hop surface.format_kind + params. Same-process implementations may use bounded private route caches keyed by account + product/publisher option identity. Across restarts or package-only update/sync flows, require re-discovery/readback or an explicit canonical-to-legacy resolver backed by adopter storage.Please mirror these rules and the shared transition fixtures from adcontextprotocol/adcp-client#2391.
bokelley commentedon Jul 26, 2026
Triage
Classification: Feature request (major, breaking)
Bucket(s): client, handlers
Status: ready-for-human
Milestone: omitted (epic-shaped)
What the expert said (re: new rules):
format_option_refswire encoding (how a buyer serializes them into OpenRTB or equivalent) is still unspecified. Three new schema gaps surface:FORMAT_PROJECTION_FAILEDentry schema is undefined; Rule 2 requires "dimensional discriminators" forv1_format_refexact-match but doesn't enumerate them; Rule 3's three-tier cascade leaves same-ID collision resolution and what "approved" community mirror means operationally both open.What changes with these rules: The TS gate is partially lifted — discovery plumbing, three-tier resolver, catalog snapshot ingestion, and
source: "aao_mirror"tagging can begin without waiting for the RC to close. Fixture-locked test assertions still need the finalized cross-language fixtures from adcontextprotocol/adcp-client#2391.Two clarifications still needed before full task decomposition:
format_option_refswire encoding — likely warrants a sub-issue referencing the TS RC OpenRTB extension point.v1_format_refexact-match (Rule 2) — without them the legacy-projection gate predicate cannot be written and thecanonical_formats_only: trueguard cannot be correctly enforced.My take: The new rules meaningfully enrich the implementation brief and partially unlock scaffolding work. The issue remains epic-shaped with two hard open questions; recommend filing the two sub-issues above before decomposing into implementation tasks.
Triaged by Claude Code. Session: https://claude.ai/code/session_012CG8DwCpbwFK2adVj35cfK
Generated by Claude Code
bokelley commentedon Jul 27, 2026
Implementation update: the authoritative catalog aliases are now in adcontextprotocol/adcp#6028, and the reference TypeScript behavior is in adcontextprotocol/adcp-client#2391 (commit 63be3dde2). Cross-SDK parity should include more than kind lookup: extract unambiguous fixed width/height/duration from catalog renders/asset requirements; use AdCP URL canonicalization while preserving path/query scope; allow validated inline discriminators only for parameterized templates; and emit FORMAT_PROJECTION_FAILED with distinct invalid-parameter vs catalog-conflict reasons for partial, nonpositive, fractional, ranged/ambiguous, or contradictory values.
bokelley commentedon Jul 27, 2026
Triage
Classification: Feature request (major, breaking)
Bucket(s): client, handlers
Status: ready-for-human
Milestone: omitted (epic-shaped)
What the expert said (re: adcp#6028 + TS commit 63be3dde2):
renders[]or assetrequirementsfor dimensional values; this is net-new implementation work. FORMAT_PROJECTION_FAILED'sErrorCodeexists but the five sub-reason categories still lack a formaldetailsobject schema — partially resolves. Buy-sideformat_option_refsOpenRTB wire encoding does not resolve — still entirely unaddressed.My take: The adcp#6028 reference and TS commit 63be3dde2 enrich the brief and partially advance the dimensional-discriminator blocker, but both prior blockers remain open. A new scope item surfaces: dimension extraction from catalog renders. The issue is still epic-shaped; recommend @bokelley confirm whether adcp#6028 alias entries enumerate valid parameter ranges (not just canonical kind names), and file a sub-issue for the buy-side OpenRTB mapping.
Two open questions remain:
format_option_refswire encoding in OpenRTB — still unspecified; warrants a dedicated sub-issue referencing the TS RC extension point.Triaged by Claude Code. Session: https://claude.ai/code/session_01AA2VHWAmS5Fj7vbMdeHnaj
Generated by Claude Code
bokelley commentedon Jul 27, 2026
TypeScript reference behavior is now implemented in adcontextprotocol/adcp-client#2391:
{agent_url, id}first uses exact owner+ID catalog identity;Production coverage includes all 16 observed Vox, Triton, and OpenAds refs, plus an end-to-end Vox getProducts → create/update/sync exact-tuple regression. Please mirror these precedence and safety semantics rather than doing an unrestricted bare-ID match.
bokelley commentedon Jul 27, 2026
Triage
Classification: Feature request (major, breaking)
Bucket(s): client, handlers
Status: ready-for-human
Milestone: omitted (epic-shaped)
What the expert said (re: TS #2391 now implemented):
v1-canonical-mappingregistry, so the bare-ID AAO fallback has no concrete match set yet; (2) option-ID generation algorithm — must be spec-normative (not implementation-defined) to prevent cross-language fixture divergence; (3) durable catalog adapter interface — the TS adopter converter hook is now an instantiated contract that Python must mirror. Buy-sideformat_option_refswire encoding is entirely unaddressed; that track remains fully blocked.My take: The issue moves from "blocked on TS gate" to "inbound track unblocked, buy-side track still blocked" — two distinct workstreams that shouldn't wait on each other. Still epic-shaped (multi-PR, RC required, cross-language fixtures). Recommend @bokelley convert to an epic with a task list, separating the inbound-resolution track (now assignable, with TS #2391 as the normative reference) from the buy-side
format_option_refsencoding track (needs a dedicated spec contribution before it can proceed).Triaged by Claude Code. Session: https://claude.ai/code/session_0161dWfTq9GczgSYDt9J5Pxq
Generated by Claude Code