Metadata-Version: 2.4
Name: bitbabble-sdk
Version: 1.0.2
Summary: Official Python SDK for the BitBabble sentiment analysis API
Author: BitBabble
License-Expression: MIT
Project-URL: Homepage, https://bitbabble.net
Project-URL: Documentation, https://bitbabble.net/docs
Project-URL: Repository, https://github.com/bitbabble/bitbabble-sdk
Keywords: bitbabble,sentiment,sentiment-analysis,nlp,api,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0

# bitbabble-sdk

Official Python SDK for the [BitBabble](https://bitbabble.net) sentiment analysis API.

**Get 100 tokens free when you sign up.** Create an account at [bitbabble.net](https://bitbabble.net) to receive your API key.

## Creating an Account

1. Go to [bitbabble.net](https://bitbabble.net)
2. Sign up for a new account
3. Copy your API key from the dashboard
4. **100 tokens** are credited automatically—no credit card required

## Installation

```bash
pip install bitbabble-sdk
```

## Quick Start

```python
from bitbabble import BitBabbleClient

client = BitBabbleClient(api_key="bb_your_api_key")
result = client.sentiment("I love this product!")

print(result)
# {
#     "sentiment": "positive",
#     "score": 0.82,
#     "confidence": "high",
#     "cached": False,
# }
```

## API

### `BitBabbleClient(api_key, *, base_url=...)`

| Parameter  | Type  | Description                          |
| ---------- | ----- | ------------------------------------ |
| `api_key`  | `str` | Your BitBabble API key               |
| `base_url` | `str` | Override the API base URL (optional) |

### `client.sentiment(text)`

Analyze the sentiment of a text string (1–140 characters).

Returns a `SentimentResult` (TypedDict):

| Field        | Type                                       | Description                              |
| ------------ | ------------------------------------------ | ---------------------------------------- |
| `sentiment`  | `"negative" \| "neutral" \| "positive"`    | Predicted sentiment label                |
| `score`      | `float`                                    | Score from -1 (bearish) to +1 (bullish)  |
| `confidence` | `"low" \| "medium" \| "high"`              | Confidence of the prediction             |
| `cached`     | `bool`                                     | Whether the result was served from cache |

## Error Handling

```python
from bitbabble import (
    BitBabbleClient,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
)

try:
    result = client.sentiment("some text")
except AuthenticationError:
    # 401 — invalid or missing API key
    ...
except InsufficientCreditsError:
    # 402 — out of credits
    ...
except RateLimitError:
    # 429 — too many requests
    ...
```

## Requirements

- Python 3.8+
- [httpx](https://www.python-httpx.org/)

## License

MIT
