Overview

Initialize a Beaker client with Beaker.from_env():

>>> from beaker import *
>>> beaker = Beaker.from_env(default_workspace=workspace_name)

Accounts

Manage your Beaker account with Beaker.account.

For example, you can check who you are logged in as with Beaker.account.whoami():

>>> username = beaker.account.whoami().name

Important

In this example - and all other examples - beaker is an instance of the Beaker client class, not the beaker module. See Quick start to learn how to instantiate the client.

Organizations

Manage Beaker organizations with Beaker.organization.

For example, you can get information about an organization with Beaker.organization.get():

>>> beaker.organization.get(beaker_org_name).display_name
'AI2'

You can also add, get, list, or remove members with Beaker.organization.add_member(), .get_member(), .list_members(), or .remove_member(), respectively.

Workspaces

Manage Beaker workspaces with Beaker.workspace.

For example, you can create a workspace with Beaker.workspace.ensure():

>>> workspace = beaker.workspace.ensure(workspace_name)

You can retreive metadata about a workspace with Beaker.workspace.get():

>>> beaker.workspace.get(workspace_name).id
'01G370GVHJQZYF50XYXM7VB53N'

You can list datasets in a workspace with Beaker.workspace.datasets():

>>> datasets = beaker.workspace.datasets(workspace_name, results=False)

Similarly, you can list experiments or images with Beaker.workspace.experiments() or Beaker.workspace.images(), respectively.

Clusters

Manage Beaker clusters with Beaker.cluster.

For example, you can get information about a cluster with Beaker.cluster.get():

>>> beaker.cluster.get(beaker_cluster_name).name
'ai2/canary'

Or you could check how many GPUs are free on an on-premise cluster with Beaker.cluster.utilization():

>>> free_gpus = 0
>>> for node_util in beaker.cluster.utilization(beaker_on_prem_cluster_name).nodes:
...     free_gpus += node_util.free.gpu_count

Nodes

Manage Beaker nodes with Beaker.node.

For example, you can get information about a node with Beaker.node.get():

>>> beaker.node.get(beaker_node_id).limits.gpu_count
8

Images

Manage Beaker images with Beaker.image.

For example, upload a local Docker image to Beaker with Beaker.image.create():

>>> image = beaker.image.create(beaker_image_name, docker_image_name, quiet=True)

The object returned is the same Image object you get from Beaker.image.get(). It contains some metadata about the image:

>>> image = beaker.image.get(f"{username}/{beaker_image_name}")
>>> image.original_tag
'hello-world'

Experiments

Manage Beaker experiments with Beaker.experiment.

For example, create an experiment with Beaker.experiment.create():

>>> spec = ExperimentSpec(
...     budget="ai2/allennlp",
...     tasks=[
...         TaskSpec(
...             name="main",
...             image=ImageSource(beaker=image.id),
...             context=TaskContext(cluster=beaker_cluster_name),
...             result=ResultSpec(
...                 path="/unused"  # required even if the task produces no output.
...             ),
...         ),
...     ],
... )
>>> experiment = beaker.experiment.create(
...     experiment_name,
...     spec,
...     workspace=workspace_name,
... )

Wait for the experiment to complete with Beaker.experiment.wait_for():

>>> experiment = beaker.experiment.wait_for(
...     experiment,
...     timeout=60 * 5,
...     quiet=True,
... )[0]

Get the logs from the execution of a task in an experiment with Beaker.experiment.logs():

>>> logs = "".join([
...    line.decode() for line in
...    beaker.experiment.logs(experiment, quiet=True)
... ])

Get the results from a task in an experiment with Beaker.experiment.results:

>>> results = beaker.experiment.results(experiment)

Jobs

Manage Beaker jobs with Beaker.job.

For example, get the logs from a job with Beaker.job.logs() (equivalent to Beaker.experiment.logs() when there is only one task in the experiment):

>>> job = experiment.jobs[0]
>>> logs = "".join([
...    line.decode() for line in
...    beaker.job.logs(job, quiet=True)
... ])

Datasets

Manage Beaker datasets with Beaker.dataset.

For example, create a dataset from a local file with Beaker.dataset.create():

>>> dataset = beaker.dataset.create(dataset_name, "README.md", quiet=True)

Or create a dataset from a local directory:

>>> dataset = beaker.dataset.create(dataset_name, "docs/source/", force=True, quiet=True)

Tip

The force=True flag is used to overwrite any existing dataset with the same name.

And download a dataset with Beaker.dataset.fetch():

>>> beaker.dataset.fetch(dataset, target=download_path, quiet=True)

You can also download a single file using Beaker.dataset.stream_file():

>>> contents = b"".join(beaker.dataset.stream_file(dataset, "docs/source/conf.py", quiet=True))

Secrets

Manage Beaker secrets with Beaker.secret.

For example, you can read, write, or delete secrets with Beaker.secret.read(), Beaker.secret.write(), and Beaker.secret.delete(), respectively.

Groups

Manage Beaker groups with Beaker.group.

For example, create a group with Beaker.group.create():

>>> group = beaker.group.create(group_name, experiment)