adcp 2.18.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

adcp/types/generated_poc/protocol/get_adcp_capabilities_response.py

@@ -0,0 +1,353 @@
+# generated by datamodel-codegen:
+#   filename:  protocol/get_adcp_capabilities_response.json
+#   timestamp: 2026-01-25T21:17:54+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, AwareDatetime, ConfigDict, Field, RootModel
+
+from ..core import context as context_1
+from ..core import error
+from ..core import ext as ext_1
+from ..core import media_buy_features
+from ..enums import channels
+from ..sponsored_intelligence import si_capabilities
+
+
+class MajorVersion(RootModel[int]):
+    root: Annotated[int, Field(ge=1)]
+
+
+class Adcp(AdCPBaseModel):
+    major_versions: Annotated[
+        list[MajorVersion],
+        Field(
+            description='AdCP major versions supported by this seller. Major versions indicate breaking changes.',
+            min_length=1,
+        ),
+    ]
+
+
+class ExtensionsSupportedItem(RootModel[str]):
+    root: Annotated[
+        str,
+        Field(
+            description="Extension namespace (lowercase alphanumeric with underscores, e.g., 'scope3', 'garm', 'iab_tcf')",
+            pattern='^[a-z][a-z0-9_]*$',
+        ),
+    ]
+
+
+class Range(AdCPBaseModel):
+    max: Annotated[float, Field(description='Maximum value')]
+    min: Annotated[float, Field(description='Minimum value')]
+
+
+class Type(Enum):
+    binary = 'binary'
+    quantitative = 'quantitative'
+    categorical = 'categorical'
+
+
+class PropertyFeature(AdCPBaseModel):
+    categories: Annotated[
+        list[str] | None, Field(description='For categorical features, the valid values')
+    ] = None
+    description: Annotated[
+        str | None, Field(description='Human-readable description of what this feature measures')
+    ] = None
+    feature_id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for this feature (e.g., 'consent_quality', 'coppa_certified', 'carbon_score')"
+        ),
+    ]
+    methodology_url: Annotated[
+        AnyUrl | None,
+        Field(
+            description='URL to documentation explaining how this feature is calculated or measured. Helps buyers understand and compare methodologies across vendors.'
+        ),
+    ] = None
+    range: Annotated[
+        Range | None, Field(description='For quantitative features, the valid range')
+    ] = None
+    type: Annotated[
+        Type,
+        Field(
+            description="Data type: 'binary' for yes/no, 'quantitative' for numeric scores, 'categorical' for enum values"
+        ),
+    ]
+
+
+class Governance(AdCPBaseModel):
+    property_features: Annotated[
+        list[PropertyFeature] | None,
+        Field(
+            description='Property features this governance agent can evaluate. Each feature describes a score, rating, or certification the agent can provide for properties.'
+        ),
+    ] = None
+
+
+class MraidVersion(RootModel[str]):
+    root: Annotated[str, Field(pattern='^[0-9]+\\.[0-9]+$')]
+
+
+class VastVersion(MraidVersion):
+    pass
+
+
+class CreativeSpecs(AdCPBaseModel):
+    mraid_versions: Annotated[
+        list[MraidVersion] | None,
+        Field(description='MRAID versions supported for rich media mobile creatives'),
+    ] = None
+    simid: Annotated[bool | None, Field(description='SIMID support for interactive video ads')] = (
+        None
+    )
+    vast_versions: Annotated[
+        list[VastVersion] | None, Field(description='VAST versions supported for video creatives')
+    ] = None
+    vpaid: Annotated[bool | None, Field(description='VPAID support for interactive video ads')] = (
+        None
+    )
+
+
+class GeoMetros(AdCPBaseModel):
+    eurostat_nuts2: Annotated[
+        bool | None, Field(description='Supports Eurostat NUTS Level 2 regions (EU)')
+    ] = None
+    nielsen_dma: Annotated[
+        bool | None,
+        Field(description="Supports Nielsen DMA codes (US market, e.g., '501' for NYC)"),
+    ] = None
+    uk_itl1: Annotated[bool | None, Field(description='Supports UK ITL Level 1 regions')] = None
+    uk_itl2: Annotated[bool | None, Field(description='Supports UK ITL Level 2 regions')] = None
+
+
+class GeoPostalAreas(AdCPBaseModel):
+    au_postcode: Annotated[
+        bool | None, Field(description="Australian postcode, 4 digits (e.g., '2000')")
+    ] = None
+    ca_fsa: Annotated[
+        bool | None, Field(description="Canadian Forward Sortation Area (e.g., 'K1A')")
+    ] = None
+    ca_full: Annotated[
+        bool | None, Field(description="Canadian full postal code (e.g., 'K1A 0B1')")
+    ] = None
+    de_plz: Annotated[
+        bool | None, Field(description="German Postleitzahl, 5 digits (e.g., '10115')")
+    ] = None
+    fr_code_postal: Annotated[
+        bool | None, Field(description="French code postal, 5 digits (e.g., '75001')")
+    ] = None
+    gb_full: Annotated[bool | None, Field(description="UK full postcode (e.g., 'SW1A 1AA')")] = None
+    gb_outward: Annotated[
+        bool | None, Field(description="UK postcode district / outward code (e.g., 'SW1', 'EC1')")
+    ] = None
+    us_zip: Annotated[bool | None, Field(description="US 5-digit ZIP codes (e.g., '10001')")] = None
+    us_zip_plus_four: Annotated[
+        bool | None, Field(description="US 9-digit ZIP+4 codes (e.g., '10001-1234')")
+    ] = None
+
+
+class Targeting(AdCPBaseModel):
+    geo_countries: Annotated[
+        bool | None,
+        Field(
+            description="Supports country-level geo targeting using ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE')"
+        ),
+    ] = None
+    geo_metros: Annotated[
+        GeoMetros | None,
+        Field(
+            description='Metro area targeting support. Specifies which classification systems are supported.'
+        ),
+    ] = None
+    geo_postal_areas: Annotated[
+        GeoPostalAreas | None,
+        Field(
+            description='Postal area targeting support. Specifies which postal code systems are supported. System names encode country and precision.'
+        ),
+    ] = None
+    geo_regions: Annotated[
+        bool | None,
+        Field(
+            description="Supports region/state-level geo targeting using ISO 3166-2 subdivision codes (e.g., 'US-NY', 'GB-SCT', 'DE-BY')"
+        ),
+    ] = None
+
+
+class Execution(AdCPBaseModel):
+    axe_integrations: Annotated[
+        list[AnyUrl] | None,
+        Field(
+            description='Agentic ad exchange (AXE) integrations supported. URLs are canonical identifiers for exchanges this seller can execute through.'
+        ),
+    ] = None
+    creative_specs: Annotated[
+        CreativeSpecs | None, Field(description='Creative specification support')
+    ] = None
+    targeting: Annotated[
+        Targeting | None,
+        Field(
+            description='Targeting capabilities. If declared true/supported, buyer can use these targeting parameters and seller MUST honor them.'
+        ),
+    ] = None
+
+
+class PrimaryCountry(RootModel[str]):
+    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]
+
+
+class PublisherDomain(RootModel[str]):
+    root: Annotated[
+        str, Field(pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$')
+    ]
+
+
+class Portfolio(AdCPBaseModel):
+    advertising_policies: Annotated[
+        str | None,
+        Field(
+            description='Advertising content policies, restrictions, and guidelines',
+            max_length=10000,
+        ),
+    ] = None
+    description: Annotated[
+        str | None,
+        Field(
+            description='Markdown-formatted description of the inventory portfolio', max_length=5000
+        ),
+    ] = None
+    primary_channels: Annotated[
+        list[channels.MediaChannel] | None,
+        Field(description='Primary advertising channels in this portfolio'),
+    ] = None
+    primary_countries: Annotated[
+        list[PrimaryCountry] | None,
+        Field(description='Primary countries (ISO 3166-1 alpha-2) where inventory is concentrated'),
+    ] = None
+    publisher_domains: Annotated[
+        list[PublisherDomain],
+        Field(
+            description="Publisher domains this seller is authorized to represent. Buyers should fetch each publisher's adagents.json for property definitions.",
+            min_length=1,
+        ),
+    ]
+
+
+class Signals(AdCPBaseModel):
+    features: Annotated[
+        dict[str, bool] | None, Field(description='Optional signals features supported')
+    ] = None
+
+
+class Preferred(Enum):
+    mcp = 'mcp'
+    a2a = 'a2a'
+
+
+class Transport(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    type: Annotated[Preferred, Field(description='Protocol transport type')]
+    url: Annotated[AnyUrl, Field(description='Agent endpoint URL for this transport')]
+
+
+class Endpoint(AdCPBaseModel):
+    preferred: Annotated[
+        Preferred | None, Field(description='Preferred transport when host supports multiple')
+    ] = None
+    transports: Annotated[
+        list[Transport],
+        Field(
+            description='Available protocol transports. Hosts select based on their capabilities.',
+            min_length=1,
+        ),
+    ]
+
+
+class SupportedProtocol(Enum):
+    media_buy = 'media_buy'
+    signals = 'signals'
+    governance = 'governance'
+    sponsored_intelligence = 'sponsored_intelligence'
+
+
+class MediaBuy(AdCPBaseModel):
+    execution: Annotated[
+        Execution | None, Field(description='Technical execution capabilities for media buying')
+    ] = None
+    features: media_buy_features.MediaBuyFeatures | None = None
+    portfolio: Annotated[
+        Portfolio | None,
+        Field(description="Information about the seller's media inventory portfolio"),
+    ] = None
+
+
+class SponsoredIntelligence(AdCPBaseModel):
+    brand_manifest_url: Annotated[
+        AnyUrl | None, Field(description='URL to brand manifest with colors, fonts, logos, tone')
+    ] = None
+    capabilities: Annotated[
+        si_capabilities.SiCapabilities,
+        Field(description='Modalities, components, and commerce capabilities'),
+    ]
+    endpoint: Annotated[Endpoint, Field(description='SI agent endpoint configuration')]
+
+
+class GetAdcpCapabilitiesResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    adcp: Annotated[Adcp, Field(description='Core AdCP protocol information')]
+    context: context_1.ContextObject | None = None
+    errors: Annotated[
+        list[error.Error] | None, Field(description='Task-specific errors and warnings')
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    extensions_supported: Annotated[
+        list[ExtensionsSupportedItem] | None,
+        Field(
+            description='Extension namespaces this agent supports. Buyers can expect meaningful data in ext.{namespace} fields on responses from this agent. Extension schemas are published in the AdCP extension registry.'
+        ),
+    ] = None
+    governance: Annotated[
+        Governance | None,
+        Field(
+            description='Governance protocol capabilities. Only present if governance is in supported_protocols. Governance agents provide property data like compliance scores, brand safety ratings, and sustainability metrics.'
+        ),
+    ] = None
+    last_updated: Annotated[
+        AwareDatetime | None,
+        Field(
+            description='ISO 8601 timestamp of when capabilities were last updated. Buyers can use this for cache invalidation.'
+        ),
+    ] = None
+    media_buy: Annotated[
+        MediaBuy | None,
+        Field(
+            description='Media-buy protocol capabilities. Only present if media_buy is in supported_protocols.'
+        ),
+    ] = None
+    signals: Annotated[
+        Signals | None,
+        Field(
+            description='Signals protocol capabilities. Only present if signals is in supported_protocols. Reserved for future use.'
+        ),
+    ] = None
+    sponsored_intelligence: Annotated[
+        SponsoredIntelligence | None,
+        Field(
+            description='Sponsored Intelligence protocol capabilities. Only present if sponsored_intelligence is in supported_protocols. SI agents handle conversational brand experiences.'
+        ),
+    ] = None
+    supported_protocols: Annotated[
+        list[SupportedProtocol],
+        Field(description='Which AdCP domain protocols this seller supports', min_length=1),
+    ]

adcp/types/generated_poc/protocols/adcp_extension.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  protocols/adcp_extension.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -8,7 +8,11 @@ from enum import Enum
 from typing import Annotated
 
 from adcp.types.base import AdCPBaseModel
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, RootModel
+
+
+class ExtensionsSupportedItem(RootModel[str]):
+    root: Annotated[str, Field(pattern='^[a-z][a-z0-9_]*$')]
 
 
 class ProtocolsSupportedEnum(Enum):
@@ -17,21 +21,30 @@ class ProtocolsSupportedEnum(Enum):
     signals = 'signals'
 
 
-class AdcpAgentCardExtension(AdCPBaseModel):
+class AdcpAgentCardExtensionParamsDeprecated(AdCPBaseModel):
     model_config = ConfigDict(
         extra='allow',
     )
     adcp_version: Annotated[
         str,
         Field(
-            description="Semantic version of the AdCP specification this agent implements (e.g., '2.4.0')",
+            deprecated=True,
+            description='DEPRECATED: Use get_adcp_capabilities response adcp.major_versions instead.',
             pattern='^\\d+\\.\\d+\\.\\d+$',
         ),
     ]
+    extensions_supported: Annotated[
+        list[ExtensionsSupportedItem] | None,
+        Field(
+            deprecated=True,
+            description='DEPRECATED: Typed extensions can be declared in get_adcp_capabilities ext field.',
+        ),
+    ] = None
     protocols_supported: Annotated[
         list[ProtocolsSupportedEnum],
         Field(
-            description='AdCP protocol domains supported by this agent. At least one must be specified.',
+            deprecated=True,
+            description='DEPRECATED: Use get_adcp_capabilities response supported_protocols instead.',
             min_length=1,
         ),
     ]

adcp/types/generated_poc/signals/activate_signal_request.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/activate_signal_request.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 

adcp/types/generated_poc/signals/activate_signal_response.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/activate_signal_response.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 

adcp/types/generated_poc/signals/get_signals_request.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/get_signals_request.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 

adcp/types/generated_poc/signals/get_signals_response.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/get_signals_response.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 

adcp/types/generated_poc/sponsored_intelligence/__init__.py

@@ -0,0 +1,3 @@
+# generated by datamodel-codegen:
+#   filename:  .schema_temp
+#   timestamp: 2026-01-25T21:17:54+00:00

adcp/types/generated_poc/sponsored_intelligence/si_capabilities.py

@@ -0,0 +1,102 @@
+# generated by datamodel-codegen:
+#   filename:  sponsored_intelligence/si_capabilities.json
+#   timestamp: 2026-01-25T21:17:54+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class Commerce(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    acp_checkout: Annotated[
+        bool | None, Field(description='Supports ACP (Agentic Commerce Protocol) checkout handoff')
+    ] = None
+
+
+class StandardEnum(Enum):
+    text = 'text'
+    link = 'link'
+    image = 'image'
+    product_card = 'product_card'
+    carousel = 'carousel'
+    action_button = 'action_button'
+
+
+class Components(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    extensions: Annotated[
+        dict[str, Any] | None,
+        Field(description='Platform-specific extensions (chatgpt_apps_sdk, maps, forms, etc.)'),
+    ] = None
+    standard: Annotated[
+        list[StandardEnum] | None,
+        Field(description='Standard components that all SI hosts must render'),
+    ] = None
+
+
+class Avatar(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    avatar_id: Annotated[str | None, Field(description='Brand avatar identifier')] = None
+    provider: Annotated[
+        str | None, Field(description='Avatar provider (d-id, heygen, synthesia, etc.)')
+    ] = None
+
+
+class Video(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    formats: Annotated[
+        list[str] | None, Field(description='Supported video formats (mp4, webm, etc.)')
+    ] = None
+    max_duration_seconds: Annotated[int | None, Field(description='Maximum video duration')] = None
+
+
+class Voice(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    provider: Annotated[
+        str | None, Field(description='TTS provider (elevenlabs, openai, etc.)')
+    ] = None
+    voice_id: Annotated[str | None, Field(description='Brand voice identifier')] = None
+
+
+class Modalities(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    avatar: Annotated[
+        bool | Avatar | None, Field(description='Animated video presence with brand avatar')
+    ] = None
+    conversational: Annotated[
+        bool | None, Field(description='Pure text exchange - the baseline modality')
+    ] = True
+    video: Annotated[bool | Video | None, Field(description='Brand video content playback')] = None
+    voice: Annotated[
+        bool | Voice | None, Field(description='Audio-based interaction using brand voice')
+    ] = None
+
+
+class SiCapabilities(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    commerce: Annotated[Commerce | None, Field(description='Commerce capabilities')] = None
+    components: Annotated[Components | None, Field(description='Visual components supported')] = (
+        None
+    )
+    modalities: Annotated[
+        Modalities | None, Field(description='Interaction modalities supported')
+    ] = None

adcp/types/generated_poc/sponsored_intelligence/si_get_offering_request.py

@@ -0,0 +1,34 @@
+# generated by datamodel-codegen:
+#   filename:  sponsored_intelligence/si_get_offering_request.json
+#   timestamp: 2026-01-25T21:17:54+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from ..core import ext as ext_1
+
+
+class SiGetOfferingRequest(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    context: Annotated[
+        str | None,
+        Field(
+            description="Optional natural language context about user intent for personalized results (e.g., 'mens size 14 near Cincinnati'). Must be anonymous - no PII."
+        ),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    include_products: Annotated[
+        bool | None, Field(description='Whether to include matching products in the response')
+    ] = False
+    offering_id: Annotated[
+        str, Field(description='Offering identifier from promoted offerings to get details for')
+    ]
+    product_limit: Annotated[
+        int | None, Field(description='Maximum number of matching products to return', ge=1, le=50)
+    ] = 5

adcp/types/generated_poc/sponsored_intelligence/si_get_offering_response.py

@@ -0,0 +1,100 @@
+# generated by datamodel-codegen:
+#   filename:  sponsored_intelligence/si_get_offering_response.json
+#   timestamp: 2026-01-25T21:17:54+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, AwareDatetime, ConfigDict, Field
+
+from ..core import error
+from ..core import ext as ext_1
+
+
+class MatchingProduct(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    availability_summary: Annotated[
+        str | None,
+        Field(
+            description="Brief availability info (e.g., 'In stock', 'Size 14 available', '3 left')"
+        ),
+    ] = None
+    image_url: Annotated[AnyUrl | None, Field(description='Product image')] = None
+    name: Annotated[str, Field(description='Product name')]
+    original_price: Annotated[str | None, Field(description='Original price if on sale')] = None
+    price: Annotated[str | None, Field(description="Display price (e.g., '$129', '$89.99')")] = None
+    product_id: Annotated[str, Field(description='Product identifier')]
+    url: Annotated[AnyUrl | None, Field(description='Product detail page URL')] = None
+
+
+class Offering(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    expires_at: Annotated[AwareDatetime | None, Field(description='When this offering expires')] = (
+        None
+    )
+    image_url: Annotated[AnyUrl | None, Field(description='Hero image for the offering')] = None
+    landing_url: Annotated[AnyUrl | None, Field(description='Landing page URL')] = None
+    offering_id: Annotated[str | None, Field(description='Offering identifier')] = None
+    price_hint: Annotated[
+        str | None, Field(description="Price indication (e.g., 'from $199', '50% off')")
+    ] = None
+    summary: Annotated[str | None, Field(description='Brief summary of the offering')] = None
+    tagline: Annotated[str | None, Field(description='Short promotional tagline')] = None
+    title: Annotated[str | None, Field(description='Offering title')] = None
+
+
+class SiGetOfferingResponse(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    alternative_offering_ids: Annotated[
+        list[str] | None,
+        Field(description='Alternative offerings to consider if this one is unavailable'),
+    ] = None
+    available: Annotated[bool, Field(description='Whether the offering is currently available')]
+    checked_at: Annotated[
+        AwareDatetime | None, Field(description='When this offering information was retrieved')
+    ] = None
+    errors: Annotated[
+        list[error.Error] | None, Field(description='Errors during offering lookup')
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    matching_products: Annotated[
+        list[MatchingProduct] | None,
+        Field(
+            description='Products matching the request context. Only included if include_products was true.'
+        ),
+    ] = None
+    offering: Annotated[Offering | None, Field(description='Offering details')] = None
+    offering_token: Annotated[
+        str | None,
+        Field(
+            description="Token to pass to si_initiate_session for session continuity. Brand stores the full query context server-side (products shown, order, context) so they can resolve references like 'the second one' when the session starts."
+        ),
+    ] = None
+    total_matching: Annotated[
+        int | None,
+        Field(
+            description='Total number of products matching the context (may be more than returned in matching_products)',
+            ge=0,
+        ),
+    ] = None
+    ttl_seconds: Annotated[
+        int | None,
+        Field(
+            description='How long this offering information is valid (seconds). Host should re-fetch after TTL expires.',
+            ge=0,
+        ),
+    ] = None
+    unavailable_reason: Annotated[
+        str | None,
+        Field(
+            description="If not available, why (e.g., 'expired', 'sold_out', 'region_restricted')"
+        ),
+    ] = None