Metadata-Version: 2.4
Name: synchronity-sdk
Version: 0.2.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

[![PyPI version](https://img.shields.io/pypi/v/synchronity-sdk?style=flat-square&color=2d6a4f)](https://pypi.org/project/synchronity-sdk/)
[![PyPI downloads](https://img.shields.io/pypi/dm/synchronity-sdk?style=flat-square&color=2d6a4f)](https://pypi.org/project/synchronity-sdk/)
[![License: MIT](https://img.shields.io/badge/license-MIT-2d6a4f?style=flat-square)](../../LICENSE)

Python SDK for the [Synchronity](https://github.com/josephjerryrhule/agentmesh) agentic commerce infrastructure — makes any e-commerce site transactable by autonomous AI agents via authenticated REST APIs.

## Installation

```bash
pip install synchronity-sdk
```

Or with dev dependencies for testing:

```bash
pip install "synchronity-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://agentmesh-production.up.railway.app",  # 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
```
