adcp 1.6.1__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.6.1
+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
@@ -33,6 +33,8 @@ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: datamodel-code-generator[http]>=0.35.0; extra == "dev"
+Requires-Dist: email-validator>=2.0.0; extra == "dev"
 Dynamic: license-file
 
 # adcp - Python Client for Ad Context Protocol
@@ -92,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')
@@ -122,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:
@@ -185,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(
@@ -241,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
@@ -256,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-1.6.1 → 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-1.6.1 → adcp-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "1.6.1"
+version = "2.1.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
@@ -44,6 +44,8 @@ dev = [
     "mypy>=1.0.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
+    "datamodel-code-generator[http]>=0.35.0",
+    "email-validator>=2.0.0",
 ]
 
 [project.urls]
@@ -55,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"]
@@ -63,7 +68,11 @@ extend-exclude = "/(generated|tasks)\\.py$"
 [tool.ruff]
 line-length = 100
 target-version = "py310"
-extend-exclude = ["src/adcp/types/generated.py", "src/adcp/types/tasks.py"]
+extend-exclude = [
+    "src/adcp/types/generated.py",
+    "src/adcp/types/tasks.py",
+    "src/adcp/types/generated_poc/",
+]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
@@ -86,3 +95,9 @@ ignore_errors = true
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "datamodel-code-generator>=0.35.0",
+    "pre-commit>=4.4.0",
+]

{adcp-1.6.1 → adcp-2.1.0}/src/adcp/__init__.py

@@ -48,122 +48,87 @@ from adcp.testing import (
     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 (
-    ActivateSignalError,
-    # Request/Response types
+    # Audience & Targeting
     ActivateSignalRequest,
     ActivateSignalResponse,
-    ActivateSignalSuccess,
-    ActivationKey,
-    AgentDeployment,
-    AgentDestination,
-    BothPreviewRender,
-    # Brand types
-    BrandManifest,
-    BrandManifestRef,
+    # Creative Operations
     BuildCreativeRequest,
     BuildCreativeResponse,
-    # Channel types
-    Channels,
-    CreateMediaBuyError,
+    # Media Buy Operations
     CreateMediaBuyRequest,
     CreateMediaBuyResponse,
-    CreateMediaBuySuccess,
-    # Creative types
-    CreativeAsset,
-    CreativeAssignment,
-    CreativeManifest,
-    CreativePolicy,
-    DaastAsset,
-    # Metrics types
-    DeliveryMetrics,
-    # Delivery types
-    DeliveryType,
-    Deployment,
-    # Deployment types
-    Destination,
+    # Common data types
     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,
+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__ = "1.6.1"
+__version__ = "2.1.0"
 
 __all__ = [
     # Client classes
@@ -175,6 +140,37 @@ __all__ = [
     "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",
@@ -210,113 +206,38 @@ __all__ = [
     "AdagentsValidationError",
     "AdagentsNotFoundError",
     "AdagentsTimeoutError",
-    # 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",
+    # 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-1.6.1 → adcp-2.1.0}/src/adcp/adagents.py

@@ -14,6 +14,7 @@ from urllib.parse import urlparse
 import httpx
 
 from adcp.exceptions import AdagentsNotFoundError, AdagentsTimeoutError, AdagentsValidationError
+from adcp.validation import ValidationError, validate_adagents
 
 
 def _normalize_domain(domain: str) -> str:
@@ -56,9 +57,7 @@ def _validate_publisher_domain(domain: str) -> str:
     suspicious_chars = ["\\", "@", "\n", "\r", "\t"]
     for char in suspicious_chars:
         if char in domain:
-            raise AdagentsValidationError(
-                f"Invalid character in publisher domain: {char!r}"
-            )
+            raise AdagentsValidationError(f"Invalid character in publisher domain: {char!r}")
 
     domain = domain.strip()
 
@@ -70,9 +69,7 @@ def _validate_publisher_domain(domain: str) -> str:
 
     # Check for spaces after stripping leading/trailing whitespace
     if " " in domain:
-        raise AdagentsValidationError(
-            "Invalid character in publisher domain: ' '"
-        )
+        raise AdagentsValidationError("Invalid character in publisher domain: ' '")
 
     # Remove protocol if present (common user error) - do this BEFORE checking for slashes
     if "://" in domain:
@@ -87,9 +84,7 @@ def _validate_publisher_domain(domain: str) -> str:
 
     # Final validation - must look like a domain
     if "." not in domain:
-        raise AdagentsValidationError(
-            f"Publisher domain must contain at least one dot: {domain!r}"
-        )
+        raise AdagentsValidationError(f"Publisher domain must contain at least one dot: {domain!r}")
 
     return domain
 
@@ -359,13 +354,17 @@ async def fetch_adagents(
             raise AdagentsValidationError("adagents.json must be a JSON object")
 
         if "authorized_agents" not in data:
-            raise AdagentsValidationError(
-                "adagents.json must have 'authorized_agents' field"
-            )
+            raise AdagentsValidationError("adagents.json must have 'authorized_agents' field")
 
         if not isinstance(data["authorized_agents"], list):
             raise AdagentsValidationError("'authorized_agents' must be an array")
 
+        # Validate mutual exclusivity constraints
+        try:
+            validate_adagents(data)
+        except ValidationError as e:
+            raise AdagentsValidationError(f"Invalid adagents.json structure: {e}") from e
+
         return data
 
     except httpx.TimeoutException as e: