{"id":7855,"library":"wandb-workspaces","title":"Weights & Biases Workspaces","description":"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.","status":"active","version":"0.3.9","language":"en","source_language":"en","source_url":"https://github.com/wandb/wandb-workspaces","tags":["machine learning","MLOps","Weights & Biases","reporting","data visualization","experiment tracking"],"install":[{"cmd":"pip install wandb-workspaces","lang":"bash","label":"Primary installation"},{"cmd":"pip install wandb[workspaces]","lang":"bash","label":"Install as an extra with the main wandb library"}],"dependencies":[{"reason":"Core dependency for interacting with the Weights & Biases platform.","package":"wandb","optional":false},{"reason":"Used for data validation and settings management within the library.","package":"pydantic","optional":false},{"reason":"Runtime environment requirement.","package":"python","optional":false}],"imports":[{"note":"Report is part of the separate wandb-workspaces library, not a direct submodule of the main wandb library.","wrong":"from wandb.reports import Report","symbol":"Report","correct":"from wandb_workspaces.reports import Report"},{"note":"Workspace is part of the separate wandb-workspaces library, not a direct submodule of the main wandb library.","wrong":"from wandb.workspaces import Workspace","symbol":"Workspace","correct":"from wandb_workspaces.workspaces import Workspace"},{"note":"Panel types like LinePlot are imported from the panels submodule.","symbol":"LinePlot","correct":"from wandb_workspaces.panels import LinePlot"},{"note":"Runset is used for defining collections of W&B runs within reports and workspaces.","symbol":"Runset","correct":"from wandb_workspaces.runsets import Runset"}],"quickstart":{"code":"import os\nimport wandb\nfrom wandb_workspaces.reports import Report, H1, P, PanelGrid\nfrom wandb_workspaces.panels import LinePlot, BarPlot, ScalarChart\n\n# Ensure you are logged into W&B (e.g., via `wandb login` or WANDB_API_KEY env var)\n# For a runnable example, ensure WANDB_API_KEY is set in your environment\n# os.environ['WANDB_API_KEY'] = 'YOUR_API_KEY' \n# os.environ['WANDB_ENTITY'] = 'your-entity'\n# os.environ['WANDB_PROJECT'] = 'your-project'\n\nentity = os.environ.get('WANDB_ENTITY', 'your-entity') # Replace with your W&B entity\nproject = os.environ.get('WANDB_PROJECT', 'your-project') # Replace with your W&B project\n\n# Initialize a dummy W&B run to ensure authentication if not already logged in\n# Not strictly necessary for report creation if API key is set, but good practice.\n# try:\n#     wandb.init(project=project, entity=entity, mode='offline')\n# finally:\n#     wandb.finish()\n\n\n# Create a W&B Report\nreport = Report(\n    entity=entity,\n    project=project,\n    title=\"My Programmatic Report Example\",\n    description=\"A report created entirely with wandb-workspaces.\"\n)\n\n# Add blocks and panels to the report\nreport.blocks = [\n    H1(\"Introduction\"),\n    P(\"This report demonstrates how to programmatically generate W&B reports with various visualizations.\"),\n    H1(\"Key Metrics\"),\n    PanelGrid(\n        panels=[\n            LinePlot(x=\"Step\", y=[\"val_loss\", \"train_loss\"], title=\"Loss Over Steps\"),\n            BarPlot(metrics=[\"val_accuracy\"], title=\"Validation Accuracy\"),\n            ScalarChart(metric=\"f1_score\", groupby_aggfunc=\"mean\", title=\"Mean F1 Score\")\n        ]\n    )\n]\n\n# Save the report\nreport.save()\n\nprint(f\"Report saved: {report.url}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (0.3.x)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions (0.3.x)"},{"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.","message":"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.","severity":"breaking","affected_versions":"Potentially across 0.3.x, specifically noticeable in updates like v0.3.1, v0.3.5, v0.3.6, v0.3.8, v0.3.9."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the `entity` and `project` parameters are correct. Ensure you are authenticated via `wandb login` or `WANDB_API_KEY` environment variable.","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.","error":"wandb.errors.CommError: W&B API Error: Not Found (e.g., for entity or project)"},{"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.","cause":"The `wandb-workspaces` library is trying to access W&B backend resources but is not correctly authenticated to infer the user's entity.","error":"AttributeError: 'NoneType' object has no attribute 'entity' (or similar during .save())"},{"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.","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.","error":"ValidationError: 1 validation error for WorkspaceViewspec section.panelBankConfig... (or similar Pydantic validation error during .save())"},{"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.","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.","error":"Report/Workspace panels are empty or display 'No runs found' in the W&B UI after saving, even though runs exist."}]}