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

adcp/types/generated_poc/protocols/adcp_extension.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  protocols/adcp_extension.json
-#   timestamp: 2025-11-29T12:00:45+00:00
+#   timestamp: 2026-01-14T17:08:13+00:00
 
 from __future__ import annotations
 
@@ -8,30 +8,46 @@ 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(
+            description="Extension namespace (e.g., 'sustainability'). Must be lowercase alphanumeric with underscores.",
+            pattern="^[a-z][a-z0-9_]*$",
+        ),
+    ]
 
 
 class ProtocolsSupportedEnum(Enum):
-    media_buy = 'media_buy'
-    creative = 'creative'
-    signals = 'signals'
+    media_buy = "media_buy"
+    creative = "creative"
+    signals = "signals"
 
 
-class AdcpAgentCardExtension(AdCPBaseModel):
+class AdcpAgentCardExtensionParams(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     adcp_version: Annotated[
         str,
         Field(
-            description="Semantic version of the AdCP specification this agent implements (e.g., '2.4.0')",
-            pattern='^\\d+\\.\\d+\\.\\d+$',
+            description="Semantic version of the AdCP specification this agent implements (e.g., '2.5.0'). Extension schemas are versioned along with the AdCP spec.",
+            pattern="^\\d+\\.\\d+\\.\\d+$",
         ),
     ]
+    extensions_supported: Annotated[
+        list[ExtensionsSupportedItem] | None,
+        Field(
+            description="Typed extensions this agent supports. Each extension has a formal schema in /schemas/extensions/. Extension version is determined by adcp_version."
+        ),
+    ] = None
     protocols_supported: Annotated[
         list[ProtocolsSupportedEnum],
         Field(
-            description='AdCP protocol domains supported by this agent. At least one must be specified.',
+            description="AdCP protocol domains supported by this agent. At least one must be specified.",
             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: 2025-12-11T15:09:37+00:00
+#   timestamp: 2026-01-08T19:25:24+00:00
 
 from __future__ import annotations
 
@@ -16,17 +16,17 @@ from ..core import ext as ext_1
 
 class ActivateSignalRequest(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     context: context_1.ContextObject | None = None
     deployments: Annotated[
         list[destination.Destination],
         Field(
-            description='Target deployment(s) for activation. If the authenticated caller matches one of these deployment targets, activation keys will be included in the response.',
+            description="Target deployment(s) for activation. If the authenticated caller matches one of these deployment targets, activation keys will be included in the response.",
             min_length=1,
         ),
     ]
     ext: ext_1.ExtensionObject | None = None
     signal_agent_segment_id: Annotated[
-        str, Field(description='The universal identifier for the signal to activate')
+        str, Field(description="The universal identifier for the signal to activate")
     ]

adcp/types/generated_poc/signals/activate_signal_response.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/activate_signal_response.json
-#   timestamp: 2025-12-11T15:09:37+00:00
+#   timestamp: 2026-01-08T19:25:24+00:00
 
 from __future__ import annotations
 
@@ -16,25 +16,25 @@ from ..core import ext as ext_1
 
 class ActivateSignalResponse1(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     context: context_1.ContextObject | None = None
     deployments: Annotated[
         list[deployment.Deployment],
-        Field(description='Array of deployment results for each deployment target'),
+        Field(description="Array of deployment results for each deployment target"),
     ]
     ext: ext_1.ExtensionObject | None = None
 
 
 class ActivateSignalResponse2(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     context: context_1.ContextObject | None = None
     errors: Annotated[
         list[error.Error],
         Field(
-            description='Array of errors explaining why activation failed (e.g., platform connectivity issues, signal definition problems, authentication failures)',
+            description="Array of errors explaining why activation failed (e.g., platform connectivity issues, signal definition problems, authentication failures)",
             min_length=1,
         ),
     ]
@@ -45,7 +45,7 @@ class ActivateSignalResponse(RootModel[ActivateSignalResponse1 | ActivateSignalR
     root: Annotated[
         ActivateSignalResponse1 | ActivateSignalResponse2,
         Field(
-            description='Response payload for activate_signal task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - the signal is either fully activated or not activated at all.',
-            title='Activate Signal Response',
+            description="Response payload for activate_signal task. Returns either complete success data OR error information, never both. This enforces atomic operation semantics - the signal is either fully activated or not activated at all.",
+            title="Activate Signal Response",
         ),
     ]

adcp/types/generated_poc/signals/get_signals_request.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/get_signals_request.json
-#   timestamp: 2025-12-11T15:09:37+00:00
+#   timestamp: 2026-01-08T19:25:24+00:00
 
 from __future__ import annotations
 
@@ -16,20 +16,20 @@ from ..core import signal_filters
 
 
 class Country(RootModel[str]):
-    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]
+    root: Annotated[str, Field(pattern="^[A-Z]{2}$")]
 
 
 class DeliverTo(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     countries: Annotated[
-        list[Country], Field(description='Countries where signals will be used (ISO codes)')
+        list[Country], Field(description="Countries where signals will be used (ISO codes)")
     ]
     deployments: Annotated[
         list[destination.Destination],
         Field(
-            description='List of deployment targets (DSPs, sales agents, etc.). If the authenticated caller matches one of these deployment targets, activation keys will be included in the response.',
+            description="List of deployment targets (DSPs, sales agents, etc.). If the authenticated caller matches one of these deployment targets, activation keys will be included in the response.",
             min_length=1,
         ),
     ]
@@ -37,17 +37,17 @@ class DeliverTo(AdCPBaseModel):
 
 class GetSignalsRequest(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     context: context_1.ContextObject | None = None
     deliver_to: Annotated[
-        DeliverTo, Field(description='Deployment targets where signals need to be activated')
+        DeliverTo, Field(description="Deployment targets where signals need to be activated")
     ]
     ext: ext_1.ExtensionObject | None = None
     filters: signal_filters.SignalFilters | None = None
     max_results: Annotated[
-        int | None, Field(description='Maximum number of results to return', ge=1)
+        int | None, Field(description="Maximum number of results to return", ge=1)
     ] = None
     signal_spec: Annotated[
-        str, Field(description='Natural language description of the desired signals')
+        str, Field(description="Natural language description of the desired signals")
     ]

adcp/types/generated_poc/signals/get_signals_response.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  signals/get_signals_response.json
-#   timestamp: 2025-12-11T15:09:37+00:00
+#   timestamp: 2026-01-08T19:25:24+00:00
 
 from __future__ import annotations
 
@@ -17,42 +17,42 @@ from ..enums import signal_catalog_type
 
 class Pricing(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
-    cpm: Annotated[float, Field(description='Cost per thousand impressions', ge=0.0)]
-    currency: Annotated[str, Field(description='Currency code', pattern='^[A-Z]{3}$')]
+    cpm: Annotated[float, Field(description="Cost per thousand impressions", ge=0.0)]
+    currency: Annotated[str, Field(description="Currency code", pattern="^[A-Z]{3}$")]
 
 
 class Signal(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     coverage_percentage: Annotated[
-        float, Field(description='Percentage of audience coverage', ge=0.0, le=100.0)
+        float, Field(description="Percentage of audience coverage", ge=0.0, le=100.0)
     ]
-    data_provider: Annotated[str, Field(description='Name of the data provider')]
+    data_provider: Annotated[str, Field(description="Name of the data provider")]
     deployments: Annotated[
-        list[deployment.Deployment], Field(description='Array of deployment targets')
+        list[deployment.Deployment], Field(description="Array of deployment targets")
     ]
-    description: Annotated[str, Field(description='Detailed signal description')]
-    name: Annotated[str, Field(description='Human-readable signal name')]
-    pricing: Annotated[Pricing, Field(description='Pricing information')]
-    signal_agent_segment_id: Annotated[str, Field(description='Unique identifier for the signal')]
+    description: Annotated[str, Field(description="Detailed signal description")]
+    name: Annotated[str, Field(description="Human-readable signal name")]
+    pricing: Annotated[Pricing, Field(description="Pricing information")]
+    signal_agent_segment_id: Annotated[str, Field(description="Unique identifier for the signal")]
     signal_type: Annotated[
-        signal_catalog_type.SignalCatalogType, Field(description='Type of signal')
+        signal_catalog_type.SignalCatalogType, Field(description="Type of signal")
     ]
 
 
 class GetSignalsResponse(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="allow",
     )
     context: context_1.ContextObject | None = None
     errors: Annotated[
         list[error.Error] | None,
         Field(
-            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
+            description="Task-specific errors and warnings (e.g., signal discovery or pricing issues)"
         ),
     ] = None
     ext: ext_1.ExtensionObject | None = None
-    signals: Annotated[list[Signal], Field(description='Array of matching signals')]
+    signals: Annotated[list[Signal], Field(description="Array of matching signals")]

adcp/utils/__init__.py

@@ -2,6 +2,29 @@ from __future__ import annotations
 
 """Utility functions."""
 
+from adcp.utils.format_assets import (
+    get_asset_count,
+    get_format_assets,
+    get_individual_assets,
+    get_optional_assets,
+    get_repeatable_groups,
+    get_required_assets,
+    has_assets,
+    normalize_assets_required,
+    uses_deprecated_assets_field,
+)
 from adcp.utils.operation_id import create_operation_id
 
-__all__ = ["create_operation_id"]
+__all__ = [
+    "create_operation_id",
+    # Format asset utilities
+    "get_format_assets",
+    "normalize_assets_required",
+    "get_required_assets",
+    "get_optional_assets",
+    "get_individual_assets",
+    "get_repeatable_groups",
+    "uses_deprecated_assets_field",
+    "get_asset_count",
+    "has_assets",
+]

adcp/utils/format_assets.py

@@ -0,0 +1,224 @@
+"""Format Asset Utilities.
+
+Provides backward-compatible access to format assets.
+The v2.6 `assets` field replaces the deprecated `assets_required` field.
+
+These utilities help users work with format assets regardless of which field
+the agent uses, providing a smooth migration path.
+
+Example:
+    ```python
+    from adcp import Format
+    from adcp.utils.format_assets import get_format_assets, get_required_assets
+
+    # Get all assets from a format (handles both new and deprecated fields)
+    all_assets = get_format_assets(format)
+
+    # Get only required assets
+    required = get_required_assets(format)
+
+    # Check if using deprecated field
+    if uses_deprecated_assets_field(format):
+        print("Agent should migrate to 'assets' field")
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Union
+
+from adcp.types.generated_poc.core.format import Assets as AssetsModel
+from adcp.types.generated_poc.core.format import Assets1 as Assets1Model
+
+if TYPE_CHECKING:
+    from adcp.types.generated_poc.core.format import Assets, Assets1, Format
+
+# Type alias for any format asset (individual or repeatable group)
+FormatAsset = Union["Assets", "Assets1"]
+
+
+def get_format_assets(format: Format) -> list[FormatAsset]:
+    """Get assets from a Format, preferring new `assets` field, falling back to `assets_required`.
+
+    This provides backward compatibility during the migration from `assets_required` to `assets`.
+    - If `assets` exists and has items, returns it directly
+    - If only `assets_required` exists, normalizes it to the new format (sets required=True)
+    - Returns empty list if neither field exists (flexible format with no assets)
+
+    Args:
+        format: The Format object from list_creative_formats response
+
+    Returns:
+        List of assets in the new format structure
+
+    Example:
+        ```python
+        formats = await agent.simple.list_creative_formats()
+        for format in formats.formats:
+            assets = get_format_assets(format)
+            print(f"{format.name} has {len(assets)} assets")
+        ```
+    """
+    # Prefer new `assets` field (v2.6+)
+    if format.assets and len(format.assets) > 0:
+        return list(format.assets)
+
+    # Fall back to deprecated `assets_required` and normalize
+    if format.assets_required and len(format.assets_required) > 0:
+        return normalize_assets_required(format.assets_required)
+
+    return []
+
+
+def normalize_assets_required(assets_required: list[Any]) -> list[FormatAsset]:
+    """Convert deprecated assets_required to new assets format.
+
+    All assets in assets_required are required by definition (that's why they were in
+    that array). The new `assets` field has an explicit `required: boolean` to allow
+    both required AND optional assets.
+
+    Args:
+        assets_required: The deprecated assets_required array
+
+    Returns:
+        Normalized assets as Pydantic models with explicit required=True
+    """
+    normalized: list[FormatAsset] = []
+    for asset in assets_required:
+        # Get asset data as dict
+        if isinstance(asset, dict):
+            asset_dict = asset
+        else:
+            asset_dict = asset.model_dump() if hasattr(asset, "model_dump") else dict(asset)
+
+        # Check if it's a repeatable group (has asset_group_id) or individual asset
+        if "asset_group_id" in asset_dict:
+            # Repeatable group - use Assets1Model
+            normalized.append(Assets1Model(**{**asset_dict, "required": True}))
+        else:
+            # Individual asset - use AssetsModel
+            normalized.append(AssetsModel(**{**asset_dict, "required": True}))
+
+    return normalized
+
+
+def get_required_assets(format: Format) -> list[FormatAsset]:
+    """Get only required assets from a Format.
+
+    Args:
+        format: The Format object
+
+    Returns:
+        List of required assets only
+
+    Example:
+        ```python
+        required_assets = get_required_assets(format)
+        print(f"Must provide {len(required_assets)} assets")
+        ```
+    """
+    return [asset for asset in get_format_assets(format) if _is_required(asset)]
+
+
+def get_optional_assets(format: Format) -> list[FormatAsset]:
+    """Get only optional assets from a Format.
+
+    Note: When using deprecated `assets_required`, this will always return empty
+    since assets_required only contained required assets.
+
+    Args:
+        format: The Format object
+
+    Returns:
+        List of optional assets only
+
+    Example:
+        ```python
+        optional_assets = get_optional_assets(format)
+        print(f"Can optionally provide {len(optional_assets)} additional assets")
+        ```
+    """
+    return [asset for asset in get_format_assets(format) if not _is_required(asset)]
+
+
+def get_individual_assets(format: Format) -> list[FormatAsset]:
+    """Get individual assets (not repeatable groups) from a Format.
+
+    Args:
+        format: The Format object
+
+    Returns:
+        List of individual assets (item_type='individual')
+    """
+    return [asset for asset in get_format_assets(format) if _get_item_type(asset) == "individual"]
+
+
+def get_repeatable_groups(format: Format) -> list[FormatAsset]:
+    """Get repeatable asset groups from a Format.
+
+    Args:
+        format: The Format object
+
+    Returns:
+        List of repeatable asset groups (item_type='repeatable_group')
+    """
+    return [
+        asset for asset in get_format_assets(format) if _get_item_type(asset) == "repeatable_group"
+    ]
+
+
+def uses_deprecated_assets_field(format: Format) -> bool:
+    """Check if format uses deprecated assets_required field (for migration warnings).
+
+    Args:
+        format: The Format object
+
+    Returns:
+        True if using deprecated field, False if using new field or neither
+
+    Example:
+        ```python
+        if uses_deprecated_assets_field(format):
+            print(f"Format {format.name} uses deprecated assets_required field")
+        ```
+    """
+    has_assets = format.assets is not None and len(format.assets) > 0
+    has_assets_required = format.assets_required is not None and len(format.assets_required) > 0
+    return not has_assets and has_assets_required
+
+
+def get_asset_count(format: Format) -> int:
+    """Get the count of assets in a format (for display purposes).
+
+    Args:
+        format: The Format object
+
+    Returns:
+        Number of assets, or 0 if none defined
+    """
+    return len(get_format_assets(format))
+
+
+def has_assets(format: Format) -> bool:
+    """Check if a format has any assets defined.
+
+    Args:
+        format: The Format object
+
+    Returns:
+        True if format has assets, False otherwise
+    """
+    return get_asset_count(format) > 0
+
+
+# Internal helpers
+
+
+def _is_required(asset: FormatAsset) -> bool:
+    """Check if an asset is required."""
+    return getattr(asset, "required", False) is True
+
+
+def _get_item_type(asset: FormatAsset) -> str:
+    """Get the item_type of an asset."""
+    return getattr(asset, "item_type", "individual")

adcp/utils/preview_cache.py

@@ -399,25 +399,47 @@ def _create_sample_manifest_for_format(fmt: Format) -> CreativeManifest | None:
         Sample CreativeManifest, or None if unable to create one
     """
     from adcp.types import CreativeManifest
+    from adcp.utils.format_assets import get_required_assets
 
-    if not fmt.assets_required:
+    required_assets = get_required_assets(fmt)
+    if not required_assets:
         return None
 
     assets: dict[str, Any] = {}
 
-    for asset in fmt.assets_required:
+    for asset in required_assets:
         if isinstance(asset, dict):
+            # Handle dict input
             asset_id = asset.get("asset_id")
             asset_type = asset.get("asset_type")
 
             if asset_id:
                 assets[asset_id] = _create_sample_asset(asset_type)
         else:
-            # Handle Pydantic model
-            asset_id = asset.asset_id
-            has_value = hasattr(asset.asset_type, "value")
-            asset_type = asset.asset_type.value if has_value else str(asset.asset_type)
-            assets[asset_id] = _create_sample_asset(asset_type)
+            # Handle Pydantic model - check for individual vs repeatable_group
+            item_type = getattr(asset, "item_type", "individual")
+
+            if item_type == "individual":
+                asset_id = asset.asset_id
+                has_value = hasattr(asset.asset_type, "value")
+                asset_type = asset.asset_type.value if has_value else str(asset.asset_type)
+                assets[asset_id] = _create_sample_asset(asset_type)
+            elif item_type == "repeatable_group":
+                # For repeatable groups, create sample assets for each asset in the group
+                group_assets = getattr(asset, "assets", [])
+                for group_asset in group_assets:
+                    if isinstance(group_asset, dict):
+                        asset_id = group_asset.get("asset_id")
+                        asset_type = group_asset.get("asset_type")
+                    else:
+                        asset_id = group_asset.asset_id
+                        if hasattr(group_asset.asset_type, "value"):
+                            asset_type = group_asset.asset_type.value
+                        else:
+                            asset_type = str(group_asset.asset_type)
+
+                    if asset_id:
+                        assets[asset_id] = _create_sample_asset(asset_type)
 
     if not assets:
         return None

{adcp-2.17.0.dist-info → adcp-2.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.17.0
+Version: 2.19.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0