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 "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.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.0a2

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.0a2
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)

Table of built distributions (wheels) for qbrix 0.4.0a2
File Interpreter ABI Platform Actions
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.

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