Skip to content

feat(types): export the legacy asset_type inference as a public helper #1308

Closed

Description

@bokelley

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 deprecated spec_compat_hooks();
  • adcp/compat/legacy/v2_5/sync_creatives.py:63-93, a second copy used by the v2.5 sync_creatives adapter.

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

  1. Export the rules once, for example from adcp.types or adcp.compat.legacy:

    • infer_asset_type(asset_key: str, asset: Mapping[str, Any]) -> str | None
    • coerce_legacy_assets(assets: Mapping[str, Any]) -> dict[str, Any] (inference plus the image to url demotion; returns a new dict)

    Have spec_compat and the v2.5 adapter call the public function instead of keeping their own copies.

  2. 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

  1. added
    enhancementNew feature or request
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    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:

    • code-reviewer: Non-breaking and additive; implementation path is clear, but from_legacy() classmethod must be injected via _ergonomic.py (not attached directly in legacy.py) to respect the import-layering contract enforced by tests/test_import_layering.py — a codegen re-run would otherwise erase it. Also recommends coerce_legacy_asset(key, asset) (single-asset) alongside coerce_legacy_assets to match the granularity of infer_asset_type, and notes _KNOWN_ASSET_TYPES must collapse to one copy.
    • dx-expert: adcp.types.legacy is the right export home (not adcp.compat.legacy, which is server-plumbing); from_legacy is worth shipping but must carry full type annotations (assets: Mapping[str, Mapping[str, Any]]) and a docstring naming the coercions applied; recommends reconsidering the name coerce_legacy_assets — upgrade_asset_types or normalize_assets_to_v3 would 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.py is the correct mechanism and is well-precedented in this codebase.

    Implementation scope:

    • Create adcp/compat/legacy/_asset_coerce.py (or add to adcp/types/legacy.py) as the single canonical home for _KNOWN_ASSET_TYPES, infer_asset_type, coerce_legacy_asset, and coerce_legacy_assets; export from adcp.types.legacy and adcp.compat.legacy (re-export only).
    • Replace the bodies of spec_compat._infer_asset_type / _coerce_asset and v2_5/sync_creatives._infer_asset_type / _coerce_asset with delegates to the new public functions; delete the duplicated _KNOWN_ASSET_TYPES sets.
    • Add LegacyCreativeAsset.from_legacy as a classmethod injected in _ergonomic.py (same pattern as existing BeforeValidator coercions); signature: from_legacy(cls, creative_id, name, format_id, assets: Mapping[str, Mapping[str, Any]], **kw) -> LegacyCreativeAsset.
    • Required checks: pytest tests/ (especially tests/test_import_layering.py and any compat/legacy/ tests), mypy src/adcp/types/, ruff check ., black --check ..
    • Non-breaking rationale: only new public symbols added; no existing public API changed or removed.

    Triaged by Claude Code. Session: https://claude.ai/code/session_01C28y5gn5Rf2g6ZP1L78Htf


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions