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

adcp/protocols/base.py

@@ -3,30 +3,131 @@ from __future__ import annotations
 """Base protocol adapter interface."""
 
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, TypeVar
 
-from adcp.types.core import AgentConfig, TaskResult
+from pydantic import BaseModel
+
+from adcp.types.core import AgentConfig, TaskResult, TaskStatus
+from adcp.utils.response_parser import parse_json_or_text, parse_mcp_content
+
+T = TypeVar("T", bound=BaseModel)
 
 
 class ProtocolAdapter(ABC):
-    """Base class for protocol adapters."""
+    """
+    Base class for protocol adapters.
+
+    Each adapter implements the ADCP protocol methods and handles
+    protocol-specific translation (MCP/A2A) while returning properly
+    typed responses.
+    """
 
     def __init__(self, agent_config: AgentConfig):
         """Initialize adapter with agent configuration."""
         self.agent_config = agent_config
 
-    @abstractmethod
-    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+    # ========================================================================
+    # Helper methods for response parsing
+    # ========================================================================
+
+    def _parse_response(self, raw_result: TaskResult[Any], response_type: type[T]) -> TaskResult[T]:
         """
-        Call a tool on the agent.
+        Parse raw TaskResult into typed TaskResult.
+
+        Handles both MCP content arrays and A2A dict responses.
 
         Args:
-            tool_name: Name of the tool to call
-            params: Tool parameters
+            raw_result: Raw TaskResult from adapter
+            response_type: Expected Pydantic response type
 
         Returns:
-            TaskResult with the response
+            Typed TaskResult
         """
+        # Handle failed results or missing data
+        if not raw_result.success or raw_result.data is None:
+            # Explicitly construct typed result to satisfy type checker
+            return TaskResult[T](
+                status=raw_result.status,
+                data=None,
+                success=False,
+                error=raw_result.error or "No data returned from adapter",
+                metadata=raw_result.metadata,
+                debug_info=raw_result.debug_info,
+            )
+
+        try:
+            # Handle MCP content arrays
+            if isinstance(raw_result.data, list):
+                parsed_data = parse_mcp_content(raw_result.data, response_type)
+            else:
+                # Handle A2A or direct responses
+                parsed_data = parse_json_or_text(raw_result.data, response_type)
+
+            return TaskResult[T](
+                status=raw_result.status,
+                data=parsed_data,
+                success=raw_result.success,
+                error=raw_result.error,
+                metadata=raw_result.metadata,
+                debug_info=raw_result.debug_info,
+            )
+        except ValueError as e:
+            # Parsing failed - return error result
+            return TaskResult[T](
+                status=TaskStatus.FAILED,
+                error=f"Failed to parse response: {e}",
+                success=False,
+                debug_info=raw_result.debug_info,
+            )
+
+    # ========================================================================
+    # ADCP Protocol Methods - Type-safe, spec-aligned interface
+    # Each adapter MUST implement these methods explicitly.
+    # ========================================================================
+
+    @abstractmethod
+    async def get_products(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get advertising products."""
+        pass
+
+    @abstractmethod
+    async def list_creative_formats(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List supported creative formats."""
+        pass
+
+    @abstractmethod
+    async def sync_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Sync creatives."""
+        pass
+
+    @abstractmethod
+    async def list_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List creatives."""
+        pass
+
+    @abstractmethod
+    async def get_media_buy_delivery(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get media buy delivery."""
+        pass
+
+    @abstractmethod
+    async def list_authorized_properties(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List authorized properties."""
+        pass
+
+    @abstractmethod
+    async def get_signals(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get signals."""
+        pass
+
+    @abstractmethod
+    async def activate_signal(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Activate signal."""
+        pass
+
+    @abstractmethod
+    async def provide_performance_feedback(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Provide performance feedback."""
         pass
 
     @abstractmethod

adcp/protocols/mcp.py

@@ -186,7 +186,41 @@ class MCPAdapter(ProtocolAdapter):
         else:
             raise ValueError(f"Unsupported transport scheme: {parsed.scheme}")
 
-    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+    def _serialize_mcp_content(self, content: list[Any]) -> list[dict[str, Any]]:
+        """
+        Convert MCP SDK content objects to plain dicts.
+
+        The MCP SDK returns Pydantic objects (TextContent, ImageContent, etc.)
+        but the rest of the ADCP client expects protocol-agnostic dicts.
+        This method handles the translation at the protocol boundary.
+
+        Args:
+            content: List of MCP content items (may be dicts or Pydantic objects)
+
+        Returns:
+            List of plain dicts representing the content
+        """
+        result = []
+        for item in content:
+            # Already a dict, pass through
+            if isinstance(item, dict):
+                result.append(item)
+            # Pydantic v2 model with model_dump()
+            elif hasattr(item, "model_dump"):
+                result.append(item.model_dump())
+            # Pydantic v1 model with dict()
+            elif hasattr(item, "dict") and callable(item.dict):
+                result.append(item.dict())
+            # Fallback: try to access __dict__
+            elif hasattr(item, "__dict__"):
+                result.append(dict(item.__dict__))
+            # Last resort: serialize as unknown type
+            else:
+                logger.warning(f"Unknown MCP content type: {type(item)}, serializing as string")
+                result.append({"type": "unknown", "data": str(item)})
+        return result
+
+    async def _call_mcp_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
         """Call a tool using MCP protocol."""
         start_time = time.time() if self.agent_config.debug else None
         debug_info = None
@@ -205,12 +239,15 @@ class MCPAdapter(ProtocolAdapter):
             # Call the tool using MCP client session
             result = await session.call_tool(tool_name, params)
 
+            # Serialize MCP SDK types to plain dicts at protocol boundary
+            serialized_content = self._serialize_mcp_content(result.content)
+
             if self.agent_config.debug and start_time:
                 duration_ms = (time.time() - start_time) * 1000
                 debug_info = DebugInfo(
                     request=debug_request,
                     response={
-                        "content": result.content,
+                        "content": serialized_content,
                         "is_error": result.isError if hasattr(result, "isError") else False,
                     },
                     duration_ms=duration_ms,
@@ -220,7 +257,7 @@ class MCPAdapter(ProtocolAdapter):
             # For AdCP, we expect the data in the content
             return TaskResult[Any](
                 status=TaskStatus.COMPLETED,
-                data=result.content,
+                data=serialized_content,
                 success=True,
                 debug_info=debug_info,
             )
@@ -240,6 +277,46 @@ class MCPAdapter(ProtocolAdapter):
                 debug_info=debug_info,
             )
 
+    # ========================================================================
+    # ADCP Protocol Methods
+    # ========================================================================
+
+    async def get_products(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get advertising products."""
+        return await self._call_mcp_tool("get_products", params)
+
+    async def list_creative_formats(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List supported creative formats."""
+        return await self._call_mcp_tool("list_creative_formats", params)
+
+    async def sync_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Sync creatives."""
+        return await self._call_mcp_tool("sync_creatives", params)
+
+    async def list_creatives(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """List creatives."""
+        return await self._call_mcp_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_mcp_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_mcp_tool("list_authorized_properties", params)
+
+    async def get_signals(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Get signals."""
+        return await self._call_mcp_tool("get_signals", params)
+
+    async def activate_signal(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Activate signal."""
+        return await self._call_mcp_tool("activate_signal", params)
+
+    async def provide_performance_feedback(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Provide performance feedback."""
+        return await self._call_mcp_tool("provide_performance_feedback", params)
+
     async def list_tools(self) -> list[str]:
         """List available tools from MCP agent."""
         session = await self._get_session()

adcp/types/generated.py

@@ -11,9 +11,10 @@ To regenerate:
 
 from __future__ import annotations
 
+import re
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 # ============================================================================
@@ -22,7 +23,6 @@ from pydantic import BaseModel, Field
 
 # These types are referenced in schemas but don't have schema files
 # Defining them as type aliases to maintain type safety
-FormatId = str
 PackageRequest = dict[str, Any]
 PushNotificationConfig = dict[str, Any]
 ReportingCapabilities = dict[str, Any]
@@ -32,6 +32,23 @@ ReportingCapabilities = dict[str, Any]
 # CORE DOMAIN TYPES
 # ============================================================================
 
+class FormatId(BaseModel):
+    """Structured format identifier with agent URL and format name"""
+
+    agent_url: str = 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)")
+    id: str = Field(description="Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id_pattern(cls, v: str) -> str:
+        """Validate format ID contains only alphanumeric characters, hyphens, and underscores."""
+        if not re.match(r"^[a-zA-Z0-9_-]+$", v):
+            raise ValueError(
+                f"Invalid format ID: {v!r}. Must contain only alphanumeric characters, hyphens, and underscores"
+            )
+        return v
+
+
 class Product(BaseModel):
     """Represents available advertising inventory"""