Post-toolregistry follow-ups: uxarray 2026.6.0, new ops, science workflows

[rajeeja]

Summary

Follow-up work after the toolregistry-server port (#63). Three themes: refresh
the UXarray dependency to the latest release, expose new UXarray operations, and
grow the guided science-workflow surface beyond the single vorticity_analysis
helper.

No breaking changes to existing tool behavior. The full suite passes (322
tests); pre-commit (ruff + mypy) is clean; uv lock --check is consistent.

Dependencies

• Bump the uxarray floor to >=2026.6.0 (released 2026-06-18) and regenerate
  uv.lock. The lock now reflects the toolregistry stack (fastmcp fully gone).

New run_analysis operations

• zonal_anomaly — per-face deviation from the zonal mean of each latitude
  band (UxDataArray.zonal_anomaly). Natural sibling to calculate_zonal_mean.
• remap_to_rectilinear — remap an unstructured variable onto a regular
  lon/lat grid (UxDataArray.remap.to_rectilinear).
• gradient / curl gain scale_by_radius — defaults to False to
  preserve the historical unit-sphere result; set True to divide by
  uxgrid.sphere_radius for physical units. (UXarray 2026.6.0 changed its own
  default to True; keeping False here avoids a silent change to existing
  results.)

Guided science workflows (prompt/ tools)

Previously vorticity_analysis was the only domain-science guided workflow.
Added four more, each composing existing operations around a scientific question
and returning an interpretation plan (instruction text, no new computation):

• cyclone_structure — storm/vortex radial structure (azimuthal_mean +
  subset_bbox, optionally curl).
• eddy_activity — departures from the zonal mean (calculate_zonal_mean +
  zonal_anomaly + gradient).
• model_evaluation — verification vs a reference (bias + rmse +
  pattern_correlation).
• climatology_anomaly — time-mean state and anomalies (temporal_mean +
  anomaly, optionally calculate_zonal_mean).

Profiles: core 27 → 31, deferred-full 58 → 64.

Policy tags

• Add FILE_SYSTEM to the session tools (they persist/read JSON records) and
  FILE_SYSTEM + NETWORK to get_execution_mode (reads config; queries the
  endpoint when configured).
• Fix a stale RuntimeError message that referenced the removed FastMCP
  mcp.tool() registration.

Docs

• Fix stale docs/architecture.html labels (toolregistry, Python 3.12).
• CHANGELOG.md: 0.2.0 section, backfill 0.1.1, new Unreleased entries.
• New docs/serving.md (profiles, transports, OpenAPI/REST, tool discovery,
  no-AI-client usage).
• docs/tools.md operations table + science-workflow prompts; AGENTS.md counts.

Tests

• New tests/test_new_uxarray_features.py covering scale_by_radius,
  zonal_anomaly, and remap_to_rectilinear (incl. a capability-guard negative
  test).
• New science-workflow-prompt test and policy-tag tests; updated deferred/prompt
  counts.

322 passed, 8 warnings

The 8 warnings are a benign scale_by_radius UserWarning from UXarray's
divergence (which calls gradient internally) on test grids without a
sphere_radius; results correctly stay on the unit sphere.

Notes

• The new operations are backed by methods present in the pinned UXarray
  (>=2026.6.0); defensive capability guards remain so a clear error is raised
  if a method is ever absent.
• Conda packaging of the toolregistry stack is tracked separately; this PR does
  not touch the conda recipe.

[rajeeja]

HPC end-to-end tested on the Improv endpoint (caf37dc0-...): diagnose_endpoint status/validate pass, and remote inspect_mesh, calculate_area, inspect_variable, calculate_zonal_mean, and gradient all run with venue=hpc:improv (cold worker spin-up ~49s, warm round-trips ~1s).

Noted that the two new operations (zonal_anomaly, remap_to_rectilinear) are local-only — documented in tools.md, and the broader HPC/local segregation design (per @Oaklight's review feedback) is tracked in #66.

[rljacob]

The HPC option is only possible if the user has an account on that HPC system, right?

[rajeeja]

Ran a full old+new function matrix on the Improv endpoint - 9/9 checks pass:

Old functions (remote, venue=hpc:improv): inspect_mesh, calculate_area, inspect_variable, calculate_zonal_mean, calculate_gradient — all OK on real MPAS QU480 + dyamond-30km data.

New features: gradient/curl scale_by_radius remote, plus the local-only zonal_anomaly/remap_to_rectilinear correctly raising FileNotFoundError on HPC-resident files.

The run surfaced a real bug: the remote gradient/curl path was dropping scale_by_radius, so use_remote=True silently ran on the unit sphere. Fixed in edc2314 — the flag is now threaded through the agent + remote compute functions, applied capability-safely (the worker may run an older UXarray), and the result honestly reports the scale_by_radius actually applied. Verified on Improv: with the older worker UXarray the remote result correctly reports scale_by_radius=False (fallback). Added a regression test.

Timing: warm round-trips ~1–7s; cold worker re-spin ~3–4 min (PBS provisioning).

[rajeeja]

@rljacob requesting your review when you have a moment. Quick orientation:

What this does (post-#63 follow-ups):

• Bumps uxarray floor to >=2026.6.0 (latest release) and relocks.
• Adds 3 run_analysis operations: zonal_anomaly, remap_to_rectilinear, and a scale_by_radius flag on gradient/curl (default False preserves existing unit-sphere results).
• Adds 4 guided science-workflow prompts (cyclone, eddy, model-eval, climatology) so vorticity isn't a one-off.
• Docs cleanup + new docs/serving.md.

Verification: 323 tests pass, CI green, and validated end-to-end on the Improv endpoint (real MPAS data; the HPC run caught and fixed a scale_by_radius remote-path bug).

Two judgment calls worth your eye:

1. toolregistry-server capped at <0.4 — 0.4.0 dropped the toolregistry_server.mcp module we import (breaks fresh installs). Short-term cap; migration is separate.
2. zonal_anomaly/remap_to_rectilinear are local-only for now (no remote path). Documented; broader HPC/local segregation tracked in Design: uniform HPC/local segregation across the tool surface #66 (from Peng's review feedback).

[rajeeja]

The HPC option is only possible if the user has an account on that HPC system, right?

Right; the HPC option only kicks in once you've set up a Globus Compute endpoint on that system, which requires an account/allocation there to run it. Without a configured endpoint, everything just runs locally with the same tools.