1 reporting.wandb

reporting.wandb

W&B run discovery, history analysis, media, and frozen report evidence.

1.1 Package guide

This package owns W&B run acquisition and its reporting adapters. The package marker exports no catalogue: callers choose a workflow from an explicit leaf.

  • runs.py owns API protocols, discovery/filtering, and metadata/config/summary tables. Constructing the API client is explicit and imports W&B lazily.
  • history.py owns interactive sampled-history acquisition, optional infinity cleanup, axis selection, and deterministic dynamics/dataframe projections.
  • media.py reads local run image directories; it makes no API calls.
  • plots.py renders exploratory Matplotlib/Seaborn views of acquired tables.
  • _evidence.py is the existing scientific-report transaction, relocated intact: it acquires exact run IDs, freezes metadata and history, checks identity before and after acquisition, and produces canonical report products. Use the public ScientificReportBuilder for this workflow.
runs protocols/discovery -> sampled history -> exploratory plots
          |
          +-> exact report evidence -> immutable report snapshot -> export
local run directories -> media

1.2 Usage

This example performs no network request:

import pandas as pd
from aria_nbv.reporting.wandb.history import prepare_history_long_dataframe

history = pd.DataFrame({"_step": [0, 1], "loss": [2.0, 1.0]})
curves = prepare_history_long_dataframe({"demo": history}, metric="loss")
assert list(curves.columns) == [
    "run_id",
    "run_name",
    "x_kind",
    "source_row_ordinal",
    "step",
    "value",
]

For interactive acquisition, load_run_histories(runs, max_rows=2000) requests sampled histories and replaces infinities in a new dataframe by default; replace_inf=False retains the raw returned history. These samples do not establish complete-run evidence. Scientific reports retain their explicit sampled versus complete mode; complete mode uses scan_history, confirmatory runs must be finished, and changed run identity fails closed. Export consumes an already frozen snapshot and does not reacquire a run.

History cleanup, row order, dataframe columns, NaNs, and digest bytes are behavioral contracts. The move does not unify exploratory summaries with exact report evidence: their acquisition and completeness requirements differ. Scientific interpretation and immutable publication remain with the report builder, results and explanation owners described in the parent README.

1.3 Optional post-run QH history mirror

qh_history_mirror.mirror_qh_diagnostic_histories mirrors an explicit batch of complete local QH histories into one new W&B run. It validates every sidecar, terminal receipt digest, fit identity, and recorded execution controls before opening a run. Each cell has its own optimizer-update axis. The local files remain authoritative; W&B transport errors return mirror-only failure status.

from pathlib import Path
from aria_nbv.configs.wandb_config import WandbConfig
from aria_nbv.reporting.wandb.qh_history_mirror import QhMirrorAttempt, mirror_qh_diagnostic_histories

status = mirror_qh_diagnostic_histories(
    (QhMirrorAttempt(Path("attempt-0001.jsonl"), Path("diagnostic-receipt.json")),),
    config=WandbConfig(offline=True),
)

The caller chooses the paths and W&B mode. Fitting never starts a mirror. Older opt-in receipts without recorded execution controls cannot pass this mirror’s admission check; their local history remains readable.

1.4 Migration and proof

Former utils.wandb_utils callers now import the relevant leaf. The former private reporting._wandb owner is reporting.wandb._evidence; no parallel acquisition implementation or root re-export layer remains. The two time-series reducers formerly in utils.reporting moved unchanged into history.py; its remaining cosmetic label formatter joins utils.console.formatting.pretty_label. The old generic reporting helper module is removed.

From the repository root:

cd aria_nbv
uv run pytest tests/reporting tests/app/panels/test_wandb_panel.py \
  tests/app/panels/test_reporting_panel.py tests/lightning/test_cli.py

Tests cover exact sorted-run acquisition, complete history, changing metadata, zero acquisition during export, sampled API arguments and non-mutating cleanup.

Back to top