adcp 2.0.0__tar.gz → 2.1.0__tar.gz

{adcp-2.0.0/src/adcp.egg-info → adcp-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.0.0
+Version: 2.1.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -94,7 +94,7 @@ print(products.products[0].name)
 **Standard API** (`client.*`) - Recommended for production:
 ```python
 from adcp.testing import test_agent
-from adcp.types.generated import GetProductsRequest
+from adcp import GetProductsRequest
 
 # Explicit request objects and TaskResult wrapper
 request = GetProductsRequest(brief='Coffee brands')
@@ -124,6 +124,8 @@ Pre-configured agents (all include `.simple` accessor):
 
 See [examples/simple_api_demo.py](examples/simple_api_demo.py) for a complete comparison.
 
+> **Tip**: Import types from the main `adcp` package (e.g., `from adcp import GetProductsRequest`) rather than `adcp.types.generated` for better API stability.
+
 ## Quick Start: Distributed Operations
 
 For production use, configure your own agents:
@@ -187,7 +189,7 @@ from adcp.testing import (
     test_agent_no_auth, test_agent_a2a_no_auth,
     creative_agent, test_agent_client, create_test_agent
 )
-from adcp.types.generated import GetProductsRequest, PreviewCreativeRequest
+from adcp import GetProductsRequest, PreviewCreativeRequest
 
 # 1. Single agent with authentication (MCP)
 result = await test_agent.get_products(
@@ -243,6 +245,7 @@ client = ADCPClient(config)
 - **Auto-detection**: Automatically detect which protocol an agent uses
 
 ### Type Safety
+
 Full type hints with Pydantic validation and auto-generated types from the AdCP spec:
 
 ```python
@@ -258,6 +261,40 @@ if result.success:
         print(product.name, product.pricing_options)  # Full IDE autocomplete!
 ```
 
+#### Semantic Type Aliases
+
+For discriminated union types (success/error responses), use semantic aliases for clearer code:
+
+```python
+from adcp import (
+    CreateMediaBuySuccessResponse,  # Clear: this is the success case
+    CreateMediaBuyErrorResponse,     # Clear: this is the error case
+)
+
+def handle_response(
+    response: CreateMediaBuySuccessResponse | CreateMediaBuyErrorResponse
+) -> None:
+    if isinstance(response, CreateMediaBuySuccessResponse):
+        print(f"✅ Media buy created: {response.media_buy_id}")
+    else:
+        print(f"❌ Errors: {response.errors}")
+```
+
+**Available semantic aliases:**
+- Response types: `*SuccessResponse` / `*ErrorResponse` (e.g., `CreateMediaBuySuccessResponse`)
+- Request variants: `*FormatRequest` / `*ManifestRequest` (e.g., `PreviewCreativeFormatRequest`)
+- Preview renders: `PreviewRenderImage` / `PreviewRenderHtml` / `PreviewRenderIframe`
+- Activation keys: `PropertyIdActivationKey` / `PropertyTagActivationKey`
+
+See `examples/type_aliases_demo.py` for more examples.
+
+**Import guidelines:**
+- ✅ **DO**: Import from main package: `from adcp import GetProductsRequest`
+- ✅ **DO**: Use semantic aliases: `from adcp import CreateMediaBuySuccessResponse`
+- ⚠️ **AVOID**: Import from internal modules: `from adcp.types.generated import CreateMediaBuyResponse1`
+
+The main package exports provide a stable API while internal generated types may change.
+
 ### Multi-Agent Operations
 Execute across multiple agents simultaneously:
 

{adcp-2.0.0 → adcp-2.1.0}/README.md

@@ -55,7 +55,7 @@ print(products.products[0].name)
 **Standard API** (`client.*`) - Recommended for production:
 ```python
 from adcp.testing import test_agent
-from adcp.types.generated import GetProductsRequest
+from adcp import GetProductsRequest
 
 # Explicit request objects and TaskResult wrapper
 request = GetProductsRequest(brief='Coffee brands')
@@ -85,6 +85,8 @@ Pre-configured agents (all include `.simple` accessor):
 
 See [examples/simple_api_demo.py](examples/simple_api_demo.py) for a complete comparison.
 
+> **Tip**: Import types from the main `adcp` package (e.g., `from adcp import GetProductsRequest`) rather than `adcp.types.generated` for better API stability.
+
 ## Quick Start: Distributed Operations
 
 For production use, configure your own agents:
@@ -148,7 +150,7 @@ from adcp.testing import (
     test_agent_no_auth, test_agent_a2a_no_auth,
     creative_agent, test_agent_client, create_test_agent
 )
-from adcp.types.generated import GetProductsRequest, PreviewCreativeRequest
+from adcp import GetProductsRequest, PreviewCreativeRequest
 
 # 1. Single agent with authentication (MCP)
 result = await test_agent.get_products(
@@ -204,6 +206,7 @@ client = ADCPClient(config)
 - **Auto-detection**: Automatically detect which protocol an agent uses
 
 ### Type Safety
+
 Full type hints with Pydantic validation and auto-generated types from the AdCP spec:
 
 ```python
@@ -219,6 +222,40 @@ if result.success:
         print(product.name, product.pricing_options)  # Full IDE autocomplete!
 ```
 
+#### Semantic Type Aliases
+
+For discriminated union types (success/error responses), use semantic aliases for clearer code:
+
+```python
+from adcp import (
+    CreateMediaBuySuccessResponse,  # Clear: this is the success case
+    CreateMediaBuyErrorResponse,     # Clear: this is the error case
+)
+
+def handle_response(
+    response: CreateMediaBuySuccessResponse | CreateMediaBuyErrorResponse
+) -> None:
+    if isinstance(response, CreateMediaBuySuccessResponse):
+        print(f"✅ Media buy created: {response.media_buy_id}")
+    else:
+        print(f"❌ Errors: {response.errors}")
+```
+
+**Available semantic aliases:**
+- Response types: `*SuccessResponse` / `*ErrorResponse` (e.g., `CreateMediaBuySuccessResponse`)
+- Request variants: `*FormatRequest` / `*ManifestRequest` (e.g., `PreviewCreativeFormatRequest`)
+- Preview renders: `PreviewRenderImage` / `PreviewRenderHtml` / `PreviewRenderIframe`
+- Activation keys: `PropertyIdActivationKey` / `PropertyTagActivationKey`
+
+See `examples/type_aliases_demo.py` for more examples.
+
+**Import guidelines:**
+- ✅ **DO**: Import from main package: `from adcp import GetProductsRequest`
+- ✅ **DO**: Use semantic aliases: `from adcp import CreateMediaBuySuccessResponse`
+- ⚠️ **AVOID**: Import from internal modules: `from adcp.types.generated import CreateMediaBuyResponse1`
+
+The main package exports provide a stable API while internal generated types may change.
+
 ### Multi-Agent Operations
 Execute across multiple agents simultaneously:
 

{adcp-2.0.0 → adcp-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "2.0.0"
+version = "2.1.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
@@ -57,6 +57,9 @@ Issues = "https://github.com/adcontextprotocol/adcp-client-python/issues"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+adcp = ["py.typed"]
+
 [tool.black]
 line-length = 100
 target-version = ["py310", "py311", "py312"]

adcp-2.1.0/src/adcp/__init__.py

@@ -0,0 +1,243 @@
+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.adagents import (
+    domain_matches,
+    fetch_adagents,
+    get_all_properties,
+    get_all_tags,
+    get_properties_by_agent,
+    identifiers_match,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
+from adcp.client import ADCPClient, ADCPMultiAgentClient
+from adcp.exceptions import (
+    AdagentsNotFoundError,
+    AdagentsTimeoutError,
+    AdagentsValidationError,
+    ADCPAuthenticationError,
+    ADCPConnectionError,
+    ADCPError,
+    ADCPProtocolError,
+    ADCPTimeoutError,
+    ADCPToolNotFoundError,
+    ADCPWebhookError,
+    ADCPWebhookSignatureError,
+)
+
+# Test helpers
+from adcp.testing import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_A2A_NO_AUTH_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_MCP_NO_AUTH_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_a2a_no_auth,
+    test_agent_client,
+    test_agent_no_auth,
+)
+
+# Import all generated types - users can import what they need from adcp.types.generated
+from adcp.types import aliases, generated
+
+# Re-export semantic type aliases for better ergonomics
+from adcp.types.aliases import (
+    ActivateSignalErrorResponse,
+    ActivateSignalSuccessResponse,
+    BuildCreativeErrorResponse,
+    BuildCreativeSuccessResponse,
+    CreateMediaBuyErrorResponse,
+    CreateMediaBuySuccessResponse,
+    PreviewCreativeFormatRequest,
+    PreviewCreativeInteractiveResponse,
+    PreviewCreativeManifestRequest,
+    PreviewCreativeStaticResponse,
+    PreviewRenderHtml,
+    PreviewRenderIframe,
+    PreviewRenderImage,
+    PropertyIdActivationKey,
+    PropertyTagActivationKey,
+    ProvidePerformanceFeedbackErrorResponse,
+    ProvidePerformanceFeedbackSuccessResponse,
+    SyncCreativesErrorResponse,
+    SyncCreativesSuccessResponse,
+    UpdateMediaBuyErrorResponse,
+    UpdateMediaBuyPackagesRequest,
+    UpdateMediaBuyPropertiesRequest,
+    UpdateMediaBuySuccessResponse,
+)
+from adcp.types.core import AgentConfig, Protocol, TaskResult, TaskStatus, WebhookMetadata
+
+# Re-export commonly-used request/response types for convenience
+# Users should import from main package (e.g., `from adcp import GetProductsRequest`)
+# rather than internal modules for better API stability
+from adcp.types.generated import (
+    # Audience & Targeting
+    ActivateSignalRequest,
+    ActivateSignalResponse,
+    # Creative Operations
+    BuildCreativeRequest,
+    BuildCreativeResponse,
+    # Media Buy Operations
+    CreateMediaBuyRequest,
+    CreateMediaBuyResponse,
+    # Common data types
+    Error,
+    Format,
+    GetMediaBuyDeliveryRequest,
+    GetMediaBuyDeliveryResponse,
+    GetProductsRequest,
+    GetProductsResponse,
+    GetSignalsRequest,
+    GetSignalsResponse,
+    ListAuthorizedPropertiesRequest,
+    ListAuthorizedPropertiesResponse,
+    ListCreativeFormatsRequest,
+    ListCreativeFormatsResponse,
+    ListCreativesRequest,
+    ListCreativesResponse,
+    PreviewCreativeRequest,
+    PreviewCreativeResponse,
+    Product,
+    Property,
+    ProvidePerformanceFeedbackRequest,
+    ProvidePerformanceFeedbackResponse,
+    SyncCreativesRequest,
+    SyncCreativesResponse,
+    UpdateMediaBuyRequest,
+    UpdateMediaBuyResponse,
+)
+from adcp.types.generated import TaskStatus as GeneratedTaskStatus
+from adcp.validation import (
+    ValidationError,
+    validate_adagents,
+    validate_agent_authorization,
+    validate_product,
+    validate_publisher_properties_item,
+)
+
+__version__ = "2.1.0"
+
+__all__ = [
+    # Client classes
+    "ADCPClient",
+    "ADCPMultiAgentClient",
+    # Core types
+    "AgentConfig",
+    "Protocol",
+    "TaskResult",
+    "TaskStatus",
+    "WebhookMetadata",
+    # Common request/response types (re-exported for convenience)
+    "CreateMediaBuyRequest",
+    "CreateMediaBuyResponse",
+    "GetMediaBuyDeliveryRequest",
+    "GetMediaBuyDeliveryResponse",
+    "GetProductsRequest",
+    "GetProductsResponse",
+    "UpdateMediaBuyRequest",
+    "UpdateMediaBuyResponse",
+    "BuildCreativeRequest",
+    "BuildCreativeResponse",
+    "ListCreativeFormatsRequest",
+    "ListCreativeFormatsResponse",
+    "ListCreativesRequest",
+    "ListCreativesResponse",
+    "PreviewCreativeRequest",
+    "PreviewCreativeResponse",
+    "SyncCreativesRequest",
+    "SyncCreativesResponse",
+    "ActivateSignalRequest",
+    "ActivateSignalResponse",
+    "GetSignalsRequest",
+    "GetSignalsResponse",
+    "ListAuthorizedPropertiesRequest",
+    "ListAuthorizedPropertiesResponse",
+    "ProvidePerformanceFeedbackRequest",
+    "ProvidePerformanceFeedbackResponse",
+    "Error",
+    "Format",
+    "Product",
+    "Property",
+    # Adagents validation
+    "fetch_adagents",
+    "verify_agent_authorization",
+    "verify_agent_for_property",
+    "domain_matches",
+    "identifiers_match",
+    "get_all_properties",
+    "get_all_tags",
+    "get_properties_by_agent",
+    # Test helpers
+    "test_agent",
+    "test_agent_a2a",
+    "test_agent_no_auth",
+    "test_agent_a2a_no_auth",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "TEST_AGENT_MCP_NO_AUTH_CONFIG",
+    "TEST_AGENT_A2A_NO_AUTH_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
+    # Exceptions
+    "ADCPError",
+    "ADCPConnectionError",
+    "ADCPAuthenticationError",
+    "ADCPTimeoutError",
+    "ADCPProtocolError",
+    "ADCPToolNotFoundError",
+    "ADCPWebhookError",
+    "ADCPWebhookSignatureError",
+    "AdagentsValidationError",
+    "AdagentsNotFoundError",
+    "AdagentsTimeoutError",
+    # Validation utilities
+    "ValidationError",
+    "validate_adagents",
+    "validate_agent_authorization",
+    "validate_product",
+    "validate_publisher_properties_item",
+    # Generated types modules
+    "generated",
+    "aliases",
+    "GeneratedTaskStatus",
+    # Semantic type aliases (for better API ergonomics)
+    "ActivateSignalSuccessResponse",
+    "ActivateSignalErrorResponse",
+    "BuildCreativeSuccessResponse",
+    "BuildCreativeErrorResponse",
+    "CreateMediaBuySuccessResponse",
+    "CreateMediaBuyErrorResponse",
+    "ProvidePerformanceFeedbackSuccessResponse",
+    "ProvidePerformanceFeedbackErrorResponse",
+    "SyncCreativesSuccessResponse",
+    "SyncCreativesErrorResponse",
+    "UpdateMediaBuySuccessResponse",
+    "UpdateMediaBuyErrorResponse",
+    "PreviewCreativeFormatRequest",
+    "PreviewCreativeManifestRequest",
+    "PreviewCreativeStaticResponse",
+    "PreviewCreativeInteractiveResponse",
+    "PreviewRenderImage",
+    "PreviewRenderHtml",
+    "PreviewRenderIframe",
+    "PropertyIdActivationKey",
+    "PropertyTagActivationKey",
+    "UpdateMediaBuyPackagesRequest",
+    "UpdateMediaBuyPropertiesRequest",
+]

adcp-2.1.0/src/adcp/types/aliases.py

@@ -0,0 +1,209 @@
+"""Semantic type aliases for generated AdCP types.
+
+This module provides user-friendly aliases for generated types where the
+auto-generated names don't match user expectations from reading the spec.
+
+The code generator (datamodel-code-generator) creates numbered suffixes for
+discriminated union variants (e.g., Response1, Response2), but users expect
+semantic names (e.g., SuccessResponse, ErrorResponse).
+
+Categories of aliases:
+
+1. Discriminated Union Response Variants
+   - Success/Error cases for API responses
+   - Named to match the semantic meaning from the spec
+
+2. Preview/Render Types
+   - Input/Output/Request/Response variants
+   - Numbered types mapped to their semantic purpose
+
+3. Activation Keys
+   - Signal activation key variants
+
+DO NOT EDIT the generated types directly - they are regenerated from schemas.
+Add aliases here for any types where the generated name is unclear.
+
+Validation:
+This module will raise ImportError at import time if any of the referenced
+generated types do not exist. This ensures that schema changes are caught
+immediately rather than at runtime when users try to use the aliases.
+"""
+
+from __future__ import annotations
+
+# Import all generated types that need semantic aliases
+from adcp.types.generated import (
+    # Activation responses
+    ActivateSignalResponse1,
+    ActivateSignalResponse2,
+    # Activation keys
+    ActivationKey1,
+    ActivationKey2,
+    # Build creative responses
+    BuildCreativeResponse1,
+    BuildCreativeResponse2,
+    # Create media buy responses
+    CreateMediaBuyResponse1,
+    CreateMediaBuyResponse2,
+    # Preview creative requests
+    PreviewCreativeRequest1,
+    PreviewCreativeRequest2,
+    # Preview creative responses
+    PreviewCreativeResponse1,
+    PreviewCreativeResponse2,
+    # Preview renders
+    PreviewRender1,
+    PreviewRender2,
+    PreviewRender3,
+    # Performance feedback responses
+    ProvidePerformanceFeedbackResponse1,
+    ProvidePerformanceFeedbackResponse2,
+    # Sync creatives responses
+    SyncCreativesResponse1,
+    SyncCreativesResponse2,
+    # Update media buy requests
+    UpdateMediaBuyRequest1,
+    UpdateMediaBuyRequest2,
+    # Update media buy responses
+    UpdateMediaBuyResponse1,
+    UpdateMediaBuyResponse2,
+)
+
+# ============================================================================
+# RESPONSE TYPE ALIASES - Success/Error Discriminated Unions
+# ============================================================================
+# These are atomic operations where the response is EITHER success OR error,
+# never both. The numbered suffixes from the generator don't convey this
+# critical semantic distinction.
+
+# Activate Signal Response Variants
+ActivateSignalSuccessResponse = ActivateSignalResponse1
+"""Success response - signal activation succeeded."""
+
+ActivateSignalErrorResponse = ActivateSignalResponse2
+"""Error response - signal activation failed."""
+
+# Build Creative Response Variants
+BuildCreativeSuccessResponse = BuildCreativeResponse1
+"""Success response - creative built successfully, manifest returned."""
+
+BuildCreativeErrorResponse = BuildCreativeResponse2
+"""Error response - creative build failed, no manifest created."""
+
+# Create Media Buy Response Variants
+CreateMediaBuySuccessResponse = CreateMediaBuyResponse1
+"""Success response - media buy created successfully with media_buy_id."""
+
+CreateMediaBuyErrorResponse = CreateMediaBuyResponse2
+"""Error response - media buy creation failed, no media buy created."""
+
+# Performance Feedback Response Variants
+ProvidePerformanceFeedbackSuccessResponse = ProvidePerformanceFeedbackResponse1
+"""Success response - performance feedback accepted."""
+
+ProvidePerformanceFeedbackErrorResponse = ProvidePerformanceFeedbackResponse2
+"""Error response - performance feedback rejected."""
+
+# Sync Creatives Response Variants
+SyncCreativesSuccessResponse = SyncCreativesResponse1
+"""Success response - sync operation processed creatives."""
+
+SyncCreativesErrorResponse = SyncCreativesResponse2
+"""Error response - sync operation failed."""
+
+# Update Media Buy Response Variants
+UpdateMediaBuySuccessResponse = UpdateMediaBuyResponse1
+"""Success response - media buy updated successfully."""
+
+UpdateMediaBuyErrorResponse = UpdateMediaBuyResponse2
+"""Error response - media buy update failed, no changes applied."""
+
+# ============================================================================
+# REQUEST TYPE ALIASES - Operation Variants
+# ============================================================================
+
+# Preview Creative Request Variants
+PreviewCreativeFormatRequest = PreviewCreativeRequest1
+"""Preview request using format_id to identify creative format."""
+
+PreviewCreativeManifestRequest = PreviewCreativeRequest2
+"""Preview request using creative_manifest_url to identify creative."""
+
+# Update Media Buy Request Variants
+UpdateMediaBuyPackagesRequest = UpdateMediaBuyRequest1
+"""Update request modifying packages in the media buy."""
+
+UpdateMediaBuyPropertiesRequest = UpdateMediaBuyRequest2
+"""Update request modifying media buy properties (not packages)."""
+
+# ============================================================================
+# ACTIVATION KEY ALIASES
+# ============================================================================
+
+PropertyIdActivationKey = ActivationKey1
+"""Activation key using property_id for identification."""
+
+PropertyTagActivationKey = ActivationKey2
+"""Activation key using property_tags for identification."""
+
+# ============================================================================
+# PREVIEW/RENDER TYPE ALIASES
+# ============================================================================
+
+# Preview Creative Response Variants
+PreviewCreativeStaticResponse = PreviewCreativeResponse1
+"""Preview response with static renders (image/HTML snapshots)."""
+
+PreviewCreativeInteractiveResponse = PreviewCreativeResponse2
+"""Preview response with interactive renders (iframe embedding)."""
+
+# Preview Render Variants
+PreviewRenderImage = PreviewRender1
+"""Image-based preview render (PNG/JPEG)."""
+
+PreviewRenderHtml = PreviewRender2
+"""HTML-based preview render (static markup)."""
+
+PreviewRenderIframe = PreviewRender3
+"""Interactive iframe-based preview render."""
+
+# ============================================================================
+# EXPORTS
+# ============================================================================
+
+__all__ = [
+    # Activation responses
+    "ActivateSignalSuccessResponse",
+    "ActivateSignalErrorResponse",
+    # Activation keys
+    "PropertyIdActivationKey",
+    "PropertyTagActivationKey",
+    # Build creative responses
+    "BuildCreativeSuccessResponse",
+    "BuildCreativeErrorResponse",
+    # Create media buy responses
+    "CreateMediaBuySuccessResponse",
+    "CreateMediaBuyErrorResponse",
+    # Performance feedback responses
+    "ProvidePerformanceFeedbackSuccessResponse",
+    "ProvidePerformanceFeedbackErrorResponse",
+    # Preview creative requests
+    "PreviewCreativeFormatRequest",
+    "PreviewCreativeManifestRequest",
+    # Preview creative responses
+    "PreviewCreativeStaticResponse",
+    "PreviewCreativeInteractiveResponse",
+    # Preview renders
+    "PreviewRenderImage",
+    "PreviewRenderHtml",
+    "PreviewRenderIframe",
+    # Sync creatives responses
+    "SyncCreativesSuccessResponse",
+    "SyncCreativesErrorResponse",
+    # Update media buy requests
+    "UpdateMediaBuyPackagesRequest",
+    "UpdateMediaBuyPropertiesRequest",
+    # Update media buy responses
+    "UpdateMediaBuySuccessResponse",
+    "UpdateMediaBuyErrorResponse",
+]