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

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,7 +16,7 @@ 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[
@@ -28,7 +28,7 @@ class ActivateSignalResponse1(AdCPBaseModel):
 
 class ActivateSignalResponse2(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra='allow',
     )
     context: context_1.ContextObject | None = None
     errors: Annotated[

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
 
@@ -21,7 +21,7 @@ class Country(RootModel[str]):
 
 class DeliverTo(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra='allow',
     )
     countries: Annotated[
         list[Country], Field(description='Countries where signals will be used (ISO codes)')
@@ -37,7 +37,7 @@ class DeliverTo(AdCPBaseModel):
 
 class GetSignalsRequest(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra='allow',
     )
     context: context_1.ContextObject | None = None
     deliver_to: Annotated[

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,7 +17,7 @@ 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}$')]
@@ -25,7 +25,7 @@ class Pricing(AdCPBaseModel):
 
 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)
@@ -45,7 +45,7 @@ class Signal(AdCPBaseModel):
 
 class GetSignalsResponse(AdCPBaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra='allow',
     )
     context: context_1.ContextObject | None = None
     errors: Annotated[

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/utils/response_parser.py

@@ -129,12 +129,67 @@ def parse_mcp_content(content: list[dict[str, Any]], response_type: type[T]) ->
     )
 
 
+# Protocol-level fields from ProtocolResponse (core/response.json) and
+# ProtocolEnvelope (core/protocol_envelope.json). These are separated from
+# task data for schema validation, but preserved at the TaskResult level.
+# Note: 'data' and 'payload' are handled separately as wrapper fields.
+PROTOCOL_FIELDS = {
+    "message",  # Human-readable summary
+    "context_id",  # Session continuity identifier
+    "task_id",  # Async operation identifier
+    "status",  # Task execution state
+    "timestamp",  # Response timestamp
+}
+
+
+def _extract_task_data(data: dict[str, Any]) -> dict[str, Any]:
+    """
+    Extract task-specific data from a protocol response.
+
+    Servers may return responses in ProtocolResponse format:
+    {"message": "...", "context_id": "...", "data": {...}}
+
+    Or ProtocolEnvelope format:
+    {"message": "...", "status": "...", "payload": {...}}
+
+    Or task data directly with protocol fields mixed in:
+    {"message": "...", "products": [...], ...}
+
+    This function separates task-specific data for schema validation.
+    Protocol fields are preserved at the TaskResult level.
+
+    Args:
+        data: Response data dict
+
+    Returns:
+        Task-specific data suitable for schema validation.
+        Returns the same dict object if no extraction is needed.
+    """
+    # Check for wrapped payload fields
+    # (ProtocolResponse uses 'data', ProtocolEnvelope uses 'payload')
+    if "data" in data and isinstance(data["data"], dict):
+        return data["data"]
+    if "payload" in data and isinstance(data["payload"], dict):
+        return data["payload"]
+
+    # Check if any protocol fields are present
+    if not any(k in PROTOCOL_FIELDS for k in data):
+        return data  # Return same object for identity check
+
+    # Separate task data from protocol fields
+    return {k: v for k, v in data.items() if k not in PROTOCOL_FIELDS}
+
+
 def parse_json_or_text(data: Any, response_type: type[T]) -> T:
     """
     Parse data that might be JSON string, dict, or other format.
 
     Used by A2A adapter for flexible response parsing.
 
+    Handles protocol-level wrapping where servers return:
+    - {"message": "...", "data": {...task_data...}}
+    - {"message": "...", ...task_fields...}
+
     Args:
         data: Response data (string, dict, or other)
         response_type: Expected Pydantic model type
@@ -147,22 +202,42 @@ def parse_json_or_text(data: Any, response_type: type[T]) -> T:
     """
     # If already a dict, try direct validation
     if isinstance(data, dict):
+        # Try direct validation first
+        original_error: Exception | None = None
         try:
             return _validate_union_type(data, response_type)
-        except ValidationError as e:
-            # Get the type name, handling Union types
-            type_name = getattr(response_type, "__name__", str(response_type))
-            raise ValueError(f"Response doesn't match expected schema {type_name}: {e}") from e
+        except (ValidationError, ValueError) as e:
+            original_error = e
+
+        # Try extracting task data (separates protocol fields)
+        task_data = _extract_task_data(data)
+        if task_data is not data:
+            try:
+                return _validate_union_type(task_data, response_type)
+            except (ValidationError, ValueError):
+                pass  # Fall through to raise original error
+
+        # Report the original validation error
+        type_name = getattr(response_type, "__name__", str(response_type))
+        raise ValueError(
+            f"Response doesn't match expected schema {type_name}: {original_error}"
+        ) from original_error
 
     # If string, try JSON parsing
     if isinstance(data, str):
         try:
             parsed = json.loads(data)
-            return _validate_union_type(parsed, response_type)
         except json.JSONDecodeError as e:
             raise ValueError(f"Response is not valid JSON: {e}") from e
+
+        # Recursively handle dict parsing (which includes protocol field extraction)
+        if isinstance(parsed, dict):
+            return parse_json_or_text(parsed, response_type)
+
+        # Non-dict JSON (shouldn't happen for AdCP responses)
+        try:
+            return _validate_union_type(parsed, response_type)
         except ValidationError as e:
-            # Get the type name, handling Union types
             type_name = getattr(response_type, "__name__", str(response_type))
             raise ValueError(f"Response doesn't match expected schema {type_name}: {e}") from e
 

{adcp-2.16.0.dist-info → adcp-2.18.0.dist-info}/METADATA

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