adcp 2.12.0__py3-none-any.whl

adcp/types/generated_poc/core/format.py

@@ -0,0 +1,260 @@
+# generated by datamodel-codegen:
+#   filename:  core/format.json
+#   timestamp: 2025-11-22T19:54:03+00:00
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+from ..enums import asset_content_type, format_category, format_id_parameter
+from . import format_id as format_id_1
+
+
+class AssetsRequired(AdCPBaseModel):
+    asset_id: Annotated[
+        str,
+        Field(
+            description='Unique identifier for this asset. Creative manifests MUST use this exact value as the key in the assets object.'
+        ),
+    ]
+    asset_role: Annotated[
+        str | None,
+        Field(
+            description="Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests—use asset_id instead. This field is for human-readable documentation and UI display only."
+        ),
+    ] = None
+    asset_type: Annotated[asset_content_type.AssetContentType, Field(description='Type of asset')]
+    item_type: Annotated[
+        Literal['individual'],
+        Field(description='Discriminator indicating this is an individual asset requirement'),
+    ]
+    required: Annotated[bool | None, Field(description='Whether this asset is required')] = None
+    requirements: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description='Technical requirements for this asset (dimensions, file size, duration, etc.). For template formats, use parameters_from_format_id: true to indicate asset parameters must match the format_id parameters (width/height/unit and/or duration_ms).'
+        ),
+    ] = None
+
+
+class Asset(AdCPBaseModel):
+    asset_id: Annotated[str, Field(description='Identifier for this asset within the group')]
+    asset_role: Annotated[
+        str | None,
+        Field(
+            description="Optional descriptive label for this asset's purpose (e.g., 'hero_image', 'logo'). Not used for referencing assets in manifests—use asset_id instead. This field is for human-readable documentation and UI display only."
+        ),
+    ] = None
+    asset_type: Annotated[asset_content_type.AssetContentType, Field(description='Type of asset')]
+    required: Annotated[
+        bool | None, Field(description='Whether this asset is required in each repetition')
+    ] = None
+    requirements: Annotated[
+        dict[str, Any] | None,
+        Field(
+            description='Technical requirements for this asset. For template formats, use parameters_from_format_id: true to indicate asset parameters must match the format_id parameters (width/height/unit and/or duration_ms).'
+        ),
+    ] = None
+
+
+class AssetsRequired1(AdCPBaseModel):
+    asset_group_id: Annotated[
+        str, Field(description="Identifier for this asset group (e.g., 'product', 'slide', 'card')")
+    ]
+    assets: Annotated[list[Asset], Field(description='Assets within each repetition of this group')]
+    item_type: Annotated[
+        Literal['repeatable_group'],
+        Field(description='Discriminator indicating this is a repeatable asset group'),
+    ]
+    max_count: Annotated[int, Field(description='Maximum number of repetitions allowed', ge=1)]
+    min_count: Annotated[int, Field(description='Minimum number of repetitions required', ge=1)]
+
+
+class Responsive(AdCPBaseModel):
+    height: bool
+    width: bool
+
+
+class Dimensions(AdCPBaseModel):
+    aspect_ratio: Annotated[
+        str | None,
+        Field(
+            description="Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1')",
+            pattern='^\\d+:\\d+$',
+        ),
+    ] = None
+    height: Annotated[int | None, Field(description='Fixed height in pixels', ge=1)] = None
+    max_height: Annotated[
+        int | None, Field(description='Maximum height in pixels for responsive renders', ge=1)
+    ] = None
+    max_width: Annotated[
+        int | None, Field(description='Maximum width in pixels for responsive renders', ge=1)
+    ] = None
+    min_height: Annotated[
+        int | None, Field(description='Minimum height in pixels for responsive renders', ge=1)
+    ] = None
+    min_width: Annotated[
+        int | None, Field(description='Minimum width in pixels for responsive renders', ge=1)
+    ] = None
+    responsive: Annotated[
+        Responsive | None, Field(description='Indicates which dimensions are responsive/fluid')
+    ] = None
+    width: Annotated[int | None, Field(description='Fixed width in pixels', ge=1)] = None
+
+
+class Renders(AdCPBaseModel):
+    dimensions: Annotated[
+        Dimensions, Field(description='Dimensions for this rendered piece (in pixels)')
+    ]
+    parameters_from_format_id: Annotated[
+        bool | None,
+        Field(
+            description='When true, parameters for this render (dimensions and/or duration) are specified in the format_id. Used for template formats that accept parameters. Mutually exclusive with specifying dimensions object explicitly.'
+        ),
+    ] = None
+    role: Annotated[
+        str,
+        Field(
+            description="Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')"
+        ),
+    ]
+
+
+Dimensions2 = Dimensions
+
+
+class Renders1(AdCPBaseModel):
+    dimensions: Annotated[
+        Dimensions2 | None, Field(description='Dimensions for this rendered piece (in pixels)')
+    ] = None
+    parameters_from_format_id: Annotated[
+        Literal[True],
+        Field(
+            description='When true, parameters for this render (dimensions and/or duration) are specified in the format_id. Used for template formats that accept parameters. Mutually exclusive with specifying dimensions object explicitly.'
+        ),
+    ]
+    role: Annotated[
+        str,
+        Field(
+            description="Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')"
+        ),
+    ]
+
+
+class FormatCard(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description='Creative format defining the card layout (typically format_card_standard)'
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(description='Asset manifest for rendering the card, structure defined by the format'),
+    ]
+
+
+class FormatCardDetailed(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(
+            description='Creative format defining the detailed card layout (typically format_card_detailed)'
+        ),
+    ]
+    manifest: Annotated[
+        dict[str, Any],
+        Field(
+            description='Asset manifest for rendering the detailed card, structure defined by the format'
+        ),
+    ]
+
+
+class Format(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    accepts_parameters: Annotated[
+        list[format_id_parameter.FormatIdParameter] | None,
+        Field(
+            description='List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.'
+        ),
+    ] = None
+    assets_required: Annotated[
+        list[AssetsRequired | AssetsRequired1] | None,
+        Field(
+            description='Array of required assets or asset groups for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).'
+        ),
+    ] = None
+    delivery: Annotated[
+        dict[str, Any] | None,
+        Field(description='Delivery method specifications (e.g., hosted, VAST, third-party tags)'),
+    ] = None
+    description: Annotated[
+        str | None,
+        Field(
+            description='Plain text explanation of what this format does and what assets it requires'
+        ),
+    ] = None
+    example_url: Annotated[
+        AnyUrl | None,
+        Field(
+            description='Optional URL to showcase page with examples and interactive demos of this format'
+        ),
+    ] = None
+    format_card: Annotated[
+        FormatCard | None,
+        Field(
+            description='Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.'
+        ),
+    ] = None
+    format_card_detailed: Annotated[
+        FormatCardDetailed | None,
+        Field(
+            description='Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.'
+        ),
+    ] = None
+    format_id: Annotated[
+        format_id_1.FormatId,
+        Field(description='Structured format identifier with agent URL and format name'),
+    ]
+    name: Annotated[str, Field(description='Human-readable format name')]
+    output_format_ids: Annotated[
+        list[format_id_1.FormatId] | None,
+        Field(
+            description='For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).'
+        ),
+    ] = None
+    preview_image: Annotated[
+        AnyUrl | None,
+        Field(
+            description='DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach.'
+        ),
+    ] = None
+    renders: Annotated[
+        list[Renders | Renders1] | None,
+        Field(
+            description='Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.',
+            min_length=1,
+        ),
+    ] = None
+    supported_macros: Annotated[
+        list[str] | None,
+        Field(
+            description='List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.'
+        ),
+    ] = None
+    type: Annotated[
+        format_category.FormatCategory,
+        Field(
+            description='Media type of this format - determines rendering method and asset requirements'
+        ),
+    ]

adcp/types/generated_poc/core/format_id.py

@@ -0,0 +1,50 @@
+# generated by datamodel-codegen:
+#   filename:  core/format_id.json
+#   timestamp: 2025-11-22T19:54:03+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, ConfigDict, Field
+
+
+class FormatId(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    agent_url: Annotated[
+        AnyUrl,
+        Field(
+            description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)"
+        ),
+    ]
+    duration_ms: Annotated[
+        float | None,
+        Field(
+            description='Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.',
+            ge=1.0,
+        ),
+    ] = None
+    height: Annotated[
+        int | None,
+        Field(
+            description='Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
+            ge=1,
+        ),
+    ] = None
+    id: Annotated[
+        str,
+        Field(
+            description="Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.",
+            pattern='^[a-zA-Z0-9_-]+$',
+        ),
+    ]
+    width: Annotated[
+        int | None,
+        Field(
+            description='Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
+            ge=1,
+        ),
+    ] = None

adcp/types/generated_poc/core/frequency_cap.py

@@ -0,0 +1,19 @@
+# generated by datamodel-codegen:
+#   filename:  core/frequency_cap.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class FrequencyCap(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    suppress_minutes: Annotated[
+        float, Field(description='Minutes to suppress after impression', ge=0.0)
+    ]

adcp/types/generated_poc/core/measurement.py

@@ -0,0 +1,40 @@
+# generated by datamodel-codegen:
+#   filename:  core/measurement.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class Measurement(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    attribution: Annotated[
+        str,
+        Field(
+            description='Attribution methodology',
+            examples=['deterministic_purchase', 'probabilistic'],
+        ),
+    ]
+    reporting: Annotated[
+        str,
+        Field(
+            description='Reporting frequency and format',
+            examples=['weekly_dashboard', 'real_time_api'],
+        ),
+    ]
+    type: Annotated[
+        str,
+        Field(
+            description='Type of measurement',
+            examples=['incremental_sales_lift', 'brand_lift', 'foot_traffic'],
+        ),
+    ]
+    window: Annotated[
+        str | None, Field(description='Attribution window', examples=['30_days', '7_days'])
+    ] = None

adcp/types/generated_poc/core/media_buy.py

@@ -0,0 +1,40 @@
+# generated by datamodel-codegen:
+#   filename:  core/media_buy.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field
+
+from ..enums import media_buy_status
+from . import ext as ext_1
+from . import package
+
+
+class MediaBuy(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    buyer_ref: Annotated[
+        str | None, Field(description="Buyer's reference identifier for this media buy")
+    ] = None
+    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
+    creative_deadline: Annotated[
+        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    media_buy_id: Annotated[
+        str, Field(description="Publisher's unique identifier for the media buy")
+    ]
+    packages: Annotated[
+        list[package.Package], Field(description='Array of packages within this media buy')
+    ]
+    promoted_offering: Annotated[
+        str, Field(description='Description of advertiser and what is being promoted')
+    ]
+    status: media_buy_status.MediaBuyStatus
+    total_budget: Annotated[float, Field(description='Total budget amount', ge=0.0)]
+    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None

adcp/types/generated_poc/core/package.py

@@ -0,0 +1,68 @@
+# generated by datamodel-codegen:
+#   filename:  core/package.json
+#   timestamp: 2025-11-22T19:54:03+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from ..enums import pacing as pacing_1
+from . import creative_assignment
+from . import ext as ext_1
+from . import format_id, targeting
+
+
+class Package(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    bid_price: Annotated[
+        float | None,
+        Field(
+            description='Bid price for auction-based CPM pricing (present if using cpm-auction-option)',
+            ge=0.0,
+        ),
+    ] = None
+    budget: Annotated[
+        float | None,
+        Field(
+            description='Budget allocation for this package in the currency specified by the pricing option',
+            ge=0.0,
+        ),
+    ] = None
+    buyer_ref: Annotated[
+        str | None, Field(description="Buyer's reference identifier for this package")
+    ] = None
+    creative_assignments: Annotated[
+        list[creative_assignment.CreativeAssignment] | None,
+        Field(description='Creative assets assigned to this package'),
+    ] = None
+    ext: ext_1.ExtensionObject | None = None
+    format_ids_to_provide: Annotated[
+        list[format_id.FormatId] | None,
+        Field(description='Format IDs that creative assets will be provided for this package'),
+    ] = None
+    impressions: Annotated[
+        float | None, Field(description='Impression goal for this package', ge=0.0)
+    ] = None
+    pacing: pacing_1.Pacing | None = None
+    package_id: Annotated[str, Field(description="Publisher's unique identifier for the package")]
+    paused: Annotated[
+        bool | None,
+        Field(
+            description='Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.'
+        ),
+    ] = False
+    pricing_option_id: Annotated[
+        str | None,
+        Field(
+            description="ID of the selected pricing option from the product's pricing_options array"
+        ),
+    ] = None
+    product_id: Annotated[
+        str | None, Field(description='ID of the product this package is based on')
+    ] = None
+    targeting_overlay: targeting.TargetingOverlay | None = None

adcp/types/generated_poc/core/performance_feedback.py

@@ -0,0 +1,78 @@
+# generated by datamodel-codegen:
+#   filename:  core/performance_feedback.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AwareDatetime, ConfigDict, Field
+
+from ..enums import feedback_source as feedback_source_1
+from ..enums import metric_type as metric_type_1
+
+
+class MeasurementPeriod(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    end: Annotated[
+        AwareDatetime, Field(description='ISO 8601 end timestamp for measurement period')
+    ]
+    start: Annotated[
+        AwareDatetime, Field(description='ISO 8601 start timestamp for measurement period')
+    ]
+
+
+class Status(Enum):
+    accepted = 'accepted'
+    queued = 'queued'
+    applied = 'applied'
+    rejected = 'rejected'
+
+
+class PerformanceFeedback(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    applied_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            description='ISO 8601 timestamp when feedback was applied to optimization algorithms'
+        ),
+    ] = None
+    creative_id: Annotated[
+        str | None, Field(description='Specific creative asset (if feedback is creative-specific)')
+    ] = None
+    feedback_id: Annotated[
+        str, Field(description='Unique identifier for this performance feedback submission')
+    ]
+    feedback_source: Annotated[
+        feedback_source_1.FeedbackSource, Field(description='Source of the performance data')
+    ]
+    measurement_period: Annotated[
+        MeasurementPeriod, Field(description='Time period for performance measurement')
+    ]
+    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
+    metric_type: Annotated[
+        metric_type_1.MetricType, Field(description='The business metric being measured')
+    ]
+    package_id: Annotated[
+        str | None,
+        Field(
+            description='Specific package within the media buy (if feedback is package-specific)'
+        ),
+    ] = None
+    performance_index: Annotated[
+        float,
+        Field(
+            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
+            ge=0.0,
+        ),
+    ]
+    status: Annotated[Status, Field(description='Processing status of the performance feedback')]
+    submitted_at: Annotated[
+        AwareDatetime, Field(description='ISO 8601 timestamp when feedback was submitted')
+    ]

adcp/types/generated_poc/core/placement.py

@@ -0,0 +1,37 @@
+# generated by datamodel-codegen:
+#   filename:  core/placement.json
+#   timestamp: 2025-11-22T19:54:03+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+from . import format_id
+
+
+class Placement(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    description: Annotated[
+        str | None, Field(description='Detailed description of where and how the placement appears')
+    ] = None
+    format_ids: Annotated[
+        list[format_id.FormatId] | None,
+        Field(
+            description='Format IDs supported by this specific placement. Can include: (1) concrete format_ids (fixed dimensions), (2) template format_ids without parameters (accepts any dimensions/duration), or (3) parameterized format_ids (specific dimension/duration constraints).',
+            min_length=1,
+        ),
+    ] = None
+    name: Annotated[
+        str,
+        Field(
+            description="Human-readable name for the placement (e.g., 'Homepage Banner', 'Article Sidebar')"
+        ),
+    ]
+    placement_id: Annotated[
+        str, Field(description='Unique identifier for the placement within the product')
+    ]