Metadata-Version: 2.5
Name: medullabs
Version: 0.1.0
Summary: Official Python client for the MedullaAI API
Project-URL: Homepage, https://platform.medullabs.com/docs/sdks/python
Project-URL: Documentation, https://platform.medullabs.com/docs/sdks/python
Author-email: Medullabs Technologies Private Limited <support@medullabs.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,attention,eye-tracking,medullabs,neuromarketing,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.26
Description-Content-Type: text/markdown

# medullabs

Official Python client for the [MedullaAI API](https://platform.medullabs.com/docs).

- Upload an image once, then run any analysis against it.
- Timeouts, retries and idempotency keys are handled for you, so a retry never charges twice.
- Sync and async clients, fully typed.
- Python 3.9 or newer. One dependency: [`httpx`](https://www.python-httpx.org/).

> **Server-side only.** Your API key is a secret. Call the API from your backend, never from
> code that runs on your users' devices.

**Full documentation:** https://platform.medullabs.com/docs/sdks/python

## Install

```sh
pip install medullabs
```

## Quickstart

```python
from medullabs import Medullabs

client = Medullabs()  # reads the MEDULLABS_API_KEY environment variable

# 1. Upload once. Free.
media = client.media.upload("creative.png")

# 2. Run analyses against the uid.
attention = client.attention(uid=media.uid)
load = client.cognitive_load(uid=media.uid, industry="FMCG")

print(load.charged_credits, load.result)
```

### Async

```python
import asyncio
from medullabs import AsyncMedullabs


async def main() -> None:
    async with AsyncMedullabs() as client:
        media = await client.media.upload("creative.png")
        r = await client.attention(uid=media.uid)
        print(r.charged_credits)


asyncio.run(main())
```

## Methods

| Method | API | Credits |
|---|---|---|
| `media.upload(file)` | `POST /v1/media` | free |
| `media.get(uid)` / `media.delete(uid)` | `GET` / `DELETE /v1/media/{uid}` | free |
| `industries()` | `GET /v1/industries` | free |
| `attention(uid=)` | `POST /v1/attention` | 2 |
| `cognitive_load(uid=, industry=)` | `POST /v1/cognitive-load` | 1 |
| `focus_score(uid=, industry=)` | `POST /v1/focus-score` | 1 |
| `emotion(uid=, industry=, human_present=)` | `POST /v1/emotion` | 1 |
| `aoi(uid=, final_dict=, industry=None)` | `POST /v1/aoi` | 3 |
| `analyze(uid=, industry=, human_present=, final_dict=)` | `POST /v1/analyze` | 5 |
| `validate(uid=, campaign_objective=, industry=, ...)` | `POST /v1/validate` | 3 |

`media.upload` accepts a file path, `bytes`, or a file opened in binary mode (`open(path, "rb")`).

Every analysis returns a `FeatureResult` with `request_id`, `uid`, `status`, `feature`,
`charged_credits` (an `int`), `result` (a `dict`, overlays inline as base64), `created_at`,
`finished_at`, `replayed` (`True` for a free replay) and `rate_limit`.

## Errors

Every error is a `MedullabsError` with `code`, `status`, `message`, `details`, `request_id`
(quote it to support) and `idempotency_key`.

```python
from medullabs import InsufficientCreditsError, RateLimitError, ValidationError

try:
    client.emotion(uid=uid, industry="FMCG", human_present=True)
except InsufficientCreditsError:
    ...  # top up
except RateLimitError as e:
    ...  # wait e.retry_after seconds
except ValidationError as e:
    print(e.message)  # e.g. "industry: Invalid enum value"
```

Classes: `ValidationError` (400/422), `AuthenticationError` (401), `InsufficientCreditsError`
(402), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409),
`RateLimitError` (429), `ServerError` (5xx), `APIConnectionError` and `APITimeoutError` (no
response). You are never charged for a failed call.

## Retries and timeouts

The client retries server errors, dropped connections and short rate-limit waits, up to
`max_retries` (default 2), reusing the same `Idempotency-Key` so a retry never charges twice.
The default timeout is 400 seconds, enough for the slowest analysis.

```python
client = Medullabs(
    api_key="sk_live_...",  # or MEDULLABS_API_KEY
    timeout=400.0,  # seconds per attempt
    max_retries=2,
    max_retry_wait=60.0,  # longest Retry-After to wait out automatically
)
```

## License

MIT
