Weights & Biases Workspaces

0.3.9 · active · verified Thu Apr 16

wandb-workspaces is a Python library designed for programmatic interaction with the Weights & Biases (W&B) UI, specifically for creating, modifying, and sharing W&B Reports and Workspaces. It allows users to define complex data visualizations, organize runs into runsets, and manage report layouts directly from Python code. The current version is 0.3.9, with a frequent release cadence, typically releasing minor bug fixes and new features every few weeks. This feature is in Public Preview.

Common errors

```
wandb.errors.CommError: W&B API Error: Not Found (e.g., for entity or project)
```
cause The specified W&B 'entity' or 'project' name does not exist or is misspelled, or the API key does not have access. This also happens if not authenticated.

fix Verify the `entity` and `project` parameters are correct. Ensure you are authenticated via `wandb login` or `WANDB_API_KEY` environment variable.
```
AttributeError: 'NoneType' object has no attribute 'entity' (or similar during .save())
```
cause The `wandb-workspaces` library is trying to access W&B backend resources but is not correctly authenticated to infer the user's entity.

fix Before creating or saving a `Report` or `Workspace`, make sure you have authenticated your environment with `wandb login` or by setting the `WANDB_API_KEY` environment variable.
```
ValidationError: 1 validation error for WorkspaceViewspec section.panelBankConfig... (or similar Pydantic validation error during .save())
```
cause The structure or configuration of your `Report` or `Workspace` object is invalid and does not conform to the expected schema by the W&B backend. This can occur with complex panel arrangements or invalid filter expressions.

fix Review the exact error message to pinpoint the problematic field. Consult the `wandb-workspaces` documentation for the correct way to structure panels, sections, and runsets for your library version. Simplify complex configurations to isolate the issue.
```
Report/Workspace panels are empty or display 'No runs found' in the W&B UI after saving, even though runs exist.
```
cause Runset filters are too restrictive, or the metrics/config keys specified in panels (e.g., `x`, `y` for `LinePlot`) do not match any available data in the selected runs.

fix Carefully check the `Runset` filters to ensure they correctly select the desired runs. Verify that the metric and config keys used in panel definitions exactly match the data logged in W&B. Ensure that the 'Step' metric is logged if it is used for an X-axis.

Warnings

gotcha The `wandb-workspaces` library is in 'Public Preview' status. This implies that the API, features, and internal implementations may evolve rapidly, potentially leading to breaking changes or shifts in best practices in future releases.
Fix: Refer to the latest official documentation and release notes for updated API usage and recommended patterns when upgrading. Be prepared for potential adjustments to your code.
gotcha Attempting to save a Report or Workspace without prior authentication to Weights & Biases (e.g., via `wandb login` CLI command or by setting the `WANDB_API_KEY` environment variable) will result in API errors.
Fix: Ensure `wandb login` has been successfully executed in your environment or set the `WANDB_API_KEY` environment variable before running scripts that use `wandb-workspaces`.
breaking Changes to Report and Workspace definition schemas, particularly related to runset filtering, panel configurations, and serialization logic, can cause issues when loading or saving reports/workspaces defined with older versions of the library.
Fix: If encountering issues with existing report definitions, try regenerating them with the latest library version or carefully review the changelog for relevant fixes and update your code accordingly. Pay close attention to how `Runset` filters and panel properties are defined.

Install

pip install wandb-workspaces Primary installation
pip install wandb[workspaces] Install as an extra with the main wandb library

Imports

Report
wrong:
```
from wandb.reports import Report
```
correct:
```
from wandb_workspaces.reports import Report
```
Report is part of the separate wandb-workspaces library, not a direct submodule of the main wandb library.
Workspace
wrong:
```
from wandb.workspaces import Workspace
```
correct:
```
from wandb_workspaces.workspaces import Workspace
```
Workspace is part of the separate wandb-workspaces library, not a direct submodule of the main wandb library.
LinePlot
```
from wandb_workspaces.panels import LinePlot
```
Panel types like LinePlot are imported from the panels submodule.
Runset
```
from wandb_workspaces.runsets import Runset
```
Runset is used for defining collections of W&B runs within reports and workspaces.

Quickstart

This quickstart demonstrates how to create a basic Weights & Biases Report with a title, description, and a grid of common panels (LinePlot, BarPlot, ScalarChart). It emphasizes the need for W&B authentication and proper import paths.

import os
import wandb
from wandb_workspaces.reports import Report, H1, P, PanelGrid
from wandb_workspaces.panels import LinePlot, BarPlot, ScalarChart

# Ensure you are logged into W&B (e.g., via `wandb login` or WANDB_API_KEY env var)
# For a runnable example, ensure WANDB_API_KEY is set in your environment
# os.environ['WANDB_API_KEY'] = 'YOUR_API_KEY' 
# os.environ['WANDB_ENTITY'] = 'your-entity'
# os.environ['WANDB_PROJECT'] = 'your-project'

entity = os.environ.get('WANDB_ENTITY', 'your-entity') # Replace with your W&B entity
project = os.environ.get('WANDB_PROJECT', 'your-project') # Replace with your W&B project

# Initialize a dummy W&B run to ensure authentication if not already logged in
# Not strictly necessary for report creation if API key is set, but good practice.
# try:
#     wandb.init(project=project, entity=entity, mode='offline')
# finally:
#     wandb.finish()


# Create a W&B Report
report = Report(
    entity=entity,
    project=project,
    title="My Programmatic Report Example",
    description="A report created entirely with wandb-workspaces."
)

# Add blocks and panels to the report
report.blocks = [
    H1("Introduction"),
    P("This report demonstrates how to programmatically generate W&B reports with various visualizations."),
    H1("Key Metrics"),
    PanelGrid(
        panels=[
            LinePlot(x="Step", y=["val_loss", "train_loss"], title="Loss Over Steps"),
            BarPlot(metrics=["val_accuracy"], title="Validation Accuracy"),
            ScalarChart(metric="f1_score", groupby_aggfunc="mean", title="Mean F1 Score")
        ]
    )
]

# Save the report
report.save()

print(f"Report saved: {report.url}")

view raw JSON →