adcp 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.2.0
+Version: 1.3.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -59,8 +59,45 @@ AdCP operations are **distributed and asynchronous by default**. An agent might:
 pip install adcp
 ```
 
+> **Note**: This client requires Python 3.10 or later and supports both synchronous and asynchronous workflows.
+
+## Quick Start: Test Helpers
+
+The fastest way to get started is using the pre-configured test agents:
+
+```python
+from adcp.testing import test_agent
+from adcp.types.generated import GetProductsRequest
+
+# Zero configuration - just import and use!
+result = await test_agent.get_products(
+    GetProductsRequest(
+        brief="Coffee subscription service",
+        promoted_offering="Premium coffee deliveries"
+    )
+)
+
+if result.success:
+    print(f"Found {len(result.data.products)} products")
+```
+
+Test helpers include:
+- **`test_agent`**: Pre-configured MCP test agent with authentication
+- **`test_agent_a2a`**: Pre-configured A2A test agent with authentication
+- **`test_agent_no_auth`**: Pre-configured MCP test agent WITHOUT authentication
+- **`test_agent_a2a_no_auth`**: Pre-configured A2A test agent WITHOUT authentication
+- **`creative_agent`**: Reference creative agent for preview functionality
+- **`test_agent_client`**: Multi-agent client with both protocols
+- **`create_test_agent()`**: Factory for custom test configurations
+
+> **Note**: Test agents are rate-limited and for testing/examples only. DO NOT use in production.
+
+See [examples/test_helpers_demo.py](examples/test_helpers_demo.py) for more examples.
+
 ## Quick Start: Distributed Operations
 
+For production use, configure your own agents:
+
 ```python
 from adcp import ADCPMultiAgentClient, AgentConfig, GetProductsRequest
 
@@ -110,6 +147,66 @@ async with ADCPMultiAgentClient(
 
 ## Features
 
+### Test Helpers
+
+Pre-configured test agents for instant prototyping and testing:
+
+```python
+from adcp.testing import (
+    test_agent, test_agent_a2a,
+    test_agent_no_auth, test_agent_a2a_no_auth,
+    creative_agent, test_agent_client, create_test_agent
+)
+from adcp.types.generated import GetProductsRequest, PreviewCreativeRequest
+
+# 1. Single agent with authentication (MCP)
+result = await test_agent.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 2. Single agent with authentication (A2A)
+result = await test_agent_a2a.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 3. Single agent WITHOUT authentication (MCP)
+# Useful for testing unauthenticated behavior
+result = await test_agent_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 4. Single agent WITHOUT authentication (A2A)
+result = await test_agent_a2a_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 5. Creative agent (preview functionality, no auth required)
+result = await creative_agent.preview_creative(
+    PreviewCreativeRequest(
+        manifest={"format_id": "banner_300x250", "assets": {...}}
+    )
+)
+
+# 6. Multi-agent (parallel execution with both protocols)
+results = await test_agent_client.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 7. Custom configuration
+from adcp.client import ADCPClient
+config = create_test_agent(id="my-test", timeout=60.0)
+client = ADCPClient(config)
+```
+
+**Use cases:**
+- Quick prototyping and experimentation
+- Example code and documentation
+- Integration testing without mock servers
+- Testing authentication behavior (comparing auth vs no-auth results)
+- Learning AdCP concepts
+
+**Important:** Test agents are public, rate-limited, and for testing only. Never use in production.
+
 ### Full Protocol Support
 - **A2A Protocol**: Native support for Agent-to-Agent protocol
 - **MCP Protocol**: Native support for Model Context Protocol
@@ -375,6 +472,46 @@ uvx adcp --json myagent get_products '{"brief":"TV ads"}'
 uvx adcp --debug myagent get_products '{"brief":"TV ads"}'
 ```
 
+### Using Test Agents from CLI
+
+The CLI provides easy access to public test agents without configuration:
+
+```bash
+# Use test agent with authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent WITHOUT authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent with authentication (A2A)
+uvx adcp --protocol a2a \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  https://test-agent.adcontextprotocol.org \
+  get_products '{"brief":"Coffee brands"}'
+
+# Save test agent for easier access
+uvx adcp --save-auth test-agent https://test-agent.adcontextprotocol.org/mcp/ mcp
+# Enter token when prompted: 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ
+
+# Now use saved config
+uvx adcp test-agent get_products '{"brief":"Coffee brands"}'
+
+# Use creative agent (no auth required)
+uvx adcp https://creative.adcontextprotocol.org/mcp \
+  preview_creative @creative_manifest.json
+```
+
+**Test Agent Details:**
+- **URL (MCP)**: `https://test-agent.adcontextprotocol.org/mcp/`
+- **URL (A2A)**: `https://test-agent.adcontextprotocol.org`
+- **Auth Token**: `1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ` (optional, public token)
+- **Rate Limited**: For testing only, not for production
+- **No Auth Mode**: Omit `--auth` flag to test unauthenticated behavior
+```
+
 ### Configuration Management
 
 ```bash

{adcp-1.2.0 → adcp-1.3.0}/README.md

@@ -22,8 +22,45 @@ AdCP operations are **distributed and asynchronous by default**. An agent might:
 pip install adcp
 ```
 
+> **Note**: This client requires Python 3.10 or later and supports both synchronous and asynchronous workflows.
+
+## Quick Start: Test Helpers
+
+The fastest way to get started is using the pre-configured test agents:
+
+```python
+from adcp.testing import test_agent
+from adcp.types.generated import GetProductsRequest
+
+# Zero configuration - just import and use!
+result = await test_agent.get_products(
+    GetProductsRequest(
+        brief="Coffee subscription service",
+        promoted_offering="Premium coffee deliveries"
+    )
+)
+
+if result.success:
+    print(f"Found {len(result.data.products)} products")
+```
+
+Test helpers include:
+- **`test_agent`**: Pre-configured MCP test agent with authentication
+- **`test_agent_a2a`**: Pre-configured A2A test agent with authentication
+- **`test_agent_no_auth`**: Pre-configured MCP test agent WITHOUT authentication
+- **`test_agent_a2a_no_auth`**: Pre-configured A2A test agent WITHOUT authentication
+- **`creative_agent`**: Reference creative agent for preview functionality
+- **`test_agent_client`**: Multi-agent client with both protocols
+- **`create_test_agent()`**: Factory for custom test configurations
+
+> **Note**: Test agents are rate-limited and for testing/examples only. DO NOT use in production.
+
+See [examples/test_helpers_demo.py](examples/test_helpers_demo.py) for more examples.
+
 ## Quick Start: Distributed Operations
 
+For production use, configure your own agents:
+
 ```python
 from adcp import ADCPMultiAgentClient, AgentConfig, GetProductsRequest
 
@@ -73,6 +110,66 @@ async with ADCPMultiAgentClient(
 
 ## Features
 
+### Test Helpers
+
+Pre-configured test agents for instant prototyping and testing:
+
+```python
+from adcp.testing import (
+    test_agent, test_agent_a2a,
+    test_agent_no_auth, test_agent_a2a_no_auth,
+    creative_agent, test_agent_client, create_test_agent
+)
+from adcp.types.generated import GetProductsRequest, PreviewCreativeRequest
+
+# 1. Single agent with authentication (MCP)
+result = await test_agent.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 2. Single agent with authentication (A2A)
+result = await test_agent_a2a.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 3. Single agent WITHOUT authentication (MCP)
+# Useful for testing unauthenticated behavior
+result = await test_agent_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 4. Single agent WITHOUT authentication (A2A)
+result = await test_agent_a2a_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 5. Creative agent (preview functionality, no auth required)
+result = await creative_agent.preview_creative(
+    PreviewCreativeRequest(
+        manifest={"format_id": "banner_300x250", "assets": {...}}
+    )
+)
+
+# 6. Multi-agent (parallel execution with both protocols)
+results = await test_agent_client.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 7. Custom configuration
+from adcp.client import ADCPClient
+config = create_test_agent(id="my-test", timeout=60.0)
+client = ADCPClient(config)
+```
+
+**Use cases:**
+- Quick prototyping and experimentation
+- Example code and documentation
+- Integration testing without mock servers
+- Testing authentication behavior (comparing auth vs no-auth results)
+- Learning AdCP concepts
+
+**Important:** Test agents are public, rate-limited, and for testing only. Never use in production.
+
 ### Full Protocol Support
 - **A2A Protocol**: Native support for Agent-to-Agent protocol
 - **MCP Protocol**: Native support for Model Context Protocol
@@ -338,6 +435,46 @@ uvx adcp --json myagent get_products '{"brief":"TV ads"}'
 uvx adcp --debug myagent get_products '{"brief":"TV ads"}'
 ```
 
+### Using Test Agents from CLI
+
+The CLI provides easy access to public test agents without configuration:
+
+```bash
+# Use test agent with authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent WITHOUT authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent with authentication (A2A)
+uvx adcp --protocol a2a \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  https://test-agent.adcontextprotocol.org \
+  get_products '{"brief":"Coffee brands"}'
+
+# Save test agent for easier access
+uvx adcp --save-auth test-agent https://test-agent.adcontextprotocol.org/mcp/ mcp
+# Enter token when prompted: 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ
+
+# Now use saved config
+uvx adcp test-agent get_products '{"brief":"Coffee brands"}'
+
+# Use creative agent (no auth required)
+uvx adcp https://creative.adcontextprotocol.org/mcp \
+  preview_creative @creative_manifest.json
+```
+
+**Test Agent Details:**
+- **URL (MCP)**: `https://test-agent.adcontextprotocol.org/mcp/`
+- **URL (A2A)**: `https://test-agent.adcontextprotocol.org`
+- **Auth Token**: `1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ` (optional, public token)
+- **Rate Limited**: For testing only, not for production
+- **No Auth Mode**: Omit `--auth` flag to test unauthenticated behavior
+```
+
 ### Configuration Management
 
 ```bash

{adcp-1.2.0 → adcp-1.3.0}/pyproject.toml

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

adcp-1.3.0/src/adcp/__init__.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+"""
+AdCP Python Client Library
+
+Official Python client for the Ad Context Protocol (AdCP).
+Supports both A2A and MCP protocols with full type safety.
+"""
+
+from adcp.client import ADCPClient, ADCPMultiAgentClient
+from adcp.exceptions import (
+    ADCPAuthenticationError,
+    ADCPConnectionError,
+    ADCPError,
+    ADCPProtocolError,
+    ADCPTimeoutError,
+    ADCPToolNotFoundError,
+    ADCPWebhookError,
+    ADCPWebhookSignatureError,
+)
+
+# Test helpers
+from adcp.testing import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_client,
+)
+from adcp.types.core import AgentConfig, Protocol, TaskResult, TaskStatus, WebhookMetadata
+from adcp.types.generated import (
+    ActivateSignalError,
+    # Request/Response types
+    ActivateSignalRequest,
+    ActivateSignalResponse,
+    ActivateSignalSuccess,
+    ActivationKey,
+    AgentDeployment,
+    AgentDestination,
+    BothPreviewRender,
+    # Brand types
+    BrandManifest,
+    BrandManifestRef,
+    BuildCreativeRequest,
+    BuildCreativeResponse,
+    # Channel types
+    Channels,
+    CreateMediaBuyError,
+    CreateMediaBuyRequest,
+    CreateMediaBuyResponse,
+    CreateMediaBuySuccess,
+    # Creative types
+    CreativeAsset,
+    CreativeAssignment,
+    CreativeManifest,
+    CreativePolicy,
+    DaastAsset,
+    # Metrics types
+    DeliveryMetrics,
+    # Delivery types
+    DeliveryType,
+    Deployment,
+    # Deployment types
+    Destination,
+    Error,
+    Format,
+    FormatId,
+    FrequencyCap,
+    GetMediaBuyDeliveryRequest,
+    GetMediaBuyDeliveryResponse,
+    GetProductsRequest,
+    GetProductsResponse,
+    GetSignalsRequest,
+    GetSignalsResponse,
+    HtmlPreviewRender,
+    InlineDaastAsset,
+    InlineVastAsset,
+    Key_valueActivationKey,
+    ListAuthorizedPropertiesRequest,
+    ListAuthorizedPropertiesResponse,
+    ListCreativeFormatsRequest,
+    ListCreativeFormatsResponse,
+    ListCreativesRequest,
+    ListCreativesResponse,
+    Measurement,
+    # Core domain types
+    MediaBuy,
+    # Status enums
+    MediaBuyStatus,
+    # Sub-asset types
+    MediaSubAsset,
+    Pacing,
+    Package,
+    PackageStatus,
+    PerformanceFeedback,
+    Placement,
+    PlatformDeployment,
+    PlatformDestination,
+    PreviewCreativeRequest,
+    PreviewCreativeResponse,
+    # Preview render types
+    PreviewRender,
+    PricingModel,
+    # Pricing types
+    PricingOption,
+    Product,
+    PromotedProducts,
+    # Property and placement types
+    Property,
+    ProtocolEnvelope,
+    ProvidePerformanceFeedbackRequest,
+    ProvidePerformanceFeedbackResponse,
+    PushNotificationConfig,
+    ReportingCapabilities,
+    Response,
+    Segment_idActivationKey,
+    StandardFormatIds,
+    StartTiming,
+    SubAsset,
+    SyncCreativesError,
+    SyncCreativesRequest,
+    SyncCreativesResponse,
+    SyncCreativesSuccess,
+    # Targeting types
+    Targeting,
+    # Task types
+    TaskType,
+    TextSubAsset,
+    UpdateMediaBuyError,
+    UpdateMediaBuyRequest,
+    UpdateMediaBuyResponse,
+    UpdateMediaBuySuccess,
+    UrlDaastAsset,
+    UrlPreviewRender,
+    UrlVastAsset,
+    # Asset delivery types (VAST/DAAST)
+    VastAsset,
+    # Protocol types
+    WebhookPayload,
+)
+from adcp.types.generated import (
+    TaskStatus as GeneratedTaskStatus,
+)
+
+__version__ = "1.3.0"
+
+__all__ = [
+    # Client classes
+    "ADCPClient",
+    "ADCPMultiAgentClient",
+    # Core types
+    "AgentConfig",
+    "Protocol",
+    "TaskResult",
+    "TaskStatus",
+    "WebhookMetadata",
+    # Test helpers
+    "test_agent",
+    "test_agent_a2a",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
+    # Exceptions
+    "ADCPError",
+    "ADCPConnectionError",
+    "ADCPAuthenticationError",
+    "ADCPTimeoutError",
+    "ADCPProtocolError",
+    "ADCPToolNotFoundError",
+    "ADCPWebhookError",
+    "ADCPWebhookSignatureError",
+    # Request/Response types
+    "ActivateSignalRequest",
+    "ActivateSignalResponse",
+    "ActivateSignalSuccess",
+    "ActivateSignalError",
+    "ActivationKey",
+    "Segment_idActivationKey",
+    "Key_valueActivationKey",
+    "BuildCreativeRequest",
+    "BuildCreativeResponse",
+    "CreateMediaBuyRequest",
+    "CreateMediaBuyResponse",
+    "CreateMediaBuySuccess",
+    "CreateMediaBuyError",
+    "GetMediaBuyDeliveryRequest",
+    "GetMediaBuyDeliveryResponse",
+    "GetProductsRequest",
+    "GetProductsResponse",
+    "GetSignalsRequest",
+    "GetSignalsResponse",
+    "ListAuthorizedPropertiesRequest",
+    "ListAuthorizedPropertiesResponse",
+    "ListCreativeFormatsRequest",
+    "ListCreativeFormatsResponse",
+    "ListCreativesRequest",
+    "ListCreativesResponse",
+    "PreviewCreativeRequest",
+    "PreviewCreativeResponse",
+    "ProvidePerformanceFeedbackRequest",
+    "ProvidePerformanceFeedbackResponse",
+    "SyncCreativesRequest",
+    "SyncCreativesResponse",
+    "SyncCreativesSuccess",
+    "SyncCreativesError",
+    "UpdateMediaBuyRequest",
+    "UpdateMediaBuyResponse",
+    "UpdateMediaBuySuccess",
+    "UpdateMediaBuyError",
+    # Core domain types
+    "MediaBuy",
+    "Product",
+    "Package",
+    "Error",
+    # Creative types
+    "CreativeAsset",
+    "CreativeManifest",
+    "CreativeAssignment",
+    "CreativePolicy",
+    "Format",
+    "FormatId",
+    # Property and placement types
+    "Property",
+    "Placement",
+    # Targeting types
+    "Targeting",
+    "FrequencyCap",
+    "Pacing",
+    # Brand types
+    "BrandManifest",
+    "BrandManifestRef",
+    # Metrics types
+    "DeliveryMetrics",
+    "Measurement",
+    "PerformanceFeedback",
+    # Status enums
+    "MediaBuyStatus",
+    "PackageStatus",
+    # Pricing types
+    "PricingOption",
+    "PricingModel",
+    # Delivery types
+    "DeliveryType",
+    "StartTiming",
+    # Channel types
+    "Channels",
+    "StandardFormatIds",
+    # Protocol types
+    "WebhookPayload",
+    "ProtocolEnvelope",
+    "Response",
+    "PromotedProducts",
+    "PushNotificationConfig",
+    "ReportingCapabilities",
+    # Deployment types
+    "Destination",
+    "Deployment",
+    "PlatformDestination",
+    "AgentDestination",
+    "PlatformDeployment",
+    "AgentDeployment",
+    # Sub-asset types
+    "MediaSubAsset",
+    "SubAsset",
+    "TextSubAsset",
+    # Asset delivery types (VAST/DAAST)
+    "VastAsset",
+    "UrlVastAsset",
+    "InlineVastAsset",
+    "DaastAsset",
+    "UrlDaastAsset",
+    "InlineDaastAsset",
+    # Preview render types
+    "PreviewRender",
+    "UrlPreviewRender",
+    "HtmlPreviewRender",
+    "BothPreviewRender",
+    # Task types
+    "TaskType",
+    "GeneratedTaskStatus",
+]

{adcp-1.2.0 → adcp-1.3.0}/src/adcp/client.py

@@ -11,6 +11,8 @@ from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 
+from pydantic import BaseModel
+
 from adcp.exceptions import ADCPWebhookSignatureError
 from adcp.protocols.a2a import A2AAdapter
 from adcp.protocols.base import ProtocolAdapter
@@ -154,7 +156,9 @@ class ADCPClient:
             )
         )
 
-        result = self.adapter._parse_response(raw_result, GetProductsResponse)
+        result: TaskResult[GetProductsResponse] = 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
@@ -215,7 +219,9 @@ class ADCPClient:
             )
         )
 
-        result = self.adapter._parse_response(raw_result, ListCreativeFormatsResponse)
+        result: TaskResult[ListCreativeFormatsResponse] = 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
@@ -617,15 +623,16 @@ class ADCPClient:
         from adcp.utils.response_parser import parse_json_or_text
 
         # Map task types to their response types (using string literals, not enum)
-        response_type_map: dict[str, type] = {
+        # Note: Some response types are Union types (e.g., ActivateSignalResponse = Success | Error)
+        response_type_map: dict[str, type[BaseModel] | Any] = {
             "get_products": GetProductsResponse,
             "list_creative_formats": ListCreativeFormatsResponse,
-            "sync_creatives": SyncCreativesResponse,
+            "sync_creatives": SyncCreativesResponse,  # Union type
             "list_creatives": ListCreativesResponse,
             "get_media_buy_delivery": GetMediaBuyDeliveryResponse,
             "list_authorized_properties": ListAuthorizedPropertiesResponse,
             "get_signals": GetSignalsResponse,
-            "activate_signal": ActivateSignalResponse,
+            "activate_signal": ActivateSignalResponse,  # Union type
             "provide_performance_feedback": ProvidePerformanceFeedbackResponse,
         }
 

{adcp-1.2.0 → adcp-1.3.0}/src/adcp/protocols/base.py

@@ -30,15 +30,18 @@ class ProtocolAdapter(ABC):
     # Helper methods for response parsing
     # ========================================================================
 
-    def _parse_response(self, raw_result: TaskResult[Any], response_type: type[T]) -> TaskResult[T]:
+    def _parse_response(
+        self, raw_result: TaskResult[Any], response_type: type[T] | Any
+    ) -> TaskResult[T]:
         """
         Parse raw TaskResult into typed TaskResult.
 
         Handles both MCP content arrays and A2A dict responses.
+        Supports both single types and Union types (for oneOf discriminated unions).
 
         Args:
             raw_result: Raw TaskResult from adapter
-            response_type: Expected Pydantic response type
+            response_type: Expected Pydantic response type (can be a Union type)
 
         Returns:
             Typed TaskResult