WhiteBox Python SDK

Python client for the WhiteBox AI decision observability API.

Installation

pip install whitebox

Quick Start

from whitebox import Whitebox

client = Whitebox(api_key="wb_your_api_key")

# Make a single decision
decision = client.decide(
    input="The customer wants to cancel their subscription and get a refund",
    options=["approve_refund", "offer_discount", "escalate_to_manager"],
)

print(decision.value)       # "approve_refund"
print(decision.confidence)  # 0.92
print(decision.verdict)     # "consensus"

Fast Mode

Use fast mode for lower-latency decisions with fewer model runs:

decision = client.decide_fast(
    input="Is this email spam?",
    options=["spam", "not_spam"],
)

Bulk Decisions

Submit up to 100 decisions in a single request:

batch = client.decide_bulk(
    items=[
        {"input": "Unauthorized charge on my card"},
        {"input": "When does my subscription renew?"},
        {"input": "I want to upgrade my plan"},
    ],
    options=["billing", "account", "upgrade"],
    webhook_url="https://example.com/webhook",
)

print(batch.id)     # "batch_abc123"
print(batch.total)  # 3

# Poll for results
batch = client.get_batch(batch.id)
if batch.status == "completed":
    results = client.get_batch_results(batch.id)

Human Review

When a decision is escalated (low confidence), resolve it manually:

reviews = client.list_reviews()
for review in reviews:
    print(review.input, review.options, review.confidence)

# Resolve a review
client.resolve_review(review_id=42, answer="approve_refund")

Error Handling

from whitebox import (
    WhiteboxError,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
)

try:
    decision = client.decide(input="...", options=["a", "b"])
except AuthenticationError:
    print("Check your API key")
except InsufficientCreditsError:
    print("Add credits at https://whiteboxhq.ai/billing")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except WhiteboxError as e:
    print(f"API error {e.status_code}: {e}")

Documentation

Full API docs: https://whiteboxhq.ai/docs