adcp 1.0.5__tar.gz → 1.2.0__tar.gz

{adcp-1.0.5/src/adcp.egg-info → adcp-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.0.5
+Version: 1.2.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.5 → adcp-1.2.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.5 → adcp-1.2.0}/pyproject.toml

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

{adcp-1.0.5 → adcp-1.2.0}/src/adcp/__init__.py

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

{adcp-1.0.5 → adcp-1.2.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.5 → adcp-1.2.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.5 → adcp-1.2.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]:
@@ -341,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()
@@ -348,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.5 → adcp-1.2.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,6 +125,8 @@ 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)
@@ -135,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."""