adcp 2.11.1__tar.gz → 2.12.0__tar.gz

adcp-2.12.0/ADCP_VERSION

@@ -0,0 +1 @@
+2.5.0

adcp-2.12.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include ADCP_VERSION
+include README.md
+include LICENSE
+recursive-include src/adcp py.typed

{adcp-2.11.1/src/adcp.egg-info → adcp-2.12.0}/PKG-INFO

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

{adcp-2.11.1 → adcp-2.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adcp"
-version = "2.11.1"
+version = "2.12.0"
 description = "Official Python client for the Ad Context Protocol (AdCP)"
 authors = [
     {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
@@ -63,6 +63,13 @@ where = ["src"]
 [tool.setuptools.package-data]
 adcp = ["py.typed"]
 
+# Include ADCP_VERSION file in package
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.data-files]
+"." = ["ADCP_VERSION"]
+
 [tool.black]
 line-length = 100
 target-version = ["py310", "py311", "py312"]

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/__init__.py

@@ -105,7 +105,6 @@ from adcp.types import (
     MediaBuyStatus,
     Package,
     PackageRequest,
-    PackageStatus,
     PreviewCreativeRequest,
     PreviewCreativeResponse,
     PriceGuidance,
@@ -180,9 +179,31 @@ from adcp.validation import (
     validate_publisher_properties_item,
 )
 
-__version__ = "2.11.1"
+__version__ = "2.12.0"
+
+
+def get_adcp_version() -> str:
+    """
+    Get the target AdCP specification version this SDK is built for.
+
+    This version determines which AdCP schemas are used for type generation
+    and validation. The SDK is designed to work with this specific version
+    of the AdCP specification.
+
+    Returns:
+        AdCP specification version (e.g., "v1", "v2")
+    """
+    from pathlib import Path
+
+    # Read from ADCP_VERSION file at project root
+    version_file = Path(__file__).parent.parent.parent / "ADCP_VERSION"
+    if version_file.exists():
+        return version_file.read_text().strip()
+    return "v1"  # Fallback
 
 __all__ = [
+    # Version functions
+    "get_adcp_version",
     # Client classes
     "ADCPClient",
     "ADCPMultiAgentClient",
@@ -240,7 +261,6 @@ __all__ = [
     # Status enums (for control flow)
     "CreativeStatus",
     "MediaBuyStatus",
-    "PackageStatus",
     "PricingModel",
     # Pricing-related types
     "CpcPricingOption",

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/__main__.py

@@ -83,9 +83,10 @@ async def execute_tool(
 
 # Tool dispatch mapping - single source of truth for ADCP methods
 # Types are filled at runtime to avoid circular imports
-# Special case: list_tools takes no parameters (None means no request type)
+# 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),
@@ -162,7 +163,8 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
     method_name, request_type = TOOL_DISPATCH[tool_name]
     method = getattr(client, method_name)
 
-    # Special case: list_tools takes no parameters and returns list[str], not TaskResult
+    # Special case: list_tools and get_info take no parameters and return
+    # data directly, not TaskResult
     if tool_name == "list_tools":
         try:
             tools = await method()
@@ -178,7 +180,22 @@ async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str,
                 error=f"Failed to list tools: {e}",
             )
 
-    # Type guard - request_type should be initialized by this point for non-list_tools
+    if tool_name == "get_info":
+        try:
+            info = await method()
+            return TaskResult(
+                status=TaskStatus.COMPLETED,
+                data=info,
+                success=True,
+            )
+        except Exception as e:
+            return TaskResult(
+                status=TaskStatus.FAILED,
+                success=False,
+                error=f"Failed to get agent info: {e}",
+            )
+
+    # Type guard - request_type should be initialized by this point for methods that need it
     if request_type is None:
         return TaskResult(
             status=TaskStatus.FAILED,
@@ -323,6 +340,7 @@ def main() -> None:
     parser.add_argument("--list-agents", action="store_true", help="List saved agents")
     parser.add_argument("--remove-agent", metavar="ALIAS", help="Remove saved agent")
     parser.add_argument("--show-config", action="store_true", help="Show config file location")
+    parser.add_argument("--version", action="store_true", help="Show SDK and AdCP version")
 
     # Execution options
     parser.add_argument("--protocol", choices=["mcp", "a2a"], help="Force protocol type")
@@ -348,19 +366,29 @@ def main() -> None:
                 args.list_agents,
                 args.remove_agent,
                 args.show_config,
+                args.version,
             ]
         )
     ):
         parser.print_help()
         print("\nExamples:")
+        print("  adcp --version")
         print("  adcp --save-auth myagent https://agent.example.com mcp")
         print("  adcp --list-agents")
+        print("  adcp myagent get_info")
         print("  adcp myagent list_tools")
         print('  adcp myagent get_products \'{"brief":"TV ads"}\'')
         print("  adcp https://agent.example.com list_tools")
         sys.exit(0)
 
     # Handle configuration commands
+    if args.version:
+        from adcp import __version__, get_adcp_version
+
+        print(f"AdCP Python SDK: v{__version__}")
+        print(f"Target AdCP Spec: {get_adcp_version()}")
+        sys.exit(0)
+
     if args.save_auth:
         url = args.agent if args.agent else None
         protocol = args.tool if args.tool else None

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/client.py

@@ -781,6 +781,22 @@ class ADCPClient:
         """
         return await self.adapter.list_tools()
 
+    async def get_info(self) -> dict[str, Any]:
+        """
+        Get agent information including AdCP extension metadata.
+
+        Returns agent card information including:
+        - Agent name, description, version
+        - Protocol type (mcp or a2a)
+        - AdCP version (from extensions.adcp.adcp_version)
+        - Supported protocols (from extensions.adcp.protocols_supported)
+        - Available tools/skills
+
+        Returns:
+            Dictionary with agent metadata
+        """
+        return await self.adapter.get_agent_info()
+
     async def close(self) -> None:
         """Close the adapter and clean up resources."""
         if hasattr(self.adapter, "close"):

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/protocols/a2a.py

@@ -127,35 +127,51 @@ class A2AAdapter(ProtocolAdapter):
                     duration_ms=duration_ms,
                 )
 
-            # Parse A2A response format
+            # Parse A2A response format per canonical spec
             # A2A tasks have lifecycle: submitted, working, completed, failed, input-required
-            task_status = data.get("task", {}).get("status")
+            task_status = data.get("status")
 
-            if task_status in ("completed", "working"):
-                # Extract the result from the response message
+            if task_status == "completed":
+                # Extract the result from the artifacts array
                 result_data = self._extract_result(data)
 
+                # Check for task-level errors in the payload
+                errors = result_data.get("errors", []) if isinstance(result_data, dict) else []
+                has_errors = bool(errors)
+
                 return TaskResult[Any](
                     status=TaskStatus.COMPLETED,
                     data=result_data,
-                    success=True,
-                    metadata={"task_id": data.get("task", {}).get("id")},
+                    message=self._extract_text_part(data),
+                    success=not has_errors,
+                    metadata={
+                        "task_id": data.get("taskId"),
+                        "context_id": data.get("contextId"),
+                    },
                     debug_info=debug_info,
                 )
             elif task_status == "failed":
+                # Protocol-level failure - extract error message from TextPart
+                error_msg = self._extract_text_part(data) or "Task failed"
                 return TaskResult[Any](
                     status=TaskStatus.FAILED,
-                    error=data.get("message", {}).get("parts", [{}])[0].get("text", "Task failed"),
+                    error=error_msg,
                     success=False,
                     debug_info=debug_info,
                 )
             else:
-                # Handle other states (submitted, input-required)
+                # Handle all interim states (submitted, working, pending, input-required)
+                # These don't need to have structured AdCP content - only completed responses do
                 return TaskResult[Any](
                     status=TaskStatus.SUBMITTED,
-                    data=data,
+                    data=None,  # Interim responses may not have structured AdCP content
+                    message=self._extract_text_part(data),
                     success=True,
-                    metadata={"task_id": data.get("task", {}).get("id")},
+                    metadata={
+                        "task_id": data.get("taskId"),
+                        "context_id": data.get("contextId"),
+                        "status": task_status,  # submitted, working, pending, input-required, etc.
+                    },
                     debug_info=debug_info,
                 )
 
@@ -182,27 +198,79 @@ class A2AAdapter(ProtocolAdapter):
         return f"Execute tool: {tool_name}\nParameters: {json.dumps(params, indent=2)}"
 
     def _extract_result(self, response_data: dict[str, Any]) -> Any:
-        """Extract result data from A2A response."""
-        # Try to extract structured data from response
-        message = response_data.get("message", {})
-        parts = message.get("parts", [])
+        """
+        Extract result data from A2A response following canonical format.
+
+        Per A2A response spec:
+        - Responses MUST include at least one DataPart (kind: "data")
+        - When multiple DataParts exist in an artifact, the last one is authoritative
+        - When multiple artifacts exist, use the last one (most recent in streaming)
+        - DataParts contain structured AdCP payload
+        """
+        artifacts = response_data.get("artifacts", [])
+
+        if not artifacts:
+            logger.warning("A2A response missing required artifacts array")
+            return response_data
+
+        # Use last artifact (most recent in streaming scenarios)
+        # A2A spec doesn't define artifact.status, so we simply take the last one
+        target_artifact = artifacts[-1]
+
+        parts = target_artifact.get("parts", [])
 
         if not parts:
+            logger.warning("A2A response artifact has no parts")
+            return response_data
+
+        # Find all DataParts (kind: "data")
+        data_parts = [p for p in parts if p.get("kind") == "data"]
+
+        if not data_parts:
+            logger.warning("A2A response missing required DataPart (kind: 'data')")
             return response_data
 
-        # Return the first part's content
-        first_part = parts[0]
-        if first_part.get("type") == "text":
-            # Try to parse as JSON if it looks like structured data
-            text = first_part.get("text", "")
-            try:
-                import json
+        # Use last DataPart as authoritative (handles streaming scenarios within an artifact)
+        last_data_part = data_parts[-1]
+        data = last_data_part.get("data", {})
+
+        # Some A2A implementations (e.g., ADK) wrap the response in {"response": {...}}
+        # Unwrap it to get the actual AdCP payload if present
+        # ADK is inconsistent - some DataParts have the wrapper, others don't
+        if isinstance(data, dict) and "response" in data:
+            # If response is the only key, unwrap completely
+            if len(data) == 1:
+                return data["response"]
+            # If there are other keys alongside response, prefer the wrapped content
+            # but keep it flexible for edge cases
+            return data["response"]
+
+        return data
+
+    def _extract_text_part(self, response_data: dict[str, Any]) -> str | None:
+        """
+        Extract human-readable message from TextPart if present.
+
+        Uses last artifact (same logic as _extract_result).
+        """
+        artifacts = response_data.get("artifacts", [])
+
+        if not artifacts:
+            return None
+
+        # Use last artifact (most recent in streaming scenarios)
+        # A2A spec doesn't define artifact.status, so we simply take the last one
+        target_artifact = artifacts[-1]
 
-                return json.loads(text)
-            except (json.JSONDecodeError, ValueError):
-                return text
+        parts = target_artifact.get("parts", [])
 
-        return first_part
+        # Find TextPart (kind: "text")
+        for part in parts:
+            if part.get("kind") == "text":
+                text = part.get("text")
+                return str(text) if text is not None else None
+
+        return None
 
     # ========================================================================
     # ADCP Protocol Methods
@@ -329,3 +397,88 @@ class A2AAdapter(ProtocolAdapter):
                 agent_id=self.agent_config.id,
                 agent_uri=self.agent_config.agent_uri,
             ) from e
+
+    async def get_agent_info(self) -> dict[str, Any]:
+        """
+        Get agent information including AdCP extension metadata from A2A agent card.
+
+        Fetches the agent card from /.well-known/agent.json and extracts:
+        - Basic agent info (name, description, version)
+        - AdCP extension (extensions.adcp.adcp_version, extensions.adcp.protocols_supported)
+        - Available skills/tools
+
+        Returns:
+            Dictionary with agent metadata
+        """
+        client = await self._get_client()
+
+        headers = {"Content-Type": "application/json"}
+
+        if self.agent_config.auth_token:
+            if self.agent_config.auth_type == "bearer":
+                headers[self.agent_config.auth_header] = f"Bearer {self.agent_config.auth_token}"
+            else:
+                headers[self.agent_config.auth_header] = self.agent_config.auth_token
+
+        url = f"{self.agent_config.agent_uri}/.well-known/agent.json"
+
+        logger.debug(f"Fetching A2A agent info for {self.agent_config.id} from {url}")
+
+        try:
+            response = await client.get(url, headers=headers, timeout=self.agent_config.timeout)
+            response.raise_for_status()
+
+            agent_card = response.json()
+
+            # Extract basic info
+            info: dict[str, Any] = {
+                "name": agent_card.get("name"),
+                "description": agent_card.get("description"),
+                "version": agent_card.get("version"),
+                "protocol": "a2a",
+            }
+
+            # Extract skills/tools
+            skills = agent_card.get("skills", [])
+            tool_names = [skill.get("name") for skill in skills if skill.get("name")]
+            if tool_names:
+                info["tools"] = tool_names
+
+            # Extract AdCP extension metadata
+            extensions = agent_card.get("extensions", {})
+            adcp_ext = extensions.get("adcp", {})
+
+            if adcp_ext:
+                info["adcp_version"] = adcp_ext.get("adcp_version")
+                info["protocols_supported"] = adcp_ext.get("protocols_supported")
+
+            logger.info(f"Retrieved agent info for {self.agent_config.id}")
+            return info
+
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            if status_code in (401, 403):
+                raise ADCPAuthenticationError(
+                    f"Authentication failed: HTTP {status_code}",
+                    agent_id=self.agent_config.id,
+                    agent_uri=self.agent_config.agent_uri,
+                ) from e
+            else:
+                raise ADCPConnectionError(
+                    f"Failed to fetch agent card: HTTP {status_code}",
+                    agent_id=self.agent_config.id,
+                    agent_uri=self.agent_config.agent_uri,
+                ) from e
+        except httpx.TimeoutException as e:
+            raise ADCPTimeoutError(
+                f"Timeout fetching agent card: {e}",
+                agent_id=self.agent_config.id,
+                agent_uri=self.agent_config.agent_uri,
+                timeout=self.agent_config.timeout,
+            ) from e
+        except httpx.HTTPError as e:
+            raise ADCPConnectionError(
+                f"Failed to fetch agent card: {e}",
+                agent_id=self.agent_config.id,
+                agent_uri=self.agent_config.agent_uri,
+            ) from e

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/protocols/base.py

@@ -46,15 +46,18 @@ class ProtocolAdapter(ABC):
         Returns:
             Typed TaskResult
         """
-        # Handle failed results or missing data
+        # Handle failed results or interim states without data
+        # For A2A: interim states (submitted/working) have data=None but success=True
+        # For MCP: completed tasks always have data, missing data indicates failure
         if not raw_result.success or raw_result.data is None:
-            # Explicitly construct typed result to satisfy type checker
+            # If already marked as unsuccessful, preserve that
+            # If successful but no data (A2A interim state), preserve success=True
             return TaskResult[T](
                 status=raw_result.status,
                 data=None,
                 message=raw_result.message,
-                success=False,
-                error=raw_result.error or "No data returned from adapter",
+                success=raw_result.success,  # Preserve original success state
+                error=raw_result.error,  # Only use error if one was set
                 metadata=raw_result.metadata,
                 debug_info=raw_result.debug_info,
             )
@@ -161,6 +164,22 @@ class ProtocolAdapter(ABC):
         """
         pass
 
+    @abstractmethod
+    async def get_agent_info(self) -> dict[str, Any]:
+        """
+        Get agent information including AdCP extension metadata.
+
+        Returns agent card information including:
+        - Agent name, description, version
+        - AdCP version (from extensions.adcp.adcp_version)
+        - Supported protocols (from extensions.adcp.protocols_supported)
+        - Available tools/skills
+
+        Returns:
+            Dictionary with agent metadata including AdCP extension fields
+        """
+        pass
+
     @abstractmethod
     async def close(self) -> None:
         """

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/protocols/mcp.py

@@ -391,6 +391,50 @@ class MCPAdapter(ProtocolAdapter):
         result = await session.list_tools()
         return [tool.name for tool in result.tools]
 
+    async def get_agent_info(self) -> dict[str, Any]:
+        """
+        Get agent information including AdCP extension metadata from MCP server.
+
+        MCP servers may expose metadata through:
+        - Server capabilities exposed during initialization
+        - extensions.adcp in server info (if supported)
+        - Tool list
+
+        Returns:
+            Dictionary with agent metadata
+        """
+        session = await self._get_session()
+
+        # Extract basic MCP server info
+        info: dict[str, Any] = {
+            "name": getattr(session, "server_name", None),
+            "version": getattr(session, "server_version", None),
+            "protocol": "mcp",
+        }
+
+        # Get available tools
+        try:
+            tools_result = await session.list_tools()
+            tool_names = [tool.name for tool in tools_result.tools]
+            if tool_names:
+                info["tools"] = tool_names
+        except Exception as e:
+            logger.warning(f"Failed to list tools for {self.agent_config.id}: {e}")
+
+        # Try to extract AdCP extension metadata from server capabilities
+        # MCP servers may expose this in their initialization response
+        if hasattr(session, "_server_capabilities"):
+            capabilities = session._server_capabilities
+            if isinstance(capabilities, dict):
+                extensions = capabilities.get("extensions", {})
+                adcp_ext = extensions.get("adcp", {})
+                if adcp_ext:
+                    info["adcp_version"] = adcp_ext.get("adcp_version")
+                    info["protocols_supported"] = adcp_ext.get("protocols_supported")
+
+        logger.info(f"Retrieved agent info for {self.agent_config.id}")
+        return info
+
     async def close(self) -> None:
         """Close the MCP session and clean up resources."""
         await self._cleanup_failed_connection("during close")

{adcp-2.11.1 → adcp-2.12.0}/src/adcp/types/__init__.py

@@ -69,17 +69,13 @@ from adcp.types._generated import (
     DeliveryMeasurement,
     DeliveryMetrics,
     DeliveryType,
-    Details,
     DimensionUnit,
     Disclaimer,
-    Domain,
-    DomainBreakdown,
     DoohMetrics,
     Embedding,
     Error,
     FeedbackSource,
     FieldModel,
-    Filters,
     FlatRatePricingOption,
     Fonts,
     Format,
@@ -87,6 +83,7 @@ from adcp.types._generated import (
     FormatCardDetailed,
     FormatCategory,
     FormatId,
+    FormatIdParameter,
     FrequencyCap,
     FrequencyCapScope,
     GeoCountryAnyOfItem,
@@ -96,7 +93,6 @@ from adcp.types._generated import (
     GetProductsResponse,
     GetSignalsRequest,
     GetSignalsResponse,
-    HistoryItem,
     HtmlAsset,
     HttpMethod,
     Identifier,
@@ -112,7 +108,6 @@ from adcp.types._generated import (
     ListCreativesRequest,
     ListCreativesResponse,
     Logo,
-    MarkdownAsset,
     MarkdownFlavor,
     Measurement,
     MeasurementPeriod,
@@ -126,7 +121,6 @@ from adcp.types._generated import (
     Pacing,
     PackageRequest,
     Packages,
-    PackageStatus,
     Pagination,
     Parameters,
     Performance,
@@ -161,7 +155,6 @@ from adcp.types._generated import (
     PushNotificationConfig,
     QuartileData,
     QuerySummary,
-    Render,
     ReportingCapabilities,
     ReportingFrequency,
     ReportingPeriod,
@@ -184,11 +177,6 @@ from adcp.types._generated import (
     SyncCreativesResponse,
     Tags,
     TargetingOverlay,
-    Task,
-    TasksGetRequest,
-    TasksGetResponse,
-    TasksListRequest,
-    TasksListResponse,
     TaskType,
     TextAsset,
     Totals,
@@ -322,16 +310,12 @@ __all__ = [
     "CreateMediaBuyRequest",
     "CreateMediaBuyResponse",
     "DailyBreakdownItem",
-    "Details",
-    "Domain",
-    "DomainBreakdown",
     "GetMediaBuyDeliveryRequest",
     "GetMediaBuyDeliveryResponse",
     "GetProductsRequest",
     "GetProductsResponse",
     "GetSignalsRequest",
     "GetSignalsResponse",
-    "HistoryItem",
     "ListAuthorizedPropertiesRequest",
     "ListAuthorizedPropertiesResponse",
     "ListCreativeFormatsRequest",
@@ -351,11 +335,6 @@ __all__ = [
     "StatusSummary",
     "SyncCreativesRequest",
     "SyncCreativesResponse",
-    "Task",
-    "TasksGetRequest",
-    "TasksGetResponse",
-    "TasksListRequest",
-    "TasksListResponse",
     "Totals",
     "UpdateMediaBuyRequest",
     "UpdateMediaBuyResponse",
@@ -387,12 +366,12 @@ __all__ = [
     "Embedding",
     "Error",
     "FeedFormat",
-    "Filters",
     "Fonts",
     "Format",
     "FormatCard",
     "FormatCardDetailed",
     "FormatId",
+    "FormatIdParameter",
     "Identifier",
     "Input",
     "LandingPageRequirement",
@@ -419,7 +398,6 @@ __all__ = [
     "PromotedProducts",
     "Property",
     "QuartileData",
-    "Render",
     "Request",
     "Response",
     "Results",
@@ -462,7 +440,6 @@ __all__ = [
     "NotificationType",
     "PreviewOutputFormat",
     "Pacing",
-    "PackageStatus",
     "Pagination",
     "PricingModel",
     "PrimaryCountry",
@@ -503,7 +480,6 @@ __all__ = [
     "HtmlAsset",
     "ImageAsset",
     "JavascriptAsset",
-    "MarkdownAsset",
     "TextAsset",
     "UrlAsset",
     "VideoAsset",