| name | wandb-diagnostics |
| description | Read WandB run diagnostics (grad norms, losses, PPO KL/entropy, explained variance) to analyze numerical stability and training behavior for RL algorithms in this repo. Use when the user provides a WandB run URL or run id and asks for algorithm analysis from logs. |
| disable-model-invocation | true |
WandB Diagnostics Reader
What this skill does
- Fetches a WandB run’s recent history for a set of known diagnostic metric keys.
- Detects non-finite values (NaN/Inf) in key stability metrics (notably
critic/grad_norm, actor/grad_norm).
- Produces a compact human summary plus a JSON payload that an agent can interpret programmatically.
Main entrypoint (helper script)
Run:
uv run python -m active_adaptation.utils.wandb_diagnostics \
--run <wandb_run_spec> \
--samples 4000
Where <wandb_run_spec> can be one of:
run:<entity>/<project>/<run_id>- a
https://wandb.ai/... URL
<entity>/<project>/<run_id>
The command prints:
- a short “Issues:” list
- “Summary JSON:” with per-metric min/max/last and non-finite detection
- a cache path under
.cache/wandb-diagnostics/<run_id>.json (gitignored; for agent follow-up)
Use --no-cache to skip writing, or --out <path> to override the default path.
Agent follow-up: read the cached JSON instead of re-fetching WandB:
cat .cache/wandb-diagnostics/<run_id>.json
Step-by-step workflow
- Ask the user for the WandB run URL or run spec.
- If the user also knows the algorithm family, tell the agent what keys to expect:
- SAC-like:
critic/grad_norm, critic/q_loss, critic/q_upper, actor/grad_norm
- PPO-like:
critic/explained_var, actor/approx_kl, actor/entropy
- Execute the helper command above (or use the user’s requested
--samples).
- Use the JSON payload to decide what went wrong:
critic/grad_norm non-finite → numerical instability in critic (AMP overflow, target explosion, or loss outliers)- negative
critic/explained_var → value head not tracking returns
- large
actor/approx_kl → policy update too aggressive (PPO LR/clip/trust region)
- Propose code/config mitigations grounded in this repo:
- critic non-finite: try
algo.use_amp=false and/or algo.critic_loss=huber
- BAC/BEE instability: set
algo.bee_lambda=0 (turn off BEE mixing) or lower LR
- if you already changed SAC targets: re-check critic loss precision (fp32)
Notes / caveats
- This tool reads WandB via
wandb.Api(). It requires that the environment can access WandB and that credentials are available (typically via wandb login).
- Metric keys vary across configs. If the run doesn’t log one of the expected metrics, it will appear as empty in the JSON summary.
- If NaNs are intermittent, per-step detection may only flag the sampled history window controlled by
--samples.
Suggested output to return to the user
- 1 paragraph: main finding (e.g. “NaNs appear intermittently in
critic/grad_norm after enabling BEE.”)
- 3–5 bullet points: most likely causes + concrete config-level fixes to try next.
