uxarray-mcp 0.1.3__tar.gz → 0.2.0__tar.gz

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uxarray-mcp
-Version: 0.1.3
+Version: 0.2.0
 Summary: MCP server for analyzing unstructured meshes with UXarray
 Keywords: uxarray,mcp,unstructured grids,scientific computing,globus compute
 Author: Rajeev Jain, Dayan Abdulla
@@ -427,10 +427,16 @@ auditable and the server actively flags common scientific pitfalls:
 - **Derivative unit convention is never hidden.** `gradient`, `curl`, and
   `divergence` echo `scale_by_radius` in both the result and provenance, so a
   unit-sphere result can never be mistaken for a physical (per-metre) one.
+  Gradient and curl default to physical scaling, matching UXarray; pass
+  `scale_by_radius=False` explicitly for unit-sphere output.
 - **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
   when the two inputs are the same field, or when neither carries a
   velocity/flux-like `units` attribute — the classic "vorticity from two random
-  scalars" mistake now surfaces a warning in `_provenance.warnings`.
+  scalars" mistake now surfaces a warning in `_provenance.warnings` and a
+  machine-actionable `scientific_status` with stable warning codes.
+- **Applicability is not suitability.** `get_capabilities` reports whether
+  vector operations are structurally computable separately from whether
+  metadata supports physical interpretation.
 - **Local/remote version drift is surfaced.** Remote results record the
   worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
   warning when it differs from the local version, so silent numerical

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/README.md

@@ -191,10 +191,16 @@ auditable and the server actively flags common scientific pitfalls:
 - **Derivative unit convention is never hidden.** `gradient`, `curl`, and
   `divergence` echo `scale_by_radius` in both the result and provenance, so a
   unit-sphere result can never be mistaken for a physical (per-metre) one.
+  Gradient and curl default to physical scaling, matching UXarray; pass
+  `scale_by_radius=False` explicitly for unit-sphere output.
 - **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
   when the two inputs are the same field, or when neither carries a
   velocity/flux-like `units` attribute — the classic "vorticity from two random
-  scalars" mistake now surfaces a warning in `_provenance.warnings`.
+  scalars" mistake now surfaces a warning in `_provenance.warnings` and a
+  machine-actionable `scientific_status` with stable warning codes.
+- **Applicability is not suitability.** `get_capabilities` reports whether
+  vector operations are structurally computable separately from whether
+  metadata supports physical interpretation.
 - **Local/remote version drift is surfaced.** Remote results record the
   worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
   warning when it differs from the local version, so silent numerical

uxarray_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "uxarray-mcp"
+version = "0.2.0"
+description = "MCP server for analyzing unstructured meshes with UXarray"
+readme = "README.md"
+keywords = [
+    "uxarray",
+    "mcp",
+    "unstructured grids",
+    "scientific computing",
+    "globus compute",
+]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+]
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "toolregistry-server[mcp]>=0.4.0",
+    "holoviews>=1.19.0",
+    "matplotlib>=3.9.0",
+    "pyyaml>=6.0",
+    "uxarray>=2026.6.0",
+]
+
+[[project.authors]]
+name = "Rajeev Jain"
+email = "rajeeja@gmail.com"
+
+[[project.authors]]
+name = "Dayan Abdulla"
+email = "dayanabdulla000@gmail.com"
+
+[project.license]
+file = "LICENSE"
+
+[project.optional-dependencies]
+openapi = ["toolregistry-server[openapi]>=0.4.0"]
+hpc = [
+    "academy-py>=0.3.1",
+    "globus-compute-sdk>=4.5.0",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-book-theme>=1.1.0",
+    "myst-parser>=3.0",
+]
+
+[project.scripts]
+uxarray-mcp = "uxarray_mcp.cli:main"
+
+[project.urls]
+Documentation = "https://uxarray-mcp-server.readthedocs.io"
+Source = "https://github.com/UXARRAY/uxarray-mcp-server"
+Tracker = "https://github.com/UXARRAY/uxarray-mcp-server/issues"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10.0",
+    "pre-commit>=4.3.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.15.2",
+]
+
+[tool.mypy]
+python_version = "3.12"
+check_untyped_defs = true
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_return_any = false
+exclude = [
+    "tests/",
+    "docs/",
+]
+
+[[tool.mypy.overrides]]
+module = "yaml"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "uxarray_mcp.remote.agent"
+warn_unused_ignores = false
+
+[tool.ruff]
+extend-exclude = ["docs/architecture.html"]
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.ruff.lint.per-file-ignores]
+"notebooks/*.py" = ["E402"]
+"notebooks/*.ipynb" = ["E402"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["uxarray_mcp"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

uxarray_mcp-0.1.3/pyproject.toml → uxarray_mcp-0.2.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "uxarray-mcp"
-version = "0.1.3"
+version = "0.2.0"
 description = "MCP server for analyzing unstructured meshes with UXarray"
 readme = "README.md"
 keywords = ["uxarray", "mcp", "unstructured grids", "scientific computing", "globus compute"]

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/src/uxarray_mcp/__init__.py

@@ -3,4 +3,4 @@
 from uxarray_mcp.tools import inspect_mesh
 
 __all__ = ["inspect_mesh"]
-__version__ = "0.1.3"
+__version__ = "0.2.0"

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/src/uxarray_mcp/domain/area.py

@@ -14,11 +14,16 @@ def compute_area_stats(grid: Any) -> dict:
     Returns
     -------
     dict
-        Keys: total_area, mean_area, min_area, max_area, area_units, n_face
+        Keys: total_area, mean_area, min_area, max_area, area_units, n_face.
+        ``area_units`` is ``None`` when the grid carries no ``units``
+        attribute at all -- reporting a fabricated ``"m^2"`` default in
+        that case would silently invent metadata the source file never
+        provided, which is the exact failure mode this server's
+        provenance and guardrail mechanisms exist to prevent.
     """
     face_areas = grid.face_areas
 
-    area_units = "m^2"
+    area_units = None
     if hasattr(face_areas, "attrs") and "units" in face_areas.attrs:
         area_units = face_areas.attrs["units"]
 

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/src/uxarray_mcp/domain/vector_calc.py

@@ -2,7 +2,31 @@
 
 from __future__ import annotations
 
-from typing import Any
+import warnings as _warnings_module
+from typing import Any, Callable, TypeVar
+
+_T = TypeVar("_T")
+
+
+def _call_capturing_warnings(fn: Callable[[], _T]) -> tuple[_T, list[str]]:
+    """Call ``fn`` and capture any Python warnings it raises as strings.
+
+    UXarray itself emits ``UserWarning``s for conditions a caller needs to
+    know about to trust a result -- e.g. ``scale_by_radius=True`` silently
+    falling back to unit-sphere output when the grid has no
+    ``sphere_radius`` attribute. Those warnings normally only reach a
+    terminal's stderr and are invisible to an agent reading the tool's
+    structured JSON result. Capturing them here and merging them into the
+    same ``warnings`` list as our own guardrail messages means every
+    warning that would change how a scientist should trust the number ends
+    up in ``_provenance.warnings``, not just the ones this server authored.
+    """
+    with _warnings_module.catch_warnings(record=True) as caught:
+        _warnings_module.simplefilter("always")
+        value = fn()
+        messages = [str(w.message) for w in caught]
+    return value, messages
+
 
 # Units that look like a genuine 2-D vector (velocity/flux) component. Used only
 # to raise a soft, non-blocking warning when curl/divergence inputs do not look
@@ -23,13 +47,62 @@ _VELOCITY_LIKE_UNIT_HINTS = (
 )
 
 
+_FACE_DIMS = {"n_face", "nCells"}
+
+# Common non-spatial dimension names, in the order we prefer to select from
+# when a caller gives a single generic index but the data has both a time and
+# a vertical dimension (rare, but keeps behavior predictable).
+_TIME_DIM_NAMES = ("time", "Time", "time_counter")
+_LEVEL_DIM_NAMES = ("lev", "level", "levels", "plev", "z", "nVertLevels")
+
+
+def _reduce_to_face(
+    var: Any,
+    *,
+    time_index: int = 0,
+    level_index: int = 0,
+) -> Any:
+    """Select a single time/level slice so ``var`` is 1-D face-centered.
+
+    UXarray's vector-calculus operators (``.curl()``, ``.divergence()``,
+    ``.gradient()``) require a single face-centered dimension with no leading
+    time/level/ensemble axes. Real model output almost always carries at
+    least a time dimension, and 3-D fields (e.g. atmospheric wind) also carry
+    a vertical dimension, so gateway tools take explicit ``time_index`` /
+    ``level_index`` selectors rather than requiring the caller to pre-slice
+    the file themselves.
+
+    Any extra dimension not recognized as time-like or level-like, and not
+    size-1, is squeezed via index 0 with a caveat left to the caller to
+    surface as a warning if desired.
+    """
+    extra = [d for d in var.dims if d not in _FACE_DIMS]
+    if not extra:
+        return var
+
+    selection: dict[str, int] = {}
+    for dim in extra:
+        if var.sizes[dim] == 1:
+            selection[dim] = 0
+        elif dim in _TIME_DIM_NAMES:
+            selection[dim] = time_index
+        elif dim in _LEVEL_DIM_NAMES:
+            selection[dim] = level_index
+        else:
+            # Unrecognized extra dimension: fall back to the first slice
+            # rather than erroring, matching plotting.py's existing behavior.
+            selection[dim] = 0
+
+    return var.isel(**selection)
+
+
 def _vector_component_warnings(
     u_variable: str,
     v_variable: str,
     u: Any,
     v: Any,
     operation: str,
-) -> list[str]:
+) -> tuple[list[str], list[str]]:
     """Return soft warnings when (u, v) do not look like real vector components.
 
     curl and divergence are only physically meaningful when ``u`` and ``v`` are
@@ -45,8 +118,10 @@ def _vector_component_warnings(
     scientist — can see that the inputs were suspicious.
     """
     warnings: list[str] = []
+    warning_codes: list[str] = []
 
     if u_variable == v_variable:
+        warning_codes.append("VECTOR_COMPONENTS_IDENTICAL")
         warnings.append(
             f"{operation}: u_variable and v_variable are the same field "
             f"('{u_variable}'). {operation} is only physically meaningful for a "
@@ -65,6 +140,7 @@ def _vector_component_warnings(
         return any(hint in unit for hint in _VELOCITY_LIKE_UNIT_HINTS)
 
     if not (_looks_velocity(u_unit) or _looks_velocity(v_unit)):
+        warning_codes.append("VECTOR_UNITS_UNVERIFIED")
         seen = ", ".join(
             f"{name}='{unit or 'unset'}'"
             for name, unit in ((u_variable, u_unit), (v_variable, v_unit))
@@ -76,11 +152,15 @@ def _vector_component_warnings(
             f"{operation} physically."
         )
 
-    return warnings
+    return warnings, warning_codes
 
 
 def compute_gradient(
-    uxds: Any, variable_name: str, scale_by_radius: bool = False
+    uxds: Any,
+    variable_name: str,
+    scale_by_radius: bool = True,
+    time_index: int = 0,
+    level_index: int = 0,
 ) -> dict:
     """Compute the gradient of a face-centered scalar field.
 
@@ -94,10 +174,17 @@ def compute_gradient(
         Loaded UXarray dataset.
     variable_name : str
         Face-centered scalar variable to differentiate.
-    scale_by_radius : bool, default False
+    scale_by_radius : bool, default True
         When ``True``, divide the unit-sphere derivatives by
         ``uxgrid.sphere_radius`` to return physical units (requires a grid with
-        ``sphere_radius``). The default ``False`` keeps the unit-sphere result.
+        ``sphere_radius``). Pass ``False`` to keep the unit-sphere result.
+    time_index : int, default 0
+        Time index to select if the variable carries a leading time
+        dimension. Ignored if there is no time dimension.
+    level_index : int, default 0
+        Vertical-level index to select if the variable carries a level
+        dimension (e.g. atmospheric ``lev``). Ignored if there is no level
+        dimension.
 
     Returns
     -------
@@ -115,11 +202,21 @@ def compute_gradient(
             f"Variable '{variable_name}' is not face-centered. "
             "Gradient requires face-centered data."
         )
+    var = _reduce_to_face(var, time_index=time_index, level_index=level_index)
 
     import numpy as np
 
     # gradient() returns a UxDataset with zonal and meridional components.
-    grad = var.gradient(scale_by_radius=scale_by_radius)
+    grad, uxarray_warnings = _call_capturing_warnings(
+        lambda: var.gradient(scale_by_radius=scale_by_radius)
+    )
+    _dedup_seen: set[str] = set()
+    _deduped: list[str] = []
+    for _w in uxarray_warnings:
+        if _w not in _dedup_seen:
+            _dedup_seen.add(_w)
+            _deduped.append(_w)
+    uxarray_warnings = _deduped
     comp_names = list(grad.data_vars)
 
     def _stats(arr: Any) -> dict:
@@ -135,18 +232,31 @@ def compute_gradient(
 
     components = {name: _stats(grad[name]) for name in comp_names}
 
-    return {
+    result = {
         "variable_name": variable_name,
         "components": comp_names,
         "component_stats": components,
         "n_face": int(uxds.uxgrid.n_face),
         "scale_by_radius": bool(scale_by_radius),
         "interpretation": "zonal (∂/∂x) and meridional (∂/∂y) components of the gradient",
+        "component_warnings": uxarray_warnings,
     }
+    from uxarray_mcp.provenance import attach_scientific_status
+
+    return attach_scientific_status(
+        result,
+        warnings=uxarray_warnings,
+        warning_codes=["SPHERE_RADIUS_UNAVAILABLE"] if uxarray_warnings else [],
+    )
 
 
 def compute_curl(
-    uxds: Any, u_variable: str, v_variable: str, scale_by_radius: bool = False
+    uxds: Any,
+    u_variable: str,
+    v_variable: str,
+    scale_by_radius: bool = True,
+    time_index: int = 0,
+    level_index: int = 0,
 ) -> dict:
     """Compute the curl (relative vorticity) of a 2-D vector field (u, v).
 
@@ -163,10 +273,17 @@ def compute_curl(
         Zonal (east–west) component variable name.
     v_variable : str
         Meridional (north–south) component variable name.
-    scale_by_radius : bool, default False
+    scale_by_radius : bool, default True
         When ``True``, divide the unit-sphere result by ``uxgrid.sphere_radius``
         to return physical units (``1/s`` for wind in ``m/s``; requires a grid
-        with ``sphere_radius``). The default ``False`` keeps the unit sphere.
+        with ``sphere_radius``). Pass ``False`` to keep the unit sphere.
+    time_index : int, default 0
+        Time index to select if the components carry a leading time
+        dimension. Ignored if there is no time dimension.
+    level_index : int, default 0
+        Vertical-level index to select if the components carry a level
+        dimension (e.g. atmospheric ``lev``). Ignored if there is no level
+        dimension.
 
     Returns
     -------
@@ -186,14 +303,31 @@ def compute_curl(
                 f"Variable '{name}' is not face-centered. "
                 "Curl requires face-centered vector components."
             )
+    u = _reduce_to_face(u, time_index=time_index, level_index=level_index)
+    v = _reduce_to_face(v, time_index=time_index, level_index=level_index)
 
     import numpy as np
 
-    component_warnings = _vector_component_warnings(
+    component_warnings, warning_codes = _vector_component_warnings(
         u_variable, v_variable, u, v, "curl"
     )
 
-    result = u.curl(v, scale_by_radius=scale_by_radius)
+    result, uxarray_warnings = _call_capturing_warnings(
+        lambda: u.curl(v, scale_by_radius=scale_by_radius)
+    )
+    # UXarray's curl() computes an internal gradient per component, so the
+    # same sphere_radius UserWarning can fire more than once for one call;
+    # de-duplicate while preserving order for a clean, non-repetitive
+    # provenance record.
+    seen: set[str] = set()
+    deduped_uxarray_warnings = []
+    for w in uxarray_warnings:
+        if w not in seen:
+            seen.add(w)
+            deduped_uxarray_warnings.append(w)
+    component_warnings = component_warnings + deduped_uxarray_warnings
+    if deduped_uxarray_warnings:
+        warning_codes.append("SPHERE_RADIUS_UNAVAILABLE")
     vals = result.values
     finite = vals[np.isfinite(vals)]
 
@@ -208,7 +342,7 @@ def compute_curl(
     else:
         stats = {"min": None, "max": None, "mean": None, "std": None}
 
-    return {
+    result = {
         "u_variable": u_variable,
         "v_variable": v_variable,
         "interpretation": "relative vorticity ζ = ∂v/∂x − ∂u/∂y",
@@ -217,9 +351,20 @@ def compute_curl(
         "stats": stats,
         "component_warnings": component_warnings,
     }
+    from uxarray_mcp.provenance import attach_scientific_status
 
+    return attach_scientific_status(
+        result, warnings=component_warnings, warning_codes=warning_codes
+    )
 
-def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
+
+def compute_divergence(
+    uxds: Any,
+    u_variable: str,
+    v_variable: str,
+    time_index: int = 0,
+    level_index: int = 0,
+) -> dict:
     """Compute the horizontal divergence of a 2-D vector field (u, v).
 
     Divergence = ∂u/∂x + ∂v/∂y.
@@ -236,6 +381,13 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
         Zonal (east–west) component variable name.
     v_variable : str
         Meridional (north–south) component variable name.
+    time_index : int, default 0
+        Time index to select if the components carry a leading time
+        dimension. Ignored if there is no time dimension.
+    level_index : int, default 0
+        Vertical-level index to select if the components carry a level
+        dimension (e.g. atmospheric ``lev``). Ignored if there is no level
+        dimension.
 
     Returns
     -------
@@ -255,14 +407,21 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
                 f"Variable '{name}' is not face-centered. "
                 "Divergence requires face-centered vector components."
             )
+    u = _reduce_to_face(u, time_index=time_index, level_index=level_index)
+    v = _reduce_to_face(v, time_index=time_index, level_index=level_index)
 
     import numpy as np
 
-    component_warnings = _vector_component_warnings(
+    component_warnings, warning_codes = _vector_component_warnings(
         u_variable, v_variable, u, v, "divergence"
     )
 
-    result = u.divergence(v)
+    result, uxarray_warnings = _call_capturing_warnings(lambda: u.divergence(v))
+    for warning in uxarray_warnings:
+        if warning not in component_warnings:
+            component_warnings.append(warning)
+    if uxarray_warnings:
+        warning_codes.append("SPHERE_RADIUS_UNAVAILABLE")
     vals = result.values
     finite = vals[np.isfinite(vals)]
 
@@ -277,7 +436,7 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
     else:
         stats = {"min": None, "max": None, "mean": None, "std": None}
 
-    return {
+    output = {
         "u_variable": u_variable,
         "v_variable": v_variable,
         "interpretation": "horizontal divergence ∂u/∂x + ∂v/∂y",
@@ -285,6 +444,11 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
         "stats": stats,
         "component_warnings": component_warnings,
     }
+    from uxarray_mcp.provenance import attach_scientific_status
+
+    return attach_scientific_status(
+        output, warnings=component_warnings, warning_codes=warning_codes
+    )
 
 
 def compute_azimuthal_mean(

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/src/uxarray_mcp/provenance.py

@@ -77,3 +77,20 @@ def attach_provenance(
         provenance["validation_summary"] = validation_summary
     result["_provenance"] = provenance
     return result
+
+
+def attach_scientific_status(
+    result: dict[str, Any],
+    *,
+    warnings: list[str] | None = None,
+    warning_codes: list[str] | None = None,
+) -> dict[str, Any]:
+    """Attach a machine-actionable scientific interpretation status."""
+    messages = warnings or []
+    result["scientific_status"] = {
+        "status": "warning" if messages else "complete",
+        "physically_interpretable": not messages,
+        "warning_codes": warning_codes or [],
+        "warnings": messages,
+    }
+    return result

{uxarray_mcp-0.1.3 → uxarray_mcp-0.2.0}/src/uxarray_mcp/remote/agent.py

@@ -218,7 +218,9 @@ class UXarrayComputeAgent(_AcademyAgent):
         grid_path: str,
         data_path: str,
         variable_name: str,
-        scale_by_radius: bool = False,
+        scale_by_radius: bool = True,
+        time_index: int = 0,
+        level_index: int = 0,
     ) -> Dict[str, Any]:
         """Compute spatial gradient on HPC."""
         return await self._run_on_hpc(
@@ -227,6 +229,8 @@ class UXarrayComputeAgent(_AcademyAgent):
             data_path,
             variable_name,
             scale_by_radius,
+            time_index,
+            level_index,
         )
 
     @action
@@ -236,7 +240,9 @@ class UXarrayComputeAgent(_AcademyAgent):
         data_path: str,
         u_variable: str,
         v_variable: str,
-        scale_by_radius: bool = False,
+        scale_by_radius: bool = True,
+        time_index: int = 0,
+        level_index: int = 0,
     ) -> Dict[str, Any]:
         """Compute relative vorticity (curl) on HPC."""
         return await self._run_on_hpc(
@@ -246,15 +252,29 @@ class UXarrayComputeAgent(_AcademyAgent):
             u_variable,
             v_variable,
             scale_by_radius,
+            time_index,
+            level_index,
         )
 
     @action
     async def calculate_divergence_remote(
-        self, grid_path: str, data_path: str, u_variable: str, v_variable: str
+        self,
+        grid_path: str,
+        data_path: str,
+        u_variable: str,
+        v_variable: str,
+        time_index: int = 0,
+        level_index: int = 0,
     ) -> Dict[str, Any]:
         """Compute horizontal divergence on HPC."""
         return await self._run_on_hpc(
-            remote_calculate_divergence, grid_path, data_path, u_variable, v_variable
+            remote_calculate_divergence,
+            grid_path,
+            data_path,
+            u_variable,
+            v_variable,
+            time_index,
+            level_index,
         )
 
     @action