This release is a pre-release and may not be stable for production use.
Python SDK for qbrix, the open-source decision engine.
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 "qbrix[http]==0.4.0-a2" # HTTP/JSON transport (httpx) x-release-please-version
pip install "qbrix[grpc]==0.4.0-a2" # gRPC transport (grpcio) x-release-please-version
pip install "qbrix[all]==0.4.0-a2" # both x-release-please-version
Pin the exact version rather than passing --pre: --pre allows pre-releases of every dependency too, not only qbrix.
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.unitsays who the decision is for and is required; the SDK checks it before any call.propertiesare what the app knows about the request: device, plan, country. It returns aDecision(option, request_id, reason).request_idis 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). ANonerequest_id sends nothing, so call it unconditionally. Each call carries an eventid, minted by the SDK when you don't pass one, so a retried call counts once.atis adatetimefor 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
Metadata
Release files for qbrix 0.4.0a2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qbrix-0.4.0a2.tar.gz | 211.4 kB | Without provenance | Details for qbrix-0.4.0a2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qbrix-0.4.0a2-py3-none-any.whl | Python 3 | none | any | Details for qbrix-0.4.0a2-py3-none-any.whl |
Total release size: 272.8 kB
Release files / qbrix-0.4.0a2.tar.gz
| Download URL | qbrix-0.4.0a2.tar.gz |
|---|---|
| Size | 211.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3017fe8d365e0503bf969b55e105d0d9cca256ccfd6b234ba7ee24d1a2d3ee4
|
|
BLAKE2b-256 checksum How to use checksums |
eb7a1d332f6bbef1a8feffaee915d592ca988ac40f0e047d8577122af7b8b594
|
| 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.0a2-py3-none-any.whl
| Download URL | qbrix-0.4.0a2-py3-none-any.whl |
|---|---|
| Size | 61.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1cff0a15f40f62fe86772f12603f6f69c474a665e61a68a9ecc7269fd6a9f7e0
|
|
BLAKE2b-256 checksum How to use checksums |
a697916a3dc5c5d63349a16fc3c6b6a4c96304bcd6b11db1d7909f424f5cc193
|
| 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.0a2
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.