adcp 1.0.2__py3-none-any.whl → 1.0.3__py3-none-any.whl

adcp/__init__.py

@@ -46,7 +46,7 @@ from adcp.types.generated import (
     UpdateMediaBuyResponse,
 )
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 
 __all__ = [
     # Client classes

adcp/__main__.py

@@ -36,13 +36,15 @@ def print_result(result: Any, json_output: bool = False) -> None:
                 "data": result.data,
                 "error": result.error,
                 "metadata": result.metadata,
-                "debug_info": {
-                    "request": result.debug_info.request,
-                    "response": result.debug_info.response,
-                    "duration_ms": result.debug_info.duration_ms,
-                }
-                if result.debug_info
-                else None,
+                "debug_info": (
+                    {
+                        "request": result.debug_info.request,
+                        "response": result.debug_info.response,
+                        "duration_ms": result.debug_info.duration_ms,
+                    }
+                    if result.debug_info
+                    else None
+                ),
             }
         )
     else:
@@ -73,10 +75,107 @@ async def execute_tool(
     config = AgentConfig(**agent_config)
 
     async with ADCPClient(config) as client:
-        result = await client.call_tool(tool_name, payload)
+        # Dispatch to specific method based on tool name
+        result = await _dispatch_tool(client, tool_name, payload)
         print_result(result, json_output)
 
 
+# Tool dispatch mapping - single source of truth for ADCP methods
+# Types are filled at runtime to avoid circular imports
+TOOL_DISPATCH: dict[str, tuple[str, type | None]] = {
+    "get_products": ("get_products", None),
+    "list_creative_formats": ("list_creative_formats", None),
+    "sync_creatives": ("sync_creatives", None),
+    "list_creatives": ("list_creatives", None),
+    "get_media_buy_delivery": ("get_media_buy_delivery", None),
+    "list_authorized_properties": ("list_authorized_properties", None),
+    "get_signals": ("get_signals", None),
+    "activate_signal": ("activate_signal", None),
+    "provide_performance_feedback": ("provide_performance_feedback", None),
+}
+
+
+async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str, Any]) -> Any:
+    """Dispatch tool call to appropriate client method.
+
+    Args:
+        client: ADCP client instance
+        tool_name: Name of the tool to invoke
+        payload: Request payload as dict
+
+    Returns:
+        TaskResult with typed response or error
+
+    Raises:
+        ValidationError: If payload doesn't match request schema (caught and returned as TaskResult)
+    """
+    from pydantic import ValidationError
+
+    from adcp.types import generated as gen
+    from adcp.types.core import TaskResult, TaskStatus
+
+    # Lazy initialization of request types (avoid circular imports)
+    if TOOL_DISPATCH["get_products"][1] is None:
+        TOOL_DISPATCH["get_products"] = ("get_products", gen.GetProductsRequest)
+        TOOL_DISPATCH["list_creative_formats"] = (
+            "list_creative_formats",
+            gen.ListCreativeFormatsRequest,
+        )
+        TOOL_DISPATCH["sync_creatives"] = ("sync_creatives", gen.SyncCreativesRequest)
+        TOOL_DISPATCH["list_creatives"] = ("list_creatives", gen.ListCreativesRequest)
+        TOOL_DISPATCH["get_media_buy_delivery"] = (
+            "get_media_buy_delivery",
+            gen.GetMediaBuyDeliveryRequest,
+        )
+        TOOL_DISPATCH["list_authorized_properties"] = (
+            "list_authorized_properties",
+            gen.ListAuthorizedPropertiesRequest,
+        )
+        TOOL_DISPATCH["get_signals"] = ("get_signals", gen.GetSignalsRequest)
+        TOOL_DISPATCH["activate_signal"] = ("activate_signal", gen.ActivateSignalRequest)
+        TOOL_DISPATCH["provide_performance_feedback"] = (
+            "provide_performance_feedback",
+            gen.ProvidePerformanceFeedbackRequest,
+        )
+
+    # Check if tool exists
+    if tool_name not in TOOL_DISPATCH:
+        available = ", ".join(sorted(TOOL_DISPATCH.keys()))
+        return TaskResult(
+            status=TaskStatus.FAILED,
+            error=f"Unknown tool: {tool_name}. Available tools: {available}",
+        )
+
+    # Get method and request type
+    method_name, request_type = TOOL_DISPATCH[tool_name]
+
+    # Type guard - request_type should be initialized by this point
+    if request_type is None:
+        return TaskResult(
+            status=TaskStatus.FAILED,
+            error=f"Internal error: {tool_name} request type not initialized",
+        )
+
+    method = getattr(client, method_name)
+
+    # Validate and invoke
+    try:
+        request = request_type(**payload)
+        return await method(request)
+    except ValidationError as e:
+        # User-friendly error for invalid payloads
+        error_details = []
+        for error in e.errors():
+            field = ".".join(str(loc) for loc in error["loc"])
+            msg = error["msg"]
+            error_details.append(f"  - {field}: {msg}")
+
+        return TaskResult(
+            status=TaskStatus.FAILED,
+            error=f"Invalid request payload for {tool_name}:\n" + "\n".join(error_details),
+        )
+
+
 def load_payload(payload_arg: str | None) -> dict[str, Any]:
     """Load payload from argument (JSON, @file, or stdin)."""
     if not payload_arg:

adcp/client.py

@@ -41,6 +41,7 @@ from adcp.types.generated import (
     ProvidePerformanceFeedbackResponse,
     SyncCreativesRequest,
     SyncCreativesResponse,
+    WebhookPayload,
 )
 from adcp.utils.operation_id import create_operation_id
 
@@ -123,7 +124,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("get_products", params)
+        raw_result = await self.adapter.get_products(params)
 
         self._emit_activity(
             Activity(
@@ -131,12 +132,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="get_products",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, GetProductsResponse)
 
     async def list_creative_formats(
         self,
@@ -164,7 +165,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("list_creative_formats", params)
+        raw_result = await self.adapter.list_creative_formats(params)
 
         self._emit_activity(
             Activity(
@@ -172,12 +173,13 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="list_creative_formats",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        # Parse response using adapter's helper
+        return self.adapter._parse_response(raw_result, ListCreativeFormatsResponse)
 
     async def sync_creatives(
         self,
@@ -205,7 +207,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("sync_creatives", params)
+        raw_result = await self.adapter.sync_creatives(params)
 
         self._emit_activity(
             Activity(
@@ -213,12 +215,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="sync_creatives",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, SyncCreativesResponse)
 
     async def list_creatives(
         self,
@@ -246,7 +248,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("list_creatives", params)
+        raw_result = await self.adapter.list_creatives(params)
 
         self._emit_activity(
             Activity(
@@ -254,12 +256,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="list_creatives",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, ListCreativesResponse)
 
     async def get_media_buy_delivery(
         self,
@@ -287,7 +289,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("get_media_buy_delivery", params)
+        raw_result = await self.adapter.get_media_buy_delivery(params)
 
         self._emit_activity(
             Activity(
@@ -295,12 +297,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="get_media_buy_delivery",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, GetMediaBuyDeliveryResponse)
 
     async def list_authorized_properties(
         self,
@@ -328,7 +330,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("list_authorized_properties", params)
+        raw_result = await self.adapter.list_authorized_properties(params)
 
         self._emit_activity(
             Activity(
@@ -336,12 +338,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="list_authorized_properties",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, ListAuthorizedPropertiesResponse)
 
     async def get_signals(
         self,
@@ -369,7 +371,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("get_signals", params)
+        raw_result = await self.adapter.get_signals(params)
 
         self._emit_activity(
             Activity(
@@ -377,12 +379,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="get_signals",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, GetSignalsResponse)
 
     async def activate_signal(
         self,
@@ -410,7 +412,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("activate_signal", params)
+        raw_result = await self.adapter.activate_signal(params)
 
         self._emit_activity(
             Activity(
@@ -418,12 +420,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="activate_signal",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
+        return self.adapter._parse_response(raw_result, ActivateSignalResponse)
 
     async def provide_performance_feedback(
         self,
@@ -451,7 +453,7 @@ class ADCPClient:
             )
         )
 
-        result = await self.adapter.call_tool("provide_performance_feedback", params)
+        raw_result = await self.adapter.provide_performance_feedback(params)
 
         self._emit_activity(
             Activity(
@@ -459,50 +461,12 @@ class ADCPClient:
                 operation_id=operation_id,
                 agent_id=self.agent_config.id,
                 task_type="provide_performance_feedback",
-                status=result.status,
+                status=raw_result.status,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             )
         )
 
-        return result
-
-    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
-        """
-        Call any tool on the agent.
-
-        Args:
-            tool_name: Name of the tool to call
-            params: Tool parameters
-
-        Returns:
-            TaskResult with the response
-        """
-        operation_id = create_operation_id()
-
-        self._emit_activity(
-            Activity(
-                type=ActivityType.PROTOCOL_REQUEST,
-                operation_id=operation_id,
-                agent_id=self.agent_config.id,
-                task_type=tool_name,
-                timestamp=datetime.now(timezone.utc).isoformat(),
-            )
-        )
-
-        result = await self.adapter.call_tool(tool_name, params)
-
-        self._emit_activity(
-            Activity(
-                type=ActivityType.PROTOCOL_RESPONSE,
-                operation_id=operation_id,
-                agent_id=self.agent_config.id,
-                task_type=tool_name,
-                status=result.status,
-                timestamp=datetime.now(timezone.utc).isoformat(),
-            )
-        )
-
-        return result
+        return self.adapter._parse_response(raw_result, ProvidePerformanceFeedbackResponse)
 
     async def list_tools(self) -> list[str]:
         """
@@ -548,41 +512,132 @@ class ADCPClient:
 
         return hmac.compare_digest(signature, expected_signature)
 
+    def _parse_webhook_result(self, webhook: WebhookPayload) -> TaskResult[Any]:
+        """
+        Parse webhook payload into typed TaskResult based on task_type.
+
+        Args:
+            webhook: Validated webhook payload
+
+        Returns:
+            TaskResult with task-specific typed response data
+        """
+        from adcp.types.core import TaskStatus
+        from adcp.utils.response_parser import parse_json_or_text
+
+        # Map task types to their response types (using string literals, not enum)
+        response_type_map: dict[str, type] = {
+            "get_products": GetProductsResponse,
+            "list_creative_formats": ListCreativeFormatsResponse,
+            "sync_creatives": SyncCreativesResponse,
+            "list_creatives": ListCreativesResponse,
+            "get_media_buy_delivery": GetMediaBuyDeliveryResponse,
+            "list_authorized_properties": ListAuthorizedPropertiesResponse,
+            "get_signals": GetSignalsResponse,
+            "activate_signal": ActivateSignalResponse,
+            "provide_performance_feedback": ProvidePerformanceFeedbackResponse,
+        }
+
+        # Handle completed tasks with result parsing
+
+        if webhook.status == "completed" and webhook.result is not None:
+            response_type = response_type_map.get(webhook.task_type)
+            if response_type:
+                try:
+                    parsed_result: Any = parse_json_or_text(webhook.result, response_type)
+                    return TaskResult[Any](
+                        status=TaskStatus.COMPLETED,
+                        data=parsed_result,
+                        success=True,
+                        metadata={
+                            "task_id": webhook.task_id,
+                            "operation_id": webhook.operation_id,
+                            "timestamp": webhook.timestamp,
+                            "message": webhook.message,
+                        },
+                    )
+                except ValueError as e:
+                    logger.warning(f"Failed to parse webhook result: {e}")
+                    # Fall through to untyped result
+
+        # Handle failed, input-required, or unparseable results
+        # Convert webhook status string to TaskStatus enum
+        try:
+            task_status = TaskStatus(webhook.status)
+        except ValueError:
+            # Fallback to FAILED for unknown statuses
+            task_status = TaskStatus.FAILED
+
+        return TaskResult[Any](
+            status=task_status,
+            data=webhook.result,
+            success=webhook.status == "completed",
+            error=webhook.error if isinstance(webhook.error, str) else None,
+            metadata={
+                "task_id": webhook.task_id,
+                "operation_id": webhook.operation_id,
+                "timestamp": webhook.timestamp,
+                "message": webhook.message,
+                "context_id": webhook.context_id,
+                "progress": webhook.progress,
+            },
+        )
+
     async def handle_webhook(
         self,
         payload: dict[str, Any],
         signature: str | None = None,
-    ) -> None:
+    ) -> TaskResult[Any]:
         """
-        Handle incoming webhook.
+        Handle incoming webhook and return typed result.
+
+        This method:
+        1. Verifies webhook signature (if provided)
+        2. Validates payload against WebhookPayload schema
+        3. Parses task-specific result data into typed response
+        4. Emits activity for monitoring
 
         Args:
-            payload: Webhook payload
-            signature: Webhook signature for verification
+            payload: Webhook payload dict
+            signature: Optional HMAC-SHA256 signature for verification
+
+        Returns:
+            TaskResult with parsed task-specific response data
 
         Raises:
             ADCPWebhookSignatureError: If signature verification fails
+            ValidationError: If payload doesn't match WebhookPayload schema
+
+        Example:
+            >>> result = await client.handle_webhook(payload, signature)
+            >>> if result.success and isinstance(result.data, GetProductsResponse):
+            >>>     print(f"Found {len(result.data.products)} products")
         """
+        # Verify signature before processing
         if signature and not self._verify_webhook_signature(payload, signature):
             logger.warning(
                 f"Webhook signature verification failed for agent {self.agent_config.id}"
             )
             raise ADCPWebhookSignatureError("Invalid webhook signature")
 
-        operation_id = payload.get("operation_id", "unknown")
-        task_type = payload.get("task_type", "unknown")
+        # Validate and parse webhook payload
+        webhook = WebhookPayload.model_validate(payload)
 
+        # Emit activity for monitoring
         self._emit_activity(
             Activity(
                 type=ActivityType.WEBHOOK_RECEIVED,
-                operation_id=operation_id,
+                operation_id=webhook.operation_id or "unknown",
                 agent_id=self.agent_config.id,
-                task_type=task_type,
+                task_type=webhook.task_type,
                 timestamp=datetime.now(timezone.utc).isoformat(),
                 metadata={"payload": payload},
             )
         )
 
+        # Parse and return typed result
+        return self._parse_webhook_result(webhook)
+
 
 class ADCPMultiAgentClient:
     """Client for managing multiple AdCP agents."""

adcp/protocols/a2a.py

@@ -54,7 +54,7 @@ class A2AAdapter(ProtocolAdapter):
             await self._client.aclose()
             self._client = None
 
-    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+    async def _call_a2a_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
         """
         Call a tool using A2A protocol.
 
@@ -98,9 +98,11 @@ class A2AAdapter(ProtocolAdapter):
                 "url": url,
                 "method": "POST",
                 "headers": {
-                    k: v
-                    if k.lower() not in ("authorization", self.agent_config.auth_header.lower())
-                    else "***"
+                    k: (
+                        v
+                        if k.lower() not in ("authorization", self.agent_config.auth_header.lower())
+                        else "***"
+                    )
                     for k, v in headers.items()
                 },
                 "body": request_data,
@@ -202,6 +204,46 @@ class A2AAdapter(ProtocolAdapter):
 
         return first_part
 
+    # ========================================================================
+    # ADCP Protocol Methods
+    # ========================================================================
+
+    async def get_products(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get advertising products."""
+        return await self._call_a2a_tool("get_products", params)
+
+    async def list_creative_formats(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List supported creative formats."""
+        return await self._call_a2a_tool("list_creative_formats", params)
+
+    async def sync_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Sync creatives."""
+        return await self._call_a2a_tool("sync_creatives", params)
+
+    async def list_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List creatives."""
+        return await self._call_a2a_tool("list_creatives", params)
+
+    async def get_media_buy_delivery(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get media buy delivery."""
+        return await self._call_a2a_tool("get_media_buy_delivery", params)
+
+    async def list_authorized_properties(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List authorized properties."""
+        return await self._call_a2a_tool("list_authorized_properties", params)
+
+    async def get_signals(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get signals."""
+        return await self._call_a2a_tool("get_signals", params)
+
+    async def activate_signal(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Activate signal."""
+        return await self._call_a2a_tool("activate_signal", params)
+
+    async def provide_performance_feedback(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Provide performance feedback."""
+        return await self._call_a2a_tool("provide_performance_feedback", params)
+
     async def list_tools(self) -> list[str]:
         """
         List available tools from A2A agent.