adcp 2.19.0__tar.gz → 3.0.0__tar.gz

{adcp-2.19.0/src/adcp.egg-info → adcp-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 2.19.0
+Version: 3.0.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0

{adcp-2.19.0 → adcp-3.0.0}/pyproject.toml

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

adcp-3.0.0/src/adcp/ADCP_VERSION

@@ -0,0 +1 @@
+3.0.0-beta.1

{adcp-2.19.0 → adcp-3.0.0}/src/adcp/__init__.py

@@ -67,11 +67,10 @@ from adcp.types import (
     # Creative Operations
     BuildCreativeRequest,
     BuildCreativeResponse,
-    # Pricing options (all 9 types for product creation)
+    # Pricing options (all types for product creation)
     CpcPricingOption,
     CpcvPricingOption,
-    CpmAuctionPricingOption,
-    CpmFixedRatePricingOption,
+    CpmPricingOption,
     CppPricingOption,
     CpvPricingOption,
     # Media Buy Operations
@@ -121,8 +120,7 @@ from adcp.types import (
     SyncCreativesResponse,
     UpdateMediaBuyRequest,
     UpdateMediaBuyResponse,
-    VcpmAuctionPricingOption,
-    VcpmFixedRatePricingOption,
+    VcpmPricingOption,
     aliases,
 )
 
@@ -152,9 +150,7 @@ from adcp.types.aliases import (
     PreviewCreativeManifestRequest,
     PreviewCreativeStaticResponse,
     PropertyId,
-    PropertyIdActivationKey,
     PropertyTag,
-    PropertyTagActivationKey,
     ProvidePerformanceFeedbackErrorResponse,
     ProvidePerformanceFeedbackSuccessResponse,
     PublisherPropertiesAll,
@@ -197,7 +193,7 @@ from adcp.webhooks import (
     get_adcp_signed_headers_for_webhook,
 )
 
-__version__ = "2.19.0"
+__version__ = "3.0.0"
 
 
 def get_adcp_version() -> str:
@@ -291,14 +287,12 @@ __all__ = [
     # Pricing-related types
     "CpcPricingOption",
     "CpcvPricingOption",
-    "CpmAuctionPricingOption",
-    "CpmFixedRatePricingOption",
+    "CpmPricingOption",
     "CppPricingOption",
     "CpvPricingOption",
     "FlatRatePricingOption",
     "PriceGuidance",
-    "VcpmAuctionPricingOption",
-    "VcpmFixedRatePricingOption",
+    "VcpmPricingOption",
     # Configuration types
     "PushNotificationConfig",
     # Adagents validation
@@ -379,9 +373,7 @@ __all__ = [
     "PreviewCreativeStaticResponse",
     "PreviewCreativeInteractiveResponse",
     "PropertyId",
-    "PropertyIdActivationKey",
     "PropertyTag",
-    "PropertyTagActivationKey",
     "ProvidePerformanceFeedbackSuccessResponse",
     "ProvidePerformanceFeedbackErrorResponse",
     "PublisherPropertiesAll",

{adcp-2.19.0 → adcp-3.0.0}/src/adcp/__main__.py

@@ -153,26 +153,90 @@ async def execute_tool(
         print_result(result, json_output)
 
 
-# Tool dispatch mapping - single source of truth for ADCP methods
-# Types are filled at runtime to avoid circular imports
-# Special case: list_tools and get_info take no parameters (None means no request type)
-TOOL_DISPATCH: dict[str, tuple[str, type | None]] = {
-    "list_tools": ("list_tools", None),  # Protocol introspection - no request type
-    "get_info": ("get_info", None),  # Agent info - no request type
-    "get_products": ("get_products", None),
-    "list_creative_formats": ("list_creative_formats", None),
-    "preview_creative": ("preview_creative", None),
-    "build_creative": ("build_creative", None),
-    "sync_creatives": ("sync_creatives", None),
-    "list_creatives": ("list_creatives", None),
-    "create_media_buy": ("create_media_buy", None),
-    "update_media_buy": ("update_media_buy", None),
-    "get_media_buy_delivery": ("get_media_buy_delivery", None),
-    "list_authorized_properties": ("list_authorized_properties", None),
-    "get_signals": ("get_signals", None),
-    "activate_signal": ("activate_signal", None),
-    "provide_performance_feedback": ("provide_performance_feedback", None),
-}
+# Tool names that don't require request types (protocol introspection)
+_NO_REQUEST_TOOLS = frozenset({"list_tools", "get_info"})
+
+# Cached dispatch table (initialized on first use)
+_dispatch_table: dict[str, tuple[str, type | None]] | None = None
+
+
+def _get_dispatch_table() -> dict[str, tuple[str, type | None]]:
+    """Get the tool dispatch table, initializing types on first access.
+
+    This function fails fast with a clear error if types can't be imported.
+    """
+    global _dispatch_table
+
+    if _dispatch_table is not None:
+        return _dispatch_table
+
+    try:
+        from adcp.types import _generated as gen
+    except ImportError as e:
+        raise ImportError(
+            f"Failed to load ADCP types. This may indicate a code generation issue. "
+            f"Try running 'scripts/generate_types.py' to regenerate types. Error: {e}"
+        ) from e
+
+    _dispatch_table = {
+        # Protocol introspection (no request type needed)
+        "list_tools": ("list_tools", None),
+        "get_info": ("get_info", None),
+        # Core catalog
+        "get_products": ("get_products", gen.GetProductsRequest),
+        "list_creative_formats": ("list_creative_formats", gen.ListCreativeFormatsRequest),
+        "preview_creative": ("preview_creative", gen.PreviewCreativeRequest),
+        "build_creative": ("build_creative", gen.BuildCreativeRequest),
+        "sync_creatives": ("sync_creatives", gen.SyncCreativesRequest),
+        "list_creatives": ("list_creatives", gen.ListCreativesRequest),
+        # Media buy
+        "create_media_buy": ("create_media_buy", gen.CreateMediaBuyRequest),
+        "update_media_buy": ("update_media_buy", gen.UpdateMediaBuyRequest),
+        "get_media_buy_delivery": ("get_media_buy_delivery", gen.GetMediaBuyDeliveryRequest),
+        "list_authorized_properties": (
+            "list_authorized_properties",
+            gen.ListAuthorizedPropertiesRequest,
+        ),
+        # Signals
+        "get_signals": ("get_signals", gen.GetSignalsRequest),
+        "activate_signal": ("activate_signal", gen.ActivateSignalRequest),
+        "provide_performance_feedback": (
+            "provide_performance_feedback",
+            gen.ProvidePerformanceFeedbackRequest,
+        ),
+        # V3 Protocol Discovery
+        "get_adcp_capabilities": ("get_adcp_capabilities", gen.GetAdcpCapabilitiesRequest),
+        # V3 Content Standards
+        "create_content_standards": (
+            "create_content_standards",
+            gen.CreateContentStandardsRequest,
+        ),
+        "get_content_standards": ("get_content_standards", gen.GetContentStandardsRequest),
+        "list_content_standards": ("list_content_standards", gen.ListContentStandardsRequest),
+        "update_content_standards": (
+            "update_content_standards",
+            gen.UpdateContentStandardsRequest,
+        ),
+        "calibrate_content": ("calibrate_content", gen.CalibrateContentRequest),
+        "validate_content_delivery": (
+            "validate_content_delivery",
+            gen.ValidateContentDeliveryRequest,
+        ),
+        "get_media_buy_artifacts": ("get_media_buy_artifacts", gen.GetMediaBuyArtifactsRequest),
+        # V3 Sponsored Intelligence
+        "si_get_offering": ("si_get_offering", gen.SiGetOfferingRequest),
+        "si_initiate_session": ("si_initiate_session", gen.SiInitiateSessionRequest),
+        "si_send_message": ("si_send_message", gen.SiSendMessageRequest),
+        "si_terminate_session": ("si_terminate_session", gen.SiTerminateSessionRequest),
+        # V3 Governance (Property Lists)
+        "create_property_list": ("create_property_list", gen.CreatePropertyListRequest),
+        "get_property_list": ("get_property_list", gen.GetPropertyListRequest),
+        "list_property_lists": ("list_property_lists", gen.ListPropertyListsRequest),
+        "update_property_list": ("update_property_list", gen.UpdatePropertyListRequest),
+        "delete_property_list": ("delete_property_list", gen.DeletePropertyListRequest),
+    }
+
+    return _dispatch_table
 
 
 async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str, Any]) -> Any:
@@ -191,40 +255,14 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
     """
     from pydantic import ValidationError
 
-    from adcp.types import _generated as gen
     from adcp.types.core import TaskResult, TaskStatus
 
-    # Lazy initialization of request types (avoid circular imports)
-    if TOOL_DISPATCH["get_products"][1] is None:
-        TOOL_DISPATCH["get_products"] = ("get_products", gen.GetProductsRequest)
-        TOOL_DISPATCH["list_creative_formats"] = (
-            "list_creative_formats",
-            gen.ListCreativeFormatsRequest,
-        )
-        TOOL_DISPATCH["preview_creative"] = ("preview_creative", gen.PreviewCreativeRequest)
-        TOOL_DISPATCH["build_creative"] = ("build_creative", gen.BuildCreativeRequest)
-        TOOL_DISPATCH["sync_creatives"] = ("sync_creatives", gen.SyncCreativesRequest)
-        TOOL_DISPATCH["list_creatives"] = ("list_creatives", gen.ListCreativesRequest)
-        TOOL_DISPATCH["create_media_buy"] = ("create_media_buy", gen.CreateMediaBuyRequest)
-        TOOL_DISPATCH["update_media_buy"] = ("update_media_buy", gen.UpdateMediaBuyRequest)
-        TOOL_DISPATCH["get_media_buy_delivery"] = (
-            "get_media_buy_delivery",
-            gen.GetMediaBuyDeliveryRequest,
-        )
-        TOOL_DISPATCH["list_authorized_properties"] = (
-            "list_authorized_properties",
-            gen.ListAuthorizedPropertiesRequest,
-        )
-        TOOL_DISPATCH["get_signals"] = ("get_signals", gen.GetSignalsRequest)
-        TOOL_DISPATCH["activate_signal"] = ("activate_signal", gen.ActivateSignalRequest)
-        TOOL_DISPATCH["provide_performance_feedback"] = (
-            "provide_performance_feedback",
-            gen.ProvidePerformanceFeedbackRequest,
-        )
+    # Get dispatch table (initializes types on first access, fails fast on import errors)
+    dispatch_table = _get_dispatch_table()
 
     # Check if tool exists
-    if tool_name not in TOOL_DISPATCH:
-        available = ", ".join(sorted(TOOL_DISPATCH.keys()))
+    if tool_name not in dispatch_table:
+        available = ", ".join(sorted(dispatch_table.keys()))
         return TaskResult(
             status=TaskStatus.FAILED,
             success=False,
@@ -232,7 +270,7 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
         )
 
     # Get method and request type
-    method_name, request_type = TOOL_DISPATCH[tool_name]
+    method_name, request_type = dispatch_table[tool_name]
     method = getattr(client, method_name)
 
     # Special case: list_tools and get_info take no parameters and return
@@ -451,6 +489,11 @@ def main() -> None:
         print("  adcp myagent list_tools")
         print('  adcp myagent get_products \'{"brief":"TV ads"}\'')
         print("  adcp https://agent.example.com list_tools")
+        print("\nV3 Protocol Examples:")
+        print("  adcp myagent get_adcp_capabilities")
+        print("  adcp cs-agent calibrate_content '{\"content_standards_id\":\"cs-123\"}'")
+        print("  adcp si-agent si_get_offering")
+        print("  adcp gov-agent list_property_lists")
         sys.exit(0)
 
     # Handle configuration commands

{adcp-2.19.0 → adcp-3.0.0}/src/adcp/adagents.py

@@ -280,6 +280,10 @@ def verify_agent_authorization(
     return False
 
 
+# Maximum number of authoritative_location redirects to follow
+MAX_REDIRECT_DEPTH = 5
+
+
 async def fetch_adagents(
     publisher_domain: str,
     timeout: float = 10.0,
@@ -288,6 +292,11 @@ async def fetch_adagents(
 ) -> dict[str, Any]:
     """Fetch and parse adagents.json from publisher domain.
 
+    Follows authoritative_location redirects per the AdCP specification. When a
+    publisher's adagents.json contains an authoritative_location field instead of
+    authorized_agents, this function fetches the referenced URL to get the actual
+    authorization data.
+
     Args:
         publisher_domain: Domain hosting the adagents.json file
         timeout: Request timeout in seconds
@@ -297,11 +306,12 @@ async def fetch_adagents(
             If None, a new client is created for this request.
 
     Returns:
-        Parsed adagents.json data
+        Parsed adagents.json data (resolved from authoritative_location if present)
 
     Raises:
         AdagentsNotFoundError: If adagents.json not found (404)
-        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsValidationError: If JSON is invalid, malformed, or redirects
+            exceed maximum depth or form a loop
         AdagentsTimeoutError: If request times out
 
     Notes:
@@ -311,13 +321,67 @@ async def fetch_adagents(
     # Validate and normalize domain for security
     publisher_domain = _validate_publisher_domain(publisher_domain)
 
-    # Construct URL
+    # Construct initial URL
     url = f"https://{publisher_domain}/.well-known/adagents.json"
 
+    # Track visited URLs to detect loops
+    visited_urls: set[str] = set()
+
+    for depth in range(MAX_REDIRECT_DEPTH + 1):
+        # Check for redirect loop
+        if url in visited_urls:
+            raise AdagentsValidationError(
+                f"Circular redirect detected: {url} already visited"
+            )
+        visited_urls.add(url)
+
+        data = await _fetch_adagents_url(url, timeout, user_agent, client)
+
+        # Check if this is a redirect. A response with authoritative_location but no
+        # authorized_agents indicates a redirect. If both are present, authorized_agents
+        # takes precedence (response is treated as final).
+        if "authoritative_location" in data and "authorized_agents" not in data:
+            authoritative_url = data["authoritative_location"]
+
+            # Validate HTTPS requirement
+            if not isinstance(authoritative_url, str) or not authoritative_url.startswith(
+                "https://"
+            ):
+                raise AdagentsValidationError(
+                    f"authoritative_location must be an HTTPS URL, got: {authoritative_url!r}"
+                )
+
+            # Check if we've exceeded max depth
+            if depth >= MAX_REDIRECT_DEPTH:
+                raise AdagentsValidationError(
+                    f"Maximum redirect depth ({MAX_REDIRECT_DEPTH}) exceeded"
+                )
+
+            # Follow the redirect
+            url = authoritative_url
+            continue
+
+        # We have the final data with authorized_agents (or both fields present,
+        # in which case authorized_agents takes precedence)
+        return data
+
+    # Unreachable: loop always exits via return or raise above
+    raise AssertionError("Unreachable")  # pragma: no cover
+
+
+async def _fetch_adagents_url(
+    url: str,
+    timeout: float,
+    user_agent: str,
+    client: httpx.AsyncClient | None,
+) -> dict[str, Any]:
+    """Fetch and parse adagents.json from a specific URL.
+
+    This is the core fetch logic, separated to support redirect following.
+    """
     try:
         # Use provided client or create a new one
         if client is not None:
-            # Reuse provided client (connection pooling)
             response = await client.get(
                 url,
                 headers={"User-Agent": user_agent},
@@ -325,7 +389,6 @@ async def fetch_adagents(
                 follow_redirects=True,
             )
         else:
-            # Create new client for single request
             async with httpx.AsyncClient() as new_client:
                 response = await new_client.get(
                     url,
@@ -334,9 +397,11 @@ async def fetch_adagents(
                     follow_redirects=True,
                 )
 
-        # Process response (same for both paths)
+        # Process response
         if response.status_code == 404:
-            raise AdagentsNotFoundError(publisher_domain)
+            # Extract domain from URL for error message
+            parsed = urlparse(url)
+            raise AdagentsNotFoundError(parsed.netloc)
 
         if response.status_code != 200:
             raise AdagentsValidationError(
@@ -353,22 +418,29 @@ async def fetch_adagents(
         if not isinstance(data, dict):
             raise AdagentsValidationError("adagents.json must be a JSON object")
 
-        if "authorized_agents" not in data:
-            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
+        # If this has authorized_agents, validate it
+        if "authorized_agents" in data:
+            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
+        elif "authoritative_location" not in data:
+            # Neither authorized_agents nor authoritative_location
+            raise AdagentsValidationError(
+                "adagents.json must have either 'authorized_agents' or 'authoritative_location'"
+            )
 
         return data
 
     except httpx.TimeoutException as e:
-        raise AdagentsTimeoutError(publisher_domain, timeout) from e
+        parsed = urlparse(url)
+        raise AdagentsTimeoutError(parsed.netloc, timeout) from e
     except httpx.RequestError as e:
         raise AdagentsValidationError(f"Failed to fetch adagents.json: {e}") from e