rafiki.client.Client

class rafiki.client.Client(admin_host='127.0.0.1', admin_port='3000', advisor_host='127.0.0.1', advisor_port='3002')

Initializes the Client to connect to a running Rafiki Admin instance that the Client connects to.

Parameters:

• admin_host (str) – Host of Rafiki Admin
• admin_port (int) – Port of Rafiki Admin
• advisor_host (str) – Host of Rafiki Advisor
• advisor_port (int) – Port of Rafiki Advisor

login(email, password)

Creates a login session as a Rafiki user. You will have to be logged in to perform any actions.

App developers can create, list and stop train and inference jobs, as well as list models. Model developers can create and list models.

The login session (the session token) expires in 1 hour.

Parameters:

• email (str) – User’s email
• password (str) – User’s password

Returns:

Logged-in user as dictionary

Return type:

dict[str, any]

get_current_user()

Gets currently logged in user’s data.

Returns:Current user as dictionary, or None if client is not logged in Return type:dict[str, any]

logout()

Clears the current login session.

create_user(email, password, user_type)

Creates a Rafiki user.

Only admins can create users (except for admins). Only superadmins can create admins.

Parameters:

• email (str) – The new user’s email
• password (str) – The new user’s password
• user_type (rafiki.constants.UserType) – The new user’s type

Returns:

Created user as dictionary

Return type:

dict[str, any]

get_users()

Lists all Rafiki users.

Only admins can list all users.

Returns:List of users Return type:dict[str, any][]

ban_user(email)

Bans a Rafiki user, disallowing logins.

This action is irrevisible. Only admins can ban users (except for admins). Only superadmins can ban admins.

Parameters:email (str) – The user’s email Returns:Banned user as dictionary Return type:dict[str, any]

create_model(name, task, model_file_path, model_class, dependencies={}, access_right='PRIVATE', docker_image=None)

Creates a model on Rafiki.

Only admins & model developers can manage models.

Parameters:

• name (str) – Name of the model, which must be unique across all models added by the current user
• task (str) – Task associated with the model, where the model must adhere to the specification of the task
• model_file_path (str) – Path to a single Python file that contains the definition for the model class
• model_class (str) – The name of the model class inside the Python file. This class should implement rafiki.model.BaseModel
• dependencies (dict[str, str]) – List of dependencies & their versions
• access_right (rafiki.constants.ModelAccessRight) – Model access right
• docker_image (str) – A custom Docker image name that extends rafikiai/rafiki_worker

Returns:

Created model as dictionary

Return type:

dict[str, any]

model_file_path should point to a file that contains all necessary Python code for the model’s implementation. If the Python file imports any external Python modules, you should list it in dependencies or create a custom docker_image.

If a model’s access_right is set to PUBLIC, this model will be publicly available to all other users on Rafiki for training and inference. By default, a model’s access is PRIVATE.

dependencies should be a dictionary of { <dependency_name>: <dependency_version> }, where <dependency_name> corresponds to the name of the Python Package Index (PyPI) package (e.g. tensorflow) and <dependency_version> corresponds to the version of the PyPI package (e.g. 1.12.0). These dependencies will be lazily installed on top of the worker’s Docker image before the submitted model’s code is executed. If the model is to be run on GPU, Rafiki would map dependencies to their GPU-supported versions, if supported. For example, { 'tensorflow': '1.12.0' } will be installed as { 'tensorflow-gpu': '1.12.0' }. Rafiki could also parse specific dependency names to install certain non-PyPI packages. For example, { 'singa': '1.1.1' } will be installed as singa-cpu=1.1.1 or singa-gpu=1.1.1 using conda.

Refer to the list of officially supported dependencies below. For dependencies that are not listed, they will be installed as PyPI packages of the specified name and version.

Dependency	Installation Command
tensorflow	pip install tensorflow==${ver} or pip install tensorflow-gpu==${ver}
singa	conda install -c nusdbsystem singa-cpu=${ver} or conda install -c nusdbsystem singa-gpu=${ver}
Keras	pip install Keras==${ver}
scikit-learn	pip install scikit-learn==${ver}
torch	pip install torch==${ver}

Refer to Creating Models to understand more about how to write & test models for Rafiki.

get_model(model_id)

Retrieves details of a single model.

Model developers can only view their own models.

Parameters:model_id (str) – ID of model Returns:Details of model as dictionary Return type:dict[str, any]

download_model_file(model_id, out_model_file_path)

Downloads the Python model class file for the Rafiki model.

Model developers can only download their own models.

Parameters:

• model_id (str) – ID of model
• out_model_file_path (str) – Absolute/relative path to save model class file to

Returns:

Details of model as dictionary

Return type:

dict[str, any]

get_available_models(task=None)

Lists all Rafiki models available to the current user, optionally filtering by task.

Parameters:task (str) – Task name Returns:Available models as list of dictionaries Return type:dict[str, any][]

delete_model(model_id)

Deletes a single model. Models that have been used in train jobs cannot be deleted.

Model developers can only delete their own models.

Parameters:model_id (str) – ID of model Returns:Deleted model Return type:dict[str, any]

create_train_job(app, task, train_dataset_uri, test_dataset_uri, budget, models=None)

Creates and starts a train job on Rafiki.

A train job is uniquely identified by user, its associated app, and the app version (returned in output).

Only admins, model developers & app developers can manage train jobs. Model developers & app developers can only manage their own train jobs.

Parameters:

• app (str) – Name of the app associated with the train job
• task (str) – Task associated with the train job, the train job will train models associated with the task
• train_dataset_uri (str) – URI of the train dataset in a format specified by the task
• test_dataset_uri (str) – URI of the test (development) dataset in a format specified by the task
• budget (str) – Budget for each model
• models (str[]) – List of IDs of model to use for train job. Defaults to all available models

Returns:

Created train job as dictionary

Return type:

dict[str, any]

If models is unspecified, all models accessible to the user for the specified task will be used.

budget should be a dictionary of { <budget_type>: <budget_amount> }, where <budget_type> is one of rafiki.constants.BudgetType and <budget_amount> specifies the amount for the associated budget type.

The following describes the budget types available:

Budget Type	Description
MODEL_TRIAL_COUNT	No. of trials to conduct for each model (defaults to 5)
GPU_COUNT	No. of GPUs to exclusively allocate for training, across all models (defaults to 0)

get_train_jobs_by_user(user_id)

Lists all of user’s train jobs on Rafiki.

Parameters:user_id (str) – ID of the user Returns:Details of train jobs as list of dictionaries Return type:dict[str, any][]

get_train_jobs_of_app(app)

Lists all of current user’s train jobs associated to the app name on Rafiki.

Parameters:app (str) – Name of the app Returns:Details of train jobs as list of dictionaries Return type:dict[str, any][]

get_train_job(app, app_version=-1)

Retrieves details of the current user’s train job identified by an app and an app version, including workers’ details.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)

Returns:

Details of train job as dictionary

Return type:

dict[str, any]

get_best_trials_of_train_job(app, app_version=-1, max_count=2)

Lists the best scoring trials of the current user’s train job identified by an app and an app version, ordered by descending score.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)
• max_count (int) – Maximum number of trials to return

Returns:

Details of trials as list of dictionaries

Return type:

dict[str, any][]

get_trials_of_train_job(app, app_version=-1)

Lists all trials of the current user’s train job identified by an app and an app version, ordered by when the trial started.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)

Returns:

Details of trials as list of dictionaries

Return type:

dict[str, any][]

stop_train_job(app, app_version=-1)

Prematurely stops the current user’s train job identified by an app and an app version. Otherwise, the train job should stop by itself when its budget is reached.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)

Returns:

Stopped train job as dictionary

Return type:

dict[str, any]

get_trial(trial_id)

Gets a specific trial.

Parameters:trial_id (str) – ID of trial Returns:Details of trial as dictionary Return type:dict[str, any]

get_trial_logs(trial_id)

Gets the logs for a specific trial.

Parameters:trial_id (str) – ID of trial Returns:Logs of trial as dictionary Return type:dict[str, any]

get_trial_parameters(trial_id)

Gets parameters of the model associated with the trial.

Parameters:trial_id (str) – ID of trial Returns:Parameters of the trained model associated with the trial Return type:dict[str, any]

load_trial_model(trial_id, ModelClass)

Loads an instance of a trial’s model with the trial’s knobs & parameters.

Before this, you must have the trial’s model class file already in your local filesystem, the dependencies of the model must have been installed separately, and the model class must have been imported and passed into this method.

Wraps get_trial_parameters() and get_trial().

Parameters:

• trial_id (str) – ID of trial
• ModelClass (class) – model class that conincides with the trial’s model class

Returns:

A trained model instance of ModelClass, loaded with the trial’s knobs and parameters

create_inference_job(app, app_version=-1)

Creates and starts a inference job on Rafiki with the 2 best trials of an associated train job of the app. The train job must have the status of STOPPED.The inference job would be tagged with the train job’s app and app version. Throws an error if an inference job of the same train job is already running.

In this method’s response, predictor_host is this inference job’s predictor’s host.

Only admins, model developers & app developers can manage inference jobs. Model developers & app developers can only manage their own inference jobs.

Parameters:

• app (str) – Name of the app identifying the train job to use
• app_version (str) – Version of the app identifying the train job to use

Returns:

Created inference job as dictionary

Return type:

dict[str, any]

get_inference_jobs_by_user(user_id)

Lists all of user’s inference jobs on Rafiki.

Parameters:user_id (str) – ID of the user Returns:Details of inference jobs as list of dictionaries Return type:dict[str, any][]

get_inference_jobs_of_app(app)

Lists all inference jobs associated to an app on Rafiki.

Parameters:app (str) – Name of the app Returns:Details of inference jobs as list of dictionaries Return type:dict[str, any][]

get_running_inference_job(app, app_version=-1)

Retrieves details of the running inference job identified by an app and an app version, including workers’ details.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)

Returns:

Details of inference job as dictionary

Return type:

dict[str, any]

stop_inference_job(app, app_version=-1)

Stops the inference job identified by an app and an app version.

Parameters:

• app (str) – Name of the app
• app_version (int) – Version of the app (-1 for latest version)

Returns:

Stopped inference job as dictionary

Return type:

dict[str, any]

stop_all_jobs()

Stops all train and inference jobs on Rafiki.

Only admins can call this.