adcp 0.1.2__tar.gz

adcp-0.1.2/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2025 AdCP Community
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

adcp-0.1.2/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: adcp
+Version: 0.1.2
+Summary: Official Python client for the Ad Context Protocol (AdCP)
+Author-email: AdCP Community <maintainers@adcontextprotocol.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/adcontextprotocol/adcp-client-python
+Project-URL: Documentation, https://docs.adcontextprotocol.org
+Project-URL: Repository, https://github.com/adcontextprotocol/adcp-client-python
+Project-URL: Issues, https://github.com/adcontextprotocol/adcp-client-python/issues
+Keywords: adcp,mcp,a2a,protocol,advertising
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.5.0
+Requires-Dist: a2a-sdk>=0.3.0
+Requires-Dist: mcp>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+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"
+Dynamic: license-file
+
+# adcp - Python Client for Ad Context Protocol
+
+[![PyPI version](https://badge.fury.io/py/adcp.svg)](https://badge.fury.io/py/adcp)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Official Python client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
+
+## The Core Concept
+
+AdCP operations are **distributed and asynchronous by default**. An agent might:
+- Complete your request **immediately** (synchronous)
+- Need time to process and **send results via webhook** (asynchronous)
+- Ask for **clarifications** before proceeding
+- Send periodic **status updates** as work progresses
+
+**Your code stays the same.** You write handlers once, and they work for both sync completions and webhook deliveries.
+
+## Installation
+
+```bash
+pip install adcp
+```
+
+## Quick Start: Distributed Operations
+
+```python
+from adcp import ADCPMultiAgentClient
+from adcp.types import AgentConfig
+
+# Configure agents and handlers
+client = ADCPMultiAgentClient(
+    agents=[
+        AgentConfig(
+            id="agent_x",
+            agent_uri="https://agent-x.com",
+            protocol="a2a"
+        ),
+        AgentConfig(
+            id="agent_y",
+            agent_uri="https://agent-y.com/mcp/",
+            protocol="mcp"
+        )
+    ],
+    # Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
+    webhook_url_template="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}",
+
+    # Activity callback - fires for ALL events
+    on_activity=lambda activity: print(f"[{activity.type}] {activity.task_type}"),
+
+    # Status change handlers
+    handlers={
+        "on_get_products_status_change": lambda response, metadata: (
+            db.save_products(metadata.operation_id, response.products)
+            if metadata.status == "completed" else None
+        )
+    }
+)
+
+# Execute operation - library handles operation IDs, webhook URLs, context management
+agent = client.agent("agent_x")
+result = await agent.get_products(brief="Coffee brands")
+
+# Check result
+if result.status == "completed":
+    # Agent completed synchronously!
+    print(f"✅ Sync completion: {len(result.data.products)} products")
+
+if result.status == "submitted":
+    # Agent will send webhook when complete
+    print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+```
+
+## Features
+
+### Full Protocol Support
+- **A2A Protocol**: Native support for Agent-to-Agent protocol
+- **MCP Protocol**: Native support for Model Context Protocol
+- **Auto-detection**: Automatically detect which protocol an agent uses
+
+### Type Safety
+Full type hints with Pydantic validation:
+
+```python
+result = await agent.get_products(brief="Coffee brands")
+# result: TaskResult[GetProductsResponse]
+
+if result.success:
+    for product in result.data.products:
+        print(product.name, product.price)  # Full IDE autocomplete!
+```
+
+### Multi-Agent Operations
+Execute across multiple agents simultaneously:
+
+```python
+# Parallel execution across all agents
+results = await client.get_products(brief="Coffee brands")
+
+for result in results:
+    if result.status == "completed":
+        print(f"Sync: {len(result.data.products)} products")
+    elif result.status == "submitted":
+        print(f"Async: webhook to {result.submitted.webhook_url}")
+```
+
+### Webhook Handling
+Single endpoint handles all webhooks:
+
+```python
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.post("/webhook/{task_type}/{agent_id}/{operation_id}")
+async def webhook(task_type: str, agent_id: str, operation_id: str, request: Request):
+    payload = await request.json()
+    payload["task_type"] = task_type
+    payload["operation_id"] = operation_id
+
+    # Route to agent client - handlers fire automatically
+    agent = client.agent(agent_id)
+    await agent.handle_webhook(
+        payload,
+        request.headers.get("x-adcp-signature")
+    )
+
+    return {"received": True}
+```
+
+### Security
+Webhook signature verification built-in:
+
+```python
+client = ADCPMultiAgentClient(
+    agents=agents,
+    webhook_secret=os.getenv("WEBHOOK_SECRET")
+)
+# Signatures verified automatically on handle_webhook()
+```
+
+## Available Tools
+
+All AdCP tools with full type safety:
+
+**Media Buy Lifecycle:**
+- `get_products()` - Discover advertising products
+- `list_creative_formats()` - Get supported creative formats
+- `create_media_buy()` - Create new media buy
+- `update_media_buy()` - Update existing media buy
+- `sync_creatives()` - Upload/sync creative assets
+- `list_creatives()` - List creative assets
+- `get_media_buy_delivery()` - Get delivery performance
+
+**Audience & Targeting:**
+- `list_authorized_properties()` - Get authorized properties
+- `get_signals()` - Get audience signals
+- `activate_signal()` - Activate audience signals
+- `provide_performance_feedback()` - Send performance feedback
+
+## Property Discovery (AdCP v2.2.0)
+
+Build agent registries by discovering properties agents can sell:
+
+```python
+from adcp.discovery import PropertyCrawler, get_property_index
+
+# Crawl agents to discover properties
+crawler = PropertyCrawler()
+await crawler.crawl_agents([
+    {"agent_url": "https://agent-x.com", "protocol": "a2a"},
+    {"agent_url": "https://agent-y.com/mcp/", "protocol": "mcp"}
+])
+
+index = get_property_index()
+
+# Query 1: Who can sell this property?
+matches = index.find_agents_for_property("domain", "cnn.com")
+
+# Query 2: What can this agent sell?
+auth = index.get_agent_authorizations("https://agent-x.com")
+
+# Query 3: Find by tags
+premium = index.find_agents_by_property_tags(["premium", "ctv"])
+```
+
+## Environment Configuration
+
+```bash
+# .env
+WEBHOOK_URL_TEMPLATE="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
+WEBHOOK_SECRET="your-webhook-secret"
+
+ADCP_AGENTS='[
+  {
+    "id": "agent_x",
+    "agent_uri": "https://agent-x.com",
+    "protocol": "a2a",
+    "auth_token_env": "AGENT_X_TOKEN"
+  }
+]'
+AGENT_X_TOKEN="actual-token-here"
+```
+
+```python
+# Auto-discover from environment
+client = ADCPMultiAgentClient.from_env()
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Format code
+black src/ tests/
+ruff check src/ tests/
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org)
+- **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp-client-python/issues)
+- **Protocol Spec**: [AdCP Specification](https://github.com/adcontextprotocol/adcp)

adcp-0.1.2/README.md

@@ -0,0 +1,239 @@
+# adcp - Python Client for Ad Context Protocol
+
+[![PyPI version](https://badge.fury.io/py/adcp.svg)](https://badge.fury.io/py/adcp)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Official Python client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
+
+## The Core Concept
+
+AdCP operations are **distributed and asynchronous by default**. An agent might:
+- Complete your request **immediately** (synchronous)
+- Need time to process and **send results via webhook** (asynchronous)
+- Ask for **clarifications** before proceeding
+- Send periodic **status updates** as work progresses
+
+**Your code stays the same.** You write handlers once, and they work for both sync completions and webhook deliveries.
+
+## Installation
+
+```bash
+pip install adcp
+```
+
+## Quick Start: Distributed Operations
+
+```python
+from adcp import ADCPMultiAgentClient
+from adcp.types import AgentConfig
+
+# Configure agents and handlers
+client = ADCPMultiAgentClient(
+    agents=[
+        AgentConfig(
+            id="agent_x",
+            agent_uri="https://agent-x.com",
+            protocol="a2a"
+        ),
+        AgentConfig(
+            id="agent_y",
+            agent_uri="https://agent-y.com/mcp/",
+            protocol="mcp"
+        )
+    ],
+    # Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
+    webhook_url_template="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}",
+
+    # Activity callback - fires for ALL events
+    on_activity=lambda activity: print(f"[{activity.type}] {activity.task_type}"),
+
+    # Status change handlers
+    handlers={
+        "on_get_products_status_change": lambda response, metadata: (
+            db.save_products(metadata.operation_id, response.products)
+            if metadata.status == "completed" else None
+        )
+    }
+)
+
+# Execute operation - library handles operation IDs, webhook URLs, context management
+agent = client.agent("agent_x")
+result = await agent.get_products(brief="Coffee brands")
+
+# Check result
+if result.status == "completed":
+    # Agent completed synchronously!
+    print(f"✅ Sync completion: {len(result.data.products)} products")
+
+if result.status == "submitted":
+    # Agent will send webhook when complete
+    print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+```
+
+## Features
+
+### Full Protocol Support
+- **A2A Protocol**: Native support for Agent-to-Agent protocol
+- **MCP Protocol**: Native support for Model Context Protocol
+- **Auto-detection**: Automatically detect which protocol an agent uses
+
+### Type Safety
+Full type hints with Pydantic validation:
+
+```python
+result = await agent.get_products(brief="Coffee brands")
+# result: TaskResult[GetProductsResponse]
+
+if result.success:
+    for product in result.data.products:
+        print(product.name, product.price)  # Full IDE autocomplete!
+```
+
+### Multi-Agent Operations
+Execute across multiple agents simultaneously:
+
+```python
+# Parallel execution across all agents
+results = await client.get_products(brief="Coffee brands")
+
+for result in results:
+    if result.status == "completed":
+        print(f"Sync: {len(result.data.products)} products")
+    elif result.status == "submitted":
+        print(f"Async: webhook to {result.submitted.webhook_url}")
+```
+
+### Webhook Handling
+Single endpoint handles all webhooks:
+
+```python
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.post("/webhook/{task_type}/{agent_id}/{operation_id}")
+async def webhook(task_type: str, agent_id: str, operation_id: str, request: Request):
+    payload = await request.json()
+    payload["task_type"] = task_type
+    payload["operation_id"] = operation_id
+
+    # Route to agent client - handlers fire automatically
+    agent = client.agent(agent_id)
+    await agent.handle_webhook(
+        payload,
+        request.headers.get("x-adcp-signature")
+    )
+
+    return {"received": True}
+```
+
+### Security
+Webhook signature verification built-in:
+
+```python
+client = ADCPMultiAgentClient(
+    agents=agents,
+    webhook_secret=os.getenv("WEBHOOK_SECRET")
+)
+# Signatures verified automatically on handle_webhook()
+```
+
+## Available Tools
+
+All AdCP tools with full type safety:
+
+**Media Buy Lifecycle:**
+- `get_products()` - Discover advertising products
+- `list_creative_formats()` - Get supported creative formats
+- `create_media_buy()` - Create new media buy
+- `update_media_buy()` - Update existing media buy
+- `sync_creatives()` - Upload/sync creative assets
+- `list_creatives()` - List creative assets
+- `get_media_buy_delivery()` - Get delivery performance
+
+**Audience & Targeting:**
+- `list_authorized_properties()` - Get authorized properties
+- `get_signals()` - Get audience signals
+- `activate_signal()` - Activate audience signals
+- `provide_performance_feedback()` - Send performance feedback
+
+## Property Discovery (AdCP v2.2.0)
+
+Build agent registries by discovering properties agents can sell:
+
+```python
+from adcp.discovery import PropertyCrawler, get_property_index
+
+# Crawl agents to discover properties
+crawler = PropertyCrawler()
+await crawler.crawl_agents([
+    {"agent_url": "https://agent-x.com", "protocol": "a2a"},
+    {"agent_url": "https://agent-y.com/mcp/", "protocol": "mcp"}
+])
+
+index = get_property_index()
+
+# Query 1: Who can sell this property?
+matches = index.find_agents_for_property("domain", "cnn.com")
+
+# Query 2: What can this agent sell?
+auth = index.get_agent_authorizations("https://agent-x.com")
+
+# Query 3: Find by tags
+premium = index.find_agents_by_property_tags(["premium", "ctv"])
+```
+
+## Environment Configuration
+
+```bash
+# .env
+WEBHOOK_URL_TEMPLATE="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
+WEBHOOK_SECRET="your-webhook-secret"
+
+ADCP_AGENTS='[
+  {
+    "id": "agent_x",
+    "agent_uri": "https://agent-x.com",
+    "protocol": "a2a",
+    "auth_token_env": "AGENT_X_TOKEN"
+  }
+]'
+AGENT_X_TOKEN="actual-token-here"
+```
+
+```python
+# Auto-discover from environment
+client = ADCPMultiAgentClient.from_env()
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Format code
+black src/ tests/
+ruff check src/ tests/
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org)
+- **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp-client-python/issues)
+- **Protocol Spec**: [AdCP Specification](https://github.com/adcontextprotocol/adcp)

adcp-0.1.2/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adcp"
+version = "0.1.2"
+description = "Official Python client for the Ad Context Protocol (AdCP)"
+authors = [
+    {name = "AdCP Community", email = "maintainers@adcontextprotocol.org"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+keywords = ["adcp", "mcp", "a2a", "protocol", "advertising"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+    "typing-extensions>=4.5.0",
+    "a2a-sdk>=0.3.0",
+    "mcp>=0.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/adcontextprotocol/adcp-client-python"
+Documentation = "https://docs.adcontextprotocol.org"
+Repository = "https://github.com/adcontextprotocol/adcp-client-python"
+Issues = "https://github.com/adcontextprotocol/adcp-client-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disable_error_code = ["import-not-found", "no-untyped-def", "var-annotated", "operator"]
+
+[[tool.mypy.overrides]]
+module = "tests.integration.*"
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

adcp-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adcp-0.1.2/src/adcp/__init__.py

@@ -0,0 +1,18 @@
+"""
+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.client import ADCPClient, ADCPMultiAgentClient
+from adcp.types.core import AgentConfig, TaskResult, WebhookMetadata
+
+__version__ = "0.1.2"
+__all__ = [
+    "ADCPClient",
+    "ADCPMultiAgentClient",
+    "AgentConfig",
+    "TaskResult",
+    "WebhookMetadata",
+]