qbrixqbrix

Quickstart

Get from zero to a working experiment in under 5 minutes. By the end of this guide you'll have a pool, an experiment running auto mode, and a feedback loop sending real rewards.

Prerequisites

Install the SDK

pip install qbrix

The Python SDK (Python 3.10+) wraps every qbrix HTTP endpoint into a typed client — pools, experiments, selection, and feedback.

The JavaScript / TypeScript SDK (@optiqio/qbrix, Node 18+) is a tiny, isomorphic client focused on the runtime hot path: select and feedback. Create pools and experiments with the Python SDK, curl, or the console — then use the JS SDK to run selection and report rewards. See the JavaScript / TypeScript SDK guide for the full reference.

Create an API Key

  1. Log in to cloud.qbrix.io
  2. Go to Settings → API Keys
  3. Click Create API Key and copy the key

Set your environment variables:

import qbrix
 
client = qbrix.Qbrix(
    api_key="your-api-key",
    base_url="https://cloud.qbrix.io",
)
Warning

Your API key (optiq_…) is a secret — the SDK sends it as an X-API-Key header, so it travels wherever the client runs. Keep it server-side (a route handler, edge function, or backend) and never bundle it into browser code. Have the browser call your endpoint, not qbrix directly.

Create a Pool

A pool is a collection of arms (variants). Let's create one with 3 homepage hero images:

Info

The JavaScript / TypeScript SDK covers selection and feedback only. Create pools and experiments with the Python SDK, curl, or the console — then use the JS SDK at runtime to select and send feedback.

pool = client.pool.create(
    name="homepage-heroes",
    arms=[
        {"name": "minimal-dark", "metadata": {"image": "hero-1.png"}},
        {"name": "gradient-bold", "metadata": {"image": "hero-2.png"}},
        {"name": "illustration", "metadata": {"image": "hero-3.png"}},
    ],
)
 
print(pool.id)

Create an Experiment

Link the pool to a policy. The default "auto" policy runs a portfolio of learners — qbrix launches several in parallel and adaptively routes traffic toward the best performer, so you don't have to pick one upfront:

experiment = client.experiment.create(
    name="hero-optimization",
    pool_id=pool.id,
    policy="auto",
    policy_params={"reward_type": "binary"},
)
 
print(experiment.id)
Info

Prefer a specific algorithm? Pass a concrete policy name like "BetaTSPolicy" or "LinTSPolicy" — see Policies for the full list.

Select an Arm

Ask qbrix to select the best arm for a request:

result = client.agent.select(
    experiment_id=experiment.id,
    context={"id": "user-001"},
)
 
print(f"Selected: {result.arm.name}")
print(f"Request ID: {result.request_id}")

The response includes the selected arm and a request_id to link feedback:

{
  "request_id": "req-abc123",
  "arm": {"id": "...", "name": "gradient-bold", "index": 1},
  "is_default": false
}

Send Feedback

After observing the outcome (e.g., user clicked), send a reward signal:

client.agent.feedback(
    request_id=result.request_id,
    reward=1.0,
)
Info

Feedback is processed asynchronously. Policy parameters update within seconds depending on batch settings.

Verify the Loop

Run a few more select → feedback cycles. You'll see the policy begin to favor higher-reward arms:

import random
 
for i in range(20):
    # select
    result = client.agent.select(
        experiment_id=experiment.id,
        context={"id": f"user-{i}"},
    )
 
    # simulate reward: arm index 1 has 70% click rate, others 30%
    if result.arm.index == 1:
        reward = 1.0 if random.random() < 0.7 else 0.0
    else:
        reward = 1.0 if random.random() < 0.3 else 0.0
 
    # feedback
    client.agent.feedback(
        request_id=result.request_id,
        reward=reward,
    )
 
    print(f"round {i+1}: arm={result.arm.name} reward={reward}")

View Results

Open your experiment in the qbrix console to see selection distributions and reward metrics.

What's Next