adcp 2.19.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

adcp/types/generated_poc/core/product_filters.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/product_filters.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-26T11:40:01+00:00
 
 from __future__ import annotations
 
@@ -8,90 +8,155 @@ from datetime import date
 from typing import Annotated
 
 from adcp.types.base import AdCPBaseModel
-from pydantic import ConfigDict, Field, RootModel
+from pydantic import AnyUrl, ConfigDict, Field, RootModel
 
 from ..enums import channels as channels_1
 from ..enums import delivery_type as delivery_type_1
-from ..enums import format_category
-from . import format_id
+from ..enums import format_category, geo_level, metro_system
+from . import format_id, media_buy_features
 
 
 class BudgetRange(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     currency: Annotated[
         str,
         Field(
-            description="ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')", pattern="^[A-Z]{3}$"
+            description="ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')", pattern='^[A-Z]{3}$'
         ),
     ]
-    max: Annotated[float | None, Field(description="Maximum budget amount", ge=0.0)] = None
-    min: Annotated[float, Field(description="Minimum budget amount", ge=0.0)]
+    max: Annotated[float | None, Field(description='Maximum budget amount', ge=0.0)] = None
+    min: Annotated[float, Field(description='Minimum budget amount', ge=0.0)]
 
 
 class BudgetRange1(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     currency: Annotated[
         str,
         Field(
-            description="ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')", pattern="^[A-Z]{3}$"
+            description="ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')", pattern='^[A-Z]{3}$'
         ),
     ]
-    max: Annotated[float, Field(description="Maximum budget amount", ge=0.0)]
-    min: Annotated[float | None, Field(description="Minimum budget amount", ge=0.0)] = None
+    max: Annotated[float, Field(description='Maximum budget amount', ge=0.0)]
+    min: Annotated[float | None, Field(description='Minimum budget amount', ge=0.0)] = None
 
 
 class Country(RootModel[str]):
-    root: Annotated[str, Field(pattern="^[A-Z]{2}$")]
+    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]
+
+
+class Metro(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    code: Annotated[
+        str, Field(description="Metro code within the system (e.g., '501' for NYC DMA)")
+    ]
+    system: Annotated[
+        metro_system.MetroAreaSystem, Field(description='Metro classification system')
+    ]
+
+
+class Region(RootModel[str]):
+    root: Annotated[str, Field(pattern='^[A-Z]{2}-[A-Z0-9]+$')]
+
+
+class RequiredGeoTargetingItem(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    level: Annotated[
+        geo_level.GeographicTargetingLevel,
+        Field(description='Geographic targeting level (country, region, metro, postal_area)'),
+    ]
+    system: Annotated[
+        str | None,
+        Field(
+            description="Classification system within the level. Required for metro (e.g., 'nielsen_dma') and postal_area (e.g., 'us_zip'). Not applicable for country/region which use ISO standards."
+        ),
+    ] = None
 
 
 class ProductFilters(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     budget_range: Annotated[
         BudgetRange | BudgetRange1 | None,
-        Field(description="Budget range to filter appropriate products"),
+        Field(description='Budget range to filter appropriate products'),
     ] = None
     channels: Annotated[
-        list[channels_1.AdvertisingChannels] | None,
+        list[channels_1.MediaChannel] | None,
         Field(description="Filter by advertising channels (e.g., ['display', 'video', 'dooh'])"),
     ] = None
     countries: Annotated[
         list[Country] | None,
         Field(
-            description="Filter by target countries using ISO 3166-1 alpha-2 country codes (e.g., ['US', 'CA', 'GB'])"
+            description="Filter by country coverage using ISO 3166-1 alpha-2 codes (e.g., ['US', 'CA', 'GB']). Works for all inventory types."
         ),
     ] = None
     delivery_type: delivery_type_1.DeliveryType | None = None
     end_date: Annotated[
         date | None,
         Field(
-            description="Campaign end date (ISO 8601 date format: YYYY-MM-DD) for availability checks"
+            description='Campaign end date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
         ),
     ] = None
     format_ids: Annotated[
-        list[format_id.FormatId] | None, Field(description="Filter by specific format IDs")
+        list[format_id.FormatId] | None, Field(description='Filter by specific format IDs')
     ] = None
     format_types: Annotated[
-        list[format_category.FormatCategory] | None, Field(description="Filter by format types")
+        list[format_category.FormatCategory] | None, Field(description='Filter by format types')
     ] = None
     is_fixed_price: Annotated[
-        bool | None, Field(description="Filter for fixed price vs auction products")
+        bool | None,
+        Field(
+            description='Filter by pricing availability: true = products offering fixed pricing (at least one option with fixed_price), false = products offering auction pricing (at least one option without fixed_price). Products with both fixed and auction options match both true and false.'
+        ),
+    ] = None
+    metros: Annotated[
+        list[Metro] | None,
+        Field(
+            description='Filter by metro coverage for locally-bound inventory (radio, DOOH, local TV). Use when products have DMA/metro-specific coverage. For digital inventory where products have broad coverage, use required_geo_targeting instead to filter by seller capability.'
+        ),
     ] = None
     min_exposures: Annotated[
         int | None,
-        Field(description="Minimum exposures/impressions needed for measurement validity", ge=1),
+        Field(description='Minimum exposures/impressions needed for measurement validity', ge=1),
+    ] = None
+    regions: Annotated[
+        list[Region] | None,
+        Field(
+            description="Filter by region coverage using ISO 3166-2 codes (e.g., ['US-NY', 'US-CA', 'GB-SCT']). Use for locally-bound inventory (regional OOH, local TV) where products have region-specific coverage."
+        ),
+    ] = None
+    required_axe_integrations: Annotated[
+        list[AnyUrl] | None,
+        Field(
+            description='Filter to products executable through specific agentic ad exchanges. URLs are canonical identifiers.'
+        ),
+    ] = None
+    required_features: Annotated[
+        media_buy_features.MediaBuyFeatures | None,
+        Field(
+            description='Filter to products from sellers supporting specific protocol features. Only features set to true are used for filtering.'
+        ),
+    ] = None
+    required_geo_targeting: Annotated[
+        list[RequiredGeoTargetingItem] | None,
+        Field(
+            description='Filter to products from sellers supporting specific geo targeting capabilities. Each entry specifies a targeting level (country, region, metro, postal_area) and optionally a system for levels that have multiple classification systems.'
+        ),
     ] = None
     standard_formats_only: Annotated[
-        bool | None, Field(description="Only return products accepting IAB standard formats")
+        bool | None, Field(description='Only return products accepting IAB standard formats')
     ] = None
     start_date: Annotated[
         date | None,
         Field(
-            description="Campaign start date (ISO 8601 date format: YYYY-MM-DD) for availability checks"
+            description='Campaign start date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
         ),
     ] = None

adcp/types/generated_poc/core/promoted_offerings.py

@@ -1,41 +1,41 @@
 # generated by datamodel-codegen:
 #   filename:  core/promoted_offerings.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
 from enum import Enum
-from typing import Annotated, Any
+from typing import Annotated
 
 from adcp.types.base import AdCPBaseModel
-from pydantic import ConfigDict, Field
+from pydantic import AnyUrl, ConfigDict, Field
 
-from . import brand_manifest_ref, promoted_products
+from . import brand_manifest_ref, offering, promoted_products
 
 
 class AssetType(Enum):
-    image = "image"
-    video = "video"
-    audio = "audio"
-    vast = "vast"
-    daast = "daast"
-    text = "text"
-    url = "url"
-    html = "html"
-    css = "css"
-    javascript = "javascript"
-    webhook = "webhook"
+    image = 'image'
+    video = 'video'
+    audio = 'audio'
+    vast = 'vast'
+    daast = 'daast'
+    text = 'text'
+    url = 'url'
+    html = 'html'
+    css = 'css'
+    javascript = 'javascript'
+    webhook = 'webhook'
 
 
 class AssetSelectors(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     asset_types: Annotated[
         list[AssetType] | None, Field(description="Filter by asset type (e.g., ['image', 'video'])")
     ] = None
     exclude_tags: Annotated[
-        list[str] | None, Field(description="Exclude assets with these tags")
+        list[str] | None, Field(description='Exclude assets with these tags')
     ] = None
     tags: Annotated[
         list[str] | None,
@@ -43,44 +43,35 @@ class AssetSelectors(AdCPBaseModel):
     ] = None
 
 
-class Offering(AdCPBaseModel):
-    model_config = ConfigDict(
-        extra="allow",
-    )
-    assets: Annotated[
-        list[dict[str, Any]] | None, Field(description="Assets specific to this offering")
-    ] = None
-    description: Annotated[str | None, Field(description="Description of what's being offered")] = (
-        None
-    )
-    name: Annotated[
-        str, Field(description="Offering name (e.g., 'Winter Sale', 'New Product Launch')")
-    ]
-
-
 class PromotedOfferings(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     asset_selectors: Annotated[
         AssetSelectors | None,
-        Field(description="Selectors to choose specific assets from the brand manifest"),
+        Field(description='Selectors to choose specific assets from the brand manifest'),
     ] = None
     brand_manifest: Annotated[
         brand_manifest_ref.BrandManifestReference,
         Field(
-            description="Brand information manifest containing assets, themes, and guidelines. Can be provided inline or as a URL reference to a hosted manifest."
+            description='Brand information manifest containing assets, themes, and guidelines. Can be provided inline or as a URL reference to a hosted manifest.'
         ),
     ]
     offerings: Annotated[
-        list[Offering] | None,
+        list[offering.Offering] | None,
         Field(
-            description="Inline offerings for campaigns without a product catalog. Each offering has a name, description, and associated assets."
+            description='Offerings available for promotion. Each offering can include creative assets (via portfolio_ref or inline assets) for traditional ads. When si_agent_url is set at the parent level, hosts can offer conversational experiences about any of these offerings.'
         ),
     ] = None
     product_selectors: Annotated[
         promoted_products.PromotedProducts | None,
         Field(
-            description="Selectors to choose which products/offerings from the brand manifest product catalog to promote"
+            description='Selectors to choose which products/offerings from the brand manifest product catalog to promote'
+        ),
+    ] = None
+    si_agent_url: Annotated[
+        AnyUrl | None,
+        Field(
+            description="MCP endpoint URL for the brand's SI agent. When present, hosts can connect users to conversational experiences about any of the offerings. The agent handles si_get_offering lookups and full conversations."
         ),
     ] = None

adcp/types/generated_poc/core/promoted_products.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/promoted_products.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -12,7 +12,7 @@ from pydantic import ConfigDict, Field
 
 class PromotedProducts(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     manifest_category: Annotated[
         str | None,
@@ -28,7 +28,7 @@ class PromotedProducts(AdCPBaseModel):
     ] = None
     manifest_skus: Annotated[
         list[str] | None,
-        Field(description="Direct product SKU references from the brand manifest product catalog"),
+        Field(description='Direct product SKU references from the brand manifest product catalog'),
     ] = None
     manifest_tags: Annotated[
         list[str] | None,

adcp/types/generated_poc/core/property.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/property.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -17,11 +17,11 @@ from . import property_tag
 
 class Identifier(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     type: Annotated[
         identifier_types.PropertyIdentifierTypes,
-        Field(description="Type of identifier for this property"),
+        Field(description='Type of identifier for this property'),
     ]
     value: Annotated[
         str,
@@ -33,30 +33,30 @@ class Identifier(AdCPBaseModel):
 
 class Property(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     identifiers: Annotated[
-        list[Identifier], Field(description="Array of identifiers for this property", min_length=1)
+        list[Identifier], Field(description='Array of identifiers for this property', min_length=1)
     ]
-    name: Annotated[str, Field(description="Human-readable property name")]
+    name: Annotated[str, Field(description='Human-readable property name')]
     property_id: Annotated[
         property_id_1.PropertyId | None,
         Field(
-            description="Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects."
+            description='Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects.'
         ),
     ] = None
     property_type: Annotated[
-        property_type_1.PropertyType, Field(description="Type of advertising property")
+        property_type_1.PropertyType, Field(description='Type of advertising property')
     ]
     publisher_domain: Annotated[
         str | None,
         Field(
-            description="Domain where adagents.json should be checked for authorization validation. Required for list_authorized_properties response. Optional in adagents.json (file location implies domain)."
+            description='Domain where adagents.json should be checked for authorization validation. Required for list_authorized_properties response. Optional in adagents.json (file location implies domain).'
         ),
     ] = None
     tags: Annotated[
         list[property_tag.PropertyTag] | None,
         Field(
-            description="Tags for categorization and grouping (e.g., network membership, content categories)"
+            description='Tags for categorization and grouping (e.g., network membership, content categories)'
         ),
     ] = None

adcp/types/generated_poc/core/property_id.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/property_id.json
-#   timestamp: 2025-11-29T12:00:45+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -13,9 +13,9 @@ class PropertyId(RootModel[str]):
     root: Annotated[
         str,
         Field(
-            description="Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.",
-            examples=["cnn_ctv_app", "homepage", "mobile_ios", "instagram"],
-            pattern="^[a-z0-9_]+$",
-            title="Property ID",
+            description='Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.',
+            examples=['cnn_ctv_app', 'homepage', 'mobile_ios', 'instagram'],
+            pattern='^[a-z0-9_]+$',
+            title='Property ID',
         ),
     ]

adcp/types/generated_poc/core/property_list_ref.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/property_list_ref.json
-#   timestamp: 2026-01-14T17:08:13+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -12,15 +12,15 @@ from pydantic import AnyUrl, ConfigDict, Field
 
 class PropertyListReference(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="forbid",
+        extra='forbid',
     )
-    agent_url: Annotated[AnyUrl, Field(description="URL of the agent managing the property list")]
+    agent_url: Annotated[AnyUrl, Field(description='URL of the agent managing the property list')]
     auth_token: Annotated[
         str | None,
         Field(
-            description="JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access."
+            description='JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access.'
         ),
     ] = None
     list_id: Annotated[
-        str, Field(description="Identifier for the property list within the agent", min_length=1)
+        str, Field(description='Identifier for the property list within the agent', min_length=1)
     ]

adcp/types/generated_poc/core/property_tag.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/property_tag.json
-#   timestamp: 2025-11-29T12:00:45+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -13,9 +13,9 @@ class PropertyTag(RootModel[str]):
     root: Annotated[
         str,
         Field(
-            description="Tag for categorizing publisher properties. Must be lowercase alphanumeric with underscores only.",
-            examples=["ctv", "premium", "news", "sports", "meta_network", "social_media"],
-            pattern="^[a-z0-9_]+$",
-            title="Property Tag",
+            description='Tag for categorizing publisher properties. Must be lowercase alphanumeric with underscores only.',
+            examples=['ctv', 'premium', 'news', 'sports', 'meta_network', 'social_media'],
+            pattern='^[a-z0-9_]+$',
+            title='Property Tag',
         ),
     ]

adcp/types/generated_poc/core/proposal.py

@@ -0,0 +1,64 @@
+# generated by datamodel-codegen:
+#   filename:  core/proposal.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 AwareDatetime, ConfigDict, Field
+
+from . import ext as ext_1
+from . import product_allocation
+
+
+class TotalBudgetGuidance(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    currency: Annotated[str | None, Field(description='ISO 4217 currency code')] = None
+    max: Annotated[
+        float | None, Field(description='Maximum budget before diminishing returns', ge=0.0)
+    ] = None
+    min: Annotated[float | None, Field(description='Minimum recommended budget', ge=0.0)] = None
+    recommended: Annotated[
+        float | None, Field(description='Recommended budget for optimal performance', ge=0.0)
+    ] = None
+
+
+class Proposal(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    allocations: Annotated[
+        list[product_allocation.ProductAllocation],
+        Field(
+            description='Budget allocations across products. Allocation percentages MUST sum to 100. Publishers are responsible for ensuring the sum equals 100; buyers SHOULD validate this before execution.',
+            min_length=1,
+        ),
+    ]
+    brief_alignment: Annotated[
+        str | None,
+        Field(description='Explanation of how this proposal aligns with the campaign brief'),
+    ] = None
+    description: Annotated[
+        str | None, Field(description='Explanation of the proposal strategy and what it achieves')
+    ] = None
+    expires_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            description='When this proposal expires and can no longer be executed. After expiration, referenced products or pricing may no longer be available.'
+        ),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    name: Annotated[str, Field(description='Human-readable name for this media plan proposal')]
+    proposal_id: Annotated[
+        str,
+        Field(
+            description='Unique identifier for this proposal. Used to refine the proposal in subsequent get_products calls or to execute it via create_media_buy.'
+        ),
+    ]
+    total_budget_guidance: Annotated[
+        TotalBudgetGuidance | None, Field(description='Optional budget guidance for this proposal')
+    ] = None

adcp/types/generated_poc/core/protocol_envelope.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  core/protocol_envelope.json
-#   timestamp: 2026-01-08T19:25:24+00:00
+#   timestamp: 2026-01-25T21:17:54+00:00
 
 from __future__ import annotations
 
@@ -15,47 +15,47 @@ from . import push_notification_config as push_notification_config_1
 
 class ProtocolEnvelope(AdCPBaseModel):
     model_config = ConfigDict(
-        extra="allow",
+        extra='allow',
     )
     context_id: Annotated[
         str | None,
         Field(
-            description="Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context."
+            description='Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context.'
         ),
     ] = None
     message: Annotated[
         str | None,
         Field(
-            description="Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response."
+            description='Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.'
         ),
     ] = None
     payload: Annotated[
         dict[str, Any],
         Field(
-            description="The actual task-specific response data. This is the content defined in individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). Contains only domain-specific data without protocol-level fields."
+            description='The actual task-specific response data. This is the content defined in individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). Contains only domain-specific data without protocol-level fields.'
         ),
     ]
     push_notification_config: Annotated[
         push_notification_config_1.PushNotificationConfig | None,
         Field(
-            description="Push notification configuration for async task updates (A2A and REST protocols). Echoed from the request to confirm webhook settings. Specifies URL, authentication scheme (Bearer or HMAC-SHA256), and credentials. MCP uses progress notifications instead of webhooks."
+            description='Push notification configuration for async task updates (A2A and REST protocols). Echoed from the request to confirm webhook settings. Specifies URL, authentication scheme (Bearer or HMAC-SHA256), and credentials. MCP uses progress notifications instead of webhooks.'
         ),
     ] = None
     status: Annotated[
         task_status.TaskStatus,
         Field(
-            description="Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer."
+            description='Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer.'
         ),
     ]
     task_id: Annotated[
         str | None,
         Field(
-            description="Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete."
+            description='Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.'
         ),
     ] = None
     timestamp: Annotated[
         AwareDatetime | None,
         Field(
-            description="ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress."
+            description='ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.'
         ),
     ] = None