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.

[Copilot]

Pull request overview

This PR is a follow-up to the toolregistry-server port, updating the UXarray dependency to >=2026.6.0, exposing new run_analysis operations (zonal_anomaly, remap_to_rectilinear), adding scale_by_radius support for gradient/curl, and expanding the guided science workflow surface via additional prompt/ tools.

Changes:

• Bump dependencies (notably uxarray>=2026.6.0 and toolregistry-server>=0.4.0) and update lockfile.
• Add new analysis operations (zonal_anomaly, remap_to_rectilinear) plus scale_by_radius threading through local + HPC code paths for gradient/curl.
• Add four new guided science-workflow prompt tools and update docs/tests to reflect the expanded core/deferred surfaces.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
uv.lock	Updates resolved dependency versions for UXarray and toolregistry-server stack.
pyproject.toml	Raises dependency floors (uxarray>=2026.6.0, toolregistry-server>=0.4.0).
src/uxarray_mcp/tools/frontdoor.py	Extends run_analysis dispatcher with new operations and new parameters (incl. scale_by_radius, lat_spec, rectilinear targets).
src/uxarray_mcp/tools/vector_calc.py	Threads scale_by_radius through gradient/curl tool calls (local + remote dispatch).
src/uxarray_mcp/domain/vector_calc.py	Implements local gradient/curl computation using UXarray’s scale_by_radius.
src/uxarray_mcp/remote/compute_functions.py	Adds remote implementations that conditionally apply scale_by_radius based on worker UXarray support.
src/uxarray_mcp/remote/agent.py	Extends agent RPC surface to pass scale_by_radius through to remote compute functions.
src/uxarray_mcp/domain/zonal.py	Adds compute_zonal_anomaly_stats domain helper.
src/uxarray_mcp/domain/__init__.py	Exports compute_zonal_anomaly_stats.
src/uxarray_mcp/tools/inspection.py	Adds calculate_zonal_anomaly tool (local).
src/uxarray_mcp/tools/advanced.py	Adds remap_to_rectilinear tool (persisted rectilinear dataset result + stats).
src/uxarray_mcp/tools/__init__.py	Exposes new tools (calculate_zonal_anomaly, remap_to_rectilinear) in the public surface.
src/uxarray_mcp/tools/capabilities.py	Adds capability-gated advertisement of zonal_anomaly and remap.to_rectilinear.
src/uxarray_mcp/registry.py	Registers new deferred tools, adds new prompt/ guided workflows, updates tags/search hints.
tests/test_vector_calc.py	Adds tests for scale_by_radius defaults and remote forwarding.
tests/test_calculate_zonal_mean.py	Adds unit/integration coverage for zonal anomaly (domain + run_analysis dispatch + negative capability test).
tests/test_advanced_tools.py	Adds run_analysis dispatch tests for rectilinear remap (including missing target coords error).
tests/conftest.py	Adds fixtures for HEALPix datasets and a structured mesh NetCDF round-trip grid/data pair.
tests/test_server.py	Updates expected tool counts and adds prompt validation for referencing real operations.
docs/tools.md	Documents new operations, parameters, and new science-workflow prompts.
docs/serving.md	New documentation page for profiles/transports/OpenAPI and tool discovery.
docs/index.rst	Reorganizes toctrees to include tools/serving and clarify MCP vs REST surfaces.
docs/conf.py	Updates Sphinx exclude patterns.
docs/api.rst	Expands API docs coverage for domain/tools modules introduced/expanded here.
docs/architecture.html	Updates labels to reflect toolregistry-server and Python 3.12.
README.md	Clarifies local-by-default behavior and HPC opt-in messaging.
CHANGELOG.md	Adds Unreleased entries for new operations/prompts and backfills 0.1.1 notes.
AGENTS.md	Updates counts and prompt helper list to match the expanded core profile.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.