adcp 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

adcp/__init__.py

@@ -150,7 +150,7 @@ from adcp.types.generated import (
     TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.3.1"
+__version__ = "1.4.1"
 
 __all__ = [
     # Client classes

adcp/client.py

@@ -86,6 +86,11 @@ class ADCPClient:
         else:
             raise ValueError(f"Unsupported protocol: {agent_config.protocol}")
 
+        # Initialize simple API accessor (lazy import to avoid circular dependency)
+        from adcp.simple import SimpleAPI
+
+        self.simple = SimpleAPI(self)
+
     def get_webhook_url(self, task_type: str, operation_id: str) -> str:
         """Generate webhook URL for a task."""
         if not self.webhook_url_template:

adcp/exceptions.py

@@ -119,3 +119,37 @@ class ADCPWebhookSignatureError(ADCPWebhookError):
             "     Webhook signatures use HMAC-SHA256 for security."
         )
         super().__init__(message, agent_id, None, suggestion)
+
+
+class ADCPSimpleAPIError(ADCPError):
+    """Error from simplified API (.simple accessor).
+
+    Raised when a simple API method fails. The underlying error details
+    are available in the message. For more control over error handling,
+    use the standard API (client.method()) instead of client.simple.method().
+    """
+
+    def __init__(
+        self,
+        operation: str,
+        error_message: str | None = None,
+        agent_id: str | None = None,
+    ):
+        """Initialize simple API error.
+
+        Args:
+            operation: The operation that failed (e.g., "get_products")
+            error_message: The underlying error message from TaskResult
+            agent_id: Optional agent ID for context
+        """
+        message = f"{operation} failed"
+        if error_message:
+            message = f"{message}: {error_message}"
+
+        suggestion = (
+            f"For more control over error handling, use the standard API:\n"
+            f"     result = await client.{operation}(request)\n"
+            f"     if not result.success:\n"
+            f"         # Handle error with full TaskResult context"
+        )
+        super().__init__(message, agent_id, None, suggestion)

adcp/protocols/mcp.py

@@ -245,24 +245,12 @@ class MCPAdapter(ProtocolAdapter):
             # Call the tool using MCP client session
             result = await session.call_tool(tool_name, params)
 
-            # This SDK requires MCP tools to return structuredContent
-            # The content field may contain human-readable messages but the actual
-            # response data must be in structuredContent
-            if not hasattr(result, "structuredContent") or result.structuredContent is None:
-                raise ValueError(
-                    f"MCP tool {tool_name} did not return structuredContent. "
-                    f"This SDK requires MCP tools to provide structured responses. "
-                    f"Got content: {result.content if hasattr(result, 'content') else 'none'}"
-                )
+            # Check if this is an error response
+            is_error = hasattr(result, "isError") and result.isError
 
-            # Extract the structured data (required)
-            data_to_return = result.structuredContent
-
-            # Extract human-readable message from content (optional)
-            # This is typically a status message like "Found 42 creative formats"
+            # Extract human-readable message from content
             message_text = None
             if hasattr(result, "content") and result.content:
-                # Serialize content using the same method used for backward compatibility
                 serialized_content = self._serialize_mcp_content(result.content)
                 if isinstance(serialized_content, list):
                     for item in serialized_content:
@@ -271,6 +259,40 @@ class MCPAdapter(ProtocolAdapter):
                             message_text = item["text"]
                             break
 
+            # Handle error responses
+            if is_error:
+                # For error responses, structuredContent is optional
+                # Use the error message from content as the error
+                error_message = message_text or "Tool execution failed"
+                if self.agent_config.debug and start_time:
+                    duration_ms = (time.time() - start_time) * 1000
+                    debug_info = DebugInfo(
+                        request=debug_request,
+                        response={
+                            "error": error_message,
+                            "is_error": True,
+                        },
+                        duration_ms=duration_ms,
+                    )
+                return TaskResult[Any](
+                    status=TaskStatus.FAILED,
+                    error=error_message,
+                    success=False,
+                    debug_info=debug_info,
+                )
+
+            # For successful responses, structuredContent is required
+            if not hasattr(result, "structuredContent") or result.structuredContent is None:
+                raise ValueError(
+                    f"MCP tool {tool_name} did not return structuredContent. "
+                    f"This SDK requires MCP tools to provide structured responses "
+                    f"for successful calls. "
+                    f"Got content: {result.content if hasattr(result, 'content') else 'none'}"
+                )
+
+            # Extract the structured data (required for success)
+            data_to_return = result.structuredContent
+
             if self.agent_config.debug and start_time:
                 duration_ms = (time.time() - start_time) * 1000
                 debug_info = DebugInfo(
@@ -278,7 +300,7 @@ class MCPAdapter(ProtocolAdapter):
                     response={
                         "data": data_to_return,
                         "message": message_text,
-                        "is_error": result.isError if hasattr(result, "isError") else False,
+                        "is_error": False,
                     },
                     duration_ms=duration_ms,
                 )

adcp/simple.py

@@ -0,0 +1,347 @@
+"""Simplified API accessor for ADCPClient.
+
+Provides an ergonomic API with:
+- Kwargs instead of request objects
+- Direct return values (no TaskResult unwrapping)
+- Raises exceptions on errors
+
+Usage:
+    client = ADCPClient(config)
+
+    # Standard API: full control
+    result = await client.get_products(GetProductsRequest(brief="Coffee"))
+    if result.success:
+        print(result.data.products)
+
+    # Simple API: ergonomic
+    products = await client.simple.get_products(brief="Coffee")
+    print(products.products)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from adcp.exceptions import ADCPSimpleAPIError
+from adcp.types.generated import (
+    ActivateSignalRequest,
+    ActivateSignalResponse,
+    GetMediaBuyDeliveryRequest,
+    GetMediaBuyDeliveryResponse,
+    GetProductsRequest,
+    GetProductsResponse,
+    GetSignalsRequest,
+    GetSignalsResponse,
+    ListAuthorizedPropertiesRequest,
+    ListAuthorizedPropertiesResponse,
+    ListCreativeFormatsRequest,
+    ListCreativeFormatsResponse,
+    ListCreativesRequest,
+    ListCreativesResponse,
+    PreviewCreativeRequest,
+    PreviewCreativeResponse,
+    ProvidePerformanceFeedbackRequest,
+    ProvidePerformanceFeedbackResponse,
+    SyncCreativesRequest,
+    SyncCreativesResponse,
+)
+
+if TYPE_CHECKING:
+    from adcp.client import ADCPClient
+
+
+class SimpleAPI:
+    """Simplified API accessor for ergonomic usage.
+
+    Provides kwargs-based methods that return unwrapped response data
+    and raise exceptions on errors.
+
+    This is intended for:
+    - Quick prototyping and testing
+    - Documentation and examples
+    - Simple scripts and notebooks
+
+    For production code with complex error handling, use the standard
+    client API which returns TaskResult wrappers.
+    """
+
+    def __init__(self, client: ADCPClient):
+        """Initialize simple API accessor.
+
+        Args:
+            client: The ADCPClient instance to wrap
+        """
+        self._client = client
+
+    async def get_products(
+        self,
+        **kwargs: Any,
+    ) -> GetProductsResponse:
+        """Get advertising products (simplified).
+
+        This is a convenience wrapper around client.get_products() that:
+        - Accepts kwargs instead of GetProductsRequest
+        - Returns unwrapped GetProductsResponse
+        - Raises ADCPSimpleAPIError on failures
+
+        For full control over error handling, use client.get_products() instead.
+
+        Args:
+            **kwargs: Arguments for GetProductsRequest (brief, brand_manifest, etc.)
+
+        Returns:
+            GetProductsResponse directly (no TaskResult wrapper)
+
+        Raises:
+            ADCPSimpleAPIError: If request fails. Use standard API for detailed error handling.
+
+        Example:
+            products = await client.simple.get_products(
+                brief='Coffee subscription service'
+            )
+            print(f"Found {len(products.products)} products")
+        """
+        request = GetProductsRequest(**kwargs)
+        result = await self._client.get_products(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="get_products",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def list_creative_formats(
+        self,
+        **kwargs: Any,
+    ) -> ListCreativeFormatsResponse:
+        """List supported creative formats.
+
+        Args:
+            **kwargs: Arguments passed to ListCreativeFormatsRequest
+
+        Returns:
+            ListCreativeFormatsResponse with formats list
+
+        Raises:
+            Exception: If the request fails
+
+        Example:
+            formats = await client.simple.list_creative_formats()
+            print(f"Found {len(formats.formats)} formats")
+        """
+        request = ListCreativeFormatsRequest(**kwargs)
+        result = await self._client.list_creative_formats(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="list_creative_formats",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def preview_creative(
+        self,
+        **kwargs: Any,
+    ) -> PreviewCreativeResponse:
+        """Preview creative manifest.
+
+        Args:
+            **kwargs: Arguments passed to PreviewCreativeRequest
+
+        Returns:
+            PreviewCreativeResponse with preview data
+
+        Raises:
+            Exception: If the request fails
+
+        Example:
+            preview = await client.simple.preview_creative(
+                manifest={'format_id': 'banner_300x250', 'assets': {...}}
+            )
+            print(f"Preview: {preview.previews[0]}")
+        """
+        request = PreviewCreativeRequest(**kwargs)
+        result = await self._client.preview_creative(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="preview_creative",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def sync_creatives(
+        self,
+        **kwargs: Any,
+    ) -> SyncCreativesResponse:
+        """Sync creatives.
+
+        Args:
+            **kwargs: Arguments passed to SyncCreativesRequest
+
+        Returns:
+            SyncCreativesResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = SyncCreativesRequest(**kwargs)
+        result = await self._client.sync_creatives(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="sync_creatives",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def list_creatives(
+        self,
+        **kwargs: Any,
+    ) -> ListCreativesResponse:
+        """List creatives.
+
+        Args:
+            **kwargs: Arguments passed to ListCreativesRequest
+
+        Returns:
+            ListCreativesResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = ListCreativesRequest(**kwargs)
+        result = await self._client.list_creatives(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="list_creatives",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def get_media_buy_delivery(
+        self,
+        **kwargs: Any,
+    ) -> GetMediaBuyDeliveryResponse:
+        """Get media buy delivery.
+
+        Args:
+            **kwargs: Arguments passed to GetMediaBuyDeliveryRequest
+
+        Returns:
+            GetMediaBuyDeliveryResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = GetMediaBuyDeliveryRequest(**kwargs)
+        result = await self._client.get_media_buy_delivery(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="get_media_buy_delivery",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def list_authorized_properties(
+        self,
+        **kwargs: Any,
+    ) -> ListAuthorizedPropertiesResponse:
+        """List authorized properties.
+
+        Args:
+            **kwargs: Arguments passed to ListAuthorizedPropertiesRequest
+
+        Returns:
+            ListAuthorizedPropertiesResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = ListAuthorizedPropertiesRequest(**kwargs)
+        result = await self._client.list_authorized_properties(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="list_authorized_properties",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def get_signals(
+        self,
+        **kwargs: Any,
+    ) -> GetSignalsResponse:
+        """Get signals.
+
+        Args:
+            **kwargs: Arguments passed to GetSignalsRequest
+
+        Returns:
+            GetSignalsResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = GetSignalsRequest(**kwargs)
+        result = await self._client.get_signals(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="get_signals",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def activate_signal(
+        self,
+        **kwargs: Any,
+    ) -> ActivateSignalResponse:
+        """Activate signal.
+
+        Args:
+            **kwargs: Arguments passed to ActivateSignalRequest
+
+        Returns:
+            ActivateSignalResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = ActivateSignalRequest(**kwargs)
+        result = await self._client.activate_signal(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="activate_signal",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data
+
+    async def provide_performance_feedback(
+        self,
+        **kwargs: Any,
+    ) -> ProvidePerformanceFeedbackResponse:
+        """Provide performance feedback.
+
+        Args:
+            **kwargs: Arguments passed to ProvidePerformanceFeedbackRequest
+
+        Returns:
+            ProvidePerformanceFeedbackResponse
+
+        Raises:
+            Exception: If the request fails
+        """
+        request = ProvidePerformanceFeedbackRequest(**kwargs)
+        result = await self._client.provide_performance_feedback(request)
+        if not result.success or not result.data:
+            raise ADCPSimpleAPIError(
+                operation="provide_performance_feedback",
+                error_message=result.error,
+                agent_id=self._client.agent_config.id,
+            )
+        return result.data

adcp/testing/__init__.py

@@ -1,6 +1,21 @@
 """Test helpers for AdCP client library.
 
 Provides pre-configured test agents for examples and quick testing.
+
+All test agents include a `.simple` accessor for ergonomic usage:
+
+- **Standard API** (client methods): Full TaskResult with error handling
+- **Simple API** (client.simple methods): Direct returns, raises on error
+
+Example:
+    # Standard API - explicit control
+    result = await test_agent.get_products(GetProductsRequest(brief='Coffee'))
+    if result.success:
+        print(result.data.products)
+
+    # Simple API - ergonomic
+    products = await test_agent.simple.get_products(brief='Coffee')
+    print(products.products)
 """
 
 from __future__ import annotations

{adcp-1.3.1.dist-info → adcp-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.3.1
+Version: 1.4.1
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -63,36 +63,64 @@ pip install adcp
 
 ## Quick Start: Test Helpers
 
-The fastest way to get started is using the pre-configured test agents:
+The fastest way to get started is using pre-configured test agents with the **`.simple` API**:
 
 ```python
 from adcp.testing import test_agent
-from adcp.types.generated import GetProductsRequest
 
-# Zero configuration - just import and use!
-result = await test_agent.get_products(
-    GetProductsRequest(
-        brief="Coffee subscription service",
-        promoted_offering="Premium coffee deliveries"
-    )
+# Zero configuration - just import and call with kwargs!
+products = await test_agent.simple.get_products(
+    brief='Coffee subscription service for busy professionals'
 )
 
-if result.success:
-    print(f"Found {len(result.data.products)} products")
+print(f"Found {len(products.products)} products")
+```
+
+### Simple vs. Standard API
+
+**Every ADCPClient** includes both API styles via the `.simple` accessor:
+
+**Simple API** (`client.simple.*`) - Recommended for examples/prototyping:
+```python
+from adcp.testing import test_agent
+
+# Kwargs and direct return - raises on error
+products = await test_agent.simple.get_products(brief='Coffee brands')
+print(products.products[0].name)
+```
+
+**Standard API** (`client.*`) - Recommended for production:
+```python
+from adcp.testing import test_agent
+from adcp.types.generated import GetProductsRequest
+
+# Explicit request objects and TaskResult wrapper
+request = GetProductsRequest(brief='Coffee brands')
+result = await test_agent.get_products(request)
+
+if result.success and result.data:
+    print(result.data.products[0].name)
+else:
+    print(f"Error: {result.error}")
 ```
 
-Test helpers include:
-- **`test_agent`**: Pre-configured MCP test agent with authentication
-- **`test_agent_a2a`**: Pre-configured A2A test agent with authentication
-- **`test_agent_no_auth`**: Pre-configured MCP test agent WITHOUT authentication
-- **`test_agent_a2a_no_auth`**: Pre-configured A2A test agent WITHOUT authentication
+**When to use which:**
+- **Simple API** (`.simple`): Quick testing, documentation, examples, notebooks
+- **Standard API**: Production code, complex error handling, webhook workflows
+
+### Available Test Helpers
+
+Pre-configured agents (all include `.simple` accessor):
+- **`test_agent`**: MCP test agent with authentication
+- **`test_agent_a2a`**: A2A test agent with authentication
+- **`test_agent_no_auth`**: MCP test agent without authentication
+- **`test_agent_a2a_no_auth`**: A2A test agent without authentication
 - **`creative_agent`**: Reference creative agent for preview functionality
 - **`test_agent_client`**: Multi-agent client with both protocols
-- **`create_test_agent()`**: Factory for custom test configurations
 
 > **Note**: Test agents are rate-limited and for testing/examples only. DO NOT use in production.
 
-See [examples/test_helpers_demo.py](examples/test_helpers_demo.py) for more examples.
+See [examples/simple_api_demo.py](examples/simple_api_demo.py) for a complete comparison.
 
 ## Quick Start: Distributed Operations
 

{adcp-1.3.1.dist-info → adcp-1.4.1.dist-info}/RECORD

@@ -1,13 +1,14 @@
-adcp/__init__.py,sha256=MCmxv3akU0gGpUZhkHnieWiBHJkmwbMz67XqNWDE8fY,6976
+adcp/__init__.py,sha256=zV1J1z4uR1C7rGIccifeDGjN8pnZI1o280FioRvwRLM,6976
 adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
-adcp/client.py,sha256=co4tKdkjDrqZltCUPcYwVRr8LQfbBbG-DLjapLjcVuo,28246
+adcp/client.py,sha256=4qoFNDT5swzi4w5bnWJ5nVTG5JIL0xnLJOJMGeMyci4,28412
 adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
-adcp/exceptions.py,sha256=dNRMKV23DlkGKyB9Xmt6MtlhvDu1crjzD_en4nAEwDY,4399
+adcp/exceptions.py,sha256=9L7a3TKrMhmbEqDM0Qjdu3dQAFeKCSW4nc1IcLGSj4Y,5597
+adcp/simple.py,sha256=FgPYWT32BNXkQz07r2x2gXgOmOikWLi88SzN5UIVSiU,10440
 adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,262
 adcp/protocols/a2a.py,sha256=FHgc6G_eU2qD0vH7_RyS1eZvUFSb2j3-EsceoHPi384,12467
 adcp/protocols/base.py,sha256=vBHD23Fzl_CCk_Gy9nvSbBYopcJlYkYyzoz-rhI8wHg,5214
-adcp/protocols/mcp.py,sha256=eIk8snCinZm-ZjdarGVMt5nEYJ4_8POM9Fa5Mkw7xxU,15902
-adcp/testing/__init__.py,sha256=kPsRncZ42g4HpOljVwLrFXm2O28K5NKcPUtvykfYY6M,888
+adcp/protocols/mcp.py,sha256=d9uSpGd0BKvQ0JxztkfDvHwoDrDYhuiw5oivpYOAbmM,16647
+adcp/testing/__init__.py,sha256=ZWp_floWjVZfy8RBG5v_FUXQ8YbN7xjXvVcX-_zl_HU,1416
 adcp/testing/test_helpers.py,sha256=4n8fZYy1cVpjZpFW2SxBzpC8fmY-MBFrzY4tIPqe4rQ,10028
 adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
 adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
@@ -17,9 +18,9 @@ adcp/utils/__init__.py,sha256=uetvSJB19CjQbtwEYZiTnumJG11GsafQmXm5eR3hL7E,153
 adcp/utils/operation_id.py,sha256=wQX9Bb5epXzRq23xoeYPTqzu5yLuhshg7lKJZihcM2k,294
 adcp/utils/preview_cache.py,sha256=8_2qs5CgrHv1_WOnD4bs43VWueu-rcZRu5PZMQ_lyuE,17573
 adcp/utils/response_parser.py,sha256=uPk2vIH-RYZmq7y3i8lC4HTMQ3FfKdlgXKTjgJ1955M,6253
-adcp-1.3.1.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.3.1.dist-info/METADATA,sha256=A-iffDZHPdrerWn_-vqFTnIHhhoARKGcsTTiw-X2WQk,19097
-adcp-1.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.3.1.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.3.1.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.3.1.dist-info/RECORD,,
+adcp-1.4.1.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.4.1.dist-info/METADATA,sha256=Y2iI6jHEWqkxqXSHHv5m2NX2OHet5KyEIPktdlNfOJo,19931
+adcp-1.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.4.1.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.4.1.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.4.1.dist-info/RECORD,,