# Pivota Agent SDK for Python
Official Python SDK for integrating AI agents with the Pivota e-commerce platform.
## 🚀 Quick Start
### Installation
```bash
pip install pivota-agent-sdk
```
### Get API Key
```python
from pivota_agent import PivotaAgentClient
# Create agent and get API key
client = PivotaAgentClient.create_agent(
agent_name="MyShoppingBot",
agent_email="bot@mycompany.com",
description="AI shopping assistant"
)
print(f"Your API key: {client.api_key}")
# Save this key securely!
```
### Initialize with API Key
```python
client = PivotaAgentClient(api_key="ak_live_your_key_here")
```
## 📚 Usage Examples
### 1. Search Products
```python
# Search across all merchants
products = client.search_products(
query="gaming laptop",
max_price=1500,
limit=10
)
for product in products["products"]:
print(f"{product['name']} - ${product['price']} - {product['merchant_name']}")
```
### 2. Create Order
```python
# Create order
order = client.create_order(
merchant_id="merch_xxx",
items=[
{"product_id": "prod_123", "quantity": 1},
{"product_id": "prod_456", "quantity": 2}
],
customer_email="buyer@example.com",
shipping_address={
"street": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
)
print(f"Order created: {order['order_id']}")
print(f"Total: ${order['total_amount']}")
```
### 3. Process Payment
```python
# Create payment
payment = client.create_payment(
order_id=order["order_id"],
payment_method={
"type": "card",
"token": "tok_visa_test" # From Stripe/Adyen
},
return_url="https://mybot.com/payment-callback"
)
if payment["status"] == "requires_action":
# Handle 3DS
print(f"Redirect user to: {payment['next_action']['redirect_url']}")
elif payment["status"] == "succeeded":
print("Payment successful!")
```
### 4. Track Order
```python
# Get order status
order_status = client.get_order(order_id="order_xxx")
print(f"Status: {order_status['status']}")
print(f"Tracking: {order_status.get('tracking_number')}")
```
## 🔧 Advanced Features
### Error Handling
```python
from pivota_agent import AuthenticationError, RateLimitError, NotFoundError
try:
products = client.search_products(query="laptop")
except AuthenticationError:
print("Invalid API key")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError:
print("Resource not found")
except PivotaAPIError as e:
print(f"API error: {e.message} (status: {e.status_code})")
```
### Pagination
```python
# Get all products with pagination
all_products = []
offset = 0
limit = 50
while True:
result = client.search_products(
query="shoes",
limit=limit,
offset=offset
)
all_products.extend(result["products"])
if not result["pagination"]["has_more"]:
break
offset += limit
print(f"Total products found: {len(all_products)}")
```
### List Merchants
```python
# Get all available merchants
merchants = client.list_merchants(status="active", limit=100)
for merchant in merchants:
print(f"{merchant['business_name']} - {merchant['status']}")
if merchant['mcp_connected']:
print(f" Platform: {merchant['mcp_platform']}")
if merchant['psp_connected']:
print(f" PSP: {merchant['psp_type']}")
```
## 📖 API Reference
### PivotaAgentClient
#### Constructor
```python
PivotaAgentClient(
api_key: str = None,
base_url: str = "https://web-production-fedb.up.railway.app/agent/v1",
timeout: int = 30
)
```
#### Methods
| Method | Description | Returns |
|--------|-------------|---------|
| `create_agent(name, email, desc)` | Create agent and get API key | PivotaAgentClient |
| `health_check()` | Check API health | Dict |
| `list_merchants(status, limit, offset)` | List merchants | List[Dict] |
| `search_products(query, **filters)` | Search products | Dict |
| `create_order(merchant_id, items, email)` | Create order | Dict |
| `get_order(order_id)` | Get order status | Dict |
| `list_orders(filters)` | List orders | Dict |
| `create_payment(order_id, payment_method)` | Create payment | Dict |
| `get_payment(payment_id)` | Get payment status | Dict |
| `get_analytics_summary()` | Get analytics | Dict |
## 🔒 Rate Limits
- **Standard tier**: 1,000 requests per minute
- **Burst**: Up to 50 requests in first 10 seconds
Rate limit headers included in responses:
- `X-RateLimit-Limit`: Total limit
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Reset timestamp
## 🆘 Support
- Documentation: https://docs.pivota.com
- GitHub: https://github.com/pivota/pivota-agent-sdk-python
- Email: support@pivota.com
## 📄 License
MIT License - see LICENSE file for details
Raw data
{
"_id": null,
"home_page": "https://github.com/pivota/pivota-agent-sdk-python",
"name": "pivota-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pivota agent ecommerce api sdk payments",
"author": "Pivota",
"author_email": "support@pivota.com",
"download_url": "https://files.pythonhosted.org/packages/e9/b2/e2914a75548742a17096a76e59cb26df46c08aabcd024bba3e0b6929b27f/pivota_agent-1.0.0.tar.gz",
"platform": null,
"description": "# Pivota Agent SDK for Python\n\nOfficial Python SDK for integrating AI agents with the Pivota e-commerce platform.\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install pivota-agent-sdk\n```\n\n### Get API Key\n\n```python\nfrom pivota_agent import PivotaAgentClient\n\n# Create agent and get API key\nclient = PivotaAgentClient.create_agent(\n agent_name=\"MyShoppingBot\",\n agent_email=\"bot@mycompany.com\",\n description=\"AI shopping assistant\"\n)\n\nprint(f\"Your API key: {client.api_key}\")\n# Save this key securely!\n```\n\n### Initialize with API Key\n\n```python\nclient = PivotaAgentClient(api_key=\"ak_live_your_key_here\")\n```\n\n## \ud83d\udcda Usage Examples\n\n### 1. Search Products\n\n```python\n# Search across all merchants\nproducts = client.search_products(\n query=\"gaming laptop\",\n max_price=1500,\n limit=10\n)\n\nfor product in products[\"products\"]:\n print(f\"{product['name']} - ${product['price']} - {product['merchant_name']}\")\n```\n\n### 2. Create Order\n\n```python\n# Create order\norder = client.create_order(\n merchant_id=\"merch_xxx\",\n items=[\n {\"product_id\": \"prod_123\", \"quantity\": 1},\n {\"product_id\": \"prod_456\", \"quantity\": 2}\n ],\n customer_email=\"buyer@example.com\",\n shipping_address={\n \"street\": \"123 Main St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip\": \"94105\",\n \"country\": \"US\"\n }\n)\n\nprint(f\"Order created: {order['order_id']}\")\nprint(f\"Total: ${order['total_amount']}\")\n```\n\n### 3. Process Payment\n\n```python\n# Create payment\npayment = client.create_payment(\n order_id=order[\"order_id\"],\n payment_method={\n \"type\": \"card\",\n \"token\": \"tok_visa_test\" # From Stripe/Adyen\n },\n return_url=\"https://mybot.com/payment-callback\"\n)\n\nif payment[\"status\"] == \"requires_action\":\n # Handle 3DS\n print(f\"Redirect user to: {payment['next_action']['redirect_url']}\")\nelif payment[\"status\"] == \"succeeded\":\n print(\"Payment successful!\")\n```\n\n### 4. Track Order\n\n```python\n# Get order status\norder_status = client.get_order(order_id=\"order_xxx\")\n\nprint(f\"Status: {order_status['status']}\")\nprint(f\"Tracking: {order_status.get('tracking_number')}\")\n```\n\n## \ud83d\udd27 Advanced Features\n\n### Error Handling\n\n```python\nfrom pivota_agent import AuthenticationError, RateLimitError, NotFoundError\n\ntry:\n products = client.search_products(query=\"laptop\")\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept RateLimitError as e:\n print(f\"Rate limited. Retry after {e.retry_after} seconds\")\nexcept NotFoundError:\n print(\"Resource not found\")\nexcept PivotaAPIError as e:\n print(f\"API error: {e.message} (status: {e.status_code})\")\n```\n\n### Pagination\n\n```python\n# Get all products with pagination\nall_products = []\noffset = 0\nlimit = 50\n\nwhile True:\n result = client.search_products(\n query=\"shoes\",\n limit=limit,\n offset=offset\n )\n \n all_products.extend(result[\"products\"])\n \n if not result[\"pagination\"][\"has_more\"]:\n break\n \n offset += limit\n\nprint(f\"Total products found: {len(all_products)}\")\n```\n\n### List Merchants\n\n```python\n# Get all available merchants\nmerchants = client.list_merchants(status=\"active\", limit=100)\n\nfor merchant in merchants:\n print(f\"{merchant['business_name']} - {merchant['status']}\")\n if merchant['mcp_connected']:\n print(f\" Platform: {merchant['mcp_platform']}\")\n if merchant['psp_connected']:\n print(f\" PSP: {merchant['psp_type']}\")\n```\n\n## \ud83d\udcd6 API Reference\n\n### PivotaAgentClient\n\n#### Constructor\n```python\nPivotaAgentClient(\n api_key: str = None,\n base_url: str = \"https://web-production-fedb.up.railway.app/agent/v1\",\n timeout: int = 30\n)\n```\n\n#### Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `create_agent(name, email, desc)` | Create agent and get API key | PivotaAgentClient |\n| `health_check()` | Check API health | Dict |\n| `list_merchants(status, limit, offset)` | List merchants | List[Dict] |\n| `search_products(query, **filters)` | Search products | Dict |\n| `create_order(merchant_id, items, email)` | Create order | Dict |\n| `get_order(order_id)` | Get order status | Dict |\n| `list_orders(filters)` | List orders | Dict |\n| `create_payment(order_id, payment_method)` | Create payment | Dict |\n| `get_payment(payment_id)` | Get payment status | Dict |\n| `get_analytics_summary()` | Get analytics | Dict |\n\n## \ud83d\udd12 Rate Limits\n\n- **Standard tier**: 1,000 requests per minute\n- **Burst**: Up to 50 requests in first 10 seconds\n\nRate limit headers included in responses:\n- `X-RateLimit-Limit`: Total limit\n- `X-RateLimit-Remaining`: Remaining requests\n- `X-RateLimit-Reset`: Reset timestamp\n\n## \ud83c\udd98 Support\n\n- Documentation: https://docs.pivota.com\n- GitHub: https://github.com/pivota/pivota-agent-sdk-python\n- Email: support@pivota.com\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python SDK for Pivota Agent API",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://docs.pivota.com/agent-sdk",
"Homepage": "https://github.com/pivota/pivota-agent-sdk-python",
"Source": "https://github.com/pivota/pivota-agent-sdk-python",
"Tracker": "https://github.com/pivota/pivota-agent-sdk-python/issues"
},
"split_keywords": [
"pivota",
"agent",
"ecommerce",
"api",
"sdk",
"payments"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ee67ad824cab8d433af1bf0c490198135373fc5684f399daf94da577c4ad92d6",
"md5": "1a73f7cca18e2db52881edd3063c1724",
"sha256": "0439c96b88b8863ccfa69d4124755d53cd31cafc6bdbddd9710dd19008e80850"
},
"downloads": -1,
"filename": "pivota_agent-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a73f7cca18e2db52881edd3063c1724",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9986,
"upload_time": "2025-10-24T01:20:27",
"upload_time_iso_8601": "2025-10-24T01:20:27.850024Z",
"url": "https://files.pythonhosted.org/packages/ee/67/ad824cab8d433af1bf0c490198135373fc5684f399daf94da577c4ad92d6/pivota_agent-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e9b2e2914a75548742a17096a76e59cb26df46c08aabcd024bba3e0b6929b27f",
"md5": "27b58aa5db46a6fd588150c323a49d77",
"sha256": "bc188b9c7d5e2c65f7f3d2d04488c284b536970ad818a2b6c92ccc9c95301a33"
},
"downloads": -1,
"filename": "pivota_agent-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "27b58aa5db46a6fd588150c323a49d77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10591,
"upload_time": "2025-10-24T01:20:29",
"upload_time_iso_8601": "2025-10-24T01:20:29.444060Z",
"url": "https://files.pythonhosted.org/packages/e9/b2/e2914a75548742a17096a76e59cb26df46c08aabcd024bba3e0b6929b27f/pivota_agent-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 01:20:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pivota",
"github_project": "pivota-agent-sdk-python",
"github_not_found": true,
"lcname": "pivota-agent"
}
JSON
