adcp 1.0.4__tar.gz → 1.1.0__tar.gz

{adcp-1.0.4/src/adcp.egg-info → adcp-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.0.4
+Version: 1.1.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -64,8 +64,8 @@ pip install adcp
 ```python
 from adcp import ADCPMultiAgentClient, AgentConfig, GetProductsRequest
 
-# Configure agents and handlers
-client = ADCPMultiAgentClient(
+# Configure agents and handlers (context manager ensures proper cleanup)
+async with ADCPMultiAgentClient(
     agents=[
         AgentConfig(
             id="agent_x",
@@ -91,21 +91,21 @@ client = ADCPMultiAgentClient(
             if metadata.status == "completed" else None
         )
     }
-)
-
-# Execute operation - library handles operation IDs, webhook URLs, context management
-agent = client.agent("agent_x")
-request = GetProductsRequest(brief="Coffee brands")
-result = await agent.get_products(request)
+) as client:
+    # Execute operation - library handles operation IDs, webhook URLs, context management
+    agent = client.agent("agent_x")
+    request = GetProductsRequest(brief="Coffee brands")
+    result = await agent.get_products(request)
 
-# Check result
-if result.status == "completed":
-    # Agent completed synchronously!
-    print(f"✅ Sync completion: {len(result.data.products)} products")
+    # Check result
+    if result.status == "completed":
+        # Agent completed synchronously!
+        print(f"✅ Sync completion: {len(result.data.products)} products")
 
-if result.status == "submitted":
-    # Agent will send webhook when complete
-    print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+    if result.status == "submitted":
+        # Agent will send webhook when complete
+        print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+# Connections automatically cleaned up here
 ```
 
 ## Features
@@ -210,6 +210,51 @@ Or use the CLI:
 uvx adcp --debug myagent get_products '{"brief":"TV ads"}'
 ```
 
+### Resource Management
+
+**Why use async context managers?**
+- Ensures HTTP connections are properly closed, preventing resource leaks
+- Handles cleanup even when exceptions occur
+- Required for production applications with connection pooling
+- Prevents issues with async task group cleanup in MCP protocol
+
+The recommended pattern uses async context managers:
+
+```python
+from adcp import ADCPClient, AgentConfig, GetProductsRequest
+
+# Recommended: Automatic cleanup with context manager
+config = AgentConfig(id="agent_x", agent_uri="https://...", protocol="a2a")
+async with ADCPClient(config) as client:
+    request = GetProductsRequest(brief="Coffee brands")
+    result = await client.get_products(request)
+    # Connection automatically closed on exit
+
+# Multi-agent client also supports context managers
+async with ADCPMultiAgentClient(agents) as client:
+    # Execute across all agents in parallel
+    results = await client.get_products(request)
+    # All agent connections closed automatically (even if some failed)
+```
+
+Manual cleanup is available for special cases (e.g., managing client lifecycle manually):
+
+```python
+# Use manual cleanup when you need fine-grained control over lifecycle
+client = ADCPClient(config)
+try:
+    result = await client.get_products(request)
+finally:
+    await client.close()  # Explicit cleanup
+```
+
+**When to use manual cleanup:**
+- Managing client lifecycle across multiple functions
+- Testing scenarios requiring explicit control
+- Integration with frameworks that manage resources differently
+
+In most cases, prefer the context manager pattern.
+
 ### Error Handling
 
 The library provides a comprehensive exception hierarchy with helpful error messages:

{adcp-1.0.4 → adcp-1.1.0}/README.md

@@ -27,8 +27,8 @@ pip install adcp
 ```python
 from adcp import ADCPMultiAgentClient, AgentConfig, GetProductsRequest
 
-# Configure agents and handlers
-client = ADCPMultiAgentClient(
+# Configure agents and handlers (context manager ensures proper cleanup)
+async with ADCPMultiAgentClient(
     agents=[
         AgentConfig(
             id="agent_x",
@@ -54,21 +54,21 @@ client = ADCPMultiAgentClient(
             if metadata.status == "completed" else None
         )
     }
-)
-
-# Execute operation - library handles operation IDs, webhook URLs, context management
-agent = client.agent("agent_x")
-request = GetProductsRequest(brief="Coffee brands")
-result = await agent.get_products(request)
+) as client:
+    # Execute operation - library handles operation IDs, webhook URLs, context management
+    agent = client.agent("agent_x")
+    request = GetProductsRequest(brief="Coffee brands")
+    result = await agent.get_products(request)
 
-# Check result
-if result.status == "completed":
-    # Agent completed synchronously!
-    print(f"✅ Sync completion: {len(result.data.products)} products")
+    # Check result
+    if result.status == "completed":
+        # Agent completed synchronously!
+        print(f"✅ Sync completion: {len(result.data.products)} products")
 
-if result.status == "submitted":
-    # Agent will send webhook when complete
-    print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+    if result.status == "submitted":
+        # Agent will send webhook when complete
+        print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+# Connections automatically cleaned up here
 ```
 
 ## Features
@@ -173,6 +173,51 @@ Or use the CLI:
 uvx adcp --debug myagent get_products '{"brief":"TV ads"}'
 ```
 
+### Resource Management
+
+**Why use async context managers?**
+- Ensures HTTP connections are properly closed, preventing resource leaks
+- Handles cleanup even when exceptions occur
+- Required for production applications with connection pooling
+- Prevents issues with async task group cleanup in MCP protocol
+
+The recommended pattern uses async context managers:
+
+```python
+from adcp import ADCPClient, AgentConfig, GetProductsRequest
+
+# Recommended: Automatic cleanup with context manager
+config = AgentConfig(id="agent_x", agent_uri="https://...", protocol="a2a")
+async with ADCPClient(config) as client:
+    request = GetProductsRequest(brief="Coffee brands")
+    result = await client.get_products(request)
+    # Connection automatically closed on exit
+
+# Multi-agent client also supports context managers
+async with ADCPMultiAgentClient(agents) as client:
+    # Execute across all agents in parallel
+    results = await client.get_products(request)
+    # All agent connections closed automatically (even if some failed)
+```
+
+Manual cleanup is available for special cases (e.g., managing client lifecycle manually):
+
+```python
+# Use manual cleanup when you need fine-grained control over lifecycle
+client = ADCPClient(config)
+try:
+    result = await client.get_products(request)
+finally:
+    await client.close()  # Explicit cleanup
+```
+
+**When to use manual cleanup:**
+- Managing client lifecycle across multiple functions
+- Testing scenarios requiring explicit control
+- Integration with frameworks that manage resources differently
+
+In most cases, prefer the context manager pattern.
+
 ### Error Handling
 
 The library provides a comprehensive exception hierarchy with helpful error messages:

{adcp-1.0.4 → adcp-1.1.0}/pyproject.toml

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

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/__init__.py

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

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/__main__.py

@@ -23,37 +23,38 @@ from adcp.types.core import AgentConfig, Protocol
 
 def print_json(data: Any) -> None:
     """Print data as JSON."""
-    print(json.dumps(data, indent=2, default=str))
+    from pydantic import BaseModel
+
+    # Handle Pydantic models
+    if isinstance(data, BaseModel):
+        print(data.model_dump_json(indent=2, exclude_none=True))
+    else:
+        print(json.dumps(data, indent=2, default=str))
 
 
 def print_result(result: Any, json_output: bool = False) -> None:
     """Print result in formatted or JSON mode."""
     if json_output:
-        print_json(
-            {
-                "status": result.status.value,
-                "success": result.success,
-                "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
-                ),
-            }
-        )
+        # Match JavaScript client: output just the data for scripting
+        if result.success and result.data:
+            print_json(result.data)
+        else:
+            # On error, output error info
+            print_json({"error": result.error, "success": False})
     else:
-        print(f"\nStatus: {result.status.value}")
+        # Pretty output with message and data (like JavaScript client)
         if result.success:
+            print("\nSUCCESS\n")
+            # Show protocol message if available
+            if hasattr(result, "message") and result.message:
+                print("Protocol Message:")
+                print(result.message)
+                print()
             if result.data:
-                print("\nResult:")
+                print("Response:")
                 print_json(result.data)
         else:
+            print("\nFAILED\n")
             print(f"Error: {result.error}")
 
 

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/client.py

@@ -37,6 +37,8 @@ from adcp.types.generated import (
     ListCreativeFormatsResponse,
     ListCreativesRequest,
     ListCreativesResponse,
+    PreviewCreativeRequest,
+    PreviewCreativeResponse,
     ProvidePerformanceFeedbackRequest,
     ProvidePerformanceFeedbackResponse,
     SyncCreativesRequest,
@@ -101,16 +103,31 @@ class ADCPClient:
     async def get_products(
         self,
         request: GetProductsRequest,
+        fetch_previews: bool = False,
+        preview_output_format: str = "url",
+        creative_agent_client: ADCPClient | None = None,
     ) -> TaskResult[GetProductsResponse]:
         """
         Get advertising products.
 
         Args:
             request: Request parameters
+            fetch_previews: If True, generate preview URLs for each product's formats
+                (uses batch API for 5-10x performance improvement)
+            preview_output_format: "url" for iframe URLs (default), "html" for direct
+                embedding (2-3x faster, no iframe overhead)
+            creative_agent_client: Client for creative agent (required if
+                fetch_previews=True)
 
         Returns:
-            TaskResult containing GetProductsResponse
+            TaskResult containing GetProductsResponse with optional preview URLs in metadata
+
+        Raises:
+            ValueError: If fetch_previews=True but creative_agent_client is not provided
         """
+        if fetch_previews and not creative_agent_client:
+            raise ValueError("creative_agent_client is required when fetch_previews=True")
+
         operation_id = create_operation_id()
         params = request.model_dump(exclude_none=True)
 
@@ -137,20 +154,40 @@ class ADCPClient:
             )
         )
 
-        return self.adapter._parse_response(raw_result, GetProductsResponse)
+        result = self.adapter._parse_response(raw_result, GetProductsResponse)
+
+        if fetch_previews and result.success and result.data and creative_agent_client:
+            from adcp.utils.preview_cache import add_preview_urls_to_products
+
+            products_with_previews = await add_preview_urls_to_products(
+                result.data.products,
+                creative_agent_client,
+                use_batch=True,
+                output_format=preview_output_format,
+            )
+            result.metadata = result.metadata or {}
+            result.metadata["products_with_previews"] = products_with_previews
+
+        return result
 
     async def list_creative_formats(
         self,
         request: ListCreativeFormatsRequest,
+        fetch_previews: bool = False,
+        preview_output_format: str = "url",
     ) -> TaskResult[ListCreativeFormatsResponse]:
         """
         List supported creative formats.
 
         Args:
             request: Request parameters
+            fetch_previews: If True, generate preview URLs for each format using
+                sample manifests (uses batch API for 5-10x performance improvement)
+            preview_output_format: "url" for iframe URLs (default), "html" for direct
+                embedding (2-3x faster, no iframe overhead)
 
         Returns:
-            TaskResult containing ListCreativeFormatsResponse
+            TaskResult containing ListCreativeFormatsResponse with optional preview URLs in metadata
         """
         operation_id = create_operation_id()
         params = request.model_dump(exclude_none=True)
@@ -178,8 +215,62 @@ class ADCPClient:
             )
         )
 
-        # Parse response using adapter's helper
-        return self.adapter._parse_response(raw_result, ListCreativeFormatsResponse)
+        result = self.adapter._parse_response(raw_result, ListCreativeFormatsResponse)
+
+        if fetch_previews and result.success and result.data:
+            from adcp.utils.preview_cache import add_preview_urls_to_formats
+
+            formats_with_previews = await add_preview_urls_to_formats(
+                result.data.formats,
+                self,
+                use_batch=True,
+                output_format=preview_output_format,
+            )
+            result.metadata = result.metadata or {}
+            result.metadata["formats_with_previews"] = formats_with_previews
+
+        return result
+
+    async def preview_creative(
+        self,
+        request: PreviewCreativeRequest,
+    ) -> TaskResult[PreviewCreativeResponse]:
+        """
+        Generate preview of a creative manifest.
+
+        Args:
+            request: Request parameters
+
+        Returns:
+            TaskResult containing PreviewCreativeResponse with preview URLs
+        """
+        operation_id = create_operation_id()
+        params = request.model_dump(exclude_none=True)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="preview_creative",
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        raw_result = await self.adapter.preview_creative(params)  # type: ignore[attr-defined]
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="preview_creative",
+                status=raw_result.status,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+        return self.adapter._parse_response(raw_result, PreviewCreativeResponse)
 
     async def sync_creatives(
         self,

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/protocols/a2a.py

@@ -244,6 +244,10 @@ class A2AAdapter(ProtocolAdapter):
         """Provide performance feedback."""
         return await self._call_a2a_tool("provide_performance_feedback", params)
 
+    async def preview_creative(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Generate preview URLs for a creative manifest."""
+        return await self._call_a2a_tool("preview_creative", params)
+
     async def list_tools(self) -> list[str]:
         """
         List available tools from A2A agent.

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/protocols/base.py

@@ -49,6 +49,7 @@ class ProtocolAdapter(ABC):
             return TaskResult[T](
                 status=raw_result.status,
                 data=None,
+                message=raw_result.message,
                 success=False,
                 error=raw_result.error or "No data returned from adapter",
                 metadata=raw_result.metadata,
@@ -66,6 +67,7 @@ class ProtocolAdapter(ABC):
             return TaskResult[T](
                 status=raw_result.status,
                 data=parsed_data,
+                message=raw_result.message,  # Preserve human-readable message from protocol
                 success=raw_result.success,
                 error=raw_result.error,
                 metadata=raw_result.metadata,
@@ -76,6 +78,7 @@ class ProtocolAdapter(ABC):
             return TaskResult[T](
                 status=TaskStatus.FAILED,
                 error=f"Failed to parse response: {e}",
+                message=raw_result.message,
                 success=False,
                 debug_info=raw_result.debug_info,
             )

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/protocols/mcp.py

@@ -40,6 +40,39 @@ class MCPAdapter(ProtocolAdapter):
         self._session: Any = None
         self._exit_stack: Any = None
 
+    async def _cleanup_failed_connection(self, context: str) -> None:
+        """
+        Clean up resources after a failed connection attempt.
+
+        This method handles cleanup without raising exceptions to avoid
+        masking the original connection error.
+
+        Args:
+            context: Description of the context for logging (e.g., "during connection attempt")
+        """
+        if self._exit_stack is not None:
+            old_stack = self._exit_stack
+            self._exit_stack = None
+            self._session = None
+            try:
+                await old_stack.aclose()
+            except asyncio.CancelledError:
+                logger.debug(f"MCP session cleanup cancelled {context}")
+            except RuntimeError as cleanup_error:
+                # Known anyio task group cleanup issue
+                error_msg = str(cleanup_error).lower()
+                if "cancel scope" in error_msg or "async context" in error_msg:
+                    logger.debug(f"Ignoring anyio cleanup error {context}: {cleanup_error}")
+                else:
+                    logger.warning(
+                        f"Unexpected RuntimeError during cleanup {context}: {cleanup_error}"
+                    )
+            except Exception as cleanup_error:
+                # Log unexpected cleanup errors but don't raise to preserve original error
+                logger.warning(
+                    f"Unexpected error during cleanup {context}: {cleanup_error}", exc_info=True
+                )
+
     async def _get_session(self) -> ClientSession:
         """
         Get or create MCP client session with URL fallback handling.
@@ -115,35 +148,8 @@ class MCPAdapter(ProtocolAdapter):
                     return self._session  # type: ignore[no-any-return]
                 except Exception as e:
                     last_error = e
-                    # Clean up the exit stack on failure to avoid async scope issues
-                    if self._exit_stack is not None:
-                        old_stack = self._exit_stack
-                        self._exit_stack = None  # Clear immediately to prevent reuse
-                        self._session = None
-                        try:
-                            await old_stack.aclose()
-                        except asyncio.CancelledError:
-                            # Expected during shutdown
-                            pass
-                        except RuntimeError as cleanup_error:
-                            # Known MCP SDK async cleanup issue
-                            if (
-                                "async context" in str(cleanup_error).lower()
-                                or "cancel scope" in str(cleanup_error).lower()
-                            ):
-                                logger.debug(
-                                    "Ignoring MCP SDK async context error during cleanup: "
-                                    f"{cleanup_error}"
-                                )
-                            else:
-                                logger.warning(
-                                    f"Unexpected RuntimeError during cleanup: {cleanup_error}"
-                                )
-                        except Exception as cleanup_error:
-                            # Unexpected cleanup errors should be logged
-                            logger.warning(
-                                f"Unexpected error during cleanup: {cleanup_error}", exc_info=True
-                            )
+                    # Clean up the exit stack on failure to avoid resource leaks
+                    await self._cleanup_failed_connection("during connection attempt")
 
                     # If this isn't the last URL to try, create a new exit stack and continue
                     if url != urls_to_try[-1]:
@@ -239,25 +245,49 @@ 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)
+            # 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'}"
+                )
+
+            # 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"
+            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:
+                        is_text = isinstance(item, dict) and item.get("type") == "text"
+                        if is_text and item.get("text"):
+                            message_text = item["text"]
+                            break
 
             if self.agent_config.debug and start_time:
                 duration_ms = (time.time() - start_time) * 1000
                 debug_info = DebugInfo(
                     request=debug_request,
                     response={
-                        "content": serialized_content,
+                        "data": data_to_return,
+                        "message": message_text,
                         "is_error": result.isError if hasattr(result, "isError") else False,
                     },
                     duration_ms=duration_ms,
                 )
 
-            # MCP tool results contain a list of content items
-            # For AdCP, we expect the data in the content
+            # Return both the structured data and the human-readable message
             return TaskResult[Any](
                 status=TaskStatus.COMPLETED,
-                data=serialized_content,
+                data=data_to_return,
+                message=message_text,
                 success=True,
                 debug_info=debug_info,
             )
@@ -317,6 +347,10 @@ class MCPAdapter(ProtocolAdapter):
         """Provide performance feedback."""
         return await self._call_mcp_tool("provide_performance_feedback", params)
 
+    async def preview_creative(self, params: dict[str, Any]) -> TaskResult[Any]:
+        """Generate preview URLs for a creative manifest."""
+        return await self._call_mcp_tool("preview_creative", params)
+
     async def list_tools(self) -> list[str]:
         """List available tools from MCP agent."""
         session = await self._get_session()
@@ -324,15 +358,5 @@ class MCPAdapter(ProtocolAdapter):
         return [tool.name for tool in result.tools]
 
     async def close(self) -> None:
-        """Close the MCP session."""
-        if self._exit_stack is not None:
-            old_stack = self._exit_stack
-            self._exit_stack = None
-            self._session = None
-            try:
-                await old_stack.aclose()
-            except (asyncio.CancelledError, RuntimeError):
-                # Cleanup errors during shutdown are expected
-                pass
-            except Exception as e:
-                logger.debug(f"Error during MCP session cleanup: {e}")
+        """Close the MCP session and clean up resources."""
+        await self._cleanup_failed_connection("during close")

{adcp-1.0.4 → adcp-1.1.0}/src/adcp/types/core.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any, Generic, Literal, TypeVar
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class Protocol(str, Enum):
@@ -125,8 +125,11 @@ class DebugInfo(BaseModel):
 class TaskResult(BaseModel, Generic[T]):
     """Result from task execution."""
 
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     status: TaskStatus
     data: T | None = None
+    message: str | None = None  # Human-readable message from agent (e.g., MCP content text)
     submitted: SubmittedInfo | None = None
     needs_input: NeedsInputInfo | None = None
     error: str | None = None
@@ -134,9 +137,6 @@ class TaskResult(BaseModel, Generic[T]):
     metadata: dict[str, Any] | None = None
     debug_info: DebugInfo | None = None
 
-    class Config:
-        arbitrary_types_allowed = True
-
 
 class ActivityType(str, Enum):
     """Types of activity events."""