Provider

Configuration#

import belfort_ml

provider = belfort_ml.Provider()                        # from the environment
provider = belfort_ml.Provider(api_key="blf_live_...")  # or explicit

Explicit arguments take precedence over the environment. A missing key raises ConfigurationError when the provider is constructed.

Set BELFORT_BASE_URL only to point at a different gateway, for example http://localhost:8000/api/v1 for a local one. For the gateway serving these docs:

export BELFORT_BASE_URL=https://eml.belfortlabs.com/api/v1

The provider holds a connection pool. Use it as a context manager or call close():

with belfort_ml.Provider() as provider:
    ...

Objects#

provider.account.get() and provider.credits.get() return plain dicts. provider.models and provider.deploys return objects that carry their own methods, so ids rarely need to be passed around.

Methods#

deploy.infer is for ciphertexts that are already in your hands, for example test data an end client sent you. Normally the end client calls the gateway itself with the token from model.create_client, so the ciphertext does not pass through you, and the gateway loads its keys onto the deploy without a load_keys call. load_keys is for loading a key set onto a deploy yourself.

Every method that waits (create, get(name=, create_from=), deploy, load_keys) polls the resource's status, starting every 2 seconds and backing off to 10, and raises TimeoutError when its timeout runs out. wait=False returns immediately where it is offered. While a deploy starts, deploy writes the deploy id and each launch step (looking for a GPU instance, booting it, loading the model, then loading the client's keys if the end client has uploaded them) to stderr; progress=False turns that off.

Level-zero encryption#

level_zero_encryption=True compiles the model so that the end client encrypts each input at the bottom of the modulus chain, and the deploy bootstraps each input before the computation.

This is a tradeoff: it will make the ciphertext at the client much smaller, hence reducing upload time and bandwidth usage. The computation will however take longer as an additional bootstrap operation will be performed at the beginning. It is not recommended be use it with models that do not require bootstrapping as it will greatly increase the evaluation keys' size.

ReLU approximation#

Encrypted computation cannot evaluate ReLU exactly, so the compiler replaces each ReLU with a polynomial over the range that calibration recorded.

With use_composite_relu=True, the default, each ReLU is a composite approximation: three chained polynomials, of degrees 15, 15 and 27. It is accurate, but it uses many levels per activation, so the model bootstraps more often. More levels and bootstraps make each inference slower and the evaluation keys larger.

use_composite_relu=False uses a single degree-5 polynomial instead. A small model can then fit without bootstrapping, with much smaller keys. The approximation is coarser, so compare the encrypted results with the plaintext model before you use it. The Quickstart uses it.

These two are the only choices: the degree of the approximation, for ReLU and for the other approximated operations, cannot be set yet.

Uploads#

provider.models.create uploads the MLIR, and the Python file that defines the model when artifacts.source_path is set, to storage through presigned URLs, in parts, without sending your API key. A failed part is retried; an upload that still fails raises UploadError.

Logging#

The SDK logs to the standard belfort_ml logger, which is silent unless you configure a handler. DEBUG lines contain the method, path, status and request id, and omit headers and bodies.

import logging
logging.basicConfig(level=logging.INFO)