getabrain 0.1.0__py3-none-any.whl

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/_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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+getabrain/__init__.py,sha256=CouWJ8dcQX3uZRt6OcE3ylNyGurNPp4NV0pb7F5rUOg,1055
+getabrain/_http.py,sha256=7KkwopWIviMflGfRqUSRlS5y9Vw2K7yRWlylzssUts4,2718
+getabrain/client.py,sha256=jTcl8sxFXqtT_le8sziYE2n_WKqrv5MINu_wrrLepgA,1785
+getabrain/errors.py,sha256=2y_3WYNTbxTlYHkGI58KuA7oRbqVHvKCEAtGAN9hr9M,2704
+getabrain/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getabrain/types.py,sha256=QVUrs69Chb6zAkFZyE2RpnE2B_Lj-THn2Prh3jRfefw,4870
+getabrain/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+getabrain/resources/account.py,sha256=T1-DygqbeinPFKckBc9WUr5UO9d9CL6vyI5orKbbNgc,454
+getabrain/resources/queries.py,sha256=8b-65yCbYfpumiyU5L6OnMjzyR8zBaoQyCVJ9zJVub4,2190
+getabrain/resources/responses.py,sha256=UdrmIoTrufd-_PNS4OUCGSDm7s70lTdy8UhUWdN5LEk,1052
+getabrain-0.1.0.dist-info/METADATA,sha256=xgb03TdEA3nWo90xS7wI_Nu_hqiJCQ1O_dS_C4A-78k,3024
+getabrain-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+getabrain-0.1.0.dist-info/RECORD,,

getabrain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any