Metadata-Version: 2.5
Name: getabrain
Version: 0.1.2
Summary: Official Python SDK for GetABrain.ai — real human judgment as an API
Project-URL: Homepage, https://getabrain.ai
Project-URL: Documentation, https://getabrain.ai/docs/api
Project-URL: Source, https://github.com/Guitarmaniac24/Getabrain.ai
Project-URL: Bug Tracker, https://github.com/Guitarmaniac24/Getabrain.ai/issues
Author-email: GetABrain <hello@getabrain.ai>
License-Expression: MIT
Keywords: ai,api,data-labeling,getabrain,human-in-the-loop,rlhf,sdk
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# getabrain

Official Python SDK for [GetABrain.ai](https://getabrain.ai) — real human judgment as an API.

## Install

```bash
pip install getabrain
```

## Quickstart

```python
from getabrain import GetABrain, InsufficientBalanceError

gab = GetABrain(api_key="gab_k_...", api_secret="gab_s_...")

# Submit a query (returns immediately)
query = gab.queries.create(
    type="ab_test",
    title="Which headline converts better?",
    content_data={
        "question": "Which is more compelling?",
        "variant_a": {"description": "Save 20% today"},
        "variant_b": {"description": "Your future self will thank you"},
    },
    required_responses=5,
    bid_amount_cents=25,
)

# Wait for humans to answer (polls for you)
try:
    responses = gab.queries.wait_for_responses(query["id"], min_responses=5, timeout_s=600)
    for r in responses:
        print(r["response_data"])
except InsufficientBalanceError:
    print("Top up your balance at https://getabrain.ai")
```

## API

- `gab.queries.create(type=..., title=..., content_data={...}, required_responses=..., bid_amount_cents=...)`
- `gab.queries.get(query_id)` · `gab.queries.list(status=..., limit=...)` · `gab.queries.cancel(query_id)`
- `gab.queries.wait_for_responses(query_id, min_responses=..., timeout_s=600, poll_interval_s=5)`
- `gab.responses.rate(query_id, response_id, score=5, feedback_text="...")` · `gab.responses.get_rating(query_id, response_id)`
- `gab.account.stats()` · `gab.account.balance()` · `gab.account.create_topup_link(amount_cents)` (Stripe Checkout URL a human opens to fund the account; works from a test key too)

Query types: `text`, `multiple_choice`, `rating_scale`, `image_comparison`, `ranking`, `yes_no`, `sentiment`, `image_selection`, `free_form_text`, `video_review`, `audio_review`, `image_analysis`, `ab_test`, `voice_capture`, `video_capture`, `photo_capture` (also exported as `getabrain.QUERY_TYPES`).

## Errors

All errors subclass `GetABrainError`: `ValidationError`, `AuthError`, `InsufficientBalanceError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError` (`.retry_after_ms`), `ServerError`, `TimeoutError`, `NetworkError`.

`InsufficientBalanceError.payment_required` carries the raw [x402](https://github.com/coinbase/x402) v2
payment-terms body when the server returned one (e.g. `err.payment_required["accepts"][0]["extra"]["deposit_endpoint"]`)
-- see "Stablecoin / x402 payments" below.

## Stablecoin / x402 payments

Balance top-ups also accept USDC (Base/Solana/Tempo), not just cards, via a Stripe crypto
PaymentIntent -- settlement is asynchronous (on-chain confirmation + Stripe capture, not instant).
The SDK doesn't wrap the billing endpoints yet (`gab.account.balance()` is read-only), so call the
REST endpoint directly:

```python
import requests

# Mint a real, one-time on-chain USDC deposit address for $50
res = requests.post(
    "https://getabrain.ai/api/v1/requestor/billing/crypto-checkout",
    headers={"X-API-Key": api_key, "X-API-Secret": api_secret},
    json={"amount_cents": 5000, "network": "base"},
)
deposit_details = res.json()["deposit_details"]  # send USDC here, then poll gab.account.balance()
```

Full API docs: https://getabrain.ai/docs/api
