feat: enforce strict AdCP v1 spec compliance for Creative model (BREAKING CHANGE)

[bokelley]

Summary

This PR removes all non-spec fields from the Creative model and refactors creative conversion to extract data from the AdCP-compliant assets dict instead of top-level fields. This resolves issue #703 where inline creatives were incorrectly required to have response-only fields.

Breaking Change

⚠️ BREAKING CHANGE: Removed 20+ non-spec fields from Creative model. Clients must update to use assets dict format per AdCP v1 spec.

Key Changes

1. Creative Model (src/core/schemas.py)

• REMOVED 20+ non-spec fields:

  • url/content_uri (use assets dict)
  • media_url (use assets dict)
  • click_url (use URL asset with url_type="clickthrough")
  • width, height, duration (use asset objects)
  • snippet, snippet_type (use HTML/JavaScript/VAST assets)
  • template_variables (use text assets)
  • delivery_settings, package_assignments (internal fields)
  • platform_id, review_feedback, compliance (internal fields)

• KEPT AdCP v1 spec fields only:

  • Required: creative_id, name, format_id, assets
  • Optional: inputs, tags, approved
  • Internal: principal_id, created_at, updated_at, status

2. Creative Conversion (src/core/helpers/creative_helpers.py)

Complete rewrite of _convert_creative_to_adapter_asset():

• Extract all data from assets dict (per AdCP v1 spec)
• Detect asset types from structure (no asset_type field in spec)
• Use spec-compliant field names (duration_ms, tracker_pixel/tracker_script)
• Fall back to role name matching when url_type missing

3. sync_creatives & list_creatives Tools

• Refactored to only use AdCP v1 spec fields
• Added legacy data migration for list_creatives

4. Documentation

• Created AUDIT_non_spec_fields.md - Analysis of removed fields
• Created ASSET_TYPE_MAPPING.md - Spec-compliant asset mappings for all types
• Created docs/architecture/creative-model-architecture.md - Architecture explanation

5. Tests

• Updated 7 test files to use new Creative format
• Added comprehensive test_creative_conversion_assets.py with 8 tests for all asset types
• All 874 unit tests pass

Migration Guide

Before (non-compliant):

creative = Creative(
    creative_id="banner_123",
    name="Example Banner",
    format_id="display_300x250",  # String (wrong)
    url="https://example.com/image.png",  # Top-level (wrong)
    width=300,  # Top-level (wrong)
    height=250,  # Top-level (wrong)
    click_url="https://example.com/landing"  # Top-level (wrong)
)

After (AdCP v1 compliant):

creative = Creative(
    creative_id="banner_123",
    name="Example Banner",
    format_id=FormatId(  # FormatId object (correct)
        agent_url="https://creatives.adcontextprotocol.org",
        id="display_300x250"
    ),
    assets={  # All content in assets dict (correct)
        "banner_image": {
            "url": "https://example.com/image.png",
            "width": 300,
            "height": 250
        },
        "click_url": {
            "url": "https://example.com/landing",
            "url_type": "clickthrough"
        }
    }
)

Fixes

• Fixes sync_creatives doesn't accept examples from adcp sync_creatives task reference #703 - Inline creatives now work correctly without requiring response-only fields
• Removes 20+ non-spec fields that caused confusion and spec violations
• Ensures GAM adapter correctly extracts creative data from assets dict

Test Plan

• ✅ All 874 unit tests pass
• ✅ All 32 integration tests pass
• ✅ All 28 integration_v2 tests pass
• ✅ Creative conversion tests cover all asset types (image, video, html, javascript, vast)

🤖 Generated with Claude Code