Metadata-Version: 2.4
Name: coinbellai
Version: 0.1.0
Summary: Official Python SDK for the CoinBell AI crypto prediction API
Project-URL: Homepage, https://coinbell-ai.com
Project-URL: Documentation, https://coinbell-ai.com/docs/api
Author: CoinBell AI
License: MIT
License-File: LICENSE
Keywords: ai,bitcoin,coinbell,coinbellai,crypto,prediction,trading
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# CoinBell AI — Python SDK

Embed CoinBell AI crypto price forecasts into your Python application.

## Install

```bash
pip install coinbellai
```

## Quickstart

```python
from coinbellai import Client

client = Client(api_key="cb_live_...")  # or set COINBELL_API_KEY

# predict() submits the job and polls until it's done (~120s typical).
result = client.predict("bitcoin", duration=7, model="nova-pulse")

print(result["prediction"])           # full forecast object
print(result["completedAt"])
```

Get an API key from the CoinBell dashboard → **Settings → API Keys**.

## Async (submit + poll)

Predictions take ~120s, so the API is asynchronous. `predict()` blocks and polls
for you; if you'd rather manage it yourself (job queues, webhooks, UIs):

```python
job = client.submit("bitcoin", duration=7, model="nova-pulse")
print(job["id"], job["status"])       # -> "...", "queued"

# later — poll yourself, or use client.wait(job["id"])
status = client.get_prediction(job["id"])
if status["status"] == "completed":
    print(status["prediction"])
```

## `predict()`

| Argument | Type | Default | Notes |
|---|---|---|---|
| `symbol` | str | — | CoinGecko coin id, e.g. `"bitcoin"`, `"ethereum"` |
| `duration` | int | `7` | Forecast horizon in days (1–90) |
| `model` | str | `"nova-spark"` | `nova-spark` (1cr), `nova-pulse` (3cr), `nova-cortex` (10cr) |
| `current_price` | float | `None` | Optional; fetched server-side if omitted |
| `language` | str | `"en"` | `"en"` or `"zh"` |
| `context` | str | `None` | Optional free-text to steer the analysis |

## Configuration

- `COINBELL_API_KEY` — used when `api_key` is not passed.
- `COINBELL_BASE_URL` — override the API base URL (self-host / staging).

## Errors

```python
from coinbellai import (
    AuthenticationError,       # 401 — bad/missing/revoked key
    InsufficientCreditsError,  # 402 — not enough credits
    RateLimitError,            # 429 — has .retry_after
    APIError,                  # other 4xx/5xx
    CoinBellError,             # base class
)

try:
    client.predict("bitcoin")
except InsufficientCreditsError as e:
    print("Top up credits:", e.body)
except RateLimitError as e:
    print("Slow down, retry after", e.retry_after, "s")
```

Zero runtime dependencies (stdlib `urllib` only). Python 3.8+.
