Metadata-Version: 2.4
Name: llama-index-tools-buywhere
Version: 0.1.0
Summary: LlamaIndex integration for BuyWhere — search products, discover deals, and browse categories through the BuyWhere product catalog API
Author-email: BuyWhere <api@buywhere.ai>
License-Expression: MIT
Project-URL: Home, https://buywhere.ai
Project-URL: Source, https://github.com/buywhere/buywhere-site
Project-URL: Documentation, https://api.buywhere.ai/docs/guides/llamaindex
Keywords: buywhere,llamaindex,mcp,product-search,shopping,ai-agent,ecommerce
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: llama-index-core>=0.11.0
Requires-Dist: httpx>=0.27.0

# llama-index-tools-buywhere

BuyWhere product catalog tools for LlamaIndex agents. Search products, discover deals, and browse categories across 1.5M+ products from Shopee, Lazada, Amazon, Walmart, and 20+ platforms.

```bash
pip install llama-index-tools-buywhere
```

## Quick Start

```python
import os
from llama_index.tools.buywhere import BuyWhereToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

os.environ["BUYWHERE_API_KEY"] = "bw_live_xxx"

tool_spec = BuyWhereToolSpec()
agent = FunctionAgent(
    tools=tool_spec.to_tool_list(),
    llm=OpenAI(model="gpt-4o"),
    system_prompt="You are a helpful shopping assistant.",
)

response = agent.run("find wireless headphones under SGD 50 in Singapore")
print(response)
```

## Tools

| Tool | Description |
|------|-------------|
| `search_products` | Full-text search with price, category, merchant, and region filters |
| `get_deals` | Discounted products sorted by discount percentage |
| `list_categories` | Browse available product categories with counts |

## API

### `BuyWhereToolSpec`

| Method | Returns | Description |
|--------|---------|-------------|
| `to_tool_list()` | `list[FunctionTool]` | All 3 tools as LlamaIndex FunctionTool instances |
| `to_tool_dict()` | `dict[str, FunctionTool]` | Tools keyed by name |

Constructor:

```python
BuyWhereToolSpec(
    api_key: str | None = None,      # API key or BUYWHERE_API_KEY env var
    base_url: str = "https://api.buywhere.ai",
    timeout: float = 30.0,
)
```

## Error Handling

| Exception | When |
|-----------|------|
| `BuyWhereAuthError` | Missing, invalid, or expired API key |
| `BuyWhereNetworkError` | Timeout, connection failure, or HTTP error |
| `BuyWhereRateLimitError` | Rate limit exceeded (HTTP 429) |

All tool methods return `list[Document]` — LlamaIndex Document objects with structured metadata for downstream processing.
