Workspaces - Weights & Biases Documentation

W&B Report and Workspace API is in Public Preview.

Python library for programmatically working with W&B Workspace API.

# How to import
import wandb_workspaces.workspaces as ws
import wandb_workspaces.reports.v2 as wr

# Example of creating a workspace
ws.Workspace(
     name="Example W&B Workspace",
     entity="entity", # entity that owns the workspace
     project="project", # project that the workspace is associated with
     sections=[
         ws.Section(
             name="Validation Metrics",
             panels=[
                 wr.LinePlot(x="Step", y=["val_loss"]),
                 wr.BarPlot(metrics=["val_accuracy"]),
                 wr.ScalarChart(metric="f1_score", groupby_aggfunc="mean"),
             ],
             is_open=True,
         ),
     ],
)
workspace.save()

`class` `RunSettings`

Settings for a run in a runset (left hand bar). Attributes:

color (str): The color of the run in the UI. Can be hex (#ff0000), css color (red), or rgb (rgb(255, 0, 0))
disabled (bool): Whether the run is deactivated (eye closed in the UI). Default is set to False.

`class` `RunsetSettings`

Settings for the runset (the left bar containing runs) in a workspace. Attributes:

query (str): A query to filter the runset (can be a regex expr, see next param).
regex_query (bool): Controls whether the query (above) is a regex expr. Default is set to False.
filters (Union[str, LList[FilterExpr], Or, And]): Filters for the runset.
- As a list of FilterExpr: filters are AND’d together.
- As a string: Python-like expressions, e.g., “Config(‘lr’) = 0.001 and State = ‘finished’”
Supports operators: =, ==, !=, <, >, <=, >=, in, not in, and, or
- As an Or/And combinator: allows OR logic and nested groups. e.g., Or(And(Config(“lr”) == 0.01, Metric(“State”) == “finished”), Config(“lr”) == 0.1)
groupby (LList[expr.MetricType]): A list of metrics to group by in the runset. Set to Metric, Summary, Config, Tags, or KeysInfo.
order (LList[expr.Ordering]): A list of metrics and ordering to apply to the runset.
run_settings (Dict[str, RunSettings]): A dictionary of run settings, where the key is the run’s ID and the value is a RunSettings object.
pinned_columns (LList[str]): List of column names to pin.
Column names use format: “run:displayName”, “summary:metric”, “config:param”.
run: displayName is automatically added if not present.
Example: [“summary:accuracy”, “summary:loss”]
baseline_run (Optional[str]): W&B run slug of the baseline run (the value of wandb.Run.id, e.g. "1mbku38n" — also the last path segment of a run URL). Used for delta columns and comparison styling. When set, the baseline run is automatically added to pinned_runs to match the W&B app’s behavior. Must refer to a run in the workspace’s own project — cross-project pins are not supported by this SDK yet (see the W&B app’s “Add cross-project runs” drawer for the UI equivalent).
pinned_runs (LList[str]): Ordered list of W&B run slugs to keep visible in the run selector and always fetched for plots. Pass slug strings (wandb.Run.id), not GraphQL IDs. The W&B app caps this at 20 entries.

Example:

   # Using string filters (new)
   RunsetSettings(
        filters="Config('learning_rate') = 0.001 and State = 'finished'",
        pinned_columns=["summary:accuracy", "summary:loss"],
        baseline_run="1mbku38n",  # wandb.Run.id (the slug from the URL)
        pinned_runs=["1mbku38n", "2u1g3j1c"],
   )

   # Using FilterExpr list (original way)
   RunsetSettings(
        filters=[expr.Config("learning_rate") == 0.001],
        pinned_columns=["summary:accuracy", "summary:loss"],
   )

`method` `convert_filterexpr_list_to_string`

convert_filterexpr_list_to_string()

Convert FilterExpr list or Or/And to string expression.

`method` `ensure_baseline_pinned`

ensure_baseline_pinned()

Mirror the W&B app’s invariant: a baseline run is always also pinned. The frontend’s setBaselineRun action handler routes through setRunPinnedAndBaseline, so any spec produced by the UI has the baseline ID present in pinnedRunIds. We enforce the same here so SDK-produced specs match.

`method` `validate_and_setup_columns`

validate_and_setup_columns()

Ensure run:displayName is present and set up internal column fields.

`class` `Section`

Represents a section in a workspace. Attributes:

name (str): The name/title of the section.
panels (LList[PanelTypes]): An ordered list of panels in the section. By default, first is top-left and last is bottom-right.
is_open (bool): Whether the section is open or closed. Default is closed.
pinned (bool): Whether the section is pinned. Pinned sections appear at the top of the workspace. Default is False.
layout_settings (SectionLayoutSettings): Settings for panel layout in the section.
panel_settings: Panel-level settings applied to all panels in the section, similar to WorkspaceSettings for a Section.

`class` `SectionLayoutSettings`

Panel layout settings for a section, typically seen at the top right of the section of the W&B App Workspace UI. Attributes:

columns (int): The number of columns in the layout. Default is 3.
rows (int): The number of rows in the layout. Default is 2.

`class` `SectionPanelSettings`

Panel settings for a section, similar to WorkspaceSettings for a section. Settings applied here can be overrided by more granular Panel settings in this priority: Section < Panel. Attributes:

x_axis (str): X-axis metric name setting. By default, set to “Step”.
x_min Optional[float]: Minimum value for the x-axis.
x_max Optional[float]: Maximum value for the x-axis.
smoothing_type (Literal[‘exponentialTimeWeighted’, ‘exponential’, ‘gaussian’, ‘average’, ‘none’]): Smoothing type applied to all panels.
smoothing_weight (int): Smoothing weight applied to all panels.

`class` `Workspace`

Represents a W&B workspace, including sections, settings, and config for run sets. Attributes:

entity (str): The entity this workspace will be saved to (usually user or team name).
project (str): The project this workspace will be saved to.
name: The name of the workspace.
sections (LList[Section]): An ordered list of sections in the workspace. The first section is at the top of the workspace.
settings (WorkspaceSettings): Settings for the workspace, typically seen at the top of the workspace in the UI.
runset_settings (RunsetSettings): Settings for the runset (the left bar containing runs) in a workspace.
auto_generate_panels (bool): Whether to automatically generate panels for all keys logged in this project. Recommended if you would like all available data to be visualized by default. This can only be set during workspace creation and cannot be modified afterward.

`property` auto_generate_panels

`property` url

The URL to the workspace in the W&B app.

`classmethod` `from_url`

from_url(url: str)

Get a workspace from a URL.

`method` `save`

save()

Save the current workspace to W&B. Returns:

Workspace: The updated workspace with the saved internal name and ID.

`method` `save_as_new_view`

save_as_new_view()

Save the current workspace as a new view to W&B. Returns:

Workspace: The updated workspace with the saved internal name and ID.

`class` `WorkspaceSettings`

Settings for the workspace, typically seen at the top of the workspace in the UI. This object includes settings for the x-axis, smoothing, outliers, panels, tooltips, runs, and panel query bar. Settings applied here can be overrided by more granular Section and Panel settings in this priority: Workspace < Section < Panel Attributes:

x_axis (str): X-axis metric name setting.
x_min (Optional[float]): Minimum value for the x-axis.
x_max (Optional[float]): Maximum value for the x-axis.
smoothing_type (Literal[‘exponentialTimeWeighted’, ‘exponential’, ‘gaussian’, ‘average’, ‘none’]): Smoothing type applied to all panels.
smoothing_weight (int): Smoothing weight applied to all panels.
ignore_outliers (bool): Ignore outliers in all panels.
sort_panels_alphabetically (bool): Sorts panels in all sections alphabetically.
group_by_prefix (Literal[“first”, “last”]): Group panels by the first or up to last prefix (first or last). Default is set to last.
remove_legends_from_panels (bool): Remove legends from all panels.
tooltip_number_of_runs (Literal[“default”, “all”, “none”]): The number of runs to show in the tooltip.
tooltip_color_run_names (bool): Whether to color run names in the tooltip to match the runset (True) or not (False). Default is set to True.
max_runs (int): The maximum number of runs to show per panel (this will be the first 10 runs in the runset).
point_visualization_method (Literal[“line”, “point”, “line_point”]): The visualization method for points.
panel_search_query (str): The query for the panel search bar (can be a regex expression).
auto_expand_panel_search_results (bool): Whether to auto expand the panel search results.

​class RunSettings

​class RunsetSettings

​method convert_filterexpr_list_to_string

​method ensure_baseline_pinned

​method validate_and_setup_columns

​class Section

​class SectionLayoutSettings

​class SectionPanelSettings

​class Workspace

​property auto_generate_panels

​property url

​classmethod from_url

​method save

​method save_as_new_view

​class WorkspaceSettings

`class` `RunSettings`

`class` `RunsetSettings`

`method` `convert_filterexpr_list_to_string`

`method` `ensure_baseline_pinned`

`method` `validate_and_setup_columns`

`class` `Section`

`class` `SectionLayoutSettings`

`class` `SectionPanelSettings`

`class` `Workspace`

`property` auto_generate_panels

`property` url

`classmethod` `from_url`

`method` `save`

`method` `save_as_new_view`

`class` `WorkspaceSettings`