Add one-shot analysis entry point: analyze(path) or analyze(session_id, dataset_handle)

[rajeeja]

Problem

The most natural user request — "analyze this dataset" — today requires the user (or agent) to know and orchestrate 5+ tool calls:

1. inspect_mesh
2. validate_dataset
3. inspect_variable
4. calculate_area
5. calculate_zonal_mean
6. plot_variable

This is not how the best tools work. The user should say one thing and get a complete answer.

Proposed tool: analyze_dataset

def analyze_dataset(
    grid_path: str | None = None,
    data_path: str | None = None,
    session_id: str | None = None,
    dataset_handle: str | None = None,
    use_remote: bool = False,
) -> dict:

Runs the full pipeline internally:

• Inspect mesh topology
• Validate dataset
• Discover variables
• Calculate area statistics
• Compute zonal mean for first face-centered variable
• Render mesh and variable plots (as base64 PNG)
• Return everything in one structured result

Why this matters

This is what makes the difference between a library wrapper and a scientific assistant. A climate scientist with no uxarray knowledge should be able to point at a file and get a complete picture of their data in one call.

Relationship to run_scientific_agent

run_scientific_agent is the autonomous LLM-driven version of this. analyze_dataset is the deterministic, always-works version. Both should exist — one for simple use, one for complex reasoning.

[rajeeja]

Status check (2026-05-09): still open. There is no analyze_dataset tool. run_scientific_agent (tools/scientific_agent.py) overlaps in spirit but has a different shape — it runs an Analyze→Plan→Execute→Verify trace and returns a structured reasoning record, not a one-shot {topology, validation, area, zonal_mean, plots} bundle. If we want the lightweight "point at a file, get a complete picture" UX described here, it should be a thin orchestrator over the existing tools rather than a new agent loop.

[rajeeja]

Implemented in #40 (analyze_dataset orchestrator) and validated end-to-end in #41 against local + Improv + UCAR endpoints.