adcp 2.12.0__py3-none-any.whl

adcp/types/base.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+"""Base model for AdCP types with spec-compliant serialization."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class AdCPBaseModel(BaseModel):
+    """Base model for AdCP types with spec-compliant serialization.
+
+    AdCP JSON schemas use additionalProperties: false and do not allow null
+    for optional fields. Therefore, optional fields must be omitted entirely
+    when not present (not sent as null).
+    """
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump(**kwargs)
+
+    def model_dump_json(self, **kwargs: Any) -> str:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump_json(**kwargs)

adcp/types/core.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+"""Core type definitions."""
+
+from enum import Enum
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Protocol(str, Enum):
+    """Supported protocols."""
+
+    A2A = "a2a"
+    MCP = "mcp"
+
+
+class AgentConfig(BaseModel):
+    """Agent configuration."""
+
+    id: str
+    agent_uri: str
+    protocol: Protocol
+    auth_token: str | None = None
+    requires_auth: bool = False
+    auth_header: str = "x-adcp-auth"  # Header name for authentication
+    auth_type: str = "token"  # "token" for direct value, "bearer" for "Bearer {token}"
+    timeout: float = 30.0  # Request timeout in seconds
+    mcp_transport: str = (
+        "streamable_http"  # "streamable_http" (default, modern) or "sse" (legacy fallback)
+    )
+    debug: bool = False  # Enable debug mode to capture request/response details
+
+    @field_validator("agent_uri")
+    @classmethod
+    def validate_agent_uri(cls, v: str) -> str:
+        """Validate agent URI format."""
+        if not v:
+            raise ValueError("agent_uri cannot be empty")
+
+        if not v.startswith(("http://", "https://")):
+            raise ValueError(
+                f"agent_uri must start with http:// or https://, got: {v}\n"
+                "Example: https://agent.example.com"
+            )
+
+        # Remove trailing slash for consistency
+        return v.rstrip("/")
+
+    @field_validator("timeout")
+    @classmethod
+    def validate_timeout(cls, v: float) -> float:
+        """Validate timeout is reasonable."""
+        if v <= 0:
+            raise ValueError(f"timeout must be positive, got: {v}")
+
+        if v > 300:  # 5 minutes
+            raise ValueError(
+                f"timeout is very large ({v}s). Consider a value under 300 seconds.\n"
+                "Large timeouts can cause long hangs if agent is unresponsive."
+            )
+
+        return v
+
+    @field_validator("mcp_transport")
+    @classmethod
+    def validate_mcp_transport(cls, v: str) -> str:
+        """Validate MCP transport type."""
+        valid_transports = ["streamable_http", "sse"]
+        if v not in valid_transports:
+            raise ValueError(
+                f"mcp_transport must be one of {valid_transports}, got: {v}\n"
+                "Use 'streamable_http' for modern agents (recommended)"
+            )
+        return v
+
+    @field_validator("auth_type")
+    @classmethod
+    def validate_auth_type(cls, v: str) -> str:
+        """Validate auth type."""
+        valid_types = ["token", "bearer"]
+        if v not in valid_types:
+            raise ValueError(
+                f"auth_type must be one of {valid_types}, got: {v}\n"
+                "Use 'bearer' for OAuth2/standard Authorization header"
+            )
+        return v
+
+
+class TaskStatus(str, Enum):
+    """Task execution status."""
+
+    COMPLETED = "completed"
+    SUBMITTED = "submitted"
+    NEEDS_INPUT = "needs_input"
+    FAILED = "failed"
+    WORKING = "working"
+
+
+T = TypeVar("T")
+
+
+class SubmittedInfo(BaseModel):
+    """Information about submitted async task."""
+
+    webhook_url: str
+    operation_id: str
+
+
+class NeedsInputInfo(BaseModel):
+    """Information when agent needs clarification."""
+
+    message: str
+    field: str | None = None
+
+
+class DebugInfo(BaseModel):
+    """Debug information for troubleshooting."""
+
+    request: dict[str, Any]
+    response: dict[str, Any]
+    duration_ms: float | None = None
+
+
+class TaskResult(BaseModel, Generic[T]):
+    """Result from task execution."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    status: TaskStatus
+    data: T | None = None
+    message: str | None = None  # Human-readable message from agent (e.g., MCP content text)
+    submitted: SubmittedInfo | None = None
+    needs_input: NeedsInputInfo | None = None
+    error: str | None = None
+    success: bool = Field(default=True)
+    metadata: dict[str, Any] | None = None
+    debug_info: DebugInfo | None = None
+
+
+class ActivityType(str, Enum):
+    """Types of activity events."""
+
+    PROTOCOL_REQUEST = "protocol_request"
+    PROTOCOL_RESPONSE = "protocol_response"
+    WEBHOOK_RECEIVED = "webhook_received"
+    HANDLER_CALLED = "handler_called"
+    STATUS_CHANGE = "status_change"
+
+
+class Activity(BaseModel):
+    """Activity event for observability."""
+
+    model_config = {"frozen": True}
+
+    type: ActivityType
+    operation_id: str
+    agent_id: str
+    task_type: str
+    status: TaskStatus | None = None
+    timestamp: str
+    metadata: dict[str, Any] | None = None
+
+
+class WebhookMetadata(BaseModel):
+    """Metadata passed to webhook handlers."""
+
+    operation_id: str
+    agent_id: str
+    task_type: str
+    status: TaskStatus
+    sequence_number: int | None = None
+    notification_type: Literal["scheduled", "final", "delayed"] | None = None
+    timestamp: str

adcp/types/generated_poc/__init__.py

@@ -0,0 +1,3 @@
+# generated by datamodel-codegen:
+#   filename:  .schema_temp
+#   timestamp: 2025-11-18T04:34:42+00:00

adcp/types/generated_poc/adagents.py

@@ -0,0 +1,411 @@
+# generated by datamodel-codegen:
+#   filename:  adagents.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import AnyUrl, AwareDatetime, ConfigDict, EmailStr, Field, RootModel
+
+from .core import property, property_id, property_tag, publisher_property_selector
+
+
+class AuthorizedSalesAgents1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    field_schema: Annotated[
+        str | None,
+        Field(alias='$schema', description='JSON Schema identifier for this adagents.json file'),
+    ] = 'https://adcontextprotocol.org/schemas/adagents.json'
+    authoritative_location: Annotated[
+        AnyUrl,
+        Field(
+            description='HTTPS URL of the authoritative adagents.json file. When present, this file is a reference and the authoritative location contains the actual agent authorization data.'
+        ),
+    ]
+    last_updated: Annotated[
+        AwareDatetime | None,
+        Field(description='ISO 8601 timestamp indicating when this reference was last updated'),
+    ] = None
+
+
+class Contact(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    domain: Annotated[
+        str | None,
+        Field(
+            description='Primary domain of the entity managing this file',
+            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
+        ),
+    ] = None
+    email: Annotated[
+        EmailStr | None,
+        Field(
+            description='Contact email for questions or issues with this authorization file',
+            max_length=255,
+            min_length=1,
+        ),
+    ] = None
+    name: Annotated[
+        str,
+        Field(
+            description="Name of the entity managing this file (e.g., 'Meta Advertising Operations', 'Clear Channel Digital')",
+            max_length=255,
+            min_length=1,
+        ),
+    ]
+    seller_id: Annotated[
+        str | None,
+        Field(
+            description='Seller ID from IAB Tech Lab sellers.json (if applicable)',
+            max_length=255,
+            min_length=1,
+        ),
+    ] = None
+    tag_id: Annotated[
+        str | None,
+        Field(
+            description='TAG Certified Against Fraud ID for verification (if applicable)',
+            max_length=100,
+            min_length=1,
+        ),
+    ] = None
+
+
+class Tags(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    description: Annotated[str, Field(description='Description of what this tag represents')]
+    name: Annotated[str, Field(description='Human-readable name for this tag')]
+
+
+class AuthorizedAgents(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    authorization_type: Annotated[
+        Literal['property_ids'],
+        Field(description='Discriminator indicating authorization by specific property IDs'),
+    ]
+    authorized_for: Annotated[
+        str,
+        Field(
+            description='Human-readable description of what this agent is authorized to sell',
+            max_length=500,
+            min_length=1,
+        ),
+    ]
+    property_ids: Annotated[
+        list[property_id.PropertyId],
+        Field(
+            description='Property IDs this agent is authorized for. Resolved against the top-level properties array in this file',
+            min_length=1,
+        ),
+    ]
+    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
+
+
+class AuthorizedAgents1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    authorization_type: Annotated[
+        Literal['property_tags'],
+        Field(description='Discriminator indicating authorization by property tags'),
+    ]
+    authorized_for: Annotated[
+        str,
+        Field(
+            description='Human-readable description of what this agent is authorized to sell',
+            max_length=500,
+            min_length=1,
+        ),
+    ]
+    property_tags: Annotated[
+        list[property_tag.PropertyTag],
+        Field(
+            description='Tags identifying which properties this agent is authorized for. Resolved against the top-level properties array in this file using tag matching',
+            min_length=1,
+        ),
+    ]
+    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
+
+
+class AuthorizedAgents3(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    authorization_type: Annotated[
+        Literal['publisher_properties'],
+        Field(
+            description='Discriminator indicating authorization for properties from other publisher domains'
+        ),
+    ]
+    authorized_for: Annotated[
+        str,
+        Field(
+            description='Human-readable description of what this agent is authorized to sell',
+            max_length=500,
+            min_length=1,
+        ),
+    ]
+    publisher_properties: Annotated[
+        list[
+            publisher_property_selector.PublisherPropertySelector1
+            | publisher_property_selector.PublisherPropertySelector2
+            | publisher_property_selector.PublisherPropertySelector3
+        ],
+        Field(
+            description='Properties from other publisher domains this agent is authorized for. Each entry specifies a publisher domain and which of their properties this agent can sell',
+            min_length=1,
+        ),
+    ]
+    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
+
+
+class AuthorizedAgents2(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    authorization_type: Annotated[
+        Literal['inline_properties'],
+        Field(description='Discriminator indicating authorization by inline property definitions'),
+    ]
+    authorized_for: Annotated[
+        str,
+        Field(
+            description='Human-readable description of what this agent is authorized to sell',
+            max_length=500,
+            min_length=1,
+        ),
+    ]
+    properties: Annotated[
+        list[property.Property],
+        Field(
+            description='Specific properties this agent is authorized for (alternative to property_ids/property_tags)',
+            min_length=1,
+        ),
+    ]
+    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
+
+
+class AuthorizedSalesAgents2(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    field_schema: Annotated[
+        str | None,
+        Field(alias='$schema', description='JSON Schema identifier for this adagents.json file'),
+    ] = 'https://adcontextprotocol.org/schemas/adagents.json'
+    authorized_agents: Annotated[
+        list[AuthorizedAgents | AuthorizedAgents1 | AuthorizedAgents2 | AuthorizedAgents3],
+        Field(
+            description='Array of sales agents authorized to sell inventory for properties in this file',
+            min_length=1,
+        ),
+    ]
+    contact: Annotated[
+        Contact | None,
+        Field(
+            description='Contact information for the entity managing this adagents.json file (may be publisher or third-party operator)'
+        ),
+    ] = None
+    last_updated: Annotated[
+        AwareDatetime | None,
+        Field(description='ISO 8601 timestamp indicating when this file was last updated'),
+    ] = None
+    properties: Annotated[
+        list[property.Property] | None,
+        Field(
+            description='Array of all properties covered by this adagents.json file. Defines the canonical property list that authorized agents reference.',
+            min_length=1,
+        ),
+    ] = None
+    tags: Annotated[
+        dict[str, Tags] | None,
+        Field(
+            description='Metadata for each tag referenced by properties. Provides human-readable context for property tag values.'
+        ),
+    ] = None
+
+
+class AuthorizedSalesAgents(RootModel[AuthorizedSalesAgents1 | AuthorizedSalesAgents2]):
+    root: Annotated[
+        AuthorizedSalesAgents1 | AuthorizedSalesAgents2,
+        Field(
+            description='Declaration of authorized sales agents for advertising inventory. Hosted at /.well-known/adagents.json on publisher domains. Can either contain the full structure inline or reference an authoritative URL.',
+            examples=[
+                {
+                    '$schema': 'https://adcontextprotocol.org/schemas/adagents.json',
+                    'authoritative_location': 'https://cdn.example.com/adagents/v2/adagents.json',
+                    'last_updated': '2025-01-15T10:00:00Z',
+                },
+                {
+                    '$schema': 'https://adcontextprotocol.org/schemas/adagents.json',
+                    'authorized_agents': [
+                        {
+                            'authorization_type': 'property_tags',
+                            'authorized_for': 'Official sales agent',
+                            'property_tags': ['all'],
+                            'url': 'https://agent.example.com',
+                        }
+                    ],
+                    'last_updated': '2025-01-10T12:00:00Z',
+                    'properties': [
+                        {
+                            'identifiers': [{'type': 'domain', 'value': 'example.com'}],
+                            'name': 'Example Site',
+                            'property_type': 'website',
+                            'publisher_domain': 'example.com',
+                        }
+                    ],
+                    'tags': {
+                        'all': {
+                            'description': 'All properties in this file',
+                            'name': 'All Properties',
+                        }
+                    },
+                },
+                {
+                    '$schema': 'https://adcontextprotocol.org/schemas/adagents.json',
+                    'authorized_agents': [
+                        {
+                            'authorization_type': 'property_tags',
+                            'authorized_for': 'All Meta properties',
+                            'property_tags': ['meta_network'],
+                            'url': 'https://meta-ads.com',
+                        }
+                    ],
+                    'contact': {
+                        'domain': 'meta.com',
+                        'email': 'adops@meta.com',
+                        'name': 'Meta Advertising Operations',
+                        'seller_id': 'pub-meta-12345',
+                        'tag_id': '12345',
+                    },
+                    'last_updated': '2025-01-10T15:30:00Z',
+                    'properties': [
+                        {
+                            'identifiers': [
+                                {'type': 'ios_bundle', 'value': 'com.burbn.instagram'},
+                                {'type': 'android_package', 'value': 'com.instagram.android'},
+                            ],
+                            'name': 'Instagram',
+                            'property_type': 'mobile_app',
+                            'publisher_domain': 'instagram.com',
+                            'tags': ['meta_network', 'social_media'],
+                        },
+                        {
+                            'identifiers': [
+                                {'type': 'ios_bundle', 'value': 'com.facebook.Facebook'},
+                                {'type': 'android_package', 'value': 'com.facebook.katana'},
+                            ],
+                            'name': 'Facebook',
+                            'property_type': 'mobile_app',
+                            'publisher_domain': 'facebook.com',
+                            'tags': ['meta_network', 'social_media'],
+                        },
+                        {
+                            'identifiers': [
+                                {'type': 'ios_bundle', 'value': 'net.whatsapp.WhatsApp'},
+                                {'type': 'android_package', 'value': 'com.whatsapp'},
+                            ],
+                            'name': 'WhatsApp',
+                            'property_type': 'mobile_app',
+                            'publisher_domain': 'whatsapp.com',
+                            'tags': ['meta_network', 'messaging'],
+                        },
+                    ],
+                    'tags': {
+                        'messaging': {
+                            'description': 'Messaging and communication apps',
+                            'name': 'Messaging Apps',
+                        },
+                        'meta_network': {
+                            'description': 'All Meta-owned properties',
+                            'name': 'Meta Network',
+                        },
+                        'social_media': {
+                            'description': 'Social networking applications',
+                            'name': 'Social Media Apps',
+                        },
+                    },
+                },
+                {
+                    '$schema': 'https://adcontextprotocol.org/schemas/adagents.json',
+                    'authorized_agents': [
+                        {
+                            'authorization_type': 'property_tags',
+                            'authorized_for': 'Tumblr corporate properties only',
+                            'property_tags': ['corporate'],
+                            'url': 'https://tumblr-sales.com',
+                        }
+                    ],
+                    'contact': {'name': 'Tumblr Advertising'},
+                    'last_updated': '2025-01-10T16:00:00Z',
+                    'properties': [
+                        {
+                            'identifiers': [{'type': 'domain', 'value': 'tumblr.com'}],
+                            'name': 'Tumblr Corporate',
+                            'property_type': 'website',
+                            'publisher_domain': 'tumblr.com',
+                            'tags': ['corporate'],
+                        }
+                    ],
+                    'tags': {
+                        'corporate': {
+                            'description': 'Tumblr-owned corporate properties (not user blogs)',
+                            'name': 'Corporate Properties',
+                        }
+                    },
+                },
+                {
+                    '$schema': 'https://adcontextprotocol.org/schemas/adagents.json',
+                    'authorized_agents': [
+                        {
+                            'authorization_type': 'publisher_properties',
+                            'authorized_for': 'CNN CTV properties via publisher authorization',
+                            'publisher_properties': [
+                                {
+                                    'property_ids': ['cnn_ctv_app'],
+                                    'publisher_domain': 'cnn.com',
+                                    'selection_type': 'by_id',
+                                }
+                            ],
+                            'url': 'https://agent.example/api',
+                        },
+                        {
+                            'authorization_type': 'publisher_properties',
+                            'authorized_for': 'All CTV properties from multiple publishers',
+                            'publisher_properties': [
+                                {
+                                    'property_tags': ['ctv'],
+                                    'publisher_domain': 'cnn.com',
+                                    'selection_type': 'by_tag',
+                                },
+                                {
+                                    'property_tags': ['ctv'],
+                                    'publisher_domain': 'espn.com',
+                                    'selection_type': 'by_tag',
+                                },
+                            ],
+                            'url': 'https://agent.example/api',
+                        },
+                    ],
+                    'contact': {
+                        'domain': 'agent.example',
+                        'email': 'sales@agent.example',
+                        'name': 'Example Third-Party Sales Agent',
+                    },
+                    'last_updated': '2025-01-10T17:00:00Z',
+                },
+            ],
+            title='Authorized Sales Agents',
+        ),
+    ]

adcp/types/generated_poc/core/__init__.py

@@ -0,0 +1,3 @@
+# generated by datamodel-codegen:
+#   filename:  .schema_temp
+#   timestamp: 2025-11-22T15:23:24+00:00

adcp/types/generated_poc/core/activation_key.py

@@ -0,0 +1,30 @@
+# generated by datamodel-codegen:
+#   filename:  core/activation_key.json
+#   timestamp: 2025-11-22T15:23:24+00:00
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from adcp.types.base import AdCPBaseModel
+from pydantic import ConfigDict, Field
+
+
+class ActivationKey1(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    segment_id: Annotated[
+        str,
+        Field(description='The platform-specific segment identifier to use in campaign targeting'),
+    ]
+    type: Annotated[Literal['segment_id'], Field(description='Segment ID based targeting')]
+
+
+class ActivationKey2(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    key: Annotated[str, Field(description='The targeting parameter key')]
+    type: Annotated[Literal['key_value'], Field(description='Key-value pair based targeting')]
+    value: Annotated[str, Field(description='The targeting parameter value')]

adcp/types/generated_poc/core/assets/__init__.py

@@ -0,0 +1,3 @@
+# generated by datamodel-codegen:
+#   filename:  .schema_temp
+#   timestamp: 2025-11-22T15:23:24+00:00

adcp/types/generated_poc/core/assets/audio_asset.py

@@ -0,0 +1,26 @@
+# generated by datamodel-codegen:
+#   filename:  core/assets/audio_asset.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 AnyUrl, ConfigDict, Field
+
+
+class AudioAsset(AdCPBaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    bitrate_kbps: Annotated[
+        int | None, Field(description='Audio bitrate in kilobits per second', ge=1)
+    ] = None
+    duration_ms: Annotated[
+        int | None, Field(description='Audio duration in milliseconds', ge=0)
+    ] = None
+    format: Annotated[str | None, Field(description='Audio file format (mp3, wav, aac, etc.)')] = (
+        None
+    )
+    url: Annotated[AnyUrl, Field(description='URL to the audio asset')]