channel3-sdk 0.0.1__tar.gz → 0.1.0__tar.gz

channel3_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.1
+Name: channel3-sdk
+Version: 0.1.0
+Summary: The official Python SDK for Channel3 AI Shopping API
+Home-page: https://github.com/channel3/sdk-python
+License: MIT
+Keywords: ai,shopping,ecommerce,search,api
+Author: Channel3
+Author-email: alex@trychannel3.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.9.0,<4.0.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Repository, https://github.com/channel3/sdk-python
+Description-Content-Type: text/markdown
+
+# Channel3 Python SDK
+
+The official Python SDK for the [Channel3](https://trychannel3.com) AI Shopping API.
+
+## Installation
+
+```bash
+pip install channel3-sdk
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+import os
+from channel3_sdk import Channel3Client
+
+# Initialize the client
+client = Channel3Client(api_key="your_api_key_here")
+# Or use environment variable: CHANNEL3_API_KEY
+
+# Search for products
+products = client.search(query="blue denim jacket")
+
+for product in products:
+    print(f"Product: {product.title}")
+    print(f"Brand: {product.brand_name}")
+    print(f"Price: ${product.offers[0].price.price}")
+    print("---")
+
+# Get detailed product information
+product_detail = client.get_product("prod_123456")
+print(f"Detailed info for: {product_detail.title}")
+print(f"Materials: {product_detail.materials}")
+print(f"Key features: {product_detail.key_features}")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from channel3_sdk import AsyncChannel3Client
+
+async def main():
+    # Initialize the async client
+    client = AsyncChannel3Client(api_key="your_api_key_here")
+    
+    # Search for products
+    products = await client.search(query="running shoes")
+    
+    for product in products:
+        print(f"Product: {product.title}")
+        print(f"Score: {product.score}")
+    
+    # Get detailed product information
+    if products:
+        product_detail = await client.get_product(products[0].id)
+        print(f"Gender: {product_detail.gender}")
+
+# Run the async function
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Visual Search
+
+```python
+# Search by image URL
+products = client.search(image_url="https://example.com/image.jpg")
+
+# Search by base64 image
+with open("image.jpg", "rb") as f:
+    import base64
+    base64_image = base64.b64encode(f.read()).decode()
+    products = client.search(base64_image=base64_image)
+```
+
+### Multimodal Search
+
+```python
+# Combine text and image search
+products = client.search(
+    query="blue denim jacket",
+    image_url="https://example.com/jacket.jpg"
+)
+```
+
+### Search with Filters
+
+```python
+from channel3_sdk import SearchFilters
+
+# Create search filters
+filters = SearchFilters(
+    colors=["blue", "navy"],
+    materials=["cotton", "denim"],
+    min_price=50.0,
+    max_price=200.0
+)
+
+# Search with filters
+products = client.search(
+    query="jacket",
+    filters=filters,
+    limit=10
+)
+```
+
+## API Reference
+
+### Client Classes
+
+#### `Channel3Client`
+Synchronous client for the Channel3 API.
+
+**Methods:**
+- `search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
+- `get_product(product_id)` → `ProductDetail`
+
+#### `AsyncChannel3Client` 
+Asynchronous client for the Channel3 API.
+
+**Methods:**
+- `async search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
+- `async get_product(product_id)` → `ProductDetail`
+
+### Models
+
+#### `Product`
+- `id: str` - Unique product identifier
+- `score: float` - Search relevance score
+- `brand_name: str` - Brand name
+- `title: str` - Product title
+- `description: str` - Product description
+- `image_url: str` - Main product image URL
+- `offers: List[MerchantOffering]` - Available purchase options
+- `family: List[FamilyMember]` - Related products
+
+#### `ProductDetail`
+- `brand_id: str` - Brand identifier
+- `brand_name: str` - Brand name
+- `title: str` - Product title
+- `description: str` - Product description
+- `image_urls: List[str]` - Product image URLs
+- `merchant_offerings: List[MerchantOffering]` - Purchase options
+- `gender: Literal["na", "men", "women"]` - Target gender
+- `materials: Optional[List[str]]` - Product materials
+- `key_features: List[str]` - Key product features
+- `family_members: List[FamilyMember]` - Related products
+
+#### `SearchFilters`
+- `colors: Optional[List[str]]` - Color filters
+- `materials: Optional[List[str]]` - Material filters
+- `min_price: Optional[float]` - Minimum price
+- `max_price: Optional[float]` - Maximum price
+
+#### `MerchantOffering`
+- `url: str` - Purchase URL
+- `merchant_name: str` - Merchant name
+- `price: Price` - Price information
+- `availability: AvailabilityStatus` - Availability status
+
+#### `Price`
+- `price: float` - Current price
+- `compare_at_price: Optional[float]` - Original price (if discounted)
+- `currency: str` - Currency code
+
+## Error Handling
+
+The SDK provides specific exception types for different error conditions:
+
+```python
+from channel3_sdk import (
+    Channel3AuthenticationError,
+    Channel3ValidationError,
+    Channel3NotFoundError,
+    Channel3ServerError,
+    Channel3ConnectionError
+)
+
+try:
+    products = client.search(query="shoes")
+except Channel3AuthenticationError:
+    print("Invalid API key")
+except Channel3ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except Channel3NotFoundError:
+    print("Resource not found")
+except Channel3ServerError:
+    print("Server error - please try again later")
+except Channel3ConnectionError:
+    print("Connection error - check your internet connection")
+```
+
+## Environment Variables
+
+- `CHANNEL3_API_KEY` - Your Channel3 API key
+
+## Requirements
+
+- Python 3.8+
+- requests
+- aiohttp
+- pydantic
+
+## License
+
+MIT License
+

channel3_sdk-0.1.0/README.md

@@ -0,0 +1,210 @@
+# Channel3 Python SDK
+
+The official Python SDK for the [Channel3](https://trychannel3.com) AI Shopping API.
+
+## Installation
+
+```bash
+pip install channel3-sdk
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+import os
+from channel3_sdk import Channel3Client
+
+# Initialize the client
+client = Channel3Client(api_key="your_api_key_here")
+# Or use environment variable: CHANNEL3_API_KEY
+
+# Search for products
+products = client.search(query="blue denim jacket")
+
+for product in products:
+    print(f"Product: {product.title}")
+    print(f"Brand: {product.brand_name}")
+    print(f"Price: ${product.offers[0].price.price}")
+    print("---")
+
+# Get detailed product information
+product_detail = client.get_product("prod_123456")
+print(f"Detailed info for: {product_detail.title}")
+print(f"Materials: {product_detail.materials}")
+print(f"Key features: {product_detail.key_features}")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from channel3_sdk import AsyncChannel3Client
+
+async def main():
+    # Initialize the async client
+    client = AsyncChannel3Client(api_key="your_api_key_here")
+    
+    # Search for products
+    products = await client.search(query="running shoes")
+    
+    for product in products:
+        print(f"Product: {product.title}")
+        print(f"Score: {product.score}")
+    
+    # Get detailed product information
+    if products:
+        product_detail = await client.get_product(products[0].id)
+        print(f"Gender: {product_detail.gender}")
+
+# Run the async function
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Visual Search
+
+```python
+# Search by image URL
+products = client.search(image_url="https://example.com/image.jpg")
+
+# Search by base64 image
+with open("image.jpg", "rb") as f:
+    import base64
+    base64_image = base64.b64encode(f.read()).decode()
+    products = client.search(base64_image=base64_image)
+```
+
+### Multimodal Search
+
+```python
+# Combine text and image search
+products = client.search(
+    query="blue denim jacket",
+    image_url="https://example.com/jacket.jpg"
+)
+```
+
+### Search with Filters
+
+```python
+from channel3_sdk import SearchFilters
+
+# Create search filters
+filters = SearchFilters(
+    colors=["blue", "navy"],
+    materials=["cotton", "denim"],
+    min_price=50.0,
+    max_price=200.0
+)
+
+# Search with filters
+products = client.search(
+    query="jacket",
+    filters=filters,
+    limit=10
+)
+```
+
+## API Reference
+
+### Client Classes
+
+#### `Channel3Client`
+Synchronous client for the Channel3 API.
+
+**Methods:**
+- `search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
+- `get_product(product_id)` → `ProductDetail`
+
+#### `AsyncChannel3Client` 
+Asynchronous client for the Channel3 API.
+
+**Methods:**
+- `async search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
+- `async get_product(product_id)` → `ProductDetail`
+
+### Models
+
+#### `Product`
+- `id: str` - Unique product identifier
+- `score: float` - Search relevance score
+- `brand_name: str` - Brand name
+- `title: str` - Product title
+- `description: str` - Product description
+- `image_url: str` - Main product image URL
+- `offers: List[MerchantOffering]` - Available purchase options
+- `family: List[FamilyMember]` - Related products
+
+#### `ProductDetail`
+- `brand_id: str` - Brand identifier
+- `brand_name: str` - Brand name
+- `title: str` - Product title
+- `description: str` - Product description
+- `image_urls: List[str]` - Product image URLs
+- `merchant_offerings: List[MerchantOffering]` - Purchase options
+- `gender: Literal["na", "men", "women"]` - Target gender
+- `materials: Optional[List[str]]` - Product materials
+- `key_features: List[str]` - Key product features
+- `family_members: List[FamilyMember]` - Related products
+
+#### `SearchFilters`
+- `colors: Optional[List[str]]` - Color filters
+- `materials: Optional[List[str]]` - Material filters
+- `min_price: Optional[float]` - Minimum price
+- `max_price: Optional[float]` - Maximum price
+
+#### `MerchantOffering`
+- `url: str` - Purchase URL
+- `merchant_name: str` - Merchant name
+- `price: Price` - Price information
+- `availability: AvailabilityStatus` - Availability status
+
+#### `Price`
+- `price: float` - Current price
+- `compare_at_price: Optional[float]` - Original price (if discounted)
+- `currency: str` - Currency code
+
+## Error Handling
+
+The SDK provides specific exception types for different error conditions:
+
+```python
+from channel3_sdk import (
+    Channel3AuthenticationError,
+    Channel3ValidationError,
+    Channel3NotFoundError,
+    Channel3ServerError,
+    Channel3ConnectionError
+)
+
+try:
+    products = client.search(query="shoes")
+except Channel3AuthenticationError:
+    print("Invalid API key")
+except Channel3ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except Channel3NotFoundError:
+    print("Resource not found")
+except Channel3ServerError:
+    print("Server error - please try again later")
+except Channel3ConnectionError:
+    print("Connection error - check your internet connection")
+```
+
+## Environment Variables
+
+- `CHANNEL3_API_KEY` - Your Channel3 API key
+
+## Requirements
+
+- Python 3.8+
+- requests
+- aiohttp
+- pydantic
+
+## License
+
+MIT License

channel3_sdk-0.1.0/channel3_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""Channel3 SDK for Python - Official SDK for the Channel3 AI Shopping API."""
+
+from .client import Channel3Client, AsyncChannel3Client
+from .models import (
+    Product,
+    ProductDetail,
+    SearchFilters,
+    SearchRequest,
+    MerchantOffering,
+    FamilyMember,
+    Price,
+    AvailabilityStatus,
+)
+from .exceptions import (
+    Channel3Error,
+    Channel3AuthenticationError,
+    Channel3ValidationError,
+    Channel3NotFoundError,
+    Channel3ServerError,
+    Channel3ConnectionError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Clients
+    "Channel3Client",
+    "AsyncChannel3Client",
+    # Models
+    "Product",
+    "ProductDetail",
+    "SearchFilters",
+    "SearchRequest",
+    "MerchantOffering",
+    "FamilyMember",
+    "Price",
+    "AvailabilityStatus",
+    # Exceptions
+    "Channel3Error",
+    "Channel3AuthenticationError",
+    "Channel3ValidationError",
+    "Channel3NotFoundError",
+    "Channel3ServerError",
+    "Channel3ConnectionError",
+]

channel3_sdk-0.1.0/channel3_sdk/client.py

@@ -0,0 +1,341 @@
+# channel3_sdk/client.py
+import os
+import requests
+from typing import List, Optional, Dict, Any, Union
+import aiohttp
+import asyncio
+from pydantic import ValidationError
+
+from .models import Product, ProductDetail, SearchFilters, SearchRequest
+from .exceptions import (
+    Channel3Error,
+    Channel3AuthenticationError,
+    Channel3ValidationError,
+    Channel3NotFoundError,
+    Channel3ServerError,
+    Channel3ConnectionError,
+)
+
+
+class BaseChannel3Client:
+    """Base client with common functionality."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        """
+        Initialize the base Channel3 client.
+
+        Args:
+            api_key: Your Channel3 API key. If not provided, will look for CHANNEL3_API_KEY in environment.
+            base_url: Base URL for the API. Defaults to https://api.trychannel3.com/v0
+
+        Raises:
+            ValueError: If no API key is provided and none is found in environment variables.
+        """
+        self.api_key = api_key or os.getenv("CHANNEL3_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "No API key provided. Set CHANNEL3_API_KEY environment variable or pass api_key parameter."
+            )
+
+        self.base_url = base_url or "https://api.trychannel3.com/v0"
+        self.headers = {"x-api-key": self.api_key, "Content-Type": "application/json"}
+
+    def _handle_error_response(
+        self, status_code: int, response_data: Dict[str, Any], url: str
+    ) -> None:
+        """Handle error responses and raise appropriate exceptions."""
+        error_message = response_data.get(
+            "detail", f"Request failed with status {status_code}"
+        )
+
+        if status_code == 401:
+            raise Channel3AuthenticationError(
+                "Invalid or missing API key",
+                status_code=status_code,
+                response_data=response_data,
+            )
+        elif status_code == 404:
+            raise Channel3NotFoundError(
+                error_message, status_code=status_code, response_data=response_data
+            )
+        elif status_code == 422:
+            raise Channel3ValidationError(
+                f"Validation error: {error_message}",
+                status_code=status_code,
+                response_data=response_data,
+            )
+        elif status_code == 500:
+            raise Channel3ServerError(
+                "Internal server error",
+                status_code=status_code,
+                response_data=response_data,
+            )
+        else:
+            raise Channel3Error(
+                f"Request to {url} failed: {error_message}",
+                status_code=status_code,
+                response_data=response_data,
+            )
+
+
+class Channel3Client(BaseChannel3Client):
+    """Synchronous Channel3 API client."""
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        image_url: Optional[str] = None,
+        base64_image: Optional[str] = None,
+        filters: Optional[Union[SearchFilters, Dict[str, Any]]] = None,
+        limit: int = 20,
+    ) -> List[Product]:
+        """
+        Search for products using text query, image, or both with optional filters.
+
+        Args:
+            query: Text search query
+            image_url: URL to an image to use for visual search
+            base64_image: Base64-encoded image to use for visual search
+            filters: Search filters (SearchFilters object or dict)
+            limit: Maximum number of products to return (default: 20)
+
+        Returns:
+            List of Product objects
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3ValidationError: If request parameters are invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Examples:
+            ```python
+            # Text search
+            products = client.search(query="blue denim jacket")
+
+            # Image search
+            products = client.search(image_url="https://example.com/image.jpg")
+
+            # Multimodal search with filters
+            from channel3_sdk.models import SearchFilters
+            filters = SearchFilters(colors=["blue"], min_price=50.0, max_price=150.0)
+            products = client.search(query="denim jacket", filters=filters)
+            ```
+        """
+        # Build request payload
+        search_request = SearchRequest(
+            query=query,
+            image_url=image_url,
+            base64_image=base64_image,
+            filters=filters,
+            limit=limit,
+        )
+
+        url = f"{self.base_url}/search"
+
+        try:
+            response = requests.post(
+                url,
+                json=search_request.model_dump(exclude_none=True),
+                headers=self.headers,
+                timeout=30,
+            )
+
+            response_data = response.json()
+
+            if response.status_code != 200:
+                self._handle_error_response(response.status_code, response_data, url)
+
+            # Parse and validate response
+            return [Product(**item) for item in response_data]
+
+        except requests.exceptions.ConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except requests.exceptions.Timeout as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except requests.exceptions.RequestException as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
+    def get_product(self, product_id: str) -> ProductDetail:
+        """
+        Get detailed information about a specific product by its ID.
+
+        Args:
+            product_id: The unique identifier of the product
+
+        Returns:
+            ProductDetail object with detailed product information
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3NotFoundError: If product is not found
+            Channel3ValidationError: If product_id is invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            product_detail = client.get_product("prod_123456")
+            print(f"Product: {product_detail.title}")
+            print(f"Brand: {product_detail.brand_name}")
+            ```
+        """
+        if not product_id or not product_id.strip():
+            raise ValueError("product_id cannot be empty")
+
+        url = f"{self.base_url}/products/{product_id}"
+
+        try:
+            response = requests.get(url, headers=self.headers, timeout=30)
+            response_data = response.json()
+
+            if response.status_code != 200:
+                self._handle_error_response(response.status_code, response_data, url)
+
+            # Parse and validate response
+            return ProductDetail(**response_data)
+
+        except requests.exceptions.ConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except requests.exceptions.Timeout as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except requests.exceptions.RequestException as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
+
+class AsyncChannel3Client(BaseChannel3Client):
+    """Asynchronous Channel3 API client."""
+
+    async def search(
+        self,
+        query: Optional[str] = None,
+        image_url: Optional[str] = None,
+        base64_image: Optional[str] = None,
+        filters: Optional[Union[SearchFilters, Dict[str, Any]]] = None,
+        limit: int = 20,
+    ) -> List[Product]:
+        """
+        Search for products using text query, image, or both with optional filters.
+
+        Args:
+            query: Text search query
+            image_url: URL to an image to use for visual search
+            base64_image: Base64-encoded image to use for visual search
+            filters: Search filters (SearchFilters object or dict)
+            limit: Maximum number of products to return (default: 20)
+
+        Returns:
+            List of Product objects
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3ValidationError: If request parameters are invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Examples:
+            ```python
+            # Text search
+            products = await async_client.search(query="blue denim jacket")
+
+            # Image search
+            products = await async_client.search(image_url="https://example.com/image.jpg")
+            ```
+        """
+        # Build request payload
+        search_request = SearchRequest(
+            query=query,
+            image_url=image_url,
+            base64_image=base64_image,
+            filters=filters,
+            limit=limit,
+        )
+
+        url = f"{self.base_url}/search"
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    url,
+                    json=search_request.model_dump(exclude_none=True),
+                    headers=self.headers,
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as response:
+                    response_data = await response.json()
+
+                    if response.status != 200:
+                        self._handle_error_response(response.status, response_data, url)
+
+                    # Parse and validate response
+                    return [Product(**item) for item in response_data]
+
+        except aiohttp.ClientConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except asyncio.TimeoutError as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except aiohttp.ClientError as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
+    async def get_product(self, product_id: str) -> ProductDetail:
+        """
+        Get detailed information about a specific product by its ID.
+
+        Args:
+            product_id: The unique identifier of the product
+
+        Returns:
+            ProductDetail object with detailed product information
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3NotFoundError: If product is not found
+            Channel3ValidationError: If product_id is invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            product_detail = await async_client.get_product("prod_123456")
+            print(f"Product: {product_detail.title}")
+            ```
+        """
+        if not product_id or not product_id.strip():
+            raise ValueError("product_id cannot be empty")
+
+        url = f"{self.base_url}/products/{product_id}"
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url, headers=self.headers, timeout=aiohttp.ClientTimeout(total=30)
+                ) as response:
+                    response_data = await response.json()
+
+                    if response.status != 200:
+                        self._handle_error_response(response.status, response_data, url)
+
+                    # Parse and validate response
+                    return ProductDetail(**response_data)
+
+        except aiohttp.ClientConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except asyncio.TimeoutError as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except aiohttp.ClientError as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")

channel3_sdk-0.1.0/channel3_sdk/exceptions.py

@@ -0,0 +1,48 @@
+"""Custom exceptions for the Channel3 SDK."""
+
+from typing import Optional, Dict, Any
+
+
+class Channel3Error(Exception):
+    """Base exception for all Channel3 SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_data: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data or {}
+
+
+class Channel3AuthenticationError(Channel3Error):
+    """Raised when authentication fails (401)."""
+
+    pass
+
+
+class Channel3ValidationError(Channel3Error):
+    """Raised when request validation fails (422)."""
+
+    pass
+
+
+class Channel3NotFoundError(Channel3Error):
+    """Raised when a resource is not found (404)."""
+
+    pass
+
+
+class Channel3ServerError(Channel3Error):
+    """Raised when the server encounters an error (500)."""
+
+    pass
+
+
+class Channel3ConnectionError(Channel3Error):
+    """Raised when there are connection issues."""
+
+    pass

channel3_sdk-0.1.0/channel3_sdk/models.py

@@ -0,0 +1,116 @@
+"""Pydantic models for the Channel3 API."""
+
+from enum import Enum
+from typing import List, Optional, Union, Literal
+from pydantic import BaseModel, Field
+
+
+class AvailabilityStatus(str, Enum):
+    """Availability status of a product."""
+
+    IN_STOCK = "InStock"
+    OUT_OF_STOCK = "OutOfStock"
+    PRE_ORDER = "PreOrder"
+    LIMITED_AVAILABILITY = "LimitedAvailability"
+    BACK_ORDER = "BackOrder"
+    DISCONTINUED = "Discontinued"
+    SOLD_OUT = "SoldOut"
+    UNKNOWN = "Unknown"
+
+
+class Price(BaseModel):
+    """Price information for a product."""
+
+    price: float = Field(
+        ..., description="The current price of the product, including any discounts."
+    )
+    compare_at_price: Optional[float] = Field(
+        None, description="The original price of the product before any discounts."
+    )
+    currency: str = Field(..., description="The currency code of the product.")
+
+
+class MerchantOffering(BaseModel):
+    """A merchant offering a product."""
+
+    url: str = Field(
+        default="https://buy.trychannel3.com", description="URL to purchase the product"
+    )
+    merchant_name: str = Field(..., description="Name of the merchant")
+    price: Price = Field(..., description="Price information")
+    availability: AvailabilityStatus = Field(
+        ..., description="Product availability status"
+    )
+
+
+class FamilyMember(BaseModel):
+    """A family member product."""
+
+    id: str = Field(..., description="Unique identifier for the family member")
+    title: str = Field(..., description="Title of the family member product")
+    image_url: str = Field(..., description="Image URL for the family member product")
+
+
+class Product(BaseModel):
+    """A product returned from search."""
+
+    id: str = Field(..., description="Unique identifier for the product")
+    score: float = Field(..., description="Relevance score for the search query")
+    brand_name: str = Field(..., description="Brand name of the product")
+    title: str = Field(..., description="Product title")
+    description: str = Field(..., description="Product description")
+    image_url: str = Field(..., description="Main product image URL")
+    offers: List[MerchantOffering] = Field(
+        ..., description="List of merchant offerings"
+    )
+    family: List[FamilyMember] = Field(
+        default_factory=list, description="Related family products"
+    )
+
+
+class ProductDetail(BaseModel):
+    """Detailed information about a product."""
+
+    brand_id: str = Field(..., description="Unique identifier for the brand")
+    brand_name: str = Field(..., description="Brand name of the product")
+    title: str = Field(..., description="Product title")
+    description: str = Field(..., description="Product description")
+    image_urls: List[str] = Field(..., description="List of product image URLs")
+    merchant_offerings: List[MerchantOffering] = Field(
+        ..., description="List of merchant offerings"
+    )
+    gender: Literal["na", "men", "women"] = Field(
+        default="na", description="Target gender"
+    )
+    materials: Optional[List[str]] = Field(None, description="List of materials")
+    key_features: List[str] = Field(
+        default_factory=list, description="List of key product features"
+    )
+    family_members: List[FamilyMember] = Field(
+        default_factory=list, description="Related family products"
+    )
+
+
+class SearchFilters(BaseModel):
+    """Search filters for product search."""
+
+    colors: Optional[List[str]] = Field(None, description="List of colors to filter by")
+    materials: Optional[List[str]] = Field(
+        None, description="List of materials to filter by"
+    )
+    min_price: Optional[float] = Field(None, description="Minimum price filter")
+    max_price: Optional[float] = Field(None, description="Maximum price filter")
+
+
+class SearchRequest(BaseModel):
+    """Request model for product search."""
+
+    query: Optional[str] = Field(None, description="Text search query")
+    image_url: Optional[str] = Field(None, description="URL of image for visual search")
+    base64_image: Optional[str] = Field(
+        None, description="Base64-encoded image for visual search"
+    )
+    filters: Optional[SearchFilters] = Field(None, description="Search filters")
+    limit: Optional[int] = Field(
+        default=20, description="Maximum number of results to return"
+    )

channel3_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[tool.poetry]
+name = "channel3-sdk"
+version = "0.1.0"
+description = "The official Python SDK for Channel3 AI Shopping API"
+authors = ["Channel3 <alex@trychannel3.com>"]
+readme = "README.md"
+license = "MIT"
+packages = [{ include = "channel3_sdk" }]
+repository = "https://github.com/channel3/sdk-python"
+keywords = ["ai", "shopping", "ecommerce", "search", "api"]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+requests = "^2.31.0"
+aiohttp = "^3.9.0"
+pydantic = "^2.5.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-asyncio = "^0.21.0"
+black = "^23.0.0"
+isort = "^5.12.0"
+mypy = "^1.7.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ['py38']
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

channel3_sdk-0.0.1/PKG-INFO

@@ -1,18 +0,0 @@
-Metadata-Version: 2.1
-Name: channel3-sdk
-Version: 0.0.1
-Summary: The API for AI Shopping
-License: MIT
-Author: Alex
-Author-email: alex@trychannel3.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT 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
-Requires-Dist: requests (>=2.31.0,<3.0.0)
-Description-Content-Type: text/markdown
-
-

channel3_sdk-0.0.1/channel3_sdk/__init__.py

@@ -1 +0,0 @@
-from .client import Channel3Client

channel3_sdk-0.0.1/channel3_sdk/client.py

@@ -1,134 +0,0 @@
-# channel3_sdk/client.py
-import os
-import requests
-from typing import List, Optional, Dict, Any, Union
-
-
-class Channel3Client:
-    def __init__(self, api_key: str = None):
-        """
-        Initialize a Channel3 API client.
-
-        The client provides methods to interact with Channel3's product search and retrieval API.
-
-        Args:
-            api_key: Your Channel3 API key. If not provided, will look for CHANNEL3_API_KEY in environment.
-
-        Raises:
-            ValueError: If no API key is provided and none is found in environment variables.
-
-        Example:
-            ```python
-            # Initialize with explicit API key
-            client = Channel3Client(api_key="your_api_key")
-
-            # Or use environment variable
-            # os.environ["CHANNEL3_API_KEY"] = "your_api_key"
-            # client = Channel3Client()
-            ```
-        """
-        self.api_key = api_key or os.getenv("CHANNEL3_API_KEY")
-        if not self.api_key:
-            raise ValueError("No API key provided for Channel3Client")
-        self.headers = {"x-api-key": self.api_key}
-        self.api_version = "v0"
-        self.base_url = f"https://api.channel3.com/{self.api_version}"
-
-    def search(
-        self,
-        query: Optional[str] = None,
-        image_url: Optional[str] = None,
-        base64_image: Optional[str] = None,
-        filters: Optional[Dict[str, Any]] = None,
-        limit: int = 20,
-    ) -> List[Dict[str, Any]]:
-        """
-        Search for products using text query, image, or both with optional filters.
-
-        Args:
-            query: Text search query
-            image_url: URL to an image to use for visual search
-            base64_image: Base64-encoded image to use for visual search
-            filters: Dict containing optional filters with these possible keys:
-                - colors: List of color strings
-                - materials: List of material strings
-                - min_price: Minimum price (float)
-                - max_price: Maximum price (float)
-            limit: Maximum number of products to return (default: 20)
-
-        Returns:
-            List of product dictionaries containing:
-                id, url, score, price, brand_id, brand_name, title, description, image_url, variants
-
-        Examples:
-            ```python
-            # Text search
-            products = client.search(query="blue denim jacket")
-
-            # Image search
-            products = client.search(image_url="https://example.com/image.jpg")
-
-            # Multimodal search
-            products = client.search(
-                query="blue denim jacket",
-                base64_image="data:image/jpeg;base64,...",
-            )
-
-            # Search with filters
-            products = client.search(
-                query="running shoes",
-                filters={
-                    "colors": ["black", "white"],
-                    "min_price": 50.0,
-                    "max_price": 150.0
-                },
-                limit=10
-            )
-            ```
-        """
-        payload = {
-            "query": query,
-            "image_url": image_url,
-            "base64_image": base64_image,
-            "limit": limit,
-        }
-
-        if filters:
-            payload["filters"] = filters
-
-        response = requests.post(
-            f"{self.base_url}/search",
-            json={k: v for k, v in payload.items() if v is not None},
-            headers=self.headers,
-        )
-        response.raise_for_status()
-        return response.json()
-
-    def get_product(self, product_id: str) -> Dict[str, Any]:
-        """
-        Get detailed information about a specific product by its ID.
-
-        Args:
-            product_id: The unique identifier of the product
-
-        Returns:
-            Dictionary containing detailed product information:
-                url, brand_id, brand_name, title, description, image_urls, variants,
-                price, gender, materials, key_features
-
-        Raises:
-            requests.HTTPError: If the product does not exist or other API errors occur
-
-        Example:
-            ```python
-            product_detail = client.get_product("prod_123456")
-            print(product_detail["title"])
-            print(product_detail["price"]["price"])
-            ```
-        """
-        response = requests.get(
-            f"{self.base_url}/products/{product_id}",
-            headers=self.headers,
-        )
-        response.raise_for_status()
-        return response.json()

channel3_sdk-0.0.1/pyproject.toml

@@ -1,17 +0,0 @@
-[tool.poetry]
-name = "channel3-sdk"
-version = "0.0.1"
-description = "The API for AI Shopping"
-authors = ["Alex <alex@trychannel3.com>"]
-readme = "README.md"
-license = "MIT"
-packages = [{ include = "channel3_sdk" }]
-
-[tool.poetry.dependencies]
-python = "^3.10"
-requests = "^2.31.0"
-
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"