Metadata-Version: 2.4
Name: pangolinfo-alexa
Version: 0.1.0
Summary: Python SDK for the Pangolinfo Amazon Alexa (Rufus) Shopping API
Project-URL: Homepage, https://docs.pangolinfo.com
Project-URL: Documentation, https://docs.pangolinfo.com
Project-URL: Repository, https://github.com/Pangolin-spg/pangolinfo-alexa
Project-URL: Changelog, https://github.com/Pangolin-spg/pangolinfo-alexa/releases
Project-URL: Issues, https://github.com/Pangolin-spg/pangolinfo-alexa/issues
Project-URL: Free API Key, https://tool.pangolinfo.com
Author-email: "Pangolin Info Tech Pte. Ltd." <support@pangolinfo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-shopping,alexa,amazon,api,pangolinfo,product-recommendation,rufus,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# pangolinfo-alexa

Python SDK for the **Pangolinfo Amazon Alexa (Rufus) Shopping API**.

This SDK provides a thin, typed wrapper around the Pangolinfo `amazonAlexa`
scraper, letting you drive Amazon's Alexa/Rufus shopping assistant
programmatically — submit prompts, receive Alexa's natural-language answers,
recommended products, follow-up questions, and optional page screenshots.

## Features

- Simple, synchronous `AlexaClient` based on `httpx`
- Accepts a single prompt or a list of prompts (multi-turn conversations)
- Returns structured product data (ASIN, price, ratings, cover image, ...)
- Optional page URL context and screenshot capture
- Clear exception hierarchy (`AuthenticationError`, `APIError`, `TimeoutError`)
- Context-manager support for automatic resource cleanup

## Installation

```bash
pip install pangolinfo-alexa
```

## Authentication

You need a Pangolinfo API token (Bearer token). Get a free API key at
<https://tool.pangolinfo.com>.

## Quick Start

```python
from pangolinfo_alexa import AlexaClient

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask("What are the best noise-cancelling headphones under $200?")
    for turn in data["json"]:
        print(turn["content"])
        for product in turn.get("products", []):
            for item in product.get("items", []):
                print(item["asin"], item["title"], item["price"])
```

## Multi-turn conversation

Pass a list of prompts — each element is one conversation turn. The response
`data["json"]` array will contain one result element per turn, in order.

```python
with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask([
        "Recommend a gift for a 6-year-old boy.",
        "Are any of those educational?",
    ])
    for turn in data["json"]:
        print(turn["prompt"], "->", turn["content"])
```

## API Reference

### `AlexaClient`

```python
AlexaClient(token, base_url="https://scrapeapi.pangolinfo.com", timeout=180)
```

#### Parameters

| Name      | Type   | Default                          | Description                                                                 |
| --------- | ------ | -------------------------------- | --------------------------------------------------------------------------- |
| `token`   | `str`  | — (required)                     | Pangolinfo API Bearer token.                                                |
| `base_url`| `str`  | `https://scrapeapi.pangolinfo.com` | API base URL.                                                               |
| `timeout` | `int`  | `180`                            | Request timeout in seconds. Alexa responses take 60–120s, so extra time is given. |

#### Methods

##### `ask(prompt, url=None, screenshot=False)`

Submit one or more prompts to Amazon Alexa (Rufus) and return the parsed
response data.

**Parameters:**

| Name        | Type            | Default | Description                                                                 |
| ----------- | --------------- | ------- | --------------------------------------------------------------------------- |
| `prompt`    | `str` or `list[str]` | — (required) | A single prompt string, or a list of prompts (one per conversation turn). Recommended ≤ 5 prompts. |
| `url`       | `str` or `None` | `None`  | Optional Amazon page URL to provide contextual intelligent responses based on page content. |
| `screenshot`| `bool`          | `False` | Whether to capture page screenshots.                                        |

**Returns:** `dict` — the `data` field of the API response, containing:

| Key         | Type      | Description                                                |
| ----------- | --------- | ---------------------------------------------------------- |
| `json`      | `list`    | Array of per-turn result objects (one per prompt).         |
| `taskId`    | `str`     | Server-side task identifier.                               |
| `url`       | `str`     | Echoed/processed URL (may be empty).                       |
| `screenshot`| `str`     | Screenshot URL if `screenshot=True`, otherwise empty.      |

**Per-turn result object** (each element of `data["json"]`):

| Key                  | Type       | Description                                         |
| -------------------- | ---------- | --------------------------------------------------- |
| `prompt`             | `str`      | The prompt that produced this turn.                 |
| `content`            | `str`      | Alexa's natural-language text response.             |
| `products`           | `list`     | Recommended product groups (see below).             |
| `follow_up_questions`| `list[str]`| Suggested follow-up questions.                      |
| `screenshot`         | `str`      | Per-turn screenshot URL (if enabled).               |

**Product group** (element of `turn["products"]`):

| Key     | Type    | Description                                  |
| ------- | ------- | -------------------------------------------- |
| `title` | `str`   | Group/category title.                        |
| `items` | `list`  | Array of product items (see below).          |

**Product item** (element of `group["items"]`):

| Key             | Type    | Description                                  |
| --------------- | ------- | -------------------------------------------- |
| `asin`          | `str`   | Amazon Standard Identification Number.       |
| `url`           | `str`   | Product page URL.                            |
| `title`         | `str`   | Product title.                               |
| `cover`         | `str`   | Cover/main image URL.                        |
| `score`         | `float` | Star rating (e.g. 4.5).                      |
| `ratingsCount`  | `int`   | Number of customer ratings.                  |
| `price`         | `str`   | Current price (formatted string).            |
| `originalPrice` | `str`   | Original/list price (formatted string).      |
| `describe`      | `str`   | Short product description / feature summary. |

##### `close()`

Close the underlying HTTP connection pool.

##### Context manager

`AlexaClient` supports `with` syntax — `close()` is called automatically on exit.

### Exceptions

All exceptions live in `pangolinfo_alexa.exceptions` and are re-exported from
the top-level package.

| Exception            | Base                | Raised when                                  |
| -------------------- | ------------------- | -------------------------------------------- |
| `AlexaError`         | `Exception`         | Base class for all SDK errors.               |
| `AuthenticationError`| `AlexaError`        | HTTP 401/403 — invalid or missing token.     |
| `APIError`           | `AlexaError`        | API returns `code != 0` or a non-2xx status. |
| `TimeoutError`       | `AlexaError`        | Request times out.                           |

## Credit Consumption

- **6 credits per conversation turn**, billed by the length of the `param` array.
- Example: 1 prompt = 6 credits; 5 prompts = 30 credits.
- Average response time: **60–120 seconds**.

## Examples

### Single prompt

```python
from pangolinfo_alexa import AlexaClient

with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask("Best mechanical keyboard for coding")
    print(data["json"][0]["content"])
```

### With page context and screenshot

```python
with AlexaClient(token="YOUR_TOKEN") as client:
    data = client.ask(
        "What are the top reviews for this product?",
        url="https://www.amazon.com/dp/B0XXXXXXXX",
        screenshot=True,
    )
    print(data["screenshot"])
```

### Error handling

```python
from pangolinfo_alexa import AlexaClient, AuthenticationError, APIError, TimeoutError

try:
    with AlexaClient(token="YOUR_TOKEN", timeout=200) as client:
        data = client.ask("Hello")
except AuthenticationError:
    print("Invalid token")
except TimeoutError:
    print("Request timed out — Alexa can take up to 120s")
except APIError as e:
    print(f"API error: {e}")
```

## Links

- Documentation: <https://docs.pangolinfo.com>
- Source code: <https://github.com/Pangolin-spg/pangolinfo-alexa>
- Issue tracker: <https://github.com/Pangolin-spg/pangolinfo-alexa/issues>
- Changelog: <https://github.com/Pangolin-spg/pangolinfo-alexa/releases>
- Free API Key: <https://tool.pangolinfo.com>

## License

MIT — Copyright (c) 2026 PANGOLIN INFO TECH PTE. LTD.
