synchronity-sdk 0.1.0__tar.gz

synchronity_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: synchronity-sdk
+Version: 0.1.0
+Summary: Python SDK for the AgentMesh agentic commerce infrastructure
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# Synchronity Python SDK
+
+Python SDK for the [Synchronity](https://agentmesh.ai) agentic commerce infrastructure — makes any e-commerce site transactable by autonomous AI agents via authenticated REST APIs.
+
+## Installation
+
+```bash
+pip install agentmesh-sdk
+```
+
+Or with dev dependencies for testing:
+
+```bash
+pip install "agentmesh-sdk[dev]"
+```
+
+## Quickstart
+
+```python
+import asyncio
+from agentmesh import SynchronityClient, SynchronityConfig
+
+async def main():
+    config = SynchronityConfig(agent_token="your-agent-token")
+
+    async with SynchronityClient(config) as client:
+        # Search products on a site
+        results = await client.products.search("site_abc123", q="laptop", in_stock=True)
+        print(results["products"])
+
+        # Create a cart and add an item
+        cart = await client.cart.create("site_abc123", currency="USD")
+        cart = await client.cart.add_item("site_abc123", cart.cart_id, "prod_42", quantity=1)
+
+        # Apply a coupon
+        cart = await client.cart.apply_coupon("site_abc123", cart.cart_id, "SAVE10")
+
+        # Execute checkout
+        from agentmesh import ShippingAddressParams
+        order = await client.checkout.execute(
+            site_id="site_abc123",
+            cart_id=cart.cart_id,
+            buyer_delegation_token="buyer-token-from-auth-flow",
+            shipping_address=ShippingAddressParams(
+                name="Jane Smith",
+                line1="123 Main St",
+                city="San Francisco",
+                state="CA",
+                postal_code="94102",
+                country="US",
+            ),
+        )
+        print(order.order_id, order.status)
+
+asyncio.run(main())
+```
+
+## Tools for LLM Frameworks
+
+The SDK ships ready-to-use tool definitions for Anthropic, OpenAI, and LangChain.
+
+### Anthropic
+
+```python
+from agentmesh.tools import anthropic_tools, ToolExecutor
+from agentmesh import SynchronityClient, SynchronityConfig
+import anthropic
+
+client = SynchronityClient(SynchronityConfig(agent_token="your-token"))
+executor = ToolExecutor(client)
+
+anthropic_client = anthropic.Anthropic()
+response = anthropic_client.messages.create(
+    model="claude-opus-4-5",
+    max_tokens=1024,
+    tools=anthropic_tools,
+    messages=[{"role": "user", "content": "Find me a red laptop under $1000 on site site_abc123"}],
+)
+
+# Execute tool calls
+import asyncio
+for block in response.content:
+    if block.type == "tool_use":
+        result = asyncio.run(executor.execute(block.name, block.input))
+        print(result)
+```
+
+### OpenAI
+
+```python
+from agentmesh.tools import openai_tools, ToolExecutor
+from openai import OpenAI
+
+openai_client = OpenAI()
+response = openai_client.chat.completions.create(
+    model="gpt-4o",
+    tools=openai_tools,
+    messages=[{"role": "user", "content": "Search for laptops on site_abc123"}],
+)
+```
+
+### LangChain
+
+```python
+from agentmesh.tools import langchain_tools
+# langchain_tools is a list of dicts with name, description, and schema
+```
+
+## Available Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `search_products` | Search products on a site with filters |
+| `get_product` | Get full product details by ID |
+| `compare_products` | Compare products across multiple sites |
+| `create_cart` | Create a new shopping cart |
+| `add_to_cart` | Add a product/variant to a cart |
+| `remove_from_cart` | Remove a line item from a cart |
+| `apply_coupon` | Apply a discount code to a cart |
+| `get_cart` | Get current cart contents |
+| `execute_checkout` | Execute checkout and return a confirmed order |
+| `get_order` | Get order details by ID |
+| `list_orders` | List orders with optional status filter |
+
+## Configuration
+
+```python
+from agentmesh import SynchronityConfig
+
+config = SynchronityConfig(
+    agent_token="your-agent-token",   # required
+    base_url="https://gateway.agentmesh.ai",  # default
+    timeout=30.0,    # seconds
+    retries=3,       # auto-retry on 429 and 5xx
+    retry_delay=1.0, # base delay for exponential backoff
+)
+```
+
+## Error Handling
+
+```python
+from agentmesh.errors import (
+    AuthenticationError,   # 401
+    AuthorizationError,    # 403
+    NotFoundError,         # 404 / 410
+    ValidationError,       # 400
+    RateLimitError,        # 429 — has .retry_after attribute
+    ConnectorError,        # 422
+    NetworkError,          # network failures
+    TimeoutError,          # request timeout
+    SynchronityError,        # base class
+)
+
+try:
+    product = await client.products.get_by_id("site_abc", "prod_999")
+except NotFoundError as e:
+    print(f"Product not found: {e.code}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

synchronity_sdk-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Synchronity Python SDK
+
+Python SDK for the [Synchronity](https://agentmesh.ai) agentic commerce infrastructure — makes any e-commerce site transactable by autonomous AI agents via authenticated REST APIs.
+
+## Installation
+
+```bash
+pip install agentmesh-sdk
+```
+
+Or with dev dependencies for testing:
+
+```bash
+pip install "agentmesh-sdk[dev]"
+```
+
+## Quickstart
+
+```python
+import asyncio
+from agentmesh import SynchronityClient, SynchronityConfig
+
+async def main():
+    config = SynchronityConfig(agent_token="your-agent-token")
+
+    async with SynchronityClient(config) as client:
+        # Search products on a site
+        results = await client.products.search("site_abc123", q="laptop", in_stock=True)
+        print(results["products"])
+
+        # Create a cart and add an item
+        cart = await client.cart.create("site_abc123", currency="USD")
+        cart = await client.cart.add_item("site_abc123", cart.cart_id, "prod_42", quantity=1)
+
+        # Apply a coupon
+        cart = await client.cart.apply_coupon("site_abc123", cart.cart_id, "SAVE10")
+
+        # Execute checkout
+        from agentmesh import ShippingAddressParams
+        order = await client.checkout.execute(
+            site_id="site_abc123",
+            cart_id=cart.cart_id,
+            buyer_delegation_token="buyer-token-from-auth-flow",
+            shipping_address=ShippingAddressParams(
+                name="Jane Smith",
+                line1="123 Main St",
+                city="San Francisco",
+                state="CA",
+                postal_code="94102",
+                country="US",
+            ),
+        )
+        print(order.order_id, order.status)
+
+asyncio.run(main())
+```
+
+## Tools for LLM Frameworks
+
+The SDK ships ready-to-use tool definitions for Anthropic, OpenAI, and LangChain.
+
+### Anthropic
+
+```python
+from agentmesh.tools import anthropic_tools, ToolExecutor
+from agentmesh import SynchronityClient, SynchronityConfig
+import anthropic
+
+client = SynchronityClient(SynchronityConfig(agent_token="your-token"))
+executor = ToolExecutor(client)
+
+anthropic_client = anthropic.Anthropic()
+response = anthropic_client.messages.create(
+    model="claude-opus-4-5",
+    max_tokens=1024,
+    tools=anthropic_tools,
+    messages=[{"role": "user", "content": "Find me a red laptop under $1000 on site site_abc123"}],
+)
+
+# Execute tool calls
+import asyncio
+for block in response.content:
+    if block.type == "tool_use":
+        result = asyncio.run(executor.execute(block.name, block.input))
+        print(result)
+```
+
+### OpenAI
+
+```python
+from agentmesh.tools import openai_tools, ToolExecutor
+from openai import OpenAI
+
+openai_client = OpenAI()
+response = openai_client.chat.completions.create(
+    model="gpt-4o",
+    tools=openai_tools,
+    messages=[{"role": "user", "content": "Search for laptops on site_abc123"}],
+)
+```
+
+### LangChain
+
+```python
+from agentmesh.tools import langchain_tools
+# langchain_tools is a list of dicts with name, description, and schema
+```
+
+## Available Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `search_products` | Search products on a site with filters |
+| `get_product` | Get full product details by ID |
+| `compare_products` | Compare products across multiple sites |
+| `create_cart` | Create a new shopping cart |
+| `add_to_cart` | Add a product/variant to a cart |
+| `remove_from_cart` | Remove a line item from a cart |
+| `apply_coupon` | Apply a discount code to a cart |
+| `get_cart` | Get current cart contents |
+| `execute_checkout` | Execute checkout and return a confirmed order |
+| `get_order` | Get order details by ID |
+| `list_orders` | List orders with optional status filter |
+
+## Configuration
+
+```python
+from agentmesh import SynchronityConfig
+
+config = SynchronityConfig(
+    agent_token="your-agent-token",   # required
+    base_url="https://gateway.agentmesh.ai",  # default
+    timeout=30.0,    # seconds
+    retries=3,       # auto-retry on 429 and 5xx
+    retry_delay=1.0, # base delay for exponential backoff
+)
+```
+
+## Error Handling
+
+```python
+from agentmesh.errors import (
+    AuthenticationError,   # 401
+    AuthorizationError,    # 403
+    NotFoundError,         # 404 / 410
+    ValidationError,       # 400
+    RateLimitError,        # 429 — has .retry_after attribute
+    ConnectorError,        # 422
+    NetworkError,          # network failures
+    TimeoutError,          # request timeout
+    SynchronityError,        # base class
+)
+
+try:
+    product = await client.products.get_by_id("site_abc", "prod_999")
+except NotFoundError as e:
+    print(f"Product not found: {e.code}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

synchronity_sdk-0.1.0/agentmesh/__init__.py

@@ -0,0 +1,62 @@
+from .client import AgentMeshClient
+from .config import AgentMeshConfig, SDK_VERSION
+from .errors import (
+    AgentMeshError,
+    AuthenticationError,
+    AuthorizationError,
+    ConnectorError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+from .http import HttpClient
+from .modules import (
+    CartModule,
+    CheckoutModule,
+    DiscoveryModule,
+    OrdersModule,
+    ProductsModule,
+    ShippingAddressParams,
+)
+from .types import (
+    AMPSCapabilityManifest,
+    AMPSCart,
+    AMPSOrder,
+    AMPSOrderStatus,
+    AMPSProduct,
+    AvailabilityStatus,
+    MonetaryAmount,
+    SiteListItem,
+)
+
+__all__ = [
+    "AgentMeshClient",
+    "AgentMeshConfig",
+    "SDK_VERSION",
+    "AgentMeshError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConnectorError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "TimeoutError",
+    "ValidationError",
+    "HttpClient",
+    "CartModule",
+    "CheckoutModule",
+    "DiscoveryModule",
+    "OrdersModule",
+    "ProductsModule",
+    "ShippingAddressParams",
+    "AMPSCapabilityManifest",
+    "AMPSCart",
+    "AMPSOrder",
+    "AMPSOrderStatus",
+    "AMPSProduct",
+    "AvailabilityStatus",
+    "MonetaryAmount",
+    "SiteListItem",
+]

synchronity_sdk-0.1.0/agentmesh/client.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .config import AgentMeshConfig
+from .http import HttpClient
+from .modules.cart import CartModule
+from .modules.checkout import CheckoutModule
+from .modules.discovery import DiscoveryModule
+from .modules.orders import OrdersModule
+from .modules.products import ProductsModule
+
+
+class AgentMeshClient:
+    def __init__(self, config: AgentMeshConfig) -> None:
+        self._http = HttpClient(config)
+        self.discovery = DiscoveryModule(self._http)
+        self.products = ProductsModule(self._http)
+        self.cart = CartModule(self._http)
+        self.checkout = CheckoutModule(self._http)
+        self.orders = OrdersModule(self._http)
+
+    async def __aenter__(self) -> "AgentMeshClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._http.close()
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    @classmethod
+    def with_http_client(
+        cls, config: AgentMeshConfig, http_client: HttpClient
+    ) -> "AgentMeshClient":
+        """Inject a pre-built HttpClient — useful for testing."""
+        instance = cls.__new__(cls)
+        instance._http = http_client
+        instance.discovery = DiscoveryModule(http_client)
+        instance.products = ProductsModule(http_client)
+        instance.cart = CartModule(http_client)
+        instance.checkout = CheckoutModule(http_client)
+        instance.orders = OrdersModule(http_client)
+        return instance

synchronity_sdk-0.1.0/agentmesh/config.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+SDK_VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://gateway.agentmesh.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_RETRIES = 3
+DEFAULT_RETRY_DELAY = 1.0
+
+
+@dataclass
+class AgentMeshConfig:
+    agent_token: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+    retries: int = DEFAULT_RETRIES
+    retry_delay: float = DEFAULT_RETRY_DELAY

synchronity_sdk-0.1.0/agentmesh/errors.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+from typing import Optional, Union
+
+
+class AgentMeshError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+
+
+class AuthenticationError(AgentMeshError):
+    """Raised on HTTP 401 responses."""
+
+
+class AuthorizationError(AgentMeshError):
+    """Raised on HTTP 403 responses."""
+
+
+class NotFoundError(AgentMeshError):
+    """Raised on HTTP 404 / 410 responses."""
+
+
+class ValidationError(AgentMeshError):
+    """Raised on HTTP 400 responses."""
+
+
+class RateLimitError(AgentMeshError):
+    """Raised on HTTP 429 responses."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        request_id: Optional[str] = None,
+        retry_after: int = 60,
+    ) -> None:
+        super().__init__(message, code, status_code, request_id)
+        self.retry_after = retry_after
+
+
+class ConnectorError(AgentMeshError):
+    """Raised on HTTP 422 responses (upstream connector failure)."""
+
+
+class NetworkError(AgentMeshError):
+    """Raised on network-level failures (connection errors, etc.)."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(message, "NETWORK_ERROR", 0, request_id)
+
+
+class TimeoutError(AgentMeshError):
+    """Raised when a request times out."""
+
+    def __init__(self, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(message, "TIMEOUT", 0, request_id)
+
+
+def parse_error_response(
+    status: int,
+    body: dict,
+    request_id: Optional[str] = None,
+    retry_after: Optional[int] = None,
+) -> AgentMeshError:
+    error = body.get("error", {})
+    code = error.get("code", "UNKNOWN_ERROR")
+    message = error.get("message", f"HTTP {status}")
+
+    if status == 400:
+        return ValidationError(message, code, status, request_id)
+    elif status == 401:
+        return AuthenticationError(message, code, status, request_id)
+    elif status == 403:
+        return AuthorizationError(message, code, status, request_id)
+    elif status in (404, 410):
+        return NotFoundError(message, code, status, request_id)
+    elif status == 422:
+        return ConnectorError(message, code, status, request_id)
+    elif status == 429:
+        return RateLimitError(
+            message,
+            code,
+            status,
+            request_id,
+            retry_after=retry_after if retry_after is not None else 60,
+        )
+    else:
+        return AgentMeshError(message, code, status, request_id)

synchronity_sdk-0.1.0/agentmesh/http.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from .config import AgentMeshConfig, SDK_VERSION
+from .errors import (
+    AgentMeshError,
+    NetworkError,
+    TimeoutError,
+    parse_error_response,
+)
+
+
+class HttpClient:
+    def __init__(
+        self,
+        config: AgentMeshConfig,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._config = config
+        self._base_url = config.base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {config.agent_token}",
+            "User-Agent": f"agentmesh-python/{SDK_VERSION}",
+            "Accept": "application/json",
+        }
+        self._owned = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=config.timeout,
+        )
+
+    async def __aenter__(self) -> "HttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owned:
+            await self._client.aclose()
+
+    async def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> dict:
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, body: Optional[dict] = None) -> dict:
+        return await self._request("POST", path, body=body)
+
+    async def delete(self, path: str) -> dict:
+        return await self._request("DELETE", path)
+
+    def _build_url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    def _clean_params(
+        self, params: Optional[Dict[str, Any]]
+    ) -> Optional[Dict[str, str]]:
+        if not params:
+            return None
+        result: Dict[str, str] = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, list):
+                result[k] = ",".join(str(i) for i in v)
+            else:
+                result[k] = str(v)
+        return result or None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[dict] = None,
+        attempt: int = 0,
+    ) -> dict:
+        url = self._build_url(path)
+        cleaned_params = self._clean_params(params)
+
+        headers = dict(self._headers)
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            response = await self._client.request(
+                method,
+                url,
+                params=cleaned_params,
+                json=body,
+                headers=headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Request timed out: {method} {path}") from exc
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Network error: {method} {path}: {exc}") from exc
+
+        request_id = response.headers.get("X-AgentMesh-Request-Id")
+
+        if response.is_success:
+            if response.status_code == 204:
+                return {}
+            return response.json()
+
+        # Parse retry-after header for 429
+        retry_after: Optional[int] = None
+        raw_retry = response.headers.get("Retry-After")
+        if raw_retry is not None:
+            try:
+                retry_after = int(raw_retry)
+            except ValueError:
+                retry_after = 60
+
+        # Retry on 429 and 5xx
+        should_retry = attempt < self._config.retries and (
+            response.status_code == 429 or response.status_code >= 500
+        )
+
+        if should_retry:
+            if response.status_code == 429 and retry_after is not None:
+                delay = float(retry_after)
+            else:
+                delay = self._config.retry_delay * (2**attempt)
+            await asyncio.sleep(delay)
+            return await self._request(method, path, params=params, body=body, attempt=attempt + 1)
+
+        try:
+            error_body = response.json()
+        except Exception:
+            error_body = {
+                "error": {
+                    "code": "UNKNOWN_ERROR",
+                    "message": f"HTTP {response.status_code}: {response.text}",
+                }
+            }
+
+        raise parse_error_response(response.status_code, error_body, request_id, retry_after)