### Python Environment Detection Examples

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

Provides examples of how to configure run and install commands based on the detected Python environment. Covers common environments like uv, poetry, conda, bare venv, and Docker. Includes a fallback for when the environment cannot be determined.

```Markdown
| Environment | Run command | Install command |
|---|---|---|
| uv | `uv run script.py` | `uv pip install pandas` |
| poetry | `poetry run python script.py` | `poetry add pandas` |
| conda | `conda run python script.py` | `conda install pandas` |
| bare venv | `python script.py` (with venv activated) | `pip install pandas` |
| docker | `docker exec <ctr> python script.py` | `docker exec <ctr> pip install pandas` |
```

```Markdown
**If you cannot determine the environment, write this:**

```
# Run command: uv run script.py        # always use uv run, never bare python
# Install command: uv pip install <pkg>
```
```

--------------------------------

### Quick Start: Initialize W&B API and List Runs

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Initializes the W&B API client and retrieves a list of finished runs for a specified project. It demonstrates how to set up the API object, extract entity and project information from environment variables, and filter runs by their state.

```python
import wandb
import pandas as pd
import numpy as np

api = wandb.Api()

# Entity and project from environment
import os
entity = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]
path = f"{entity}/{project}"

# List runs
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
print(f"Found {len(runs)} finished runs")
```

--------------------------------

### Initialize Weave Client and Get Calls

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This Python snippet demonstrates how to initialize the Weave client with an entity and project, and then retrieve a list of calls using the `get_calls` method. This is a fundamental step for interacting with Weave data.

```python
# --- Weave: Init and get calls ---
import weave
client = weave.init(f"{entity}/{project}")
calls = client.get_calls(limit=10)
```

--------------------------------

### Install W&B Skills via NPX

Source: https://github.com/wandb/skills/blob/main/README.md

Installs the W&B skills package into a coding agent environment. This command uses the npx utility to fetch and configure the necessary skill definitions.

```bash
npx skills add wandb/skills
```

--------------------------------

### Update wandb skills installation

Source: https://github.com/wandb/skills/blob/main/CONTRIBUTING.md

Executes the installation script with a force flag to update the current environment. This command ensures all dependencies and files are overwritten to match the latest repository state.

```bash
./install.sh --force
```

--------------------------------

### Detect Python Environment for W&B Project

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This snippet outlines the process for detecting the Python environment in a project before executing any Python code. It prioritizes checking for lock files, virtual environments, Docker configurations, and explicit user instructions. The detected environment dictates the appropriate run and install commands.

```Markdown
**Detected Python environment:** _not yet detected_

```
# Run command: <not yet detected>
# Install command: <not yet detected>
```
```

--------------------------------

### Query and Filter Calls

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WEAVE_SDK.md

Shows how to retrieve and filter trace calls using the CallsFilter class. Includes examples for sorting, limiting results, and converting output to pandas DataFrames.

```python
from weave.trace.weave_client import CallsFilter

# Basic query with limit
calls = client.get_calls(limit=100)

# Filter by op name and parent ID
op_ref = f"weave:///{client.entity}/{client.project}/op/Evaluation.evaluate:*"
calls = client.get_calls(filter=CallsFilter(op_names=[op_ref], parent_ids=["019ca0aa-745b-73f9-be4c-05e1759d3ca7"]))

# Convert to pandas for analysis
df = client.get_calls(limit=500).to_pandas()
```

--------------------------------

### W&B SDK: Get Metrics History (Sampled)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Retrieves a sampled history of metrics for a W&B run using `run.history()`. This method performs server-side downsampling using min/max bucketing to return a specified number of samples, making it fast for overviews and plotting.

```python
# Quick 500-point overview (default)
df = run.history()

# Specific metrics with more samples
df = run.history(samples=2000, keys=["loss", "val_loss", "learning_rate"])
```

--------------------------------

### W&B SDK: Get Full Metrics History (Unsampled)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Retrieves the complete, unsampled history of metrics for a W&B run using `run.scan_history()`. This method returns an iterator yielding all data points, suitable for detailed analysis or when specific data points are crucial. It also supports filtering by step range.

```python
# ALL loss values (no sampling)
losses = [row["loss"] for row in run.scan_history(keys=["loss"])]

# Step range
for row in run.scan_history(keys=["loss"], min_step=1000, max_step=2000):
    print(row["_step"], row.get("loss"))
```

--------------------------------

### W&B SDK - Initialize API and Query Runs

Source: https://context7.com/wandb/skills/llms.txt

Initialize the W&B API client and query runs with various filters, sorting options, and pagination. This allows for efficient retrieval of experiment data.

```APIDOC
## POST /api/runs

### Description
Initializes the Weights & Biases API client and allows querying of training runs based on specified filters, sorting, and pagination.

### Method
GET

### Endpoint
/api/runs

### Parameters
#### Query Parameters
- **entity** (string) - Required - The W&B entity (username or team name).
- **project** (string) - Required - The W&B project name.
- **filters** (object) - Optional - A JSON object specifying filters for runs (e.g., state, config values, summary metrics, creation date).
- **order** (string) - Optional - A string specifying the sorting order for runs (e.g., "-created_at" for newest first, "+summary_metrics.loss" for ascending loss).
- **limit** (integer) - Optional - The maximum number of runs to return.

### Request Example
```python
import wandb
import os

api = wandb.Api()
entity = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]
path = f"{entity}/{project}"

# List finished runs, newest first
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
print(f"Found {len(runs)} finished runs")

# Filter by config value
runs = api.runs(path, filters={"config.model": "gpt-4"})

# Filter by summary metric
runs = api.runs(path, filters={"summary_metrics.accuracy": {"$gt": 0.9}})

# Compound filters with date range
runs = api.runs(path, filters={
    "$and": [
        {"config.model": "transformer"},
        {"summary_metrics.loss": {"$lt": 0.5}},
        {"state": "finished"},
        {"created_at": {"$gt": "2025-01-01T00:00:00"}},
    ]
})

# Sort by best loss (ascending)
runs = api.runs(path, order="+summary_metrics.loss")

# IMPORTANT: Always slice runs - never list() all runs on large projects
first_50 = runs[:50]
```

### Response
#### Success Response (200)
- **runs** (list) - A list of run objects matching the query criteria.

#### Response Example
```json
{
  "runs": [
    {
      "id": "run-id-1",
      "name": "run-name-1",
      "state": "finished",
      "created_at": "2023-10-27T10:00:00Z",
      "config": {"learning_rate": 0.01},
      "summary_metrics": {"accuracy": 0.95, "loss": 0.1}
    },
    {
      "id": "run-id-2",
      "name": "run-name-2",
      "state": "finished",
      "created_at": "2023-10-27T09:00:00Z",
      "config": {"learning_rate": 0.005},
      "summary_metrics": {"accuracy": 0.92, "loss": 0.15}
    }
  ]
}
```
```

--------------------------------

### Initialize W&B and Weave environment

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

Retrieves project configuration from environment variables and initializes the W&B API and Weave client.

```python
import os
import wandb
import weave

entity  = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]

api = wandb.Api()
client = weave.init(f"{entity}/{project}")
```

--------------------------------

### Create and Configure W&B Reports

Source: https://context7.com/wandb/skills/llms.txt

This snippet demonstrates how to initialize a Runset, define visualization panels, and construct a report object. It requires the 'wandb[workspaces]' package and is used to automate the generation of project analysis dashboards.

```python
from wandb.apis import reports as wr

runset = wr.Runset(entity=entity, project=project, name="All runs")
plots = wr.PanelGrid(
    runsets=[runset],
    panels=[
        wr.LinePlot(title="Loss", x="_step", y=["loss"]),
        wr.BarPlot(title="Accuracy", metrics=["accuracy"], orientation="v"),
    ],
)

report = wr.Report(
    entity=entity,
    project=project,
    title="Project analysis",
    description="Summary of recent runs",
    width="fixed",
    blocks=[
        wr.H1(text="Project analysis"),
        wr.P(text="Auto-generated summary from W&B API."),
        plots,
    ],
)
# report.save(draft=True)
```

--------------------------------

### Get Run Metric Curve into NumPy Array

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Extracts a specific metric's (e.g., 'loss') historical data from a WandB run and loads it into a NumPy array. It then prints the minimum, final, and total number of steps for that metric.

```python
# Get a run's full loss curve into numpy
losses = np.array([r["loss"] for r in run.scan_history(keys=["loss"])])
print(f"Loss: min={losses.min():.6f}, final={losses[-1]:.6f}, steps={len(losses)}")
```

--------------------------------

### Initialize W&B API and Query Runs

Source: https://context7.com/wandb/skills/llms.txt

Initializes the Weights & Biases API client and demonstrates how to query runs with various filters, sorting options, and pagination. It shows filtering by state, configuration values, summary metrics, and date ranges, as well as sorting runs and slicing results for efficiency.

```python
import wandb
import pandas as pd
import numpy as np
import os

api = wandb.Api()
entity = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]
path = f"{entity}/{project}"

# List finished runs, newest first
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
print(f"Found {len(runs)} finished runs")

# Filter by config value
runs = api.runs(path, filters={"config.model": "gpt-4"})

# Filter by summary metric
runs = api.runs(path, filters={"summary_metrics.accuracy": {"$gt": 0.9}})

# Compound filters with date range
runs = api.runs(path, filters={
    "$and": [
        {"config.model": "transformer"},
        {"summary_metrics.loss": {"$lt": 0.5}},
        {"state": "finished"},
        {"created_at": {"$gt": "2025-01-01T00:00:00"}},
    ]
})

# Sort by best loss (ascending)
runs = api.runs(path, order="+summary_metrics.loss")

# IMPORTANT: Always slice runs - never list() all runs on large projects
first_50 = runs[:50]
```

--------------------------------

### Initialize Weave Client

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WEAVE_SDK.md

Demonstrates how to initialize the Weave client using the entity and project path. Note that the project string must be passed as a positional argument.

```python
import weave
import os

# Initialize with entity/project string
client = weave.init("entity/project")

# Dynamic initialization using environment variables
entity = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]
client = weave.init(f"{entity}/{project}")
```

--------------------------------

### List Projects

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Fetches a list of WandB projects for a given entity and prints their names and creation timestamps. It limits the output to the first 20 projects for brevity.

```python
projects = list(api.projects(entity, per_page=200))
for p in projects[:20]:
    print(p.name, getattr(p, "created_at", None))
```

--------------------------------

### W&B SDK: Sort and Paginate Runs

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Illustrates how to sort W&B runs based on different criteria such as creation date or summary metrics, and how to implement pagination for efficient data retrieval. It also shows how to slice the runs iterator to limit results.

```python
# Sorting
runs = api.runs(path, order="-created_at")              # newest first
runs = api.runs(path, order="+summary_metrics.loss")     # lowest loss first
runs = api.runs(path, order="-summary_metrics.val_acc")  # highest accuracy first

# Pagination
runs = api.runs(path, per_page=100)
first_50 = runs[:50]    # slice to limit (lazy)
total = len(runs)        # triggers count query
```

--------------------------------

### Compare W&B Run Configurations with wandb_helpers

Source: https://context7.com/wandb/skills/llms.txt

Compares configurations between two W&B runs side-by-side using `compare_configs` from `wandb_helpers`. The differences are returned as a list of dictionaries, which can be converted to a pandas DataFrame for easy viewing.

```python
from wandb_helpers import compare_configs
import pandas as pd

run_a = api.run(f"{path}/run-a")
run_b = api.run(f"{path}/run-b")

# Get config differences
diffs = compare_configs(run_a, run_b)
df = pd.DataFrame(diffs)
print(df.to_string(index=False))
```

--------------------------------

### Compare Configurations of Two W&B Runs

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This Python snippet shows how to compare the configurations of two W&B runs using a helper function `compare_configs`. It then prints the differences as a formatted string using a Pandas DataFrame. This is helpful for identifying changes between experiments.

```python
# --- W&B: Compare two runs ---
from wandb_helpers import compare_configs
diffs = compare_configs(run_a, run_b)
print(pd.DataFrame(diffs).to_string(index=False))
```

--------------------------------

### W&B SDK - Access Run Properties and Summary Metrics

Source: https://context7.com/wandb/skills/llms.txt

Access detailed properties of a specific run, including its identity, state, configuration (hyperparameters), and summary metrics. This is useful for analyzing individual experiment results.

```APIDOC
## GET /api/runs/{run_id}

### Description
Retrieves detailed information about a specific Weights & Biases run, including its identity, state, configuration, and summary metrics.

### Method
GET

### Endpoint
/api/runs/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.
- **entity** (string) - Required - The W&B entity (username or team name).
- **project** (string) - Required - The W&B project name.

### Request Example
```python
import wandb
import os

api = wandb.Api()
entity = os.environ["WANDB_ENTITY"]
project = os.environ["WANDB_PROJECT"]
path = f"{entity}/{project}"
run_id = "your-run-id"

run = api.run(f"{path}/{run_id}")

# Identity properties
print(f"Run ID: {run.id}")         # 8-char hash
print(f"Name: {run.name}")         # display name
print(f"URL: {run.url}")           # full URL
print(f"State: {run.state}")       # "finished", "failed", "crashed", "running"

# Configuration (hyperparameters logged at wandb.init())
print(f"Learning Rate: {run.config.get('learning_rate')}")
clean_config = {k: v for k, v in run.config.items() if not k.startswith("_")}

# Summary metrics (final values)
print(f"Final Loss: {run.summary_metrics.get('loss')}")
print(f"Accuracy: {run.summary_metrics.get('accuracy')}")

# Convert runs to DataFrame (example for multiple runs)
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
rows = []
for run in runs[:200]:  # Always slice
    rows.append({
        "id": run.id,
        "name": run.name,
        "state": run.state,
        "created_at": run.created_at,
        **{f"config.{k}": v for k, v in run.config.items() if not k.startswith("_")},
        "loss": run.summary_metrics.get("loss"),
        "accuracy": run.summary_metrics.get("accuracy"),
    })
df = pd.DataFrame(rows)
print(df.describe())
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the run.
- **name** (string) - The display name of the run.
- **url** (string) - The URL of the run in the W&B UI.
- **state** (string) - The current state of the run (e.g., "finished", "running").
- **config** (object) - A dictionary of hyperparameters used in the run.
- **summary_metrics** (object) - A dictionary of final summary metrics for the run.

#### Response Example
```json
{
  "id": "run-id-12345",
  "name": "My Awesome Run",
  "url": "https://wandb.ai/user/project/runs/run-id-12345",
  "state": "finished",
  "config": {
    "learning_rate": 0.01,
    "batch_size": 32,
    "model": "transformer"
  },
  "summary_metrics": {
    "accuracy": 0.95,
    "loss": 0.1,
    "epoch": 10
  }
}
```
```

--------------------------------

### Fetch and Download Wandb Artifacts (Python)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Demonstrates how to fetch Wandb artifacts by name and version/alias, access their properties (like type, metadata, size), and download them to a local directory. It also shows how to retrieve lineage information (producer and consumers). Requires the Wandb API.

```python
# Fetch by name + version/alias
artifact = api.artifact(f"{path}/model-weights:latest")
artifact = api.artifact(f"{path}/model-weights:v3")

# Properties
print(artifact.name)         # str
print(artifact.type)         # str: "model", "dataset"
print(artifact.version)      # str: "v0", "v1"
print(artifact.aliases)      # list[str]: ["latest", "best"]
print(artifact.metadata)     # dict
print(artifact.size)         # int: bytes
print(artifact.created_at)   # str

# Download
local_path = artifact.download()
artifact.download(root="/tmp/data")
artifact.download(path_prefix="train/")

# Lineage
producer = artifact.logged_by()
consumers = artifact.used_by()
```

--------------------------------

### Create and Save W&B Report

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This Python code snippet demonstrates how to create a W&B report with panels and blocks using the `wandb.apis.reports` module. It shows how to define a runset, create a panel grid with line and bar plots, and construct a report with titles, descriptions, and custom blocks. The report can be saved as a draft or published.

```python
from wandb.apis import reports as wr

runset = wr.Runset(entity=entity, project=project, name="All runs")
plots = wr.PanelGrid(
    runsets=[runset],
    panels=[
        wr.LinePlot(title="Loss", x="_step", y=["loss"]),
        wr.BarPlot(title="Accuracy", metrics=["accuracy"], orientation="v"),
    ],
)

report = wr.Report(
    entity=entity,
    project=project,
    title="Project analysis",
    description="Summary of recent runs",
    width="fixed",
    blocks=[
        wr.H1(text="Project analysis"),
        wr.P(text="Auto-generated summary from W&B API."),
        plots,
    ],
)

# report.save(draft=True)
```

--------------------------------

### Compare Configuration and Metrics of Two Runs (Python)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Compares the configuration parameters and key summary metrics (like 'loss', 'accuracy') between two specific Wandb runs. This helps in understanding the differences that might lead to performance variations. It requires the Wandb API and pandas.

```python
import pandas as pd

run_a = api.run(f"{path}/run-a")
run_b = api.run(f"{path}/run-b")

# Config diff
config_df = pd.DataFrame([run_a.config, run_b.config]).T
config_df.columns = [run_a.name, run_b.name]
diff = config_df[config_df.iloc[:, 0] != config_df.iloc[:, 1]]
print("Config differences:")
print(diff.to_string())

# Metric comparison
for key in ["loss", "accuracy", "val_loss"]:
    a = run_a.summary_metrics.get(key, "N/A")
    b = run_b.summary_metrics.get(key, "N/A")
    print(f"  {key}: {a} vs {b}")
```

--------------------------------

### Query Call Statistics with Weave SDK

Source: https://context7.com/wandb/skills/llms.txt

Demonstrates how to aggregate call statistics by operation name or filter for root-only traces using the Weave client's server interface.

```python
for op_name in ["rollout", "ruler_score_group", "openai.chat.completions.create"]:
    stats = client.server.calls_query_stats(CallsQueryStatsReq(
        project_id=f"{client.entity}/{client.project}",
        filter={"op_names": [f"weave:///{client.entity}/{client.project}/op/{op_name}:*"]},
    ))
    print(f"  {op_name}: {stats.count}")

stats = client.server.calls_query_stats(CallsQueryStatsReq(
    project_id=f"{client.entity}/{client.project}",
    filter={"trace_roots_only": True},
))
print(f"Root traces: {stats.count}")
```

--------------------------------

### Annotate source files with license headers

Source: https://github.com/wandb/skills/blob/main/CONTRIBUTING.md

Uses the REUSE tool to automatically inject SPDX-compliant license headers into source files. It requires specifying the license, copyright holder, and year.

```shell
reuse annotate --license Apache-2.0 --copyright 'CoreWeave, Inc.'  --year 2026 --template default_template --skip-existing $FILE
```

--------------------------------

### W&B SDK - Query Metrics History

Source: https://context7.com/wandb/skills/llms.txt

Access the training history of a run, either as a sampled overview or full unsampled data. Supports querying specific metrics and step ranges.

```APIDOC
## GET /api/runs/{run_id}/history

### Description
Retrieves the training metrics history for a specific Weights & Biases run. Supports sampling for overview and full data for precision analysis.

### Method
GET

### Endpoint
/api/runs/{run_id}/history

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.
- **entity** (string) - Required - The W&B entity (username or team name).
- **project** (string) - Required - The W&B project name.

#### Query Parameters
- **samples** (integer) - Optional - The number of samples to retrieve for a sampled overview (default is 500).
- **keys** (list of strings) - Optional - A list of specific metric keys to retrieve.
- **min_step** (integer) - Optional - The minimum step number to include in the history.
- **max_step** (integer) - Optional - The maximum step number to include in the history.
- **format** (string) - Optional - The desired output format ('pandas' for DataFrame, default is list of dicts).

### Request Example
```python
import wandb
import pandas as pd
import numpy as np

api = wandb.Api()
run = api.run("entity/project/run-id")

# Quick 500-point sampled overview (default)
df_sampled = run.history()

# Specific metrics with more samples
df_specific = run.history(samples=2000, keys=["loss", "val_loss", "learning_rate"])

# Full unsampled history - use for precision analysis
losses_history = list(run.scan_history(keys=["loss"]))

# Step range query
for row in run.scan_history(keys=["loss"], min_step=1000, max_step=2000):
    print(row["_step"], row.get("loss"))

# Full loss curve to numpy for analysis
losses = np.array([r["loss"] for r in run.scan_history(keys=["loss"])])
print(f"Loss: min={losses.min():.6f}, final={losses[-1]:.6f}, steps={len(losses)}")

# Find minimum loss
df_loss = pd.DataFrame(list(run.scan_history(keys=["loss", "_step"])))
min_idx = df_loss["loss"].idxmin()
print(f"Min loss: {df_loss.loc[min_idx, 'loss']:.6f} at step {df_loss.loc[min_idx, '_step']}")

# Bulk history for multiple runs
runs = api.runs("entity/project", filters={"state": "finished"})
df_bulk = runs.histories(samples=200, keys=["loss", "val_loss"], format="pandas")
# df_bulk has columns: run_id, _step, loss, val_loss
```

### Response
#### Success Response (200)
- **history** (list or DataFrame) - A list of dictionaries or a pandas DataFrame containing the metrics history, depending on the requested format.

#### Response Example
```json
[
  {
    "_step": 0,
    "loss": 1.5,
    "val_loss": 1.6,
    "learning_rate": 0.01
  },
  {
    "_step": 1,
    "loss": 1.4,
    "val_loss": 1.55,
    "learning_rate": 0.01
  }
  // ... more history data
]
```
```

--------------------------------

### Download Best Model Artifact

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Finds the run with the best performance based on a summary metric (e.g., 'loss'), identifies the 'model' type artifact logged by that run, and downloads it to a specified local directory. It then prints the name and version of the downloaded artifact.

```python
# Download best model artifact
best_run = api.runs(path, order="+summary_metrics.loss")[:1][0]
for art in best_run.logged_artifacts():
    if art.type == "model":
        art.download(root="/tmp/best_model")
        print(f"Downloaded {art.name}:{art.version}")
```

--------------------------------

### Diagnose W&B Training Run with wandb_helpers

Source: https://context7.com/wandb/skills/llms.txt

Provides a quick diagnostic summary of a W&B training run using `diagnose_run` from `wandb_helpers`. The summary includes metrics like convergence, overfitting indicators, and NaN detection.

```python
from wandb_helpers import diagnose_run

run = api.run(f"{path}/run-id")
diag = diagnose_run(run)

for k, v in diag.items():
    print(f"  {k}: {v}")
```

--------------------------------

### Validate and generate licensing documentation

Source: https://github.com/wandb/skills/blob/main/CONTRIBUTING.md

Commands to verify the project's licensing state and generate a Software Bill of Materials (BOM) using the REUSE tool.

```shell
reuse lint
reuse spdx
```

--------------------------------

### Access W&B Run Properties and Summary Metrics

Source: https://context7.com/wandb/skills/llms.txt

Demonstrates how to access various properties of a Weights & Biases run object, including identity, state, configuration (hyperparameters), and summary metrics. It also shows how to convert a list of runs into a pandas DataFrame for easier analysis.

```python
run = api.run(f"{path}/run-id")

# Identity properties
print(f"Run ID: {run.id}")         # 8-char hash
print(f"Name: {run.name}")         # display name
print(f"URL: {run.url}")           # full URL
print(f"State: {run.state}")       # "finished", "failed", "crashed", "running"

# Configuration (hyperparameters logged at wandb.init())
lr = run.config.get("learning_rate")
clean_config = {k: v for k, v in run.config.items() if not k.startswith("_")}

# Summary metrics (final values)
final_loss = run.summary_metrics.get("loss")
accuracy = run.summary_metrics.get("accuracy")

# Convert runs to DataFrame
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
rows = []
for run in runs[:200]:  # Always slice
    rows.append({
        "id": run.id,
        "name": run.name,
        "state": run.state,
        "created_at": run.created_at,
        **{f"config.{k}": v for k, v in run.config.items() if not k.startswith("_")},
        "loss": run.summary_metrics.get("loss"),
        "accuracy": run.summary_metrics.get("accuracy"),
    })
df = pd.DataFrame(rows)
print(df.describe())
```

--------------------------------

### Find Best Run by Loss using W&B API

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This Python snippet shows how to find the run with the best (lowest) loss from a W&B project. It uses the `api.runs` method to filter for finished runs and order them by `summary_metrics.loss`, then selects the top run and prints its name and loss value.

```python
# --- W&B: Best run by loss ---
best = api.runs(path, filters={"state": "finished"}, order="+summary_metrics.loss")[:1]
print(f"Best: {best[0].name}, loss={best[0].summary_metrics.get('loss')}")
```

--------------------------------

### Import W&B and Weave Helper Libraries (Python)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

Imports necessary helper functions from the `weave_helpers` and `wandb_helpers` modules. These functions facilitate common operations for W&B and Weave, such as unwrapping Weave types, extracting token usage, converting evaluation results, and generating dataframes from W&B runs.

```Python
import sys
sys.path.insert(0, "skills/wandb-primary/scripts")

# Weave helpers (traces, evals, GenAI)
from weave_helpers import (
    unwrap,                  # Recursively convert Weave types -> plain Python
    get_token_usage,         # Extract token counts from a call's summary
    eval_results_to_dicts,   # predict_and_score calls -> list of result dicts
    pivot_solve_rate,        # Build task-level pivot table across agents
    results_summary,         # Print compact eval summary
    eval_health,             # Extract status/counts from Evaluation.evaluate calls
    eval_efficiency,         # Compute tokens-per-success across eval calls
)

# W&B helpers (training runs, metrics)
from wandb_helpers import (
    runs_to_dataframe,       # Convert runs to a clean pandas DataFrame
    diagnose_run,            # Quick diagnostic summary of a training run
    compare_configs,         # Side-by-side config diff between two runs
)
```

--------------------------------

### W&B SDK: Filter Runs by Various Criteria

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Demonstrates various methods for filtering W&B runs using the `api.runs()` method. It covers filtering by state, configuration values, summary metrics, display name, tags, and date ranges, including compound filters using `$and`.

```python
# All runs (lazy iterator)
runs = api.runs(path)

# By state
runs = api.runs(path, filters={"state": "finished"})

# By config value
runs = api.runs(path, filters={"config.model": "gpt-4"})
runs = api.runs(path, filters={"config.learning_rate": {"$lt": 0.01}})

# By summary metric
runs = api.runs(path, filters={"summary_metrics.accuracy": {"$gt": 0.9}})
runs = api.runs(path, filters={"summary_metrics.loss": {"$lt": 0.5}})

# By display name (regex)
runs = api.runs(path, filters={"display_name": {"$regex": ".*v2.*"}})

# By tags
runs = api.runs(path, filters={"tags": {"$in": ["production"]}})
runs = api.runs(path, filters={"tags": {"$nin": ["deprecated"]}})

# Date range
runs = api.runs(path, filters={
    "$and": [
        {"created_at": {"$gt": "2025-01-01T00:00:00"}},
        {"created_at": {"$lt": "2025-06-01T00:00:00"}},
    ]
})

# Config key exists
runs = api.runs(path, filters={"config.special_param": {"$exists": True}})

# Compound filters
runs = api.runs(path, filters={
    "$and": [
        {"config.model": "transformer"},
        {"summary_metrics.loss": {"$lt": 0.5}},
        {"state": "finished"},
    ]
})
```

--------------------------------

### Summarize W&B run history data

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

Demonstrates how to avoid memory issues by computing statistics on W&B run history instead of printing raw rows. It uses numpy to calculate metrics like min, final, and mean values.

```python
import pandas as pd
import numpy as np

# GOOD: load into numpy, compute stats, print summary
losses = np.array([r["loss"] for r in run.scan_history(keys=["loss"])])
print(f"Loss: {len(losses)} steps, min={losses.min():.4f}, "
      f"final={losses[-1]:.4f}, mean_last_10%={losses[-len(losses)//10:].mean():.4f}")
```

--------------------------------

### W&B SDK - Anomaly and Overfitting Detection

Source: https://context7.com/wandb/skills/llms.txt

Utilize W&B SDK to analyze training metrics for anomalies, divergence, plateaus, and overfitting using statistical methods.

```APIDOC
## POST /api/analyze/metrics

### Description
Analyzes training metrics from W&B runs to detect anomalies, divergence, plateaus, and overfitting using statistical methods. This endpoint facilitates proactive identification of potential training issues.

### Method
POST

### Endpoint
/api/analyze/metrics

### Parameters
#### Request Body
- **run_ids** (list of strings) - Required - A list of run IDs to analyze.
- **metrics** (list of strings) - Required - A list of metric names to analyze (e.g., "loss", "val_loss").
- **analysis_type** (string) - Optional - Specifies the type of analysis to perform (e.g., "anomaly_detection", "overfitting_detection"). Defaults to "anomaly_detection".
- **parameters** (object) - Optional - Additional parameters for the analysis (e.g., window size for moving averages, thresholds for anomaly detection).

### Request Example
```python
import wandb
import pandas as pd

api = wandb.Api()
run_ids_to_analyze = ["run-id-1", "run-id-2"]
metrics_to_analyze = ["loss", "val_loss"]

# Example: Detect anomalies in loss and val_loss
anomaly_results = api.analyze_metrics(
    run_ids=run_ids_to_analyze,
    metrics=metrics_to_analyze,
    analysis_type="anomaly_detection",
    parameters={"threshold": 3.0} # Example parameter
)

# Example: Detect overfitting
overfitting_results = api.analyze_metrics(
    run_ids=run_ids_to_analyze,
    metrics=metrics_to_analyze,
    analysis_type="overfitting_detection",
    parameters={"window_size": 50} # Example parameter
)

# The analysis results can be processed further, e.g., converted to a DataFrame
df_anomaly = pd.DataFrame(anomaly_results)
print(df_anomaly)
```

### Response
#### Success Response (200)
- **analysis_results** (list) - A list of objects, where each object contains the results of the analysis for a specific run and metric. The structure of the results depends on the `analysis_type`.

#### Response Example
```json
[
  {
    "run_id": "run-id-1",
    "metric": "loss",
    "anomalies": [
      {"step": 150, "value": 5.2, "type": "spike"},
      {"step": 300, "value": 0.1, "type": "plateau"}
    ]
  },
  {
    "run_id": "run-id-2",
    "metric": "val_loss",
    "anomalies": [
      {"step": 250, "value": 1.8, "type": "divergence"}
    ]
  }
]
```
```

--------------------------------

### Retrieve token usage and costs

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

Extracts token usage statistics from a call object and retrieves cost information from the call summary.

```python
from weave_helpers import get_token_usage

usage = get_token_usage(call)
print(f"Tokens: {usage['total_tokens']} (in={usage['input_tokens']}, out={usage['output_tokens']})")

call_with_costs = client.get_call("id", include_costs=True)
costs = call_with_costs.summary.get("weave", {}).get("costs", {})
```

--------------------------------

### Advanced MongoDB-Style Queries

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WEAVE_SDK.md

Demonstrates how to use the Query interface to perform complex filtering, such as finding calls with exceptions or matching substrings within op names.

```python
from weave.trace_server.interface.query import Query

# Find calls with exceptions
error_calls = client.get_calls(
    query=Query(**{
        "$expr": {
            "$not": [{"$eq": [{"$getField": "exception"}, {"$literal": None}]}]
        }
    })
)
```

--------------------------------

### Analyze System Metrics (GPU, CPU, Memory)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Retrieves and analyzes system metrics like GPU utilization, memory usage, and CPU load from a WandB run's history. It calculates mean, min, and max values for GPU utilization and memory, and identifies periods of low GPU utilization.

```python
# GPU, CPU, memory, disk
sys_df = run.history(stream="system")
# Columns: system.cpu, system.memory, system.disk,
#           system.gpu.0.gpu, system.gpu.0.memory, system.gpu.0.temp

# GPU utilization analysis
if "system.gpu.0.gpu" in sys_df.columns:
    gpu = sys_df["system.gpu.0.gpu"].dropna()
    print(f"GPU util: mean={gpu.mean():.1f}%, min={gpu.min():.1f}%, max={gpu.max():.1f}%")
    low = gpu[gpu < 50]
    print(f"Low utilization (<50%): {len(low)}/{len(gpu)} samples")

# Memory
if "system.gpu.0.memory" in sys_df.columns:
    mem = sys_df["system.gpu.0.memory"].dropna()
    print(f"GPU memory: mean={mem.mean():.1f}%, max={mem.max():.1f}%")

# Latest snapshot
latest = run.system_metrics  # dict
```

--------------------------------

### Configure W&B API Key

Source: https://github.com/wandb/skills/blob/main/README.md

Sets the WANDB_API_KEY environment variable required for authenticating agent requests to the Weights & Biases platform. Replace <your-key> with your actual API token.

```bash
export WANDB_API_KEY=<your-key>
```

--------------------------------

### Find Minimum Loss Value and Step (Python)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Identifies the minimum loss value and its corresponding step from a run's history. This pattern is crucial for understanding the best performance achieved during training. It relies on pandas for data manipulation.

```python
import pandas as pd

df = pd.DataFrame(list(run.scan_history(keys=["loss", "_step"])))
min_idx = df["loss"].idxmin()
print(f"Min loss: {df.loc[min_idx, 'loss']:.6f} at step {df.loc[min_idx, '_step']}")
```

--------------------------------

### W&B SDK: Access Run Properties

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Shows how to access various properties of a specific W&B run object, including its ID, name, entity, project, URL, state, creation timestamp, tags, configuration parameters, and summary metrics.

```python
run = api.run(f"{path}/run-id")

# Identity
run.id           # str: 8-char hash
run.name         # str: display name
run.entity       # str
run.project      # str
run.url          # str: full URL
run.path         # list: [entity, project, run_id]

# State & metadata
run.state        # "finished", "failed", "crashed", "running"
run.created_at   # str: ISO timestamp
run.tags         # list[str]

# Config (hyperparameters)
run.config       # dict — logged at wandb.init()
lr = run.config.get("learning_rate")
clean_config = {k: v for k, v in run.config.items() if not k.startswith("_")}

# Summary (final metric values)
run.summary_metrics  # dict (read-only snapshot — prefer for reads)
final_loss = run.summary_metrics.get("loss")
```

--------------------------------

### Create Pivot Table for Cross-Agent Analysis with weave_helpers

Source: https://context7.com/wandb/skills/llms.txt

Builds a task-level pivot table aggregating results across multiple agents using `eval_results_to_dicts` and `pivot_solve_rate` from `weave_helpers`. It then converts the pivot table to a pandas DataFrame for display.

```python
from weave_helpers import eval_results_to_dicts, pivot_solve_rate
import pandas as pd

# Collect results from multiple agents
all_results = []
for agent_name in ["claude-code", "codex", "cursor"]:
    # Get calls for each agent...
    results = eval_results_to_dicts(pas_calls, agent_name=agent_name)
    all_results.extend(results)

# Build pivot table
pivot = pivot_solve_rate(all_results)
df = pd.DataFrame(pivot)
print(df.to_string(index=False))
```

--------------------------------

### W&B SDK: Convert Runs to Pandas DataFrame

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Demonstrates how to convert a list of W&B runs into a pandas DataFrame for easier analysis. It iterates through a sliced list of runs, extracts relevant properties like ID, name, config, and summary metrics, and populates a DataFrame.

```python
runs = api.runs(path, filters={"state": "finished"}, order="-created_at")
rows = []
for run in runs[:200]:  # ALWAYS slice
    rows.append({
        "id": run.id,
        "name": run.name,
        "state": run.state,
        "created_at": run.created_at,
        **{f"config.{k}": v for k, v in run.config.items() if not k.startswith("_")},
        "loss": run.summary_metrics.get("loss"),
        "accuracy": run.summary_metrics.get("accuracy"),
    })
df = pd.DataFrame(rows)
print(df.describe())
```

--------------------------------

### Query W&B Metrics History

Source: https://context7.com/wandb/skills/llms.txt

Explains how to retrieve training history from a Weights & Biases run using `history()` for sampled overviews and `scan_history()` for full, unsampled data. It covers fetching specific metrics, defining step ranges, converting history to NumPy arrays, finding minimum values, and performing bulk history queries for multiple runs.

```python
# Quick 500-point sampled overview (default)
df = run.history()

# Specific metrics with more samples
df = run.history(samples=2000, keys=["loss", "val_loss", "learning_rate"])

# Full unsampled history - use for precision analysis
losses = [row["loss"] for row in run.scan_history(keys=["loss"])]

# Step range query
for row in run.scan_history(keys=["loss"], min_step=1000, max_step=2000):
    print(row["_step"], row.get("loss"))

# Full loss curve to numpy for analysis
losses = np.array([r["loss"] for r in run.scan_history(keys=["loss"])])
print(f"Loss: min={losses.min():.6f}, final={losses[-1]:.6f}, steps={len(losses)}")

# Find minimum loss
df = pd.DataFrame(list(run.scan_history(keys=["loss", "_step"])))
min_idx = df["loss"].idxmin()
print(f"Min loss: {df.loc[min_idx, 'loss']:.6f} at step {df.loc[min_idx, '_step']}")

# Bulk history for multiple runs
runs = api.runs(path, filters={"state": "finished"})
df = runs.histories(samples=200, keys=["loss", "val_loss"], format="pandas")
# df has columns: run_id, _step, loss, val_loss
```

--------------------------------

### Fetch Multiple Runs History to DataFrame (Python)

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WANDB_SDK.md

Fetches history data from multiple finished runs, allowing for sampling and key selection, then formats it into a pandas DataFrame. This is useful for comparing metrics across different runs. It requires the Wandb API and pandas.

```python
import pandas as pd

runs = api.runs(path, filters={"state": "finished"})
df = runs.histories(samples=200, keys=["loss", "val_loss"], format="pandas")
# df has columns: run_id, _step, loss, val_loss
```

--------------------------------

### Importing Weave Components

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WEAVE_SDK.md

Provides the necessary import statements for key Weave components, including `CallsFilter` for filtering calls, `Query` for database-style queries, and `CallsQueryStatsReq` for accessing statistics endpoints.

```python
# CallsFilter
from weave.trace.weave_client import CallsFilter

# Query (MongoDB-style)
from weave.trace_server.interface.query import Query

# Stats endpoint
from weave.trace_server.trace_server_interface import CallsQueryStatsReq
```

--------------------------------

### Convert W&B Run History Loss to NumPy Array

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/SKILL.md

This Python snippet demonstrates how to extract the 'loss' metric from a W&B run's history and convert it into a NumPy array. It then prints the minimum loss, final loss, and the number of steps recorded. This is useful for analyzing training progress.

```python
# --- W&B: Loss curve to numpy ---
losses = np.array([r["loss"] for r in run.scan_history(keys=["loss"])])
print(f"min={losses.min():.6f}, final={losses[-1]:.6f}, steps={len(losses)}")
```

--------------------------------

### Accessing Call Data in Weave

Source: https://github.com/wandb/skills/blob/main/skills/wandb-primary/references/WEAVE_SDK.md

Demonstrates how to access input, output, and exception details from a Weave call object. It also shows how to retrieve the execution status and token usage associated with a call, keyed by model name.

```python
# I/O — these are WeaveDict/WeaveObject, use unwrap() if needed
call.inputs          # WeaveDict (dict-like)
call.output          # WeaveDict or WeaveObject or None
call.exception       # str | None

# Status
status = call.summary.get("weave", {}).get("status")
# "success", "error", "running", "descendant_error"

# Token usage (keyed by model name)
usage = call.summary.get("usage", {})
for model_name, u in usage.items():
    input_tokens = u.get("input_tokens") or u.get("prompt_tokens") or 0
    output_tokens = u.get("output_tokens") or u.get("completion_tokens") or 0
    total = u.get("total_tokens", 0)
```