adcp 1.3.1__tar.gz → 1.4.1__tar.gz

{adcp-1.3.1/src/adcp.egg-info → adcp-1.4.1}/PKG-INFO

@@ -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 → adcp-1.4.1}/README.md

@@ -26,36 +26,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 → adcp-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "1.3.1"
+version = "1.4.1"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}

{adcp-1.3.1 → adcp-1.4.1}/src/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-1.3.1 → adcp-1.4.1}/src/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-1.3.1 → adcp-1.4.1}/src/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-1.3.1 → adcp-1.4.1}/src/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-1.4.1/src/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-1.3.1 → adcp-1.4.1}/src/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 → adcp-1.4.1/src/adcp.egg-info}/PKG-INFO

@@ -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 → adcp-1.4.1}/src/adcp.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/adcp/__main__.py
 src/adcp/client.py
 src/adcp/config.py
 src/adcp/exceptions.py
+src/adcp/simple.py
 src/adcp.egg-info/PKG-INFO
 src/adcp.egg-info/SOURCES.txt
 src/adcp.egg-info/dependency_links.txt
@@ -34,4 +35,5 @@ tests/test_format_id_validation.py
 tests/test_helpers.py
 tests/test_preview_html.py
 tests/test_protocols.py
-tests/test_response_parser.py
+tests/test_response_parser.py
+tests/test_simple_api.py

{adcp-1.3.1 → adcp-1.4.1}/tests/test_protocols.py

@@ -164,6 +164,7 @@ class TestMCPAdapter:
         # Mock MCP result with structuredContent (required for AdCP)
         mock_result.content = [{"type": "text", "text": "Success"}]
         mock_result.structuredContent = {"products": [{"id": "prod1"}]}
+        mock_result.isError = False
         mock_session.call_tool.return_value = mock_result
 
         with patch.object(adapter, "_get_session", return_value=mock_session):
@@ -193,6 +194,7 @@ class TestMCPAdapter:
         # Mock MCP result with structuredContent (preferred over content)
         mock_result.content = [{"type": "text", "text": "Found 42 creative formats"}]
         mock_result.structuredContent = {"formats": [{"id": "format1"}, {"id": "format2"}]}
+        mock_result.isError = False
         mock_session.call_tool.return_value = mock_result
 
         with patch.object(adapter, "_get_session", return_value=mock_session):
@@ -207,24 +209,46 @@ class TestMCPAdapter:
 
     @pytest.mark.asyncio
     async def test_call_tool_missing_structured_content(self, mcp_config):
-        """Test tool call fails when structuredContent is missing."""
+        """Test tool call fails when structuredContent is missing on successful response."""
         adapter = MCPAdapter(mcp_config)
 
         mock_session = AsyncMock()
         mock_result = MagicMock()
-        # Mock MCP result WITHOUT structuredContent (invalid for AdCP)
+        # Mock MCP result WITHOUT structuredContent and isError=False (invalid)
         mock_result.content = [{"type": "text", "text": "Success"}]
         mock_result.structuredContent = None
+        mock_result.isError = False
         mock_session.call_tool.return_value = mock_result
 
         with patch.object(adapter, "_get_session", return_value=mock_session):
             result = await adapter._call_mcp_tool("get_products", {"brief": "test"})
 
-            # Verify error handling for missing structuredContent
+            # Verify error handling for missing structuredContent on success
             assert result.success is False
             assert result.status == TaskStatus.FAILED
             assert "did not return structuredContent" in result.error
 
+    @pytest.mark.asyncio
+    async def test_call_tool_error_without_structured_content(self, mcp_config):
+        """Test tool call handles error responses without structuredContent gracefully."""
+        adapter = MCPAdapter(mcp_config)
+
+        mock_session = AsyncMock()
+        mock_result = MagicMock()
+        # Mock MCP error response WITHOUT structuredContent (valid for errors)
+        mock_result.content = [{"type": "text", "text": "brand_manifest must provide brand information"}]
+        mock_result.structuredContent = None
+        mock_result.isError = True
+        mock_session.call_tool.return_value = mock_result
+
+        with patch.object(adapter, "_get_session", return_value=mock_session):
+            result = await adapter._call_mcp_tool("get_products", {"brief": "test"})
+
+            # Verify error is handled gracefully
+            assert result.success is False
+            assert result.status == TaskStatus.FAILED
+            assert result.error == "brand_manifest must provide brand information"
+
     @pytest.mark.asyncio
     async def test_call_tool_error(self, mcp_config):
         """Test tool call error via MCP."""

adcp-1.4.1/tests/test_simple_api.py

@@ -0,0 +1,183 @@
+"""Tests for the simplified API accessor."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from adcp.testing import test_agent
+from adcp.types.core import TaskResult, TaskStatus
+from adcp.types.generated import (
+    GetProductsResponse,
+    ListCreativeFormatsResponse,
+    PreviewCreativeResponse,
+    Product,
+)
+
+
+@pytest.mark.asyncio
+async def test_get_products_simple_api():
+    """Test client.simple.get_products with kwargs."""
+    # Create mock response (using model_construct to bypass validation for test data)
+    mock_product = Product.model_construct(
+        product_id="prod_1",
+        name="Test Product",
+        description="A test product",
+    )
+    mock_response = GetProductsResponse.model_construct(products=[mock_product])
+    mock_result = TaskResult[GetProductsResponse](
+        status=TaskStatus.COMPLETED, data=mock_response, success=True
+    )
+
+    # Mock the client's get_products method
+    with patch.object(test_agent, "get_products", new=AsyncMock(return_value=mock_result)):
+        # Call simplified API with kwargs
+        result = await test_agent.simple.get_products(brief="Coffee subscription service")
+
+        # Verify it returns unwrapped data
+        assert isinstance(result, GetProductsResponse)
+        assert len(result.products) == 1
+        assert result.products[0].product_id == "prod_1"
+
+        # Verify the underlying call was made correctly
+        test_agent.get_products.assert_called_once()
+        call_args = test_agent.get_products.call_args[0][0]
+        assert call_args.brief == "Coffee subscription service"
+
+
+@pytest.mark.asyncio
+async def test_get_products_simple_api_failure():
+    """Test client.simple.get_products raises exception on failure."""
+    from adcp.exceptions import ADCPSimpleAPIError
+
+    # Create mock failure response
+    mock_result = TaskResult[GetProductsResponse](
+        status=TaskStatus.FAILED, data=None, success=False, error="Test error"
+    )
+
+    with patch.object(test_agent, "get_products", new=AsyncMock(return_value=mock_result)):
+        # Should raise ADCPSimpleAPIError on failure
+        with pytest.raises(ADCPSimpleAPIError, match="get_products failed"):
+            await test_agent.simple.get_products(brief="Test")
+
+
+def test_simple_api_has_no_sync_methods():
+    """Test that simple API only provides async methods.
+
+    Users can wrap with asyncio.run() if they need sync behavior.
+    """
+    # Verify simple API doesn't have sync methods
+    assert not hasattr(test_agent.simple, "get_products_sync")
+    assert hasattr(test_agent.simple, "get_products")
+
+
+@pytest.mark.asyncio
+async def test_list_creative_formats_simple_api():
+    """Test client.simple.list_creative_formats with kwargs."""
+    from adcp.types.generated import Format
+
+    # Create mock response (using model_construct to bypass validation for test data)
+    mock_format = Format.model_construct(
+        format_id={"id": "banner_300x250"},
+        name="Banner 300x250",
+        description="Standard banner",
+    )
+    mock_response = ListCreativeFormatsResponse.model_construct(formats=[mock_format])
+    mock_result = TaskResult[ListCreativeFormatsResponse](
+        status=TaskStatus.COMPLETED, data=mock_response, success=True
+    )
+
+    with patch.object(test_agent, "list_creative_formats", new=AsyncMock(return_value=mock_result)):
+        # Call simplified API
+        result = await test_agent.simple.list_creative_formats()
+
+        # Verify it returns unwrapped data
+        assert isinstance(result, ListCreativeFormatsResponse)
+        assert len(result.formats) == 1
+        assert result.formats[0].format_id["id"] == "banner_300x250"
+
+
+def test_simple_api_exists_on_client():
+    """Test that all clients have a .simple accessor."""
+    from adcp.testing import creative_agent, test_agent_a2a
+
+    # All clients should have .simple
+    assert hasattr(test_agent, "simple")
+    assert hasattr(test_agent_a2a, "simple")
+    assert hasattr(creative_agent, "simple")
+
+    # Should be SimpleAPI instance
+    from adcp.simple import SimpleAPI
+
+    assert isinstance(test_agent.simple, SimpleAPI)
+    assert isinstance(test_agent_a2a.simple, SimpleAPI)
+    assert isinstance(creative_agent.simple, SimpleAPI)
+
+
+def test_simple_api_on_freshly_constructed_client():
+    """Test that .simple accessor works on freshly constructed ADCPClient."""
+    from adcp import ADCPClient, AgentConfig, Protocol
+    from adcp.simple import SimpleAPI
+
+    # Create a new client from scratch
+    client = ADCPClient(
+        AgentConfig(
+            id="test-agent",
+            agent_uri="https://test.example.com/mcp/",
+            protocol=Protocol.MCP,
+            auth_token="test-token",
+        )
+    )
+
+    # Should have .simple accessor
+    assert hasattr(client, "simple")
+    assert isinstance(client.simple, SimpleAPI)
+
+    # Should reference the same client
+    assert client.simple._client is client
+
+
+@pytest.mark.asyncio
+async def test_preview_creative_simple_api():
+    """Test client.simple.preview_creative."""
+    from adcp.testing import creative_agent
+
+    mock_response = PreviewCreativeResponse(
+        previews=[{"url": "https://preview.example.com/123", "html": "<html>...</html>"}]
+    )
+    mock_result = TaskResult[PreviewCreativeResponse](
+        status=TaskStatus.COMPLETED, data=mock_response, success=True
+    )
+
+    with patch.object(creative_agent, "preview_creative", new=AsyncMock(return_value=mock_result)):
+        # Call simplified API
+        result = await creative_agent.simple.preview_creative(
+            manifest={"format_id": "banner_300x250", "assets": {}}
+        )
+
+        # Verify it returns unwrapped data
+        assert isinstance(result, PreviewCreativeResponse)
+        assert result.previews is not None
+        assert len(result.previews) == 1
+
+
+def test_simple_api_methods():
+    """Test that SimpleAPI has all expected methods."""
+    # Check all methods exist
+    assert hasattr(test_agent.simple, "get_products")
+    assert hasattr(test_agent.simple, "list_creative_formats")
+    assert hasattr(test_agent.simple, "preview_creative")
+    assert hasattr(test_agent.simple, "sync_creatives")
+    assert hasattr(test_agent.simple, "list_creatives")
+    assert hasattr(test_agent.simple, "get_media_buy_delivery")
+    assert hasattr(test_agent.simple, "list_authorized_properties")
+    assert hasattr(test_agent.simple, "get_signals")
+    assert hasattr(test_agent.simple, "activate_signal")
+    assert hasattr(test_agent.simple, "provide_performance_feedback")
+
+    # Verify they're all async methods (not sync)
+    import inspect
+
+    assert inspect.iscoroutinefunction(test_agent.simple.get_products)
+    assert inspect.iscoroutinefunction(test_agent.simple.list_creative_formats)