adcp 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

adcp/utils/response_parser.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any, TypeVar
+from typing import Any, TypeVar, Union, cast, get_args, get_origin
 
 from pydantic import BaseModel, ValidationError
 
@@ -13,6 +13,56 @@ logger = logging.getLogger(__name__)
 T = TypeVar("T", bound=BaseModel)
 
 
+def _validate_union_type(data: dict[str, Any], response_type: type[T]) -> T:
+    """
+    Validate data against a Union type by trying each variant.
+
+    Args:
+        data: Data to validate
+        response_type: Union type to validate against
+
+    Returns:
+        Validated model instance
+
+    Raises:
+        ValidationError: If data doesn't match any Union variant
+    """
+    # Check if this is a Union type (handles both typing.Union and types.UnionType)
+    origin = get_origin(response_type)
+
+    # In Python 3.10+, X | Y creates a types.UnionType, not typing.Union
+    # We need to check both the origin and the type itself
+    is_union = origin is Union or str(type(response_type).__name__) == "UnionType"
+
+    if is_union:
+        # Get union args - works for both typing.Union and types.UnionType
+        args = get_args(response_type)
+        if not args:  # types.UnionType case
+            # For types.UnionType, we need to access __args__ directly
+            args = getattr(response_type, "__args__", ())
+
+        errors = []
+        for variant in args:
+            try:
+                return cast(T, variant.model_validate(data))
+            except ValidationError as e:
+                errors.append((variant.__name__, e))
+                continue
+
+        # If we get here, none of the variants worked
+        error_msgs = [f"{name}: {str(e)}" for name, e in errors]
+        # Raise a ValueError instead of ValidationError for better error messages
+        raise ValueError(
+            f"Data doesn't match any Union variant. "
+            f"Attempted variants: {', '.join([e[0] for e in errors])}. "
+            f"Errors: {'; '.join(error_msgs)}"
+        )
+
+    # Not a Union type, use regular validation
+    # Cast is needed because response_type is typed as type[T] | Any
+    return cast(T, response_type.model_validate(data))  # type: ignore[redundant-cast]
+
+
 def parse_mcp_content(content: list[dict[str, Any]], response_type: type[T]) -> T:
     """
     Parse MCP content array into structured response type.
@@ -48,8 +98,8 @@ def parse_mcp_content(content: list[dict[str, Any]], response_type: type[T]) ->
             try:
                 # Try parsing as JSON
                 data = json.loads(text)
-                # Validate against expected schema
-                return response_type.model_validate(data)
+                # Validate against expected schema (handles Union types)
+                return _validate_union_type(data, response_type)
             except json.JSONDecodeError:
                 # Not JSON, try next item
                 continue
@@ -61,7 +111,7 @@ def parse_mcp_content(content: list[dict[str, Any]], response_type: type[T]) ->
         elif item.get("type") == "resource":
             # Resource content might have structured data
             try:
-                return response_type.model_validate(item)
+                return _validate_union_type(item, response_type)
             except ValidationError:
                 # Try next item
                 continue
@@ -98,25 +148,24 @@ def parse_json_or_text(data: Any, response_type: type[T]) -> T:
     # If already a dict, try direct validation
     if isinstance(data, dict):
         try:
-            return response_type.model_validate(data)
+            return _validate_union_type(data, response_type)
         except ValidationError as e:
-            raise ValueError(
-                f"Response doesn't match expected schema {response_type.__name__}: {e}"
-            ) from e
+            # Get the type name, handling Union types
+            type_name = getattr(response_type, "__name__", str(response_type))
+            raise ValueError(f"Response doesn't match expected schema {type_name}: {e}") from e
 
     # If string, try JSON parsing
     if isinstance(data, str):
         try:
             parsed = json.loads(data)
-            return response_type.model_validate(parsed)
+            return _validate_union_type(parsed, response_type)
         except json.JSONDecodeError as e:
             raise ValueError(f"Response is not valid JSON: {e}") from e
         except ValidationError as e:
-            raise ValueError(
-                f"Response doesn't match expected schema {response_type.__name__}: {e}"
-            ) from e
+            # Get the type name, handling Union types
+            type_name = getattr(response_type, "__name__", str(response_type))
+            raise ValueError(f"Response doesn't match expected schema {type_name}: {e}") from e
 
     # Unsupported type
-    raise ValueError(
-        f"Cannot parse response of type {type(data).__name__} into {response_type.__name__}"
-    )
+    type_name = getattr(response_type, "__name__", str(response_type))
+    raise ValueError(f"Cannot parse response of type {type(data).__name__} into {type_name}")

{adcp-1.2.0.dist-info → adcp-1.3.0.dist-info}/METADATA

@@ -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.dist-info → adcp-1.3.0.dist-info}/RECORD

@@ -1,23 +1,25 @@
-adcp/__init__.py,sha256=PKqv9xsX2JUnDqOIvOGsfYFYQX4QlWKOt5w0R4IiRXw,2512
+adcp/__init__.py,sha256=FRJ5kL682ZQiohuDyzUzwLvrOEUM7Hjy0aavfo4g4gc,6724
 adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
-adcp/client.py,sha256=xs_sG7soRH1szk0S0rFu_6Ge4Ffe2aUdaTYnLmvteeo,27950
+adcp/client.py,sha256=co4tKdkjDrqZltCUPcYwVRr8LQfbBbG-DLjapLjcVuo,28246
 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/base.py,sha256=vBHD23Fzl_CCk_Gy9nvSbBYopcJlYkYyzoz-rhI8wHg,5214
 adcp/protocols/mcp.py,sha256=eIk8snCinZm-ZjdarGVMt5nEYJ4_8POM9Fa5Mkw7xxU,15902
+adcp/testing/__init__.py,sha256=kPsRncZ42g4HpOljVwLrFXm2O28K5NKcPUtvykfYY6M,888
+adcp/testing/test_helpers.py,sha256=4n8fZYy1cVpjZpFW2SxBzpC8fmY-MBFrzY4tIPqe4rQ,10028
 adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
 adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
-adcp/types/generated.py,sha256=UmHVH22lBayrNipgctAE-K_nsUuRfXvmDNhKZVq9mxQ,56514
+adcp/types/generated.py,sha256=Ig4ucbJzKRuHlwYzsqvMF9M3w2KghhQQqsXuOnBqVMM,74993
 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.2.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.2.0.dist-info/METADATA,sha256=NJowqCc7uoc4hx99dhdokdnydbZcnl9ERjyEsY7-q2o,14455
-adcp-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.2.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.2.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.2.0.dist-info/RECORD,,
+adcp/utils/response_parser.py,sha256=uPk2vIH-RYZmq7y3i8lC4HTMQ3FfKdlgXKTjgJ1955M,6253
+adcp-1.3.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.3.0.dist-info/METADATA,sha256=QQQ8zxzwIelNWUxz-ZBTTgpORHp9RrxT-1BnjFZ5S_o,19097
+adcp-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.3.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.3.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.3.0.dist-info/RECORD,,