Repository navigation
Description
Summary
The SDK correctly requires the asset_type discriminator on every creative asset. For pre-v3 payloads that omit it, the SDK has inference rules: an exact asset-key match, then field presence (url with dims is image, url alone is url, content is text), plus the image to url demotion when dims are missing. On 8.0.0 those rules only run inside request adapters, and every copy is private:
adcp/server/spec_compat.py:103-150(_infer_asset_type,_coerce_asset), behind the deprecatedspec_compat_hooks();adcp/compat/legacy/v2_5/sync_creatives.py:63-93, a second copy used by the v2.5sync_creativesadapter.
The spec_compat docstring (spec_compat.py:277-279) tells adopters to copy adcp.server.spec_compat._coerce_asset. To be clear, this is not a validation bug. It's a missing public helper for adopters who meet legacy asset dicts outside the inbound wire path.
Reproduction (adcp 8.0.0)
import adcp.compat.legacy.v2_5.sync_creatives as legacy_v25
import adcp.server.spec_compat as spec_compat
from adcp.types import LegacyCreativeAsset
FID = {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_300x250"}
assets = {"banner": {"url": "https://cdn.example/b.png", "width": 300, "height": 250},
"headline": {"content": "Hello"}}
try:
LegacyCreativeAsset(creative_id="c1", name="c1", format_id=FID, assets=assets)
except Exception as exc:
for error in exc.errors()[::2]:
print(error["loc"], "|", error["msg"])
for mod in (spec_compat, legacy_v25):
public = [n for n in dir(mod) if "asset" in n.lower() and not n.startswith("_")]
private = [n for n in ("_infer_asset_type", "_coerce_asset") if hasattr(mod, n)]
print(f"{mod.__name__}: public={public} private={private}")
fixed = {key: legacy_v25._coerce_asset(key, value) for key, value in assets.items()}
print("with private _coerce_asset:", type(LegacyCreativeAsset(creative_id="c1", name="c1", format_id=FID, assets=fixed)).__name__)Output:
('assets', 'banner', 'AssetVariant') | Unable to extract tag using discriminator 'asset_type'
('assets', 'headline', 'AssetVariant') | Unable to extract tag using discriminator 'asset_type'
adcp.server.spec_compat: public=[] private=['_infer_asset_type', '_coerce_asset']
adcp.compat.legacy.v2_5.sync_creatives: public=[] private=['_infer_asset_type', '_coerce_asset']
with private _coerce_asset: CreativeAsset
Why an adopter hits this
A seller stores creatives that arrived over several protocol versions, and it builds LegacyCreativeAsset from internal flows, stored rows and fixtures, not only from inbound sync_creatives. Those paths never pass through the request adapter.
Embedded Sales Agent copies the rules into src/core/schemas/_asset_type_compat.py (145 LOC). It also wraps LegacyCreativeAsset.__init__ at import time so every construction applies them, and reuses the same copy in its sync and listing paths. That makes three copies of one rule set (two in the SDK, one in ESA). When the SDK adds an asset type or changes the demotion rule, ESA's copy goes stale without any signal.
Ask
-
Export the rules once, for example from
adcp.typesoradcp.compat.legacy:infer_asset_type(asset_key: str, asset: Mapping[str, Any]) -> str | Nonecoerce_legacy_assets(assets: Mapping[str, Any]) -> dict[str, Any](inference plus theimagetourldemotion; returns a new dict)
Have
spec_compatand the v2.5 adapter call the public function instead of keeping their own copies. -
Optionally, add an opt-in model-level entry point, e.g.
LegacyCreativeAsset.from_legacy(**data), so adopters don't need to patch__init__. Strict construction stays the default.
Activity
bokelley commentedon Oct 2, 2026
Triage
Classification: Feature request
Bucket(s): types surface, compat/legacy layer (no matching repo label found — noting gap in run summary)
Status: ready-to-implement
Milestone: (omitted — no version target in issue)
What the experts said:
from_legacy()classmethod must be injected via_ergonomic.py(not attached directly inlegacy.py) to respect the import-layering contract enforced bytests/test_import_layering.py— a codegen re-run would otherwise erase it. Also recommendscoerce_legacy_asset(key, asset)(single-asset) alongsidecoerce_legacy_assetsto match the granularity ofinfer_asset_type, and notes_KNOWN_ASSET_TYPESmust collapse to one copy.adcp.types.legacyis the right export home (notadcp.compat.legacy, which is server-plumbing);from_legacyis worth shipping but must carry full type annotations (assets: Mapping[str, Mapping[str, Any]]) and a docstring naming the coercions applied; recommends reconsidering the namecoerce_legacy_assets—upgrade_asset_typesornormalize_assets_to_v3would make the direction unambiguous.My take: Both experts converge: purely additive, non-breaking, and the ESA case is a compelling justification (three copies of one rule, no divergence signal). The only non-trivial design call is the injection path for
from_legacy;_ergonomic.pyis the correct mechanism and is well-precedented in this codebase.Implementation scope:
adcp/compat/legacy/_asset_coerce.py(or add toadcp/types/legacy.py) as the single canonical home for_KNOWN_ASSET_TYPES,infer_asset_type,coerce_legacy_asset, andcoerce_legacy_assets; export fromadcp.types.legacyandadcp.compat.legacy(re-export only).spec_compat._infer_asset_type/_coerce_assetandv2_5/sync_creatives._infer_asset_type/_coerce_assetwith delegates to the new public functions; delete the duplicated_KNOWN_ASSET_TYPESsets.LegacyCreativeAsset.from_legacyas a classmethod injected in_ergonomic.py(same pattern as existingBeforeValidatorcoercions); signature:from_legacy(cls, creative_id, name, format_id, assets: Mapping[str, Mapping[str, Any]], **kw) -> LegacyCreativeAsset.pytest tests/(especiallytests/test_import_layering.pyand anycompat/legacy/tests),mypy src/adcp/types/,ruff check .,black --check ..Triaged by Claude Code. Session: https://claude.ai/code/session_01C28y5gn5Rf2g6ZP1L78Htf
Generated by Claude Code