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:
value set in
set_workspace()
value set in client config file
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
- Returns
- 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.
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
- 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
- Returns
- 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.
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
- 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
- Returns
- 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.
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
- 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
- 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
- Returns
- 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
- 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
- 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.
- 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.
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
- 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
- Returns
- Raises
ValueError – If an Experiment with name already exists.
AttributeError – If a Project is not yet in progress.
- 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
- Returns
- 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
- 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
- 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.
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
- 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.
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
- 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
- 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
- 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.