Initialize a Beaker client with Beaker.from_env():

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


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


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.


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

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


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

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.


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

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


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


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


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)


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)
... ])


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)


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))


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.


Manage Beaker groups with Beaker.group.

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

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