Client

class verta.Client(host=None, port=None, email=None, dev_key=None, max_retries=5, ignore_conn_err=False, use_git=True, debug=False, extra_auth_headers={}, jwt_token=None, jwt_token_sig=None, organization_id=None, organization_name=None, _connect=True)

Object for interfacing with the Verta backend.

Deprecated since version 0.12.0: The port parameter will be removed in an upcoming version; please combine port with the first parameter, e.g. Client(“localhost:8080”).

Deprecated since version 0.13.3: The expt_runs attribute will be removed in an upcoming version; consider using proj.expt_runs and expt.expt_runs instead.

New in version 0.20.4: The VERTA_DISABLE_CLIENT_CONFIG environment variable, when set to a non-empty value, disables discovery of client config files for use in protected filesystems.

New in version 0.24.0: organization_id and organization_name parameters.

This class provides functionality for starting/resuming Projects, Experiments, and Experiment Runs.

Parameters:
  • host (str, optional) – Hostname of the Verta Web App.

  • email (str, optional) – Authentication credentials for managed service. If this does not sound familiar, then there is no need to set it.

  • dev_key (str, optional) – Authentication credentials for managed service. If this does not sound familiar, then there is no need to set it.

  • max_retries (int, default 5) – Maximum number of times to retry a request on a connection failure. This only attempts retries on HTTP codes {502, 503, 504} which commonly occur during back end connection lapses.

  • ignore_conn_err (bool, default False) – Whether to ignore connection errors and instead return successes with empty contents.

  • use_git (bool, default True) – Whether to use a local Git repository for certain operations such as Code Versioning.

  • debug (bool, default False) – Whether to print extra verbose information to aid in debugging.

  • extra_auth_headers (dict, default {}) – Extra headers to include on requests, like to permit traffic through a restrictive application load balancer

  • organization_id (str, optional) – (alpha) Organization to use for the client calls. If not provided, the default organization will be used.

  • organization_name (str, optional) – (alpha) Organization to use for the client calls. If not provided, the default organization will be used.

  • _connect (str, default True) – Whether to connect to server (False for unit tests).

Variables:
  • max_retries (int) – Maximum number of times to retry a request on a connection failure. Changes to this value propagate to any objects that are/were created from this client.

  • ignore_conn_err (bool) – Whether to ignore connection errors and instead return successes with empty contents. Changes to this value propagate to any objects that are/were created from this client.

  • debug (bool) – Whether to print extra verbose information to aid in debugging. Changes to this value propagate to any objects that are/were created from this client.

  • proj (Project or None) – Currently active project.

  • projects (Projects) – Projects in the current default workspace.

  • expt (Experiment or None) – Currently active experiment.

  • experiments (Experiments) – Experiments in the current default workspace.

  • expt_runs (ExperimentRuns) – Experiment runs in the current default workspace.

  • registered_models (RegisteredModels) – Registered models in the current default workspace.

  • registered_model_versions (RegisteredModelVersions) – Registered model versions in the current default workspace.

  • endpoints (Endpoints) – Endpoints in the current default workspace.

  • datasets (Datasets) – Datasets in the current default workspace.

get_workspace()

Gets the active workspace for this client instance.

New in version 0.17.0.

The active workspace is determined by this order of precedence:

  1. value set in set_workspace()

  2. value set in client config file

  3. default workspace set in web app

Returns:

workspace (str) – Verta workspace.

set_workspace(workspace)

Sets the active workspace for this client instance.

New in version 0.17.0.

Parameters:

workspace (str) – Verta workspace.

get_project(name=None, workspace=None, id=None)

Retrieves an already created Project. Only one of name or id can be provided.

Parameters:
  • name (str, optional) – Name of the Project.

  • workspace (str, optional) – Workspace under which the Project with name name exists. If not provided, the current user’s default workspace will be used.

  • id (str, optional) – ID of the Project. This parameter cannot be provided alongside name.

Returns:

Project

set_project(name=None, desc=None, tags=None, attrs=None, workspace=None, public_within_org=None, visibility=None, id=None)

Attaches a Project to this Client.

If an accessible Project with name name does not already exist, it will be created and initialized with specified metadata parameters. If such a Project does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

If an Experiment is already attached to this Client, it will be detached.

Parameters:
  • name (str, optional) – Name of the Project. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Project.

  • tags (list of str, optional) – Tags of the Project.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Project.

  • workspace (str, optional) – Workspace under which the Project with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a Project in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this project. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • id (str, optional) – ID of the Project. This parameter cannot be provided alongside name, and other parameters will be ignored.

Returns:

Project

Raises:

ValueError – If a Project with name already exists, but metadata parameters are passed in.

get_experiment(name=None, id=None)

Retrieves an already created Experiment. Only one of name or id can be provided.

Parameters:
  • name (str, optional) – Name of the Experiment.

  • id (str, optional) – ID of the Experiment. This parameter cannot be provided alongside name.

Returns:

Experiment

set_experiment(name=None, desc=None, tags=None, attrs=None, id=None)

Attaches an Experiment under the currently active Project to this Client.

If an accessible Experiment with name name does not already exist under the currently active Project, it will be created and initialized with specified metadata parameters. If such an Experiment does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

Parameters:
  • name (str, optional) – Name of the Experiment. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Experiment.

  • tags (list of str, optional) – Tags of the Experiment.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Experiment.

  • id (str, optional) – ID of the Experiment. This parameter cannot be provided alongside name, and other parameters will be ignored.

Returns:

Experiment

Raises:
  • ValueError – If an Experiment with name already exists, but metadata parameters are passed in.

  • AttributeError – If a Project is not yet in progress.

get_experiment_run(name=None, id=None)

Retrieves an already created Experiment Run. Only one of name or id can be provided.

Parameters:
  • name (str, optional) – Name of the Experiment Run.

  • id (str, optional) – ID of the Experiment Run. This parameter cannot be provided alongside name.

Returns:

ExperimentRun

set_experiment_run(name=None, desc=None, tags=None, attrs=None, id=None, date_created=None, start_time=None, end_time=None)

Attaches an Experiment Run under the currently active Experiment to this Client.

If an accessible Experiment Run with name name does not already exist under the currently active Experiment, it will be created and initialized with specified metadata parameters. If such a Experiment Run does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

Parameters:
  • name (str, optional) – Name of the Experiment Run. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Experiment Run.

  • tags (list of str, optional) – Tags of the Experiment Run.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Experiment Run.

  • id (str, optional) – ID of the Experiment Run. This parameter cannot be provided alongside name, and other parameters will be ignored.

Returns:

ExperimentRun

Raises:
  • ValueError – If an Experiment Run with name already exists, but metadata parameters are passed in.

  • AttributeError – If an Experiment is not yet in progress.

get_or_create_project(*args, **kwargs)

Alias for Client.set_project().

get_or_create_experiment(*args, **kwargs)

Alias for Client.set_experiment().

get_or_create_experiment_run(*args, **kwargs)

Alias for Client.set_experiment_run().

get_or_create_registered_model(name=None, desc=None, labels=None, workspace=None, public_within_org=None, visibility=None, id=None, task_type=None, data_type=None, pii=False)

Attaches a registered_model to this Client.

If an accessible registered_model with name name does not already exist, it will be created and initialized with specified metadata parameters. If such a registered_model does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

Parameters:
  • name (str, optional) – Name of the registered_model. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the registered_model.

  • labels (list of str, optional) – Labels of the registered_model.

  • workspace (str, optional) – Workspace under which the registered_model with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a registered_model in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this registered model. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • id (str, optional) – ID of the registered_model. This parameter cannot be provided alongside name, and other parameters will be ignored.

  • task_type (task_type, optional) – Task type of the registered_model.

  • data_type (data_type, optional) – Data type of the registered_model.

  • pii (bool, default False) – Whether the registered_model ingests personally identifiable information.

Returns:

RegisteredModel

Raises:

ValueError – If a registered_model with name already exists, but metadata parameters are passed in.

get_registered_model(name=None, workspace=None, id=None)

Retrieve an already created Registered Model. Only one of name or id can be provided.

Parameters:
  • name (str, optional) – Name of the Registered Model.

  • id (str, optional) – ID of the Registered Model. This parameter cannot be provided alongside name.

Returns:

RegisteredModel

set_registered_model(*args, **kwargs)

Alias for Client.get_or_create_registered_model().

get_registered_model_version(id)

Retrieve an already created Model Version.

Parameters:

id (str) – ID of the Model Version.

Returns:

RegisteredModelVersion

get_or_create_endpoint(path=None, description=None, workspace=None, public_within_org=None, visibility=None, id=None)

Attaches an endpoint to this Client.

If an accessible endpoint with name path does not already exist, it will be created and initialized with specified metadata parameters. If such an endpoint does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

Parameters:
  • path (str, optional) – Path for the endpoint.

  • description (str, optional) – Description of the endpoint.

  • workspace (str, optional) – Workspace under which the endpoint with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating an endpoint in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this endpoint. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • id (str, optional) – ID of the endpoint. This parameter cannot be provided alongside name, and other parameters will be ignored.

Returns:

Endpoint

Raises:

ValueError – If an endpoint with path already exists, but metadata parameters are passed in.

get_endpoint(path=None, workspace=None, id=None)

Retrieves an already created Endpoint. Only one of path or id can be provided.

Parameters:
  • path (str, optional) – Path of the Endpoint.

  • workspace (str, optional) – Name of the workspace of the Endpoint.

  • id (str, optional) – ID of the Endpoint. This parameter cannot be provided alongside path.

Returns:

Endpoint

set_endpoint(*args, **kwargs)

Alias for Client.get_or_create_endpoint().

create_project(name=None, desc=None, tags=None, attrs=None, workspace=None, public_within_org=None, visibility=None)

Creates a new Project.

A Project with name name will be created and initialized with specified metadata parameters.

If an Experiment is already attached to this Client, it will be detached.

Parameters:
  • name (str, optional) – Name of the Project. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Project.

  • tags (list of str, optional) – Tags of the Project.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Project.

  • workspace (str, optional) – Workspace under which the Project with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a Project in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this project. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

Returns:

Project

Raises:

ValueError – If a Project with name already exists.

create_experiment(name=None, desc=None, tags=None, attrs=None)

Creates a new Experiment under the currently active Project.

Experiment with name name will be created and initialized with specified metadata parameters.

Parameters:
  • name (str, optional) – Name of the Experiment. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Experiment.

  • tags (list of str, optional) – Tags of the Experiment.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Experiment.

Returns:

Experiment

Raises:
create_experiment_run(name=None, desc=None, tags=None, attrs=None, date_created=None, start_time=None, end_time=None)

Creates a new Experiment Run under the currently active Experiment.

An Experiment Run with name name will be created and initialized with specified metadata parameters.

Parameters:
  • name (str, optional) – Name of the Experiment Run. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the Experiment Run.

  • tags (list of str, optional) – Tags of the Experiment Run.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the Experiment Run.

Returns:

ExperimentRun

Raises:
  • ValueError – If an Experiment Run with name already exists.

  • AttributeError – If an Experiment is not yet in progress.

create_registered_model(name=None, desc=None, labels=None, workspace=None, public_within_org=None, visibility=None, task_type=None, data_type=None, pii=False)

Creates a new Registered Model.

A registered_model with name name does will be created and initialized with specified metadata parameters.

Parameters:
  • name (str, optional) – Name of the registered_model. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the registered_model.

  • labels (list of str, optional) – Labels of the registered_model.

  • workspace (str, optional) – Workspace under which the registered_model with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a registered_model in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this registered model. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • task_type (task_type, optional) – Task type of the registered_model.

  • data_type (data_type, optional) – Data type of the registered_model.

  • pii (bool, default False) – Whether the registered_model ingests personally identifiable information.

Returns:

RegisteredModel

Raises:

ValueError – If a registered_model with name already exists.

create_endpoint(path, description=None, workspace=None, public_within_org=None, visibility=None, kafka_settings=None)

Attaches an endpoint to this Client.

An accessible endpoint with name name will be created and initialized with specified metadata parameters.

New in version 0.19.0: The kafka_settings parameter.

Parameters:
  • path (str) – Path for the endpoint.

  • description (str, optional) – Description of the endpoint.

  • workspace (str, optional) – Workspace under which the endpoint with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating an endpoint in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this endpoint. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • kafka_settings (verta.endpoint.KafkaSettings, optional) – Kafka settings.

Returns:

Endpoint

Raises:

ValueError – If an endpoint with path already exists.

download_endpoint_manifest(download_to_path, path, name, strategy=None, resources=None, autoscaling=None, env_vars=None, workspace=None)

Downloads this endpoint’s Kubernetes manifest YAML.

Parameters:
  • download_to_path (str) – Local path to download manifest YAML to.

  • path (str) – Path of the endpoint.

  • name (str) – Name of the endpoint.

  • strategy (update, default DirectUpdateStrategy()) – Strategy (direct or canary) for updating the endpoint.

  • resources (Resources, optional) – Resources allowed for the updated endpoint.

  • autoscaling (Autoscaling, optional) – Autoscaling condition for the updated endpoint.

  • env_vars (dict of str to str, optional) – Environment variables.

  • workspace (str, optional) – Workspace for the endpoint. If not provided, the current user’s default workspace will be used.

Returns:

downloaded_to_path (str) – Absolute path where deployment YAML was downloaded to. Matches download_to_path.

get_or_create_dataset(name=None, desc=None, tags=None, attrs=None, workspace=None, time_created=None, public_within_org=None, visibility=None, id=None)

Gets or creates a dataset.

Changed in version 0.16.0: The dataset versioning interface was overhauled.

If an accessible dataset with name name does not already exist, it will be created and initialized with specified metadata parameters. If such a dataset does already exist, it will be retrieved; specifying metadata parameters in this case will raise a warning.

Parameters:
  • name (str, optional) – Name of the dataset. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the dataset.

  • tags (list of str, optional) – Tags of the dataset.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the dataset.

  • workspace (str, optional) – Workspace under which the dataset with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a dataset in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this dataset. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

  • id (str, optional) – ID of the dataset. This parameter cannot be provided alongside name, and other parameters will be ignored.

Returns:

Dataset

Raises:

ValueError – If a dataset with name already exists, but metadata parameters are passed in.

set_dataset(*args, **kwargs)

Alias for Client.get_or_create_dataset().

Changed in version 0.16.0: The dataset versioning interface was overhauled.

create_dataset(name=None, desc=None, tags=None, attrs=None, workspace=None, time_created=None, public_within_org=None, visibility=None)

Creates a dataset, initialized with specified metadata parameters.

Changed in version 0.16.0: The dataset versioning interface was overhauled.

Parameters:
  • name (str, optional) – Name of the dataset. If no name is provided, one will be generated.

  • desc (str, optional) – Description of the dataset.

  • tags (list of str, optional) – Tags of the dataset.

  • attrs (dict of str to {None, bool, float, int, str}, optional) – Attributes of the dataset.

  • workspace (str, optional) – Workspace under which the dataset with name name exists. If not provided, the current user’s default workspace will be used.

  • public_within_org (bool, optional) – If creating a dataset in an organization’s workspace: True for public, False for private. In older backends, default is private; in newer backends, uses the org’s settings by default.

  • visibility (visibility, optional) – Visibility to set when creating this dataset. If not provided, an appropriate default will be used. This parameter should be preferred over public_within_org.

Returns:

Dataset

Raises:

ValueError – If a dataset with name already exists.

get_dataset(name=None, workspace=None, id=None)

Gets a dataset.

Changed in version 0.16.0: The dataset versioning interface was overhauled.

Parameters:
  • name (str, optional) – Name of the dataset. This parameter cannot be provided alongside id.

  • workspace (str, optional) – Workspace under which the dataset with name name exists. If not provided, the current user’s default workspace will be used.

  • id (str, optional) – ID of the dataset. This parameter cannot be provided alongside name.

Returns:

Dataset

get_dataset_version(id)

Gets a dataset version.

Changed in version 0.16.0: The dataset versioning interface was overhauled.

Parameters:

id (str) – ID of the dataset version.

Returns:

DatasetVersion

get_kafka_topics() List[str]

Get available topics for the current Kafka configuration, for associating with an endpoint via KafkaSettings.

New in version 0.23.0.

Returns:

topics (list of str) – List of topic names.

Raises:

HTTPError – If no valid Kafka configuration can be found.