Metadata-Version: 2.4
Name: ada-diamonds
Version: 1.0.0
Summary: Official Python client for the Ada Diamonds API: live lab grown diamond inventory, engagement ring settings, fine jewelry, and buying guides. No account required to read the catalog.
Author-email: "Ada Diamonds, Inc." <it@adadiamonds.com>
License: MIT
Project-URL: Homepage, https://www.adadiamonds.com/developers
Project-URL: Documentation, https://www.adadiamonds.com/developers/api
Project-URL: Repository, https://github.com/adadiamonds/ada-diamonds-nextjs
Project-URL: Source, https://github.com/adadiamonds/ada-diamonds-nextjs/tree/main/packages/ada-python
Project-URL: Bug Tracker, https://www.adadiamonds.com/developers#support
Project-URL: OpenAPI, https://www.adadiamonds.com/openapi.json
Project-URL: MCP Server, https://www.adadiamonds.com/developers/mcp
Keywords: ada-diamonds,adadiamonds,lab-grown-diamonds,lab-diamonds,diamonds,engagement-rings,jewelry,api,sdk,ai-agent,mcp,openapi
Classifier: Development Status :: 5 - Production/Stable
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 :: Only
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.9
Description-Content-Type: text/markdown

# ada-diamonds

Official Python client for the [Ada Diamonds](https://www.adadiamonds.com) API: live lab grown diamond inventory, engagement ring settings, fine jewelry, and diamond buying guides.

Pure Python, no dependencies beyond the standard library. Python 3.9 or newer.

## Install

```bash
pip install ada-diamonds
```

Publishing to PyPI is pending. Until the release lands, install from the repository:

```bash
pip install "git+https://github.com/adadiamonds/ada-diamonds-nextjs.git#subdirectory=packages/ada-python"
```

Reading the catalog needs no account and no API key.

## Examples

### Search live diamond inventory

```python
from ada_diamonds import Client

client = Client()  # anonymous, 120 requests per minute
page = client.diamonds(shape="Oval", min_carat=1, max_price=4000, sort="price_asc")
for stone in page["data"]:
    print(stone["carat"], stone["shape"], stone["color"], stone["clarity"], stone["price"])
print(page["pagination"])      # {'total': ..., 'limit': 25, 'offset': 0, 'has_more': ...}
print(client.last_rate_limit)  # RateLimit({'limit': 120, 'remaining': 119, 'reset': 58, ...})
```

### Quote a complete engagement ring

An engagement ring is a setting plus a loose diamond, priced separately. `price_from` on a setting excludes the center stone. All prices are US dollars.

```python
setting = client.engagement_rings(shape="Oval", type="Solitaire", limit=1)["data"][0]
stone = client.diamonds(shape="Oval", min_carat=1.5, max_carat=1.6, sort="price_asc", limit=1)["data"][0]
print(setting["name"], "+", stone["carat"], "ct =", setting["price_from"] + stone["price"])
```

### Get a key, then write

```python
from ada_diamonds import AdaApiError, Client

issued = Client().create_key("my-agent", env="sandbox")   # no account needed
client = Client(api_key=issued["api_key"])                  # 600 requests per minute

try:
    result = client.request_consultation(
        {"email": "test@example.com", "topic": "engagement_ring"},
        idempotency_key="consult-0001",
    )
    print(result)  # sandbox keys return {"sandbox": true, ...} and contact nobody
except AdaApiError as exc:
    print(exc.status, exc.error, exc.error_description, exc.documentation_url)
```

## Methods

| Method | Endpoint |
| --- | --- |
| `diamonds(**filters)` | `GET /api/v1/diamonds` |
| `diamond(id)` | `GET /api/v1/diamonds/{id}` |
| `engagement_rings(**filters)` | `GET /api/v1/engagement-rings` |
| `engagement_ring(slug)` | `GET /api/v1/engagement-rings/{slug}` |
| `jewelry(**filters)` | `GET /api/v1/jewelry` |
| `jewelry_item(slug)` | `GET /api/v1/jewelry/{slug}` |
| `knowledge_base(q=None)` | `GET /api/v1/knowledge-base` |
| `article(slug)` | `GET /api/v1/knowledge-base/{slug}` |
| `showrooms()` | `GET /api/v1/showrooms` |
| `request_consultation(payload, idempotency_key=None)` | `POST /api/v1/consultations` |
| `create_key(name, env="sandbox")` | `POST /api/v1/keys` |
| `batch(requests)` | `POST /api/v1/batch` |
| `ask(query)` | `GET /ask` (NLWeb) |
| `request(method, path, params=None, body=None, headers=None)` | any endpoint |

Errors raise `AdaApiError` with `status`, `error`, `error_description`, `documentation_url`, and `retry_after_seconds` (on 429). After every call `client.last_rate_limit` holds the `RateLimit-*` headers and `client.last_headers` the full header map.

Pass `base_url=` to point at another host, for example a preview deployment.

## Also available

- REST API reference: <https://www.adadiamonds.com/developers/api>
- OpenAPI 3.1: <https://www.adadiamonds.com/openapi.json>
- MCP server (Streamable HTTP): `https://www.adadiamonds.com/mcp`, docs at <https://www.adadiamonds.com/developers/mcp>
- CLI: `npx @ada-diamonds/cli`, docs at <https://www.adadiamonds.com/developers/cli>
- Authentication: <https://www.adadiamonds.com/developers/authentication>

## Support

Developer questions: it@adadiamonds.com. Automated bulk scraping of the site is not permitted; this API is the supported way to read the catalog.

## License

MIT
