Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Qbrix

Python SDK for qbrix, the open-source decision engine.

License Coverage Python 3.10+ Pydantic v2 Transports


Built against qbrix next · phase 1 (Skeleton), server optiq-io/qbrix@372219e.

Typed sync and async clients for qbrix: ask a loop for a decision, and report what happened.

Installation

pip install --pre "qbrix[http]"   # HTTP/JSON transport (httpx)
pip install --pre "qbrix[grpc]"   # gRPC transport (grpcio)
pip install --pre "qbrix[all]"    # both

Quick Start

from qbrix import Qbrix

client = Qbrix(api_key="optiq_…", base_url="https://qbrix.example.com")
decision = client.select(
    "checkout-headline",
    context={"unit": "user-1", "properties": {"device": "mobile"}},
    settings={"offline": {"key": "control", "config": {"headline": "Checkout"}}},
)
decision.option.config     # what to render
decision.reason            # "live", "draft", "paused" or "offline"
client.outcome(decision.request_id, 1)
  • select(loop, context, settings=None) takes the loop's key or id. context.unit says who the decision is for and is required; the SDK checks it before any call. properties are what the app knows about the request: device, plan, country. It returns a Decision(option, request_id, reason).
  • request_id is there only when the decision can learn: a live loop. A draft or paused loop answers its fallback without one.
  • outcome(request_id, value, *, id=None, at=None) reports what happened after one decision. The value must fit the loop's metric (a conversion is 0 or 1). A None request_id sends nothing, so call it unconditionally. Each call carries an event id, minted by the SDK when you don't pass one, so a retried call counts once. at is a datetime for when it happened; without one, qbrix uses the time it receives the outcome.

When qbrix can't be reached

select never raises because qbrix is down. On a connection error, a timeout, a 429 or a 5xx (gRPC UNAVAILABLE, DEADLINE_EXCEEDED), it returns your offline option with reason offline and no request_id, or option=None when you gave none. Errors in the call itself still raise, because they are bugs to fix: a missing unit, a bad key (AuthenticationError) or an unknown loop (NotFoundError, with the server's message).

decision = client.select(
    "checkout-headline",
    context={"unit": "user-1"},
    settings={
        "offline": {"key": "control", "config": {"headline": "Checkout"}},
        "timeout": 0.3,
        "max_retries": 0,
    },
)

settings keeps the select call on your request path within budget: timeout and max_retries override the client's for this call only. See examples/offline.py.

Async

from qbrix import AsyncQbrix

async with AsyncQbrix(api_key="optiq_…") as client:
    decision = await client.select("checkout-headline", context={"unit": "user-1"})
    await client.outcome(decision.request_id, 1)

Self-hosted qbrix

qbrix is open source. Run it with the self-hosting guide: bin/selfhost-init and docker compose up -d from the repository, or the Helm chart. Then register in the console and create an API key under Settings → API keys.

QBRIX_BASE_URL is the address of your install, not of the API path: the SDK adds /api/... itself.

Install QBRIX_BASE_URL
Docker Compose quickstart http://localhost:8000 (or your CONSOLE_URL once it's on a real host)
Helm chart your ingress origin, e.g. https://qbrix.example.com
Managed hosting the URL you were given for your deployment

The compose gateway and the chart's default ingress serve HTTP only, so use qbrix[http]. gRPC needs a direct route to the proxy's gRPC port (50050), for example from a service in the same cluster.

Transports

The same Qbrix client, resources, and Pydantic models work over either wire format — only the transport differs:

from qbrix import Qbrix

# HTTP — your install's gateway or ingress
client = Qbrix(transport="http", base_url="http://localhost:8000")

# gRPC — a directly-reachable proxy (local dev shown; or an in-cluster address)
client = Qbrix(transport="grpc", base_url="grpc://localhost:50050")

When transport is omitted it's resolved in this order: the transport= kwarg → the QBRIX_TRANSPORT env var → the base_url scheme (grpc:// / grpcs:// → gRPC) → HTTP.

gRPC needs a directly-reachable proxy gRPC endpoint. An install served over HTTPS behind a gateway or CDN usually does not expose gRPC — use transport="http" for it. Reach for gRPC against a local proxy (grpc://localhost:50050) or a service deployed alongside the proxy.

The gRPC transport covers select, outcome, and the pool, experiment, gate and policy operations. The runtime resource is HTTP-only (the proxy doesn't expose it over gRPC) — calling it on a gRPC client raises NotImplementedError. Install qbrix[all] and use transport="http" if you need it.

Configuration

Constructor kwargs take priority over environment variables, which take priority over defaults.

export QBRIX_API_KEY="optiq_xxx"
export QBRIX_BASE_URL="http://localhost:8000"
from qbrix import Qbrix

client = Qbrix()  # picks up env vars automatically
Env Var Default Description
QBRIX_API_KEY None API key (optiq_xxx)
QBRIX_BASE_URL http://localhost:8000 Your install's origin, without /api (the compose quickstart's gateway by default)
QBRIX_TRANSPORT (auto) http or grpc — overrides URL-scheme detection
QBRIX_TIMEOUT 5.0 Request timeout / gRPC deadline (seconds)
QBRIX_MAX_RETRIES 0 Retry count on transient failures (429/5xx, gRPC UNAVAILABLE)

gRPC-only knobs: QBRIX_GRPC_KEEPALIVE_TIME_MS (30000), QBRIX_GRPC_KEEPALIVE_TIMEOUT_MS (10000), QBRIX_GRPC_USE_TLS (false).

Errors

from qbrix import BadRequestError, NotFoundError

try:
    client.outcome(decision.request_id, 2)
except BadRequestError as e:
    print(e.detail)  # "a conversion is 0 or 1, got 2"

Today's API

The pool, experiment, gate and policy resources still talk to today's API until it is retired; the migration guide arrives with the release. client.agent is gone from this pre-release: use select and outcome.

License

MIT

Metadata

Release files for qbrix 0.4.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qbrix 0.4.0a1
File Size Uploaded Provenance Actions
qbrix-0.4.0a1.tar.gz 211.3 kB Without provenance Details for qbrix-0.4.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qbrix 0.4.0a1
File Interpreter ABI Platform Actions
qbrix-0.4.0a1-py3-none-any.whl Python 3 none any Details for qbrix-0.4.0a1-py3-none-any.whl

Total release size: 272.5 kB

Release files / qbrix-0.4.0a1.tar.gz

Download URL qbrix-0.4.0a1.tar.gz
Size 211.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a0a153ded1c5b2e207051e4f7868ce3450a89c41452e412b19d6d57056e6bfd2
BLAKE2b-256 checksum
How to use checksums
bc077f7979c8ab02a1974a457fd4cb7e8930178acfa5a53fd9a19c58784109c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / qbrix-0.4.0a1-py3-none-any.whl

Download URL qbrix-0.4.0a1-py3-none-any.whl
Size 61.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
81800c5d523c0915467881b6bc55addf9509f2b485f92dec86be7a7d4b4d2fe4
BLAKE2b-256 checksum
How to use checksums
06d70b4bcee9410cc387163e98361fe253e6fd3fd5f5b00fed38602053ffcb33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for qbrix 0.4.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page