adcp 1.0.5__py3-none-any.whl → 1.1.0__py3-none-any.whl

adcp/__init__.py

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

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/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/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/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."""

adcp/types/generated.py

@@ -32,23 +32,6 @@ ReportingCapabilities = dict[str, Any]
 # CORE DOMAIN TYPES
 # ============================================================================
 
-class FormatId(BaseModel):
-    """Structured format identifier with agent URL and format name"""
-
-    agent_url: str = Field(description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)")
-    id: str = Field(description="Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')")
-
-    @field_validator("id")
-    @classmethod
-    def validate_id_pattern(cls, v: str) -> str:
-        """Validate format ID contains only alphanumeric characters, hyphens, and underscores."""
-        if not re.match(r"^[a-zA-Z0-9_-]+$", v):
-            raise ValueError(
-                f"Invalid format ID: {v!r}. Must contain only alphanumeric characters, hyphens, and underscores"
-            )
-        return v
-
-
 class Product(BaseModel):
     """Represents available advertising inventory"""
 
@@ -68,6 +51,8 @@ class Product(BaseModel):
     is_custom: bool | None = Field(None, description="Whether this is a custom product")
     brief_relevance: str | None = Field(None, description="Explanation of why this product matches the brief (only included when brief is provided)")
     expires_at: str | None = Field(None, description="Expiration timestamp for custom products")
+    product_card: dict[str, Any] | None = Field(None, description="Optional standard visual card (300x400px) for displaying this product in user interfaces. Can be rendered via preview_creative or pre-generated.")
+    product_card_detailed: dict[str, Any] | None = Field(None, description="Optional detailed card with carousel and full specifications. Provides rich product presentation similar to media kit pages.")
 
 
 class MediaBuy(BaseModel):
@@ -151,7 +136,7 @@ class Format(BaseModel):
     format_id: FormatId = Field(description="Structured format identifier with agent URL and format name")
     name: str = Field(description="Human-readable format name")
     description: str | None = Field(None, description="Plain text explanation of what this format does and what assets it requires")
-    preview_image: str | None = Field(None, description="Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers.")
+    preview_image: str | None = Field(None, description="DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach.")
     example_url: str | None = Field(None, description="Optional URL to showcase page with examples and interactive demos of this format")
     type: Literal["audio", "video", "display", "native", "dooh", "rich_media", "universal"] = Field(description="Media type of this format - determines rendering method and asset requirements")
     renders: list[dict[str, Any]] | None = Field(None, description="Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.")
@@ -159,6 +144,8 @@ class Format(BaseModel):
     delivery: dict[str, Any] | None = Field(None, description="Delivery method specifications (e.g., hosted, VAST, third-party tags)")
     supported_macros: list[str] | None = Field(None, description="List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling.")
     output_format_ids: list[FormatId] | None = Field(None, description="For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).")
+    format_card: dict[str, Any] | None = Field(None, description="Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.")
+    format_card_detailed: dict[str, Any] | None = Field(None, description="Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.")
 
 
 class Targeting(BaseModel):
@@ -469,15 +456,6 @@ class ListCreativesRequest(BaseModel):
     fields: list[Literal["creative_id", "name", "format", "status", "created_date", "updated_date", "tags", "assignments", "performance", "sub_assets"]] | None = Field(None, description="Specific fields to include in response (omit for all fields)")
 
 
-class PreviewCreativeRequest(BaseModel):
-    """Request to generate a preview of a creative manifest in a specific format. The creative_manifest should include all assets required by the format (e.g., promoted_offerings for generative formats)."""
-
-    format_id: FormatId = Field(description="Format identifier for rendering the preview")
-    creative_manifest: CreativeManifest = Field(description="Complete creative manifest with all required assets (including promoted_offerings if required by the format)")
-    inputs: list[dict[str, Any]] | None = Field(None, description="Array of input sets for generating multiple preview variants. Each input set defines macros and context values for one preview rendering. If not provided, creative agent will generate default previews.")
-    template_id: str | None = Field(None, description="Specific template ID for custom format rendering")
-
-
 class ProvidePerformanceFeedbackRequest(BaseModel):
     """Request payload for provide_performance_feedback task"""
 
@@ -599,14 +577,6 @@ class ListCreativesResponse(BaseModel):
     status_summary: dict[str, Any] | None = Field(None, description="Breakdown of creatives by status")
 
 
-class PreviewCreativeResponse(BaseModel):
-    """Response containing preview links for a creative. Each preview URL returns an HTML page that can be embedded in an iframe to display the rendered creative."""
-
-    previews: list[dict[str, Any]] = Field(description="Array of preview variants. Each preview corresponds to an input set from the request. If no inputs were provided, returns a single default preview.")
-    interactive_url: str | None = Field(None, description="Optional URL to an interactive testing page that shows all preview variants with controls to switch between them, modify macro values, and test different scenarios.")
-    expires_at: str = Field(description="ISO 8601 timestamp when preview links expire")
-
-
 class ProvidePerformanceFeedbackResponse(BaseModel):
     """Response payload for provide_performance_feedback task"""
 
@@ -630,3 +600,56 @@ class UpdateMediaBuyResponse(BaseModel):
     affected_packages: list[dict[str, Any]] | None = Field(None, description="Array of packages that were modified")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings (e.g., partial update failures)")
 
+
+
+# ============================================================================
+# CUSTOM IMPLEMENTATIONS (override type aliases from generator)
+# ============================================================================
+# The simple code generator produces type aliases (e.g., PreviewCreativeRequest = Any)
+# for complex schemas that use oneOf. We override them here with proper Pydantic classes
+# to maintain type safety and enable batch API support.
+
+
+class FormatId(BaseModel):
+    """Structured format identifier with agent URL and format name"""
+
+    agent_url: str = Field(description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)")
+    id: str = Field(description="Format identifier within the agent's namespace (e.g., 'display_300x250', 'video_standard_30s')")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id_pattern(cls, v: str) -> str:
+        """Validate format ID contains only alphanumeric characters, hyphens, and underscores."""
+        if not re.match(r"^[a-zA-Z0-9_-]+$", v):
+            raise ValueError(
+                f"Invalid format ID: {v!r}. Must contain only alphanumeric characters, hyphens, and underscores"
+            )
+        return v
+
+
+class PreviewCreativeRequest(BaseModel):
+    """Request to generate a preview of a creative manifest. Supports single or batch mode."""
+
+    # Single mode fields
+    format_id: FormatId | None = Field(default=None, description="Format identifier for rendering the preview (single mode)")
+    creative_manifest: CreativeManifest | None = Field(default=None, description="Complete creative manifest with all required assets (single mode)")
+    inputs: list[dict[str, Any]] | None = Field(default=None, description="Array of input sets for generating multiple preview variants")
+    template_id: str | None = Field(default=None, description="Specific template ID for custom format rendering")
+
+    # Batch mode field
+    requests: list[dict[str, Any]] | None = Field(default=None, description="Array of preview requests for batch processing (1-50 items)")
+
+    # Output format (applies to both modes)
+    output_format: Literal["url", "html"] | None = Field(default="url", description="Output format: 'url' for iframe URLs, 'html' for direct embedding")
+
+
+class PreviewCreativeResponse(BaseModel):
+    """Response containing preview links for one or more creatives. Format matches the request: single preview response for single requests, batch results for batch requests."""
+
+    # Single mode fields
+    previews: list[dict[str, Any]] | None = Field(default=None, description="Array of preview variants (single mode)")
+    interactive_url: str | None = Field(default=None, description="Optional URL to interactive testing page (single mode)")
+    expires_at: str | None = Field(default=None, description="ISO 8601 timestamp when preview links expire (single mode)")
+
+    # Batch mode field
+    results: list[dict[str, Any]] | None = Field(default=None, description="Array of preview results for batch processing")

adcp/utils/preview_cache.py

@@ -0,0 +1,461 @@
+"""Helper utilities for generating creative preview URLs for grid rendering."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from adcp.client import ADCPClient
+    from adcp.types.generated import CreativeManifest, Format, FormatId, Product
+
+logger = logging.getLogger(__name__)
+
+
+def _make_manifest_cache_key(format_id: FormatId | str, manifest_dict: dict[str, Any]) -> str:
+    """
+    Create a cache key for a format_id and manifest.
+
+    Args:
+        format_id: Format identifier (FormatId object or string)
+        manifest_dict: Creative manifest dict
+
+    Returns:
+        Cache key string
+    """
+    # Convert FormatId to string representation
+    if isinstance(format_id, str):
+        format_id_str = format_id
+    else:
+        # FormatId is a Pydantic model with agent_url and id
+        format_id_str = f"{format_id.agent_url}:{format_id.id}"
+
+    manifest_str = str(sorted(manifest_dict.items()))
+    combined = f"{format_id_str}:{manifest_str}"
+    return hashlib.sha256(combined.encode()).hexdigest()[:16]
+
+
+class PreviewURLGenerator:
+    """Helper class for generating preview URLs from creative agents."""
+
+    def __init__(self, creative_agent_client: ADCPClient):
+        """
+        Initialize preview URL generator.
+
+        Args:
+            creative_agent_client: ADCPClient configured to talk to a creative agent
+        """
+        self.creative_agent_client = creative_agent_client
+        self._preview_cache: dict[str, dict[str, Any]] = {}
+
+    async def get_preview_data_for_manifest(
+        self, format_id: FormatId, manifest: CreativeManifest
+    ) -> dict[str, Any] | None:
+        """
+        Generate preview data for a creative manifest.
+
+        Returns preview data with URLs suitable for embedding in
+        <rendered-creative> web components or iframes.
+
+        Args:
+            format_id: Format identifier
+            manifest: Creative manifest
+
+        Returns:
+            Preview data with preview_url and metadata, or None if generation fails
+        """
+        from adcp.types.generated import PreviewCreativeRequest
+
+        cache_key = _make_manifest_cache_key(format_id, manifest.model_dump(exclude_none=True))
+
+        if cache_key in self._preview_cache:
+            return self._preview_cache[cache_key]
+
+        try:
+            request = PreviewCreativeRequest(
+                format_id=format_id, creative_manifest=manifest, inputs=None, template_id=None
+            )
+            result = await self.creative_agent_client.preview_creative(request)
+
+            if result.success and result.data and result.data.previews:
+                preview = result.data.previews[0]
+                renders = preview.get("renders", [])
+                first_render = renders[0] if renders else {}
+
+                preview_data = {
+                    "preview_id": preview.get("preview_id"),
+                    "preview_url": first_render.get("preview_url"),
+                    "preview_html": first_render.get("preview_html"),
+                    "render_id": first_render.get("render_id"),
+                    "input": preview.get("input", {}),
+                    "expires_at": result.data.expires_at,
+                }
+
+                self._preview_cache[cache_key] = preview_data
+                return preview_data
+
+        except Exception as e:
+            logger.warning(f"Failed to generate preview for format {format_id}: {e}", exc_info=True)
+
+        return None
+
+    async def get_preview_data_batch(
+        self,
+        requests: list[tuple[FormatId, CreativeManifest]],
+        output_format: str = "url",
+    ) -> list[dict[str, Any] | None]:
+        """
+        Generate preview data for multiple manifests in one API call (batch mode).
+
+        This is 5-10x faster than individual requests for multiple previews.
+
+        Args:
+            requests: List of (format_id, manifest) tuples to preview
+            output_format: "url" for iframe URLs, "html" for direct embedding
+
+        Returns:
+            List of preview data dicts (or None for failures), in same order as requests
+        """
+        from adcp.types.generated import PreviewCreativeRequest
+
+        if not requests:
+            return []
+
+        # Check cache first
+        cache_keys = [
+            _make_manifest_cache_key(fid, manifest.model_dump(exclude_none=True))
+            for fid, manifest in requests
+        ]
+
+        # Separate cached vs uncached requests
+        uncached_indices: list[int] = []
+        uncached_requests: list[dict[str, Any]] = []
+        results: list[dict[str, Any] | None] = [None] * len(requests)
+
+        for idx, (cache_key, (format_id, manifest)) in enumerate(zip(cache_keys, requests)):
+            if cache_key in self._preview_cache:
+                results[idx] = self._preview_cache[cache_key]
+            else:
+                uncached_indices.append(idx)
+                fid_dict = (
+                    format_id.model_dump()
+                    if hasattr(format_id, "model_dump")
+                    else format_id
+                )
+                uncached_requests.append({
+                    "format_id": fid_dict,
+                    "creative_manifest": manifest.model_dump(exclude_none=True),
+                })
+
+        # If everything was cached, return early
+        if not uncached_requests:
+            return results
+
+        # Make batch API call for uncached items
+        try:
+            # Batch requests in chunks of 50 (API limit)
+            batch_size = 50
+            for chunk_start in range(0, len(uncached_requests), batch_size):
+                chunk_end = min(chunk_start + batch_size, len(uncached_requests))
+                chunk_requests = uncached_requests[chunk_start:chunk_end]
+                chunk_indices = uncached_indices[chunk_start:chunk_end]
+
+                batch_request = PreviewCreativeRequest(
+                    requests=chunk_requests,
+                    output_format=output_format,  # type: ignore[arg-type]
+                )
+                result = await self.creative_agent_client.preview_creative(batch_request)
+
+                if result.success and result.data and result.data.results:
+                    # Process batch results
+                    for result_idx, batch_result in enumerate(result.data.results):
+                        original_idx = chunk_indices[result_idx]
+                        cache_key = cache_keys[original_idx]
+
+                        if batch_result.get("success") and batch_result.get("response"):
+                            response = batch_result["response"]
+                            if response.get("previews"):
+                                preview = response["previews"][0]
+                                renders = preview.get("renders", [])
+                                first_render = renders[0] if renders else {}
+                                preview_data = {
+                                    "preview_id": preview.get("preview_id"),
+                                    "preview_url": first_render.get("preview_url"),
+                                    "preview_html": first_render.get("preview_html"),
+                                    "render_id": first_render.get("render_id"),
+                                    "input": preview.get("input", {}),
+                                    "expires_at": response.get("expires_at"),
+                                }
+                                # Cache and store
+                                self._preview_cache[cache_key] = preview_data
+                                results[original_idx] = preview_data
+                        else:
+                            # Request failed
+                            error = batch_result.get("error", {})
+                            logger.warning(
+                                f"Batch preview failed for request {original_idx}: "
+                                f"{error.get('message', 'Unknown error')}"
+                            )
+
+        except Exception as e:
+            logger.warning(f"Batch preview generation failed: {e}", exc_info=True)
+
+        return results
+
+
+async def add_preview_urls_to_formats(
+    formats: list[Format],
+    creative_agent_client: ADCPClient,
+    use_batch: bool = True,
+    output_format: str = "url",
+) -> list[dict[str, Any]]:
+    """
+    Add preview URLs to each format by generating sample manifests.
+
+    Uses batch API for 5-10x better performance when previewing multiple formats.
+
+    Args:
+        formats: List of Format objects
+        creative_agent_client: Client for the creative agent
+        use_batch: If True, use batch API (default). Set False to use individual requests.
+        output_format: "url" for iframe URLs, "html" for direct embedding
+
+    Returns:
+        List of format dicts with added preview_data fields
+    """
+    if not formats:
+        return []
+
+    generator = PreviewURLGenerator(creative_agent_client)
+
+    # Prepare all requests
+    format_requests = []
+    for fmt in formats:
+        sample_manifest = _create_sample_manifest_for_format(fmt)
+        if sample_manifest:
+            format_requests.append((fmt, sample_manifest))
+
+    if not format_requests:
+        return [fmt.model_dump(exclude_none=True) for fmt in formats]
+
+    # Use batch API if requested and we have multiple formats
+    if use_batch and len(format_requests) > 1:
+        # Batch mode - much faster!
+        batch_requests = [(fmt.format_id, manifest) for fmt, manifest in format_requests]
+        preview_data_list = await generator.get_preview_data_batch(
+            batch_requests, output_format=output_format
+        )
+
+        # Merge preview data back with formats
+        result = []
+        preview_idx = 0
+        for fmt in formats:
+            format_dict = fmt.model_dump(exclude_none=True)
+            # Check if this format had a manifest
+            if preview_idx < len(format_requests) and format_requests[preview_idx][0] == fmt:
+                preview_data = preview_data_list[preview_idx]
+                if preview_data:
+                    format_dict["preview_data"] = preview_data
+                preview_idx += 1
+            result.append(format_dict)
+        return result
+    else:
+        # Fallback to individual requests (for single format or when batch disabled)
+        import asyncio
+
+        async def process_format(fmt: Format) -> dict[str, Any]:
+            """Process a single format and add preview data."""
+            format_dict = fmt.model_dump(exclude_none=True)
+
+            try:
+                sample_manifest = _create_sample_manifest_for_format(fmt)
+                if sample_manifest:
+                    preview_data = await generator.get_preview_data_for_manifest(
+                        fmt.format_id, sample_manifest
+                    )
+                    if preview_data:
+                        format_dict["preview_data"] = preview_data
+            except Exception as e:
+                logger.warning(f"Failed to add preview data for format {fmt.format_id}: {e}")
+
+            return format_dict
+
+        return await asyncio.gather(*[process_format(fmt) for fmt in formats])
+
+
+async def add_preview_urls_to_products(
+    products: list[Product],
+    creative_agent_client: ADCPClient,
+    use_batch: bool = True,
+    output_format: str = "url",
+) -> list[dict[str, Any]]:
+    """
+    Add preview URLs to products for their supported formats.
+
+    Uses batch API for 5-10x better performance when previewing many product formats.
+
+    Args:
+        products: List of Product objects
+        creative_agent_client: Client for the creative agent
+        use_batch: If True, use batch API (default). Set False to use individual requests.
+        output_format: "url" for iframe URLs, "html" for direct embedding
+
+    Returns:
+        List of product dicts with added format_previews field
+    """
+    if not products:
+        return []
+
+    generator = PreviewURLGenerator(creative_agent_client)
+
+    # Collect all unique format_id + manifest combinations across all products
+    all_requests: list[tuple[Product, FormatId, CreativeManifest]] = []
+    for product in products:
+        for format_id in product.format_ids:
+            sample_manifest = _create_sample_manifest_for_format_id(format_id, product)
+            if sample_manifest:
+                all_requests.append((product, format_id, sample_manifest))
+
+    if not all_requests:
+        return [p.model_dump(exclude_none=True) for p in products]
+
+    # Use batch API if requested and we have multiple requests
+    if use_batch and len(all_requests) > 1:
+        # Batch mode - much faster!
+        batch_requests = [(format_id, manifest) for _, format_id, manifest in all_requests]
+        preview_data_list = await generator.get_preview_data_batch(
+            batch_requests, output_format=output_format
+        )
+
+        # Map results back to products
+        # Build a mapping from product_id -> format_id -> preview_data
+        product_previews: dict[str, dict[str, dict[str, Any]]] = {}
+        for (product, format_id, _), preview_data in zip(all_requests, preview_data_list):
+            if preview_data:
+                if product.product_id not in product_previews:
+                    product_previews[product.product_id] = {}
+                product_previews[product.product_id][format_id.id] = preview_data
+
+        # Add preview data to products
+        result = []
+        for product in products:
+            product_dict = product.model_dump(exclude_none=True)
+            if product.product_id in product_previews:
+                product_dict["format_previews"] = product_previews[product.product_id]
+            result.append(product_dict)
+        return result
+    else:
+        # Fallback to individual requests (for single product/format or when batch disabled)
+        import asyncio
+
+        async def process_product(product: Product) -> dict[str, Any]:
+            """Process a single product and add preview data for all its formats."""
+            product_dict = product.model_dump(exclude_none=True)
+
+            async def process_format(format_id: FormatId) -> tuple[str, dict[str, Any] | None]:
+                """Process a single format for this product."""
+                try:
+                    sample_manifest = _create_sample_manifest_for_format_id(format_id, product)
+                    if sample_manifest:
+                        preview_data = await generator.get_preview_data_for_manifest(
+                            format_id, sample_manifest
+                        )
+                        return (format_id.id, preview_data)
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to generate preview for product {product.product_id}, "
+                        f"format {format_id}: {e}"
+                    )
+                return (format_id.id, None)
+
+            format_tasks = [process_format(fid) for fid in product.format_ids]
+            format_results = await asyncio.gather(*format_tasks)
+            format_previews = {
+                fid: data for fid, data in format_results if data is not None
+            }
+
+            if format_previews:
+                product_dict["format_previews"] = format_previews
+
+            return product_dict
+
+        return await asyncio.gather(*[process_product(product) for product in products])
+
+
+def _create_sample_manifest_for_format(fmt: Format) -> CreativeManifest | None:
+    """
+    Create a sample manifest for a format.
+
+    Args:
+        fmt: Format object
+
+    Returns:
+        Sample CreativeManifest, or None if unable to create one
+    """
+    from adcp.types.generated import CreativeManifest
+
+    if not fmt.assets_required:
+        return None
+
+    assets: dict[str, Any] = {}
+
+    for asset in fmt.assets_required:
+        if isinstance(asset, dict):
+            asset_id = asset.get("asset_id")
+            asset_type = asset.get("type")
+
+            if asset_id:
+                assets[asset_id] = _create_sample_asset(asset_type)
+
+    if not assets:
+        return None
+
+    return CreativeManifest(format_id=fmt.format_id, assets=assets, promoted_offering=None)
+
+
+def _create_sample_manifest_for_format_id(
+    format_id: FormatId, product: Product
+) -> CreativeManifest | None:
+    """
+    Create a sample manifest for a format ID referenced by a product.
+
+    Args:
+        format_id: Format identifier
+        product: Product that references this format
+
+    Returns:
+        Sample CreativeManifest with placeholder assets
+    """
+    from adcp.types.generated import CreativeManifest
+
+    assets = {
+        "primary_asset": "https://example.com/sample-image.jpg",
+        "clickthrough_url": "https://example.com",
+    }
+
+    return CreativeManifest(format_id=format_id, promoted_offering=product.name, assets=assets)
+
+
+def _create_sample_asset(asset_type: str | None) -> Any:
+    """
+    Create a sample asset value based on asset type.
+
+    Args:
+        asset_type: Type of asset (image, video, text, url, etc.)
+
+    Returns:
+        Sample asset value
+    """
+    if asset_type == "image":
+        return "https://via.placeholder.com/300x250.png"
+    elif asset_type == "video":
+        return "https://example.com/sample-video.mp4"
+    elif asset_type == "text":
+        return "Sample advertising text"
+    elif asset_type == "url":
+        return "https://example.com"
+    elif asset_type == "html":
+        return "<div>Sample HTML</div>"
+    else:
+        return "https://example.com/sample-asset"

{adcp-1.0.5.dist-info → adcp-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.0.5
+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.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+adcp/__init__.py,sha256=p3emIEsC2FN_jcnHOP62BRPs6h4lgIhFselvAlTM0LI,2512
+adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
+adcp/client.py,sha256=xs_sG7soRH1szk0S0rFu_6Ge4Ffe2aUdaTYnLmvteeo,27950
+adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
+adcp/exceptions.py,sha256=dNRMKV23DlkGKyB9Xmt6MtlhvDu1crjzD_en4nAEwDY,4399
+adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,262
+adcp/protocols/a2a.py,sha256=FHgc6G_eU2qD0vH7_RyS1eZvUFSb2j3-EsceoHPi384,12467
+adcp/protocols/base.py,sha256=CGqUilQv_ymhnfdowBV_HJhIxYUDM3sRO7ahW-kRB0M,5087
+adcp/protocols/mcp.py,sha256=eIk8snCinZm-ZjdarGVMt5nEYJ4_8POM9Fa5Mkw7xxU,15902
+adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
+adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
+adcp/types/generated.py,sha256=j21CgpQExfd2gZTEnDUlVO3hvBmdn-4yBzgC86GUEnI,52485
+adcp/types/tasks.py,sha256=Ae9TSwG2F7oWXTcl4TvLhAzinbQkHNGF1Pc0q8RMNNM,23424
+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=NQTLlbvmnM_tE4B5w3oB1Wshny1p-Uh8IWbghlwoNJc,4057
+adcp-1.1.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.1.0.dist-info/METADATA,sha256=51wZBtGtYyiqVRSaZtPW3OqvQOcZurM-A2FUvqRgrV8,14455
+adcp-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.1.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.1.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.1.0.dist-info/RECORD,,

adcp-1.0.5.dist-info/RECORD

@@ -1,22 +0,0 @@
-adcp/__init__.py,sha256=e7jeHMFSk_DxjaIWgRGqCR3A0fTOKtE-sMgulASLCWM,2512
-adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
-adcp/client.py,sha256=iIZUy5j25H48gGYlR_VuVsB9zP6SF1HtRssdPs2VJkc,24232
-adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
-adcp/exceptions.py,sha256=dNRMKV23DlkGKyB9Xmt6MtlhvDu1crjzD_en4nAEwDY,4399
-adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,262
-adcp/protocols/a2a.py,sha256=TN26ac98h2NUZTTs39Tyd6pVoS3k-sASuLKhLpdYV-A,12255
-adcp/protocols/base.py,sha256=CGqUilQv_ymhnfdowBV_HJhIxYUDM3sRO7ahW-kRB0M,5087
-adcp/protocols/mcp.py,sha256=iQTr5QkZbUj42cc_ca7esvcV4EgcOpI8IT6akut9-UA,16028
-adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
-adcp/types/core.py,sha256=BO6188PI8lIiVjpiSR0pmsCuXq3Tg9KlkHC5N2fXFxw,4824
-adcp/types/generated.py,sha256=KoILEa5Gg0tsjMYoqDEWulKvPzS0333L3qj75AHr4yI,50855
-adcp/types/tasks.py,sha256=Ae9TSwG2F7oWXTcl4TvLhAzinbQkHNGF1Pc0q8RMNNM,23424
-adcp/utils/__init__.py,sha256=uetvSJB19CjQbtwEYZiTnumJG11GsafQmXm5eR3hL7E,153
-adcp/utils/operation_id.py,sha256=wQX9Bb5epXzRq23xoeYPTqzu5yLuhshg7lKJZihcM2k,294
-adcp/utils/response_parser.py,sha256=NQTLlbvmnM_tE4B5w3oB1Wshny1p-Uh8IWbghlwoNJc,4057
-adcp-1.0.5.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.0.5.dist-info/METADATA,sha256=pmJWpMYNFVbyME-LpWm_Q9xFe3adBpivni17xNE2yaY,12724
-adcp-1.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.0.5.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.0.5.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.0.5.dist-info/RECORD,,