adcp 2.8.0__py3-none-any.whl → 2.10.0__py3-none-any.whl

adcp/__init__.py

@@ -65,7 +65,6 @@ from adcp.types.aliases import (
     BothPreviewRender,
     BuildCreativeErrorResponse,
     BuildCreativeSuccessResponse,
-    CreatedPackageReference,
     CreateMediaBuyErrorResponse,
     CreateMediaBuySuccessResponse,
     HtmlPreviewRender,
@@ -109,6 +108,8 @@ from adcp.types.stable import (
     # Audience & Targeting
     ActivateSignalRequest,
     ActivateSignalResponse,
+    # Type enums from PR #222
+    AssetContentType,
     # Core domain types
     BrandManifest,
     # Creative Operations
@@ -132,6 +133,7 @@ from adcp.types.stable import (
     Error,
     FlatRatePricingOption,
     Format,
+    FormatCategory,
     FormatId,
     GetMediaBuyDeliveryRequest,
     GetMediaBuyDeliveryResponse,
@@ -177,7 +179,7 @@ from adcp.validation import (
     validate_publisher_properties_item,
 )
 
-__version__ = "2.8.0"
+__version__ = "2.10.0"
 
 __all__ = [
     # Client classes
@@ -219,6 +221,9 @@ __all__ = [
     "Error",
     "Format",
     "FormatId",
+    # New type enums from PR #222
+    "AssetContentType",
+    "FormatCategory",
     "Product",
     "Property",
     # Core domain types (from stable API)
@@ -228,8 +233,6 @@ __all__ = [
     "MediaBuy",
     "Package",
     "PackageRequest",
-    # Package type aliases
-    "CreatedPackageReference",
     # Status enums (for control flow)
     "CreativeStatus",
     "MediaBuyStatus",

adcp/__main__.py

@@ -83,11 +83,17 @@ async def execute_tool(
 
 # Tool dispatch mapping - single source of truth for ADCP methods
 # Types are filled at runtime to avoid circular imports
+# Special case: list_tools takes no parameters (None means no request type)
 TOOL_DISPATCH: dict[str, tuple[str, type | None]] = {
+    "list_tools": ("list_tools", None),  # Protocol introspection - no request type
     "get_products": ("get_products", None),
     "list_creative_formats": ("list_creative_formats", None),
+    "preview_creative": ("preview_creative", None),
+    "build_creative": ("build_creative", None),
     "sync_creatives": ("sync_creatives", None),
     "list_creatives": ("list_creatives", None),
+    "create_media_buy": ("create_media_buy", None),
+    "update_media_buy": ("update_media_buy", None),
     "get_media_buy_delivery": ("get_media_buy_delivery", None),
     "list_authorized_properties": ("list_authorized_properties", None),
     "get_signals": ("get_signals", None),
@@ -122,8 +128,12 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
             "list_creative_formats",
             gen.ListCreativeFormatsRequest,
         )
+        TOOL_DISPATCH["preview_creative"] = ("preview_creative", gen.PreviewCreativeRequest)
+        TOOL_DISPATCH["build_creative"] = ("build_creative", gen.BuildCreativeRequest)
         TOOL_DISPATCH["sync_creatives"] = ("sync_creatives", gen.SyncCreativesRequest)
         TOOL_DISPATCH["list_creatives"] = ("list_creatives", gen.ListCreativesRequest)
+        TOOL_DISPATCH["create_media_buy"] = ("create_media_buy", gen.CreateMediaBuyRequest)
+        TOOL_DISPATCH["update_media_buy"] = ("update_media_buy", gen.UpdateMediaBuyRequest)
         TOOL_DISPATCH["get_media_buy_delivery"] = (
             "get_media_buy_delivery",
             gen.GetMediaBuyDeliveryRequest,
@@ -144,21 +154,38 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
         available = ", ".join(sorted(TOOL_DISPATCH.keys()))
         return TaskResult(
             status=TaskStatus.FAILED,
+            success=False,
             error=f"Unknown tool: {tool_name}. Available tools: {available}",
         )
 
     # Get method and request type
     method_name, request_type = TOOL_DISPATCH[tool_name]
+    method = getattr(client, method_name)
 
-    # Type guard - request_type should be initialized by this point
+    # Special case: list_tools takes no parameters and returns list[str], not TaskResult
+    if tool_name == "list_tools":
+        try:
+            tools = await method()
+            return TaskResult(
+                status=TaskStatus.COMPLETED,
+                data={"tools": tools},
+                success=True,
+            )
+        except Exception as e:
+            return TaskResult(
+                status=TaskStatus.FAILED,
+                success=False,
+                error=f"Failed to list tools: {e}",
+            )
+
+    # Type guard - request_type should be initialized by this point for non-list_tools
     if request_type is None:
         return TaskResult(
             status=TaskStatus.FAILED,
+            success=False,
             error=f"Internal error: {tool_name} request type not initialized",
         )
 
-    method = getattr(client, method_name)
-
     # Validate and invoke
     try:
         request = request_type(**payload)
@@ -173,6 +200,7 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
 
         return TaskResult(
             status=TaskStatus.FAILED,
+            success=False,
             error=f"Invalid request payload for {tool_name}:\n" + "\n".join(error_details),
         )
 

adcp/client.py

@@ -28,6 +28,10 @@ from adcp.types.core import (
 from adcp.types.stable import (
     ActivateSignalRequest,
     ActivateSignalResponse,
+    BuildCreativeRequest,
+    BuildCreativeResponse,
+    CreateMediaBuyRequest,
+    CreateMediaBuyResponse,
     GetMediaBuyDeliveryRequest,
     GetMediaBuyDeliveryResponse,
     GetProductsRequest,
@@ -46,6 +50,8 @@ from adcp.types.stable import (
     ProvidePerformanceFeedbackResponse,
     SyncCreativesRequest,
     SyncCreativesResponse,
+    UpdateMediaBuyRequest,
+    UpdateMediaBuyResponse,
     WebhookPayload,
 )
 from adcp.types.stable import (
@@ -574,6 +580,200 @@ class ADCPClient:
 
         return self.adapter._parse_response(raw_result, ProvidePerformanceFeedbackResponse)
 
+    async def create_media_buy(
+        self,
+        request: CreateMediaBuyRequest,
+    ) -> TaskResult[CreateMediaBuyResponse]:
+        """
+        Create a new media buy reservation.
+
+        Requests the agent to reserve inventory for a campaign. The agent returns a
+        media_buy_id that tracks this reservation and can be used for updates.
+
+        Args:
+            request: Media buy creation parameters including:
+                - brand_manifest: Advertiser brand information and creative assets
+                - packages: List of package requests specifying desired inventory
+                - publisher_properties: Target properties for ad placement
+                - budget: Optional budget constraints
+                - start_date/end_date: Campaign flight dates
+
+        Returns:
+            TaskResult containing CreateMediaBuyResponse with:
+                - media_buy_id: Unique identifier for this reservation
+                - status: Current state of the media buy
+                - packages: Confirmed package details
+                - Additional platform-specific metadata
+
+        Example:
+            >>> from adcp import ADCPClient, CreateMediaBuyRequest
+            >>> client = ADCPClient(agent_config)
+            >>> request = CreateMediaBuyRequest(
+            ...     brand_manifest=brand,
+            ...     packages=[package_request],
+            ...     publisher_properties=properties
+            ... )
+            >>> result = await client.create_media_buy(request)
+            >>> if result.success:
+            ...     media_buy_id = result.data.media_buy_id
+        """
+        operation_id = create_operation_id()
+        params = request.model_dump(exclude_none=True)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="create_media_buy",
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        raw_result = await self.adapter.create_media_buy(params)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="create_media_buy",
+                status=raw_result.status,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        return self.adapter._parse_response(raw_result, CreateMediaBuyResponse)
+
+    async def update_media_buy(
+        self,
+        request: UpdateMediaBuyRequest,
+    ) -> TaskResult[UpdateMediaBuyResponse]:
+        """
+        Update an existing media buy reservation.
+
+        Modifies a previously created media buy by updating packages or publisher
+        properties. The update operation uses discriminated unions to specify what
+        to change - either package details or targeting properties.
+
+        Args:
+            request: Media buy update parameters including:
+                - media_buy_id: Identifier from create_media_buy response
+                - updates: Discriminated union specifying update type:
+                    * UpdateMediaBuyPackagesRequest: Modify package selections
+                    * UpdateMediaBuyPropertiesRequest: Change targeting properties
+
+        Returns:
+            TaskResult containing UpdateMediaBuyResponse with:
+                - media_buy_id: The updated media buy identifier
+                - status: Updated state of the media buy
+                - packages: Updated package configurations
+                - Additional platform-specific metadata
+
+        Example:
+            >>> from adcp import ADCPClient, UpdateMediaBuyPackagesRequest
+            >>> client = ADCPClient(agent_config)
+            >>> request = UpdateMediaBuyPackagesRequest(
+            ...     media_buy_id="mb_123",
+            ...     packages=[updated_package]
+            ... )
+            >>> result = await client.update_media_buy(request)
+            >>> if result.success:
+            ...     updated_packages = result.data.packages
+        """
+        operation_id = create_operation_id()
+        params = request.model_dump(exclude_none=True)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="update_media_buy",
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        raw_result = await self.adapter.update_media_buy(params)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="update_media_buy",
+                status=raw_result.status,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        return self.adapter._parse_response(raw_result, UpdateMediaBuyResponse)
+
+    async def build_creative(
+        self,
+        request: BuildCreativeRequest,
+    ) -> TaskResult[BuildCreativeResponse]:
+        """
+        Generate production-ready creative assets.
+
+        Requests the creative agent to build final deliverable assets in the target
+        format (e.g., VAST, DAAST, HTML5). This is typically called after previewing
+        and approving a creative manifest.
+
+        Args:
+            request: Creative build parameters including:
+                - manifest: Creative manifest with brand info and content
+                - target_format_id: Desired output format identifier
+                - inputs: Optional user-provided inputs for template variables
+                - deployment: Platform or agent deployment configuration
+
+        Returns:
+            TaskResult containing BuildCreativeResponse with:
+                - assets: Production-ready creative files (URLs or inline content)
+                - format_id: The generated format identifier
+                - manifest: The creative manifest used for generation
+                - metadata: Additional platform-specific details
+
+        Example:
+            >>> from adcp import ADCPClient, BuildCreativeRequest
+            >>> client = ADCPClient(agent_config)
+            >>> request = BuildCreativeRequest(
+            ...     manifest=creative_manifest,
+            ...     target_format_id="vast_2.0",
+            ...     inputs={"duration": 30}
+            ... )
+            >>> result = await client.build_creative(request)
+            >>> if result.success:
+            ...     vast_url = result.data.assets[0].url
+        """
+        operation_id = create_operation_id()
+        params = request.model_dump(exclude_none=True)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="build_creative",
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        raw_result = await self.adapter.build_creative(params)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="build_creative",
+                status=raw_result.status,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        return self.adapter._parse_response(raw_result, BuildCreativeResponse)
+
     async def list_tools(self) -> list[str]:
         """
         List available tools from the agent.

adcp/protocols/a2a.py

@@ -248,6 +248,18 @@ class A2AAdapter(ProtocolAdapter):
         """Generate preview URLs for a creative manifest."""
         return await self._call_a2a_tool("preview_creative", params)
 
+    async def create_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Create media buy."""
+        return await self._call_a2a_tool("create_media_buy", params)
+
+    async def update_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Update media buy."""
+        return await self._call_a2a_tool("update_media_buy", params)
+
+    async def build_creative(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Build creative."""
+        return await self._call_a2a_tool("build_creative", params)
+
     async def list_tools(self) -> list[str]:
         """
         List available tools from A2A agent.

adcp/protocols/base.py

@@ -136,6 +136,21 @@ class ProtocolAdapter(ABC):
         """Provide performance feedback."""
         pass
 
+    @abstractmethod
+    async def create_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Create media buy."""
+        pass
+
+    @abstractmethod
+    async def update_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Update media buy."""
+        pass
+
+    @abstractmethod
+    async def build_creative(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Build creative."""
+        pass
+
     @abstractmethod
     async def list_tools(self) -> list[str]:
         """

adcp/protocols/mcp.py

@@ -373,6 +373,18 @@ class MCPAdapter(ProtocolAdapter):
         """Generate preview URLs for a creative manifest."""
         return await self._call_mcp_tool("preview_creative", params)
 
+    async def create_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Create media buy."""
+        return await self._call_mcp_tool("create_media_buy", params)
+
+    async def update_media_buy(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Update media buy."""
+        return await self._call_mcp_tool("update_media_buy", params)
+
+    async def build_creative(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Build creative."""
+        return await self._call_mcp_tool("build_creative", params)
+
     async def list_tools(self) -> list[str]:
         """List available tools from MCP agent."""
         session = await self._get_session()

adcp/simple.py

@@ -26,6 +26,10 @@ from adcp.exceptions import ADCPSimpleAPIError
 from adcp.types.stable import (
     ActivateSignalRequest,
     ActivateSignalResponse,
+    BuildCreativeRequest,
+    BuildCreativeResponse,
+    CreateMediaBuyRequest,
+    CreateMediaBuyResponse,
     GetMediaBuyDeliveryRequest,
     GetMediaBuyDeliveryResponse,
     GetProductsRequest,
@@ -44,6 +48,8 @@ from adcp.types.stable import (
     ProvidePerformanceFeedbackResponse,
     SyncCreativesRequest,
     SyncCreativesResponse,
+    UpdateMediaBuyRequest,
+    UpdateMediaBuyResponse,
 )
 
 if TYPE_CHECKING:
@@ -345,3 +351,101 @@ class SimpleAPI:
                 agent_id=self._client.agent_config.id,
             )
         return result.data
+
+    async def create_media_buy(
+        self,
+        **kwargs: Any,
+    ) -> CreateMediaBuyResponse:
+        """Create media buy.
+
+        Args:
+            **kwargs: Arguments passed to CreateMediaBuyRequest
+
+        Returns:
+            CreateMediaBuyResponse
+
+        Raises:
+            Exception: If the request fails
+
+        Example:
+            media_buy = await client.simple.create_media_buy(
+                brand_manifest=brand,
+                packages=[package_request],
+                publisher_properties=properties
+            )
+            print(f"Created media buy: {media_buy.media_buy_id}")
+        """
+        request = CreateMediaBuyRequest(**kwargs)
+        result = await self._client.create_media_buy(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="create_media_buy",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def update_media_buy(
+        self,
+        **kwargs: Any,
+    ) -> UpdateMediaBuyResponse:
+        """Update media buy.
+
+        Args:
+            **kwargs: Arguments passed to UpdateMediaBuyRequest
+
+        Returns:
+            UpdateMediaBuyResponse
+
+        Raises:
+            Exception: If the request fails
+
+        Example:
+            updated = await client.simple.update_media_buy(
+                media_buy_id="mb_123",
+                packages=[updated_package]
+            )
+            print(f"Updated media buy: {updated.media_buy_id}")
+        """
+        request = UpdateMediaBuyRequest(**kwargs)
+        result = await self._client.update_media_buy(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="update_media_buy",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def build_creative(
+        self,
+        **kwargs: Any,
+    ) -> BuildCreativeResponse:
+        """Build creative.
+
+        Args:
+            **kwargs: Arguments passed to BuildCreativeRequest
+
+        Returns:
+            BuildCreativeResponse
+
+        Raises:
+            Exception: If the request fails
+
+        Example:
+            creative = await client.simple.build_creative(
+                manifest=creative_manifest,
+                target_format_id="vast_2.0",
+                inputs={"duration": 30}
+            )
+            print(f"Built creative: {creative.assets[0].url}")
+        """
+        request = BuildCreativeRequest(**kwargs)
+        result = await self._client.build_creative(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="build_creative",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data

adcp/types/__init__.py

@@ -29,8 +29,6 @@ from adcp.types.aliases import (
     # Build creative responses
     BuildCreativeErrorResponse,
     BuildCreativeSuccessResponse,
-    # Package aliases
-    CreatedPackageReference,
     # Create media buy responses
     CreateMediaBuyErrorResponse,
     CreateMediaBuySuccessResponse,
@@ -104,13 +102,11 @@ from adcp.types.stable import (
     Action,
     ActivateSignalRequest,
     ActivateSignalResponse,
-    AffectedPackage,
     AggregatedTotals,
     Asset,
     AssetSelectors,
     AssetsRequired,
     AssetType,
-    AssetTypeSchema,
     AssignedPackage,
     Assignments,
     AudioAsset,
@@ -128,7 +124,6 @@ from adcp.types.stable import (
     CoBranding,
     Colors,
     Contact,
-    ContentLength,
     Country,
     CpcPricingOption,
     CpcvPricingOption,
@@ -153,19 +148,16 @@ from adcp.types.stable import (
     DeliveryMetrics,
     DeliveryType,
     Details,
-    Dimensions,
     Direction,
     Disclaimer,
     Domain,
     DomainBreakdown,
     DoohMetrics,
-    Duration,
     Embedding,
     Error,
     FeedbackSource,
     FeedFormat,
     FieldModel,
-    FileSize,
     Filters,
     FlatRatePricingOption,
     Fonts,
@@ -246,7 +238,6 @@ from adcp.types.stable import (
     PublisherDomain,
     PublisherIdentifierTypes,
     PushNotificationConfig,
-    Quality,
     QuartileData,
     QuerySummary,
     Render,
@@ -256,7 +247,6 @@ from adcp.types.stable import (
     ReportingWebhook,
     Request,
     RequestedMetric,
-    Requirements,
     Response,
     ResponseType,
     Responsive,
@@ -330,14 +320,12 @@ __all__ = [
     "ActivateSignalRequest",
     "ActivateSignalResponse",
     "ActivateSignalSuccessResponse",
-    "AffectedPackage",
     "AgentDeployment",
     "AgentDestination",
     "AggregatedTotals",
     "Asset",
     "AssetSelectors",
     "AssetType",
-    "AssetTypeSchema",
     "AssetsRequired",
     "AssignedPackage",
     "Assignments",
@@ -364,7 +352,6 @@ __all__ = [
     "CoBranding",
     "Colors",
     "Contact",
-    "ContentLength",
     "Country",
     "CpcPricingOption",
     "CpcvPricingOption",
@@ -376,7 +363,6 @@ __all__ = [
     "CreateMediaBuyRequest",
     "CreateMediaBuyResponse",
     "CreateMediaBuySuccessResponse",
-    "CreatedPackageReference",
     "Creative",
     "CreativeAgent",
     "CreativeAsset",
@@ -394,19 +380,16 @@ __all__ = [
     "Deployment",
     "Destination",
     "Details",
-    "Dimensions",
     "Direction",
     "Disclaimer",
     "Domain",
     "DomainBreakdown",
     "DoohMetrics",
-    "Duration",
     "Embedding",
     "Error",
     "FeedFormat",
     "FeedbackSource",
     "FieldModel",
-    "FileSize",
     "Filters",
     "FlatRatePricingOption",
     "Fonts",
@@ -507,7 +490,6 @@ __all__ = [
     "PublisherPropertiesById",
     "PublisherPropertiesByTag",
     "PushNotificationConfig",
-    "Quality",
     "QuartileData",
     "QuerySummary",
     "Render",
@@ -517,7 +499,6 @@ __all__ = [
     "ReportingWebhook",
     "Request",
     "RequestedMetric",
-    "Requirements",
     "Response",
     "ResponseType",
     "Responsive",