getabrain 0.1.0__tar.gz

getabrain-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/

getabrain-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: getabrain
+Version: 0.1.0
+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()`
+
+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`.
+
+## Errors
+
+All errors subclass `GetABrainError`: `ValidationError`, `AuthError`, `InsufficientBalanceError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError` (`.retry_after_ms`), `ServerError`, `TimeoutError`, `NetworkError`.
+
+Full API docs: https://getabrain.ai/docs/api

getabrain-0.1.0/README.md

@@ -0,0 +1,54 @@
+# 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()`
+
+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`.
+
+## Errors
+
+All errors subclass `GetABrainError`: `ValidationError`, `AuthError`, `InsufficientBalanceError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError` (`.retry_after_ms`), `ServerError`, `TimeoutError`, `NetworkError`.
+
+Full API docs: https://getabrain.ai/docs/api

getabrain-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getabrain"
+version = "0.1.0"
+description = "Official Python SDK for GetABrain.ai — real human judgment as an API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "GetABrain", email = "hello@getabrain.ai" }]
+keywords = ["getabrain", "human-in-the-loop", "ai", "api", "sdk", "rlhf", "data-labeling"]
+dependencies = ["httpx>=0.27"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://getabrain.ai"
+Documentation = "https://getabrain.ai/docs/api"
+Source = "https://github.com/Guitarmaniac24/Getabrain.ai"
+"Bug Tracker" = "https://github.com/Guitarmaniac24/Getabrain.ai/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getabrain"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

getabrain-0.1.0/src/getabrain/__init__.py

@@ -0,0 +1,57 @@
+"""getabrain — official Python SDK for GetABrain.ai."""
+from __future__ import annotations
+
+from .client import GetABrain
+from .errors import (
+    GetABrainError,
+    ValidationError,
+    AuthError,
+    InsufficientBalanceError,
+    ForbiddenError,
+    NotFoundError,
+    ConflictError,
+    ServerError,
+    RateLimitError,
+    TimeoutError,
+    NetworkError,
+    error_from_response,
+)
+from .types import (
+    QUERY_TYPES,
+    QueryType,
+    Query,
+    QueryResponse,
+    QueryList,
+    RatingResult,
+    Rating,
+    AccountStats,
+    BillingInfo,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GetABrain",
+    "GetABrainError",
+    "ValidationError",
+    "AuthError",
+    "InsufficientBalanceError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "ServerError",
+    "RateLimitError",
+    "TimeoutError",
+    "NetworkError",
+    "error_from_response",
+    "QUERY_TYPES",
+    "QueryType",
+    "Query",
+    "QueryResponse",
+    "QueryList",
+    "RatingResult",
+    "Rating",
+    "AccountStats",
+    "BillingInfo",
+    "__version__",
+]

getabrain-0.1.0/src/getabrain/_http.py

@@ -0,0 +1,85 @@
+"""HTTP transport: builds an httpx.Client and a `_request` callable with auth,
+JSON-envelope error mapping, and GET-only retries."""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import httpx
+
+from .errors import NetworkError, TimeoutError, error_from_response
+
+DEFAULT_BASE_URL = "https://www.getabrain.ai/api/v1"
+
+RequestFn = Callable[..., Any]
+
+
+def _backoff(attempt: int) -> float:
+    return min(2.0 ** (attempt - 1), 8.0)
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return int(float(value) * 1000)
+    except ValueError:
+        return None
+
+
+def build_transport(
+    *,
+    api_key: str,
+    api_secret: str,
+    base_url: Optional[str] = None,
+    timeout_s: float = 30.0,
+    max_retries: int = 2,
+    transport: Optional[httpx.BaseTransport] = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Tuple[httpx.Client, RequestFn]:
+    base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    client = httpx.Client(
+        timeout=timeout_s,
+        transport=transport,
+        headers={
+            "X-API-Key": api_key,
+            "X-API-Secret": api_secret,
+            "Content-Type": "application/json",
+        },
+    )
+
+    def request(method: str, path: str, *, body: Any = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        url = base + path
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        is_read = method.upper() == "GET"
+        attempt = 0
+        while True:
+            try:
+                resp = client.request(method, url, json=body, params=clean or None)
+            except httpx.TimeoutException:
+                raise TimeoutError()
+            except httpx.TransportError as exc:
+                if is_read and attempt < max_retries:
+                    attempt += 1
+                    sleep(_backoff(attempt))
+                    continue
+                raise NetworkError(str(exc))
+
+            if resp.is_success:
+                if resp.status_code == 204:
+                    return None
+                return resp.json()
+
+            retry_after_ms = _parse_retry_after(resp.headers.get("retry-after"))
+            if is_read and (resp.status_code == 429 or resp.status_code >= 500) and attempt < max_retries:
+                attempt += 1
+                sleep(retry_after_ms / 1000 if retry_after_ms is not None else _backoff(attempt))
+                continue
+
+            try:
+                err_body = resp.json()
+            except Exception:
+                err_body = None
+            raise error_from_response(resp.status_code, err_body, retry_after_ms)
+
+    return client, request

getabrain-0.1.0/src/getabrain/client.py

@@ -0,0 +1,58 @@
+"""The GetABrain client — wires config -> transport -> resources."""
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+import httpx
+
+from ._http import build_transport
+from .resources.account import AccountResource
+from .resources.queries import QueriesResource
+from .resources.responses import ResponsesResource
+
+
+class GetABrain:
+    """Client for the GetABrain requestor API.
+
+    Example:
+        gab = GetABrain(api_key="gab_k_...", api_secret="gab_s_...")
+        q = gab.queries.create(type="yes_no", title="Is it live?",
+                               content_data={"question": "Is it live?"},
+                               required_responses=2, bid_amount_cents=50)
+        responses = gab.queries.wait_for_responses(q["id"], min_responses=2)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout_s: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._client, request = build_transport(
+            api_key=api_key,
+            api_secret=api_secret,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            max_retries=max_retries,
+            transport=transport,
+            sleep=sleep,
+        )
+        self.queries = QueriesResource(request)
+        self.responses = ResponsesResource(request)
+        self.account = AccountResource(request)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "GetABrain":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

getabrain-0.1.0/src/getabrain/errors.py

@@ -0,0 +1,103 @@
+"""Typed error hierarchy mirroring the GetABrain HTTP envelope."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class GetABrainError(Exception):
+    """Base error. `status` is the HTTP status (0 for client-side errors)."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        code: str = "error",
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+
+class ValidationError(GetABrainError):
+    pass
+
+
+class AuthError(GetABrainError):
+    pass
+
+
+class InsufficientBalanceError(GetABrainError):
+    pass
+
+
+class ForbiddenError(GetABrainError):
+    pass
+
+
+class NotFoundError(GetABrainError):
+    pass
+
+
+class ConflictError(GetABrainError):
+    pass
+
+
+class ServerError(GetABrainError):
+    pass
+
+
+class RateLimitError(GetABrainError):
+    def __init__(
+        self,
+        message: str,
+        status: int = 429,
+        code: str = "error",
+        retry_after_ms: Optional[int] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status, code, request_id)
+        self.retry_after_ms = retry_after_ms
+
+
+class TimeoutError(GetABrainError):
+    """Request timed out, or wait_for_responses exceeded its deadline.
+
+    Subclasses GetABrainError (NOT the builtin TimeoutError) so callers can
+    `except GetABrainError`.
+    """
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message, 0, "timeout")
+
+
+class NetworkError(GetABrainError):
+    def __init__(self, message: str = "Network request failed") -> None:
+        super().__init__(message, 0, "network")
+
+
+def error_from_response(
+    status: int, body: Any, retry_after_ms: Optional[int] = None
+) -> GetABrainError:
+    b = body if isinstance(body, dict) else {}
+    message = b.get("message") or b.get("error") or f"HTTP {status}"
+    code = b.get("error") or "error"
+    if status == 400:
+        return ValidationError(message, status, code)
+    if status == 401:
+        return AuthError(message, status, code)
+    if status == 402:
+        return InsufficientBalanceError(message, status, code)
+    if status == 403:
+        return ForbiddenError(message, status, code)
+    if status == 404:
+        return NotFoundError(message, status, code)
+    if status == 409:
+        return ConflictError(message, status, code)
+    if status == 429:
+        return RateLimitError(message, status, code, retry_after_ms)
+    if status >= 500:
+        return ServerError(message, status, code)
+    return GetABrainError(message, status, code)

getabrain-0.1.0/src/getabrain/resources/account.py

@@ -0,0 +1,16 @@
+"""Account resource (stats + billing)."""
+from __future__ import annotations
+
+from .._http import RequestFn
+from ..types import AccountStats, BillingInfo
+
+
+class AccountResource:
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def stats(self) -> AccountStats:
+        return self._request("GET", "/requestor/stats")
+
+    def balance(self) -> BillingInfo:
+        return self._request("GET", "/requestor/billing")

getabrain-0.1.0/src/getabrain/resources/queries.py

@@ -0,0 +1,68 @@
+"""Queries resource."""
+from __future__ import annotations
+
+import time
+from urllib.parse import quote
+from typing import Any, Callable, Dict, List, Optional
+
+from .._http import RequestFn
+from ..errors import TimeoutError
+from ..types import Query, QueryList, QueryResponse
+
+_TERMINAL = {"completed", "cancelled", "failed", "expired"}
+
+
+class QueriesResource:
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def create(self, **input: Any) -> Query:
+        return self._request("POST", "/requestor/queries", body=input)
+
+    def get(self, query_id: str) -> Query:
+        return self._request("GET", f"/requestor/queries/{quote(query_id, safe='')}")
+
+    def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> QueryList:
+        return self._request(
+            "GET", "/requestor/queries",
+            params={"status": status, "limit": limit, "offset": offset},
+        )
+
+    def cancel(self, query_id: str) -> Dict[str, Any]:
+        return self._request(
+            "PUT", f"/requestor/queries/{quote(query_id, safe='')}",
+            body={"action": "cancel"},
+        )
+
+    def wait_for_responses(
+        self,
+        query_id: str,
+        *,
+        min_responses: int,
+        timeout_s: float = 600.0,
+        poll_interval_s: float = 5.0,
+        sleep: Callable[[float], None] = time.sleep,
+        now: Callable[[], float] = time.monotonic,
+    ) -> List[QueryResponse]:
+        deadline = now() + timeout_s
+        while True:
+            query = self.get(query_id)
+            responses = query.get("responses") or []
+            completed = query.get("completed_responses")
+            if completed is None:
+                completed = len(responses)
+            if completed >= min_responses:
+                return responses
+            if query.get("status") in _TERMINAL:
+                return responses
+            if now() >= deadline:
+                raise TimeoutError(
+                    f"wait_for_responses timed out after {timeout_s}s for query {query_id}"
+                )
+            sleep(poll_interval_s)

getabrain-0.1.0/src/getabrain/resources/responses.py

@@ -0,0 +1,36 @@
+"""Responses resource (ratings)."""
+from __future__ import annotations
+
+from urllib.parse import quote
+from typing import Optional
+
+from .._http import RequestFn
+from ..types import Rating, RatingResult
+
+
+class ResponsesResource:
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def rate(
+        self,
+        query_id: str,
+        response_id: str,
+        *,
+        score: int,
+        feedback_text: Optional[str] = None,
+    ) -> RatingResult:
+        q = quote(query_id, safe="")
+        r = quote(response_id, safe="")
+        body: dict = {"score": score}
+        if feedback_text is not None:
+            body["feedback_text"] = feedback_text
+        return self._request(
+            "POST", f"/requestor/queries/{q}/responses/{r}/rate",
+            body=body,
+        )
+
+    def get_rating(self, query_id: str, response_id: str) -> Rating:
+        q = quote(query_id, safe="")
+        r = quote(response_id, safe="")
+        return self._request("GET", f"/requestor/queries/{q}/responses/{r}/rate")

getabrain-0.1.0/src/getabrain/types.py

@@ -0,0 +1,225 @@
+"""Query-type Literal + content/response TypedDicts (mirror of the OpenAPI contract).
+
+All TypedDicts are `total=False`: the SDK is a thin typed client and the server is
+the validation authority, so every field is optional at the type level. They give
+IDE help; they do not enforce required keys at runtime.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+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",
+)
+
+QueryType = Literal[
+    "text",
+    "multiple_choice",
+    "rating_scale",
+    "image_comparison",
+    "ranking",
+    "yes_no",
+    "sentiment",
+    "image_selection",
+    "free_form_text",
+    "video_review",
+    "audio_review",
+    "image_analysis",
+    "ab_test",
+]
+
+
+class TextContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    min_words: int
+    max_words: int
+
+
+class MultipleChoiceContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    options: List[Dict[str, Any]]
+    allow_multiple: bool
+    min_selections: int
+    max_selections: int
+
+
+class RatingScaleContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    scale_type: Literal["1-5", "1-10", "0-100", "stars"]
+    scale_min: int
+    scale_max: int
+    scale_labels: Dict[str, str]
+    criteria: List[str]
+
+
+class ImageComparisonContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    images: List[Dict[str, Any]]
+    comparison_type: Literal["preference", "quality", "relevance", "custom"]
+    require_reasoning: bool
+
+
+class RankingContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    items: List[Dict[str, Any]]
+    max_items: int
+    require_all: bool
+
+
+class YesNoContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    require_explanation: bool
+    min_explanation_words: int
+
+
+class SentimentContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    subject: str
+    sentiment_options: List[str]
+    require_reasoning: bool
+
+
+class ImageSelectionContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    images: List[Dict[str, Any]]
+    min_selections: int
+    max_selections: int
+    selection_criteria: str
+
+
+class FreeFormTextContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    prompt: str
+    min_characters: int
+    max_characters: int
+    format_guidelines: str
+
+
+class VideoReviewContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    video_url: str
+    video_duration_seconds: int
+    review_aspects: List[str]
+    min_watch_time_seconds: int
+
+
+class AudioReviewContent(TypedDict, total=False):
+    question: str
+    instructions: str
+    context: str
+    audio_url: str
+    audio_duration_seconds: int
+    review_aspects: List[str]
+    transcription_required: bool
+
+
+class ImageAnalysisContent(TypedDict, total=False):
+    question: str
+    image_url: str
+
+
+class AbTestContent(TypedDict, total=False):
+    question: str
+    variant_a: Dict[str, Any]
+    variant_b: Dict[str, Any]
+
+
+class QueryResponse(TypedDict, total=False):
+    id: str
+    response_data: Dict[str, Any]
+    status: str
+    submitted_at: str
+    worker: Dict[str, Any]
+    rating: Optional[Dict[str, Any]]
+
+
+class Query(TypedDict, total=False):
+    id: str
+    type: str
+    title: str
+    description: str
+    status: str
+    required_responses: int
+    completed_responses: int
+    bid_amount_cents: int
+    bonus_amount_cents: int
+    total_cost_cents: int
+    created_at: str
+    expires_at: Optional[str]
+    content_data: Dict[str, Any]
+    responses: List[QueryResponse]
+
+
+class QueryList(TypedDict, total=False):
+    queries: List[Query]
+    total: int
+    limit: int
+    offset: int
+    has_more: bool
+
+
+class RatingResult(TypedDict, total=False):
+    response_id: str
+    score: int
+    worker_new_quality_score: float
+    worker_new_rating_count: int
+    worker_suspended: bool
+    feedback_text: Optional[str]
+
+
+class Rating(TypedDict, total=False):
+    id: str
+    response_id: str
+    score: int
+    feedback_text: Optional[str]
+    created_at: str
+
+
+class AccountStats(TypedDict, total=False):
+    balance_cents: int
+    company_name: str
+    total_queries: int
+    active_queries: int
+    completed_queries: int
+    total_spent_cents: int
+    recent_queries: List[Query]
+
+
+class BillingInfo(TypedDict, total=False):
+    balance_cents: int
+    company_name: str
+    transactions: List[Dict[str, Any]]
+    total: int
+    has_more: bool

getabrain-0.1.0/tests/test_client.py

@@ -0,0 +1,107 @@
+import httpx
+
+from getabrain import GetABrain, QUERY_TYPES, InsufficientBalanceError
+import pytest
+
+
+def client_with(handler):
+    return GetABrain(api_key="gab_k_x", api_secret="gab_s_y",
+                     transport=httpx.MockTransport(handler))
+
+
+def test_exports_present():
+    assert "ab_test" in QUERY_TYPES
+    gab = GetABrain(api_key="gab_k_x", api_secret="gab_s_y")
+    assert gab.queries is not None
+    assert gab.responses is not None
+    assert gab.account is not None
+    gab.close()
+
+
+def test_context_manager_exposes_resources():
+    def handler(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"balance_cents": 0})
+
+    with client_with(handler) as gab:
+        assert gab.account is not None
+        assert gab.account.balance()["balance_cents"] == 0
+
+
+def test_rate_omits_feedback_text_when_not_provided():
+    seen = {}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        seen["body"] = req.content.decode()
+        return httpx.Response(200, json={"response_id": "r1", "score": 5,
+                                         "worker_new_quality_score": 4.9, "worker_suspended": False})
+
+    gab = client_with(handler)
+    gab.responses.rate("q1", "r1", score=5)
+    assert '"score"' in seen["body"]
+    assert "feedback_text" not in seen["body"]  # omitted, not sent as null
+
+
+def test_account_balance_and_stats():
+    paths = []
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        paths.append(req.url.path)
+        if req.url.path.endswith("/requestor/billing"):
+            return httpx.Response(200, json={"balance_cents": 900, "company_name": "X"})
+        return httpx.Response(200, json={"balance_cents": 900, "total_queries": 3})
+
+    gab = client_with(handler)
+    assert gab.account.balance()["balance_cents"] == 900
+    assert gab.account.stats()["total_queries"] == 3
+    assert "/api/v1/requestor/billing" in paths
+    assert "/api/v1/requestor/stats" in paths
+    gab.close()
+
+
+def test_responses_rate_posts_to_the_rate_path():
+    seen = {}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        seen["method"] = req.method
+        seen["path"] = req.url.path
+        seen["body"] = req.content.decode()
+        return httpx.Response(200, json={"response_id": "r1", "score": 5,
+                                         "worker_new_quality_score": 4.9, "worker_suspended": False})
+
+    gab = client_with(handler)
+    out = gab.responses.rate("q1", "r1", score=5, feedback_text="great")
+    assert out["score"] == 5
+    assert seen["method"] == "POST"
+    assert seen["path"] == "/api/v1/requestor/queries/q1/responses/r1/rate"
+    assert '"score"' in seen["body"] and '"great"' in seen["body"]
+
+
+def test_get_rating_gets_the_rate_path():
+    def handler(req: httpx.Request) -> httpx.Response:
+        assert req.method == "GET"
+        assert req.url.path == "/api/v1/requestor/queries/q1/responses/r1/rate"
+        return httpx.Response(200, json={"id": "rt1", "response_id": "r1", "score": 4})
+
+    gab = client_with(handler)
+    assert gab.responses.get_rating("q1", "r1")["score"] == 4
+
+
+def test_create_query_flows_through_transport():
+    def handler(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(201, json={"id": "q1", "status": "active", "total_cost_cents": 100})
+
+    gab = client_with(handler)
+    q = gab.queries.create(type="yes_no", title="Is it live?",
+                           content_data={"question": "Is it live?"},
+                           required_responses=2, bid_amount_cents=50)
+    assert q["id"] == "q1"
+
+
+def test_insufficient_balance_raises():
+    def handler(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(402, json={"error": "Payment Failed", "message": "Insufficient balance"})
+
+    gab = client_with(handler)
+    with pytest.raises(InsufficientBalanceError):
+        gab.queries.create(type="yes_no", title="x", content_data={"question": "x"},
+                           required_responses=1, bid_amount_cents=5)

getabrain-0.1.0/tests/test_errors.py

@@ -0,0 +1,55 @@
+from getabrain.errors import (
+    GetABrainError, ValidationError, AuthError, InsufficientBalanceError,
+    ForbiddenError, NotFoundError, ConflictError, ServerError, RateLimitError,
+    TimeoutError, NetworkError, error_from_response,
+)
+
+
+def test_base_error_fields():
+    e = GetABrainError("boom", 418, "teapot", "req_1")
+    assert e.message == "boom"
+    assert e.status == 418
+    assert e.code == "teapot"
+    assert e.request_id == "req_1"
+    assert str(e) == "boom"
+    assert isinstance(e, Exception)
+
+
+def test_error_from_response_maps_each_status():
+    body = {"error": "bad", "message": "nope"}
+    assert isinstance(error_from_response(400, body), ValidationError)
+    assert isinstance(error_from_response(401, body), AuthError)
+    assert isinstance(error_from_response(402, body), InsufficientBalanceError)
+    assert isinstance(error_from_response(403, body), ForbiddenError)
+    assert isinstance(error_from_response(404, body), NotFoundError)
+    assert isinstance(error_from_response(409, body), ConflictError)
+    assert isinstance(error_from_response(500, body), ServerError)
+    assert isinstance(error_from_response(503, body), ServerError)
+    # unmapped 4xx falls back to the base class
+    e = error_from_response(418, body)
+    assert type(e) is GetABrainError
+
+
+def test_error_message_and_code_extracted():
+    e = error_from_response(400, {"error": "validation_error", "message": "title too short"})
+    assert e.message == "title too short"
+    assert e.code == "validation_error"
+    # missing body -> synthesized message
+    e2 = error_from_response(500, None)
+    assert e2.message == "HTTP 500"
+
+
+def test_rate_limit_error_carries_retry_after_ms():
+    e = error_from_response(429, {"message": "slow down"}, retry_after_ms=5000)
+    assert isinstance(e, RateLimitError)
+    assert e.retry_after_ms == 5000
+
+
+def test_timeout_and_network_errors_subclass_base():
+    assert isinstance(TimeoutError(), GetABrainError)
+    assert isinstance(NetworkError(), GetABrainError)
+    assert TimeoutError().code == "timeout"
+    assert NetworkError().code == "network"
+    # subclasses are catchable as the base
+    for cls in (ValidationError, AuthError, RateLimitError, ServerError):
+        assert issubclass(cls, GetABrainError)

getabrain-0.1.0/tests/test_http.py

@@ -0,0 +1,138 @@
+import httpx
+import pytest
+
+from getabrain._http import build_transport
+from getabrain.errors import AuthError, RateLimitError, ServerError, NetworkError, TimeoutError
+
+
+def make(handler, **kw):
+    sleeps = []
+    _, request = build_transport(
+        api_key="gab_k_x", api_secret="gab_s_y",
+        transport=httpx.MockTransport(handler),
+        sleep=lambda s: sleeps.append(s),
+        **kw,
+    )
+    return request, sleeps
+
+
+def test_sets_auth_headers_and_parses_json():
+    seen = {}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        seen["key"] = req.headers.get("x-api-key")
+        seen["secret"] = req.headers.get("x-api-secret")
+        seen["url"] = str(req.url)
+        return httpx.Response(200, json={"ok": True})
+
+    request, _ = make(handler)
+    out = request("GET", "/requestor/stats")
+    assert out == {"ok": True}
+    assert seen["key"] == "gab_k_x"
+    assert seen["secret"] == "gab_s_y"
+    assert seen["url"] == "https://www.getabrain.ai/api/v1/requestor/stats"
+
+
+def test_post_body_and_query_params():
+    seen = {}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        seen["method"] = req.method
+        seen["content"] = req.content.decode()
+        seen["query"] = req.url.params.get("status")
+        return httpx.Response(201, json={"id": "q1"})
+
+    request, _ = make(handler)
+    request("POST", "/requestor/queries", body={"title": "hi"})
+    assert seen["method"] == "POST"
+    assert '"title"' in seen["content"]
+
+    request2, _ = make(handler)
+    request2("GET", "/requestor/queries", params={"status": "active", "limit": None})
+    assert seen["query"] == "active"  # None params are dropped
+
+
+def test_204_returns_none():
+    request, _ = make(lambda req: httpx.Response(204))
+    assert request("GET", "/x") is None
+
+
+def test_maps_error_status_to_typed_error():
+    request, _ = make(lambda req: httpx.Response(401, json={"error": "auth", "message": "bad key"}))
+    with pytest.raises(AuthError):
+        request("GET", "/requestor/stats")
+
+
+def test_get_retries_on_500_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] < 3:
+            return httpx.Response(500, json={"error": "server"})
+        return httpx.Response(200, json={"ok": True})
+
+    request, sleeps = make(handler)
+    out = request("GET", "/requestor/stats")
+    assert out == {"ok": True}
+    assert calls["n"] == 3
+    assert len(sleeps) == 2  # two retries slept
+
+
+def test_get_honors_retry_after_and_raises_after_max():
+    def handler(req: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, headers={"Retry-After": "2"}, json={"error": "rate"})
+
+    request, sleeps = make(handler, max_retries=1)
+    with pytest.raises(RateLimitError) as ei:
+        request("GET", "/requestor/stats")
+    assert ei.value.retry_after_ms == 2000
+    assert sleeps == [2.0]  # slept the Retry-After (2s) once before giving up
+
+
+def test_post_does_not_retry_on_500():
+    calls = {"n": 0}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(500, json={"error": "server"})
+
+    request, sleeps = make(handler)
+    with pytest.raises(ServerError):
+        request("POST", "/requestor/queries", body={"x": 1})
+    assert calls["n"] == 1  # POST is never retried
+    assert sleeps == []
+
+
+def test_transport_error_on_get_retries_then_raises_network():
+    def handler(req: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("boom")
+
+    request, sleeps = make(handler, max_retries=2)
+    with pytest.raises(NetworkError):
+        request("GET", "/requestor/stats")
+    assert len(sleeps) == 2  # retried twice, then NetworkError
+
+
+def test_timeout_raises_timeout_error_without_retry():
+    def handler(req: httpx.Request) -> httpx.Response:
+        raise httpx.ReadTimeout("slow")
+
+    request, sleeps = make(handler, max_retries=2)
+    with pytest.raises(TimeoutError):
+        request("GET", "/requestor/stats")
+    assert sleeps == []  # timeout is not retried
+
+
+def test_get_backoff_values_without_retry_after():
+    calls = {"n": 0}
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] < 3:
+            return httpx.Response(500, json={"error": "server"})
+        return httpx.Response(200, json={"ok": True})
+
+    request, sleeps = make(handler)
+    assert request("GET", "/requestor/stats") == {"ok": True}
+    assert sleeps == [1.0, 2.0]  # _backoff(1)=1.0, _backoff(2)=2.0

getabrain-0.1.0/tests/test_queries.py

@@ -0,0 +1,105 @@
+import pytest
+
+from getabrain.resources.queries import QueriesResource
+from getabrain.errors import TimeoutError
+
+
+class Recorder:
+    def __init__(self, returns):
+        self.returns = list(returns)
+        self.calls = []
+
+    def __call__(self, method, path, *, body=None, params=None):
+        self.calls.append((method, path, body, params))
+        return self.returns.pop(0)
+
+
+def test_create_posts_input():
+    rec = Recorder([{"id": "q1", "status": "active"}])
+    q = QueriesResource(rec).create(type="yes_no", title="ok?", content_data={"question": "ok?"},
+                                     required_responses=1, bid_amount_cents=5)
+    assert q["id"] == "q1"
+    method, path, body, _ = rec.calls[0]
+    assert method == "POST" and path == "/requestor/queries"
+    assert body["type"] == "yes_no" and body["required_responses"] == 1
+
+
+def test_get_url_encodes_id():
+    rec = Recorder([{"id": "a/b"}])
+    QueriesResource(rec).get("a/b")
+    assert rec.calls[0][1] == "/requestor/queries/a%2Fb"
+
+
+def test_list_passes_params():
+    rec = Recorder([{"queries": []}])
+    QueriesResource(rec).list(status="active", limit=10)
+    _, path, _, params = rec.calls[0]
+    assert path == "/requestor/queries"
+    assert params == {"status": "active", "limit": 10, "offset": None}
+
+
+def test_cancel_puts_action():
+    rec = Recorder([{"success": True, "refund_amount_cents": 50}])
+    out = QueriesResource(rec).cancel("q1")
+    method, path, body, _ = rec.calls[0]
+    assert method == "PUT" and path == "/requestor/queries/q1"
+    assert body == {"action": "cancel"}
+    assert out["refund_amount_cents"] == 50
+
+
+def test_wait_returns_when_enough_responses():
+    rec = Recorder([
+        {"status": "active", "completed_responses": 0, "required_responses": 2, "responses": []},
+        {"status": "active", "completed_responses": 2, "required_responses": 2,
+         "responses": [{"id": "r1"}, {"id": "r2"}]},
+    ])
+    sleeps = []
+    out = QueriesResource(rec).wait_for_responses(
+        "q1", min_responses=2, poll_interval_s=5, sleep=lambda s: sleeps.append(s),
+    )
+    assert len(out) == 2
+    assert sleeps == [5]  # slept once between the two polls
+
+
+def test_wait_returns_on_terminal_status():
+    rec = Recorder([{"status": "cancelled", "completed_responses": 0,
+                     "required_responses": 5, "responses": []}])
+    out = QueriesResource(rec).wait_for_responses("q1", min_responses=5, sleep=lambda s: None)
+    assert out == []
+
+
+def test_wait_uses_len_responses_when_count_absent():
+    rec = Recorder([
+        {"status": "active", "required_responses": 2, "responses": [{"id": "r1"}, {"id": "r2"}]},
+    ])
+    out = QueriesResource(rec).wait_for_responses("q1", min_responses=2, sleep=lambda s: None)
+    assert len(out) == 2  # no completed_responses key -> falls back to len(responses)
+
+
+import pytest as _pytest
+
+
+@_pytest.mark.parametrize("terminal", ["completed", "cancelled", "failed", "expired"])
+def test_wait_returns_on_each_terminal_status(terminal):
+    rec = Recorder([{"status": terminal, "completed_responses": 0,
+                     "required_responses": 5, "responses": []}])
+    out = QueriesResource(rec).wait_for_responses("q1", min_responses=5, sleep=lambda s: None)
+    assert out == []
+
+
+def test_wait_raises_timeout_when_deadline_passes():
+    rec = Recorder([
+        {"status": "active", "completed_responses": 0, "required_responses": 9, "responses": []}
+        for _ in range(10)
+    ])
+    clock = {"t": 0.0}
+
+    def now():
+        clock["t"] += 10.0  # each call jumps 10s
+        return clock["t"]
+
+    with pytest.raises(TimeoutError):
+        QueriesResource(rec).wait_for_responses(
+            "q1", min_responses=9, timeout_s=5, poll_interval_s=1,
+            sleep=lambda s: None, now=now,
+        )

getabrain-0.1.0/tests/test_types.py

@@ -0,0 +1,28 @@
+from getabrain.types import QUERY_TYPES, Query, AbTestContent, RatingResult
+
+
+def test_query_types_has_the_thirteen():
+    assert len(QUERY_TYPES) == 13
+    for t in (
+        "text", "multiple_choice", "rating_scale", "image_comparison", "ranking",
+        "yes_no", "sentiment", "image_selection", "free_form_text", "video_review",
+        "audio_review", "image_analysis", "ab_test",
+    ):
+        assert t in QUERY_TYPES
+
+
+def test_typeddicts_are_constructible_as_plain_dicts():
+    # TypedDicts are dicts at runtime; this just guards the names exist + import cleanly.
+    content: AbTestContent = {
+        "question": "Which is better?",
+        "variant_a": {"description": "A"},
+        "variant_b": {"description": "B"},
+    }
+    assert content["variant_a"]["description"] == "A"
+    q: Query = {"id": "q1", "type": "ab_test", "title": "t", "status": "active",
+                "required_responses": 1, "bid_amount_cents": 5, "total_cost_cents": 5,
+                "created_at": "now"}
+    assert q["status"] == "active"
+    r: RatingResult = {"response_id": "r1", "score": 5, "worker_new_quality_score": 4.8,
+                       "worker_suspended": False}
+    assert r["score"] == 5