### Example: Build and Poll for Dataset Job

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

Demonstrates how to use `build_dataset` to create a dataset and then poll for its completion using the `get` function. This example shows how to construct a dataset job and monitor its progress.

```python
from hermes_weather.tools.dataset import build_dataset
from hermes_weather.tools.jobs import get

# Build 3-day MLECAPE dataset
result = build_dataset(env,
    task_type="render",
    dates=["20240115", "20240116", "20240117"],
    cycles=[12],
    forecast_hours=[0, 3, 6, 9, 12],
    products=["ecape_mlecape"],
    region="conus",
)
job_id = result["job_id"]

# Poll for completion
while True:
    job = get(job_id)
    if job.state == "done":
        dataset = job.result
        print(f"Generated {dataset['success_count']}/{dataset['item_count']} outputs")
        break
    time.sleep(5)
```

--------------------------------

### Start WxStore Service and Set URL

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

Starts the WxStore service and sets the necessary environment variable for the agent to connect to it. Ensure the WxStore service is running and accessible.

```bash
wxstore --http-addr 127.0.0.1:8897 --root /data/wxstore
export HERMES_WXSTORE_URL="http://127.0.0.1:8897"
```

--------------------------------

### Full WxStore Grid Plotting Workflow Example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/wxstore-integration.md

Demonstrates a complete workflow involving exporting grids, importing them into WxStore, and then plotting the cached grids into static PNGs. This example requires the `discover` function and utilizes `wxstore_grid_export`, `wxstore_grid_import`, and `wxstore_grid_plot`.

```python
from hermes_weather.tools.wxstore import (
    wxstore_grid_export, wxstore_grid_import, wxstore_grid_plot
)
from hermes_weather.tools.jobs import get

env = discover()

# Step 1: Export grids to manifests
export_result = wxstore_grid_export(env,
    products=["cape_mlcape", "stp_fixed", "wind_10m"],
    forecast_hours="0-4",
    region="conus",
)
job_id = export_result["job_id"]

# Wait for export to complete
while True:
    job = get(job_id)
    if job.state == "done":
        manifests = job.result["manifest_paths"]
        break
    elif job.state == "failed":
        print(f"Export failed: {job.error}")
        exit(1)

# Step 2: Import manifests into WxStore
import_result = wxstore_grid_import(env,
    manifests=manifests,
    publish_latest=True,
)
spatial_root = import_result["spatial_root"]

# Step 3: Plot from cache
plots = wxstore_grid_plot(env,
    products=["cape_mlcape", "stp_fixed"],
    forecast_hours="0-4",
    spatial_root=spatial_root,
)
print(f"Generated {plots['png_count']} PNGs in {plots['elapsed_s']}s")
for png in plots["pngs"]:
    print(f"  {png}")
```

--------------------------------

### Install Rustwx and Hermes Weather Agent

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/README.md

Install the necessary libraries using pip. This command installs the latest versions.

```bash
pip install -U rustwx hermes-weather-agent
```

--------------------------------

### Render Recipe with Direct Recipes (Python)

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

Illustrates the correct way to call the `render_recipe` function. The incorrect example omits necessary product information, while the correct example specifies a `direct_recipes` product.

```python
# Wrong
result = render_recipe(env, region="conus")

# Right
result = render_recipe(env, direct_recipes=["tmp_2m"], region="conus")
```

--------------------------------

### Install Hermes Weather Agent and RustWx

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/README.md

Install the hermes-weather-agent and rustwx using pip. Then, run the doctor command to verify the installation and start the weather UI.

```bash
pip install -U rustwx hermes-weather-agent
weather-mcp --doctor
weather-ui
```

--------------------------------

### Generic MCP Client Environment Setup

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Environment variables and command to run a generic MCP client for weather data.

```bash
export HERMES_CACHE_DIR=/data/weather-cache
export HERMES_OUT_DIR=/data/weather-outputs
export HERMES_RUSTWX_BIN_DIR=/path/to/rustwx/target/release
export HERMES_WXSTORE_URL=http://127.0.0.1:8897

weather-mcp
```

--------------------------------

### Claude Desktop Interaction Example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/mcp-server-and-cli.md

An example of a user interacting with Claude, which then calls the weather MCP server to retrieve weather data.

```text
User: Show me HRRR CAPE and wind for Texas
Claude: I'll render MLCAPE and 10m wind over Texas for you...
(Calls wx_render_recipe)
```

--------------------------------

### Python Example: Running ECAPE Grid Research and Polling Job Status

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/severe-weather-tools.md

Demonstrates how to initiate a background ECAPE grid research job and poll for its completion status using the `hermes-weather-agent` library. Requires `discover` and `get` functions.

```python
from hermes_weather.tools.ecape import grid
from hermes_weather.tools.jobs import get

env = discover()

# Start background job over southern plains
result = grid(env, location="Norman, OK", radius_km=500, forecast_hour=1)
if result["ok"]:
    job_id = result["job_id"]
    
    # Poll for completion
    import time
    while True:
        job = get(job_id)
        if job.state == "done":
            print(f"Completed in {job.result['elapsed_s']}s")
            print(f"Output: {job.result['output_png']}")
            break
        elif job.state == "failed":
            print(f"Error: {job.error}")
            break
        print(f"Status: {job.state}")
        time.sleep(2)
```

--------------------------------

### ECAPE Profile Probe Example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/severe-weather-tools.md

Demonstrates how to use the `profile` function to get ECAPE diagnostics for a specific location. Requires the `hrrr_ecape_profile_probe` binary to be built and accessible via `HERMES_RUSTWX_BIN_DIR`. The output includes various parcel types and their associated CAPE and ECAPE values.

```python
from hermes_weather.rustwx import discover
from hermes_weather.tools.ecape import profile

env = discover()

# Probe at Norman, OK
result = profile(env, location="Norman, OK", forecast_hour=1)
if result["ok"]:
    for parcel in result["diagnostics"]["parcels"]:
        ptype = parcel["parcel_type"]
        cape = parcel["undiluted_cape"]
        ecape = parcel["ecape"]
        ratio = parcel["ratio_ecape_to_undiluted_cape"]
        print(f"{ptype:4s}  CAPE={cape:7.0f}  ECAPE={ecape:7.0f}  ratio={ratio:.3f}")
else:
    print(f"Error: {result['error']}")
```

--------------------------------

### Bbox Example Usage

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/types.md

Demonstrates how to create a Bbox instance and access its center coordinates. This is useful for setting up geographic query parameters.

```python
bbox = Bbox(west=-100.0, east=-95.0, south=35.0, north=40.0)
lat, lon = bbox.center  # (37.5, -97.5)
```

--------------------------------

### Example Response for Missing Rustwx Module

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

This is an example of a JSON response indicating that the rustwx Python module is not installed or failed to import. The 'error' field contains a message suggesting the fix.

```json
{
    "ok": False,
    "error": "rustwx Python module not installed. Run: pip install 'rustwx>=0.5.10'",
}
```

--------------------------------

### Example Domain Dictionary

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/types.md

An example of a domain dictionary, illustrating the expected values for each field.

```python
{
    "slug": "conus",
    "label": "CONUS",
    "kind": "region",
    "bounds": [-125.0, -66.0, 24.0, 50.0],
    "center": [37.5, -95.5],
    "area_km2": 9000000.0,
}
```

--------------------------------

### Hermes Agent CLI Examples

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/mcp-server-and-cli.md

Examples of using the Hermes Agent CLI to interact with the weather MCP server. These demonstrate how to request weather data and trigger background jobs.

```bash
> Render latest HRRR 2 m temperature over CONUS
(Uses wx_render_recipe via MCP)

> What's the MLECAPE at Norman, OK?
(Uses wx_ecape_profile via MCP)

> Build a 3-day ECAPE dataset for the southern plains
(Uses wx_build_dataset via MCP, polls wx_job_status)
```

--------------------------------

### Example Usage of radar() Function

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/observations-and-satellites.md

Demonstrates how to call the radar() function to fetch all products from a specific site or a custom list of products. Ensure the 'env' object is properly initialized.

```python
from hermes_weather.tools.radar import radar

# All products from KTLX (Oklahoma)
result = radar(env, site="KTLX", products="all")
if result["ok"]:
    print(f"Rendered {len(result['pngs'])} products")
    for png in result["pngs"]:
        print(f"  {png}")

# Specific products
result = radar(env, site="KDFW", 
    products=["base_reflectivity", "velocity", "echo_tops"])
```

--------------------------------

### run

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/rustwx-integration.md

Executes a Rust binary as a subprocess. It handles environment setup, arguments, timeouts, and returns a `RunResult` object containing details about the execution and its outputs.

```APIDOC
## run

### Description
Subprocess an optional Rust binary.

### Method
N/A (Function Call)

### Signature
`run(env: RustwxEnv, binary: str, args: list[str], *, out_dir: Path | None = None, timeout: int = 600, cwd: Path | None = None) -> RunResult`

### Parameters
#### Positional Parameters
- **env** (`RustwxEnv`) - Required - Environment from `discover()`
- **binary** (`str`) - Required - Binary name (e.g. "sounding_plot")
- **args** (`list[str]`) - Required - Command-line arguments

#### Keyword Parameters
- **out_dir** (`Path | None`) - Optional - Output directory (appended to args as `--out-dir`)
- **timeout** (`int`) - Optional - Subprocess timeout in seconds (default: 600)
- **cwd** (`Path | None`) - Optional - Working directory

### Returns
`RunResult` with returncode, stdout, stderr, and discovered PNG/manifest paths.

### Raises
- `RustwxBinaryMissing` if binary not found
- `subprocess.TimeoutExpired` on timeout

### Example
```python
out = env.out_root / "soundings"
result = run(env, "sounding_plot",
    ["--model", "hrrr", "--date", "20240101", "--cycle", "0",
     "--forecast-hour", "1", "--lat", "35.2", "--lon", "-97.4"],
    out_dir=out,
    timeout=60)
if result.ok:
    print(f"Generated {len(result.pngs)} PNGs in {result.seconds}s")
```
```

--------------------------------

### Materialize and Plot Grids Example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/wxstore-integration.md

Demonstrates using wxstore_grid_materialize to cache HRRR grids in WxStore and then using wxstore_grid_plot to generate plots from the cached data. This showcases the efficiency of caching for subsequent plotting operations.

```python
from hermes_weather.tools.wxstore import wxstore_grid_materialize, wxstore_grid_plot

env = discover()

# Export HRRR grids and cache them in WxStore
mat = wxstore_grid_materialize(env,
    products=["tmp_2m", "dewpoint_2m", "wind_10m", "cape_mlcape"],
    forecast_hours="0-6",
    region="conus",
)
print(f"Cached {mat['grids_cached']} grids in {mat['elapsed_s']}s")

# Now plot from the cache (much faster)
plots = wxstore_grid_plot(env,
    products=["cape_mlcape", "tmp_2m"],
    forecast_hours="0-6",
)
print(f"Generated {plots['png_count']} PNGs")
```

--------------------------------

### Run Full Diagnostics

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/mcp-server-and-cli.md

Performs a comprehensive diagnostic of the rustwx module, checking capabilities, optional binaries, and providing setup advice.

```bash
$ weather-mcp --doctor
rustwx_module_available: true
rustwx_version: 0.5.10
cache_dir: /home/user/.cache/hermes/weather
out_root: /home/user/.cache/hermes/outputs
plot_style: operational_fast
agent_api: rustwx-agent-v1
models: [hrrr, hrrr-ak, gfs, rap, nam, ...]
domain_count: 77
optional_binaries:
  sounding_plot: /home/user/rustwx/target/release/sounding_plot
  hrrr_pressure_volume_store: /home/user/rustwx/target/release/hrrr_pressure_volume_store
  ...
specialty_tools:
  sounding: true
  cross_section: true
  volume_cross_section: true
  radar: true
  ecape_profile_probe: true
  ecape_grid_research: true
  wxstore_grid_export: true
  wxstore_import: true
  wxstore_grid_plot: true
advice: Map rendering (direct/derived/heavy ECAPE/windowed) is fully available...
```

--------------------------------

### Python meteogram() usage example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/observations-and-satellites.md

Demonstrates how to use the meteogram() function to fetch a short time series for a specified location and how to process the results. It also shows an example of using a warmed store for faster sampling of multiple locations.

```python
from hermes_weather.tools.meteogram import meteogram

# Short meteogram
result = meteogram(env, location="Los Angeles, CA", 
    forecast_hour_start=0, forecast_hour_end=6)
if result["ok"]:
    for ts in result["timeseries"]:
        hour = ts["forecast_hour"]
        tmp = ts["variables"]["tmp_2m"]
        print(f"f{hour:02d}: {tmp:.1f} K")

# Via warmed store (faster for repeated samples)
# First warm the store
warm_result = meteogram_warm_store(env, model="hrrr", 
    forecast_hours=[0, 1, 2, 3])
store_id = warm_result["store_id"]

# Then sample multiple locations quickly
for location in ["Oklahoma City", "Tulsa", "Dallas"]:
    result = meteogram(env, location=location, store_id=store_id)
```

--------------------------------

### Sounding API Usage Examples

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/observations-and-satellites.md

Demonstrates how to use the `sounding` function to generate a Skew-T diagram for a specific location and how to create a box-mean sounding by averaging data over a defined radius.

```python
from hermes_weather.tools.sounding import sounding

# Single sounding at Amarillo, TX
result = sounding(env, location="Amarillo, TX", forecast_hour=6)
if result["ok"]:
    print(f"Sounding PNG: {result['png']}")
else:
    print(f"Error: {result['error']}")

# Box-mean sounding (average over 50 km box)
result = sounding(env, lat=35.2, lon=-97.4,
    sample_method="box-mean", box_radius_km=50,
    forecast_hour=1)
```

--------------------------------

### Python meteogram_warm_store() usage example

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/observations-and-satellites.md

Illustrates warming a store for a range of forecast hours and then using the obtained store_id to sample multiple locations efficiently using the meteogram() function.

```python
# Warm store once for f0-f12
warm = meteogram_warm_store(env, forecast_hours=list(range(13)))
store_id = warm["store_id"]

# Sample 100 locations from the warmed store
locations = [
    ("New York, NY", 40.7128, -74.0060),
    ("Chicago, IL", 41.8781, -87.6298),
    # ... 98 more
]

for name, lat, lon in locations:
    met = meteogram(env, lat=lat, lon=lon, store_id=store_id)
    if met["ok"]:
        # Use timeseries...

```

--------------------------------

### Resolve Latest Run for Forecast Hours (Python)

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

Demonstrates how to correctly request forecast hours that are available for a given model. The first example shows an overly ambitious request that fails, while the second shows a valid request within the model's limits.

```python
# Too ambitious
date, cycle = resolve_latest_run_for_hours("hrrr",
    forecast_hours=[36])  # HRRR only extends to f18

# Better: request hours that exist
date, cycle = resolve_latest_run_for_hours("hrrr",
    forecast_hours=[0, 6, 12, 18])  # Within f018 limit
```

--------------------------------

### Configure Hermes Agent (YAML)

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/README.md

Example configuration for the Hermes Agent using YAML format. Set environment variables for weather MCP servers, including paths to binaries and cache directories.

```yaml
# Hermes Agent — ~/.hermes/config.yaml
mcp_servers:
  weather:
    command: weather-mcp
    env:
      HERMES_RUSTWX_BIN_DIR: /path/to/rustwx/target/release
      HERMES_WXSTORE_BIN_DIR: /path/to/wxstore/target/release
      HERMES_WXSTORE_URL: http://127.0.0.1:8897
      HERMES_RUSTWX_PLOT_STYLE: operational_fast
      HERMES_CACHE_DIR: /path/to/weather-cache         # default: ./cache/rustwx
      HERMES_OUT_DIR:   /path/to/weather-outputs       # default: ./outputs
```

--------------------------------

### Build Command for native_obs_preview

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `native_obs_preview` binary, for raw GOES/MRMS/Level-II quicklook.

```bash
cargo build --release -p rustwx-cli --bin native_obs_preview
```

--------------------------------

### Build Command for wxstore_wxa_showcase

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `wxstore_wxa_showcase` binary, a static plot renderer from WXA cache.

```bash
cargo build --release -p rustwx-cli --bin wxstore_wxa_showcase
```

--------------------------------

### Diagnose Rustwx Module State

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/catalog-and-discovery.md

Call the doctor() function to get a full diagnostic of the rustwx module's state, capabilities, and any setup advice. This function returns a dictionary containing detailed information about the module's availability, version, configuration, and available tools.

```python
def doctor(env: RustwxEnv) -> dict
```

```python
health = doctor(env)
print(f"rustwx: {health['rustwx_module_available']}")
print(f"version: {health['rustwx_version']}")
print(f"models: {health['models']}")
print(f"specialty tools: {sum(health['specialty_tools'].values())}/9 available")
print(f"advice: {health['advice']}")
```

--------------------------------

### Build WxStore Binary and Set Directory

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

Builds the WxStore binary from source and sets the environment variable for the agent to locate it. This is necessary if the wxstore binary is missing.

```bash
cd ~/wxstore
cargo build --release
export HERMES_WXSTORE_BIN_DIR="$(pwd)/target/release"
```

--------------------------------

### Build and Configure WxStore CLI

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/README.md

Clone the wxstore repository and build the WxStore CLI. Set the necessary environment variables to point Hermes at the WxStore binary directory and the WxStore service URL.

```bash
git clone https://github.com/FahrenheitResearch/wxstore
cd wxstore
cargo build --release
export HERMES_WXSTORE_BIN_DIR="$(pwd)/target/release"
export HERMES_WXSTORE_URL="http://127.0.0.1:8897"
```

--------------------------------

### Build and Configure WxStore

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Builds the wxstore in release mode and sets environment variables for its binary directory and URL. It is recommended to run the wxstore service in the background or using a process manager like systemd.

```bash
cd ~/wxstore
cargo build --release
export HERMES_WXSTORE_BIN_DIR="$(pwd)/target/release"
export HERMES_WXSTORE_URL="http://127.0.0.1:8897"
# Run wxstore service in background or systemd
```

--------------------------------

### Verify Hermes Weather Agent Installation

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Runs the weather-mcp --doctor command to verify the installation and check the status of core components and configurations.

```bash
weather-mcp --doctor
```

--------------------------------

### wxstore_sample()

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/wxstore-integration.md

Sample a single WxStore grid variable at a point.

```APIDOC
## wxstore_sample()

### Description
Sample a single WxStore grid variable at a point.

### Parameters
#### Path Parameters
- `env` (RustwxEnv) - Required - Environment from `discover()`
- `variable` (str) - Required - The grid variable to sample
- `location` (str | tuple | dict | None) - Optional - City name or (lat, lon) tuple
- `lat` (float | None) - Optional - Latitude (if not in location)
- `lon` (float | None) - Optional - Longitude (if not in location)
- `model` (str) - Optional - Model slug. Default: "hrrr"
- `run_str` (str) - Optional - Run string. Default: "latest"
- `forecast_hour` (int) - Optional - Forecast hour to sample. Default: 0

### Returns
- `ok` (bool)
- `variable` (str)
- `value` (float)
- `units` (str)
- `lat` (float)
- `lon` (float)
- `forecast_hour` (int)
```

--------------------------------

### Build Command for wxstore

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `wxstore` binary, the WxStore CLI import/service. This command should be run within the wxstore repository.

```bash
cargo build --release
```

--------------------------------

### Install Core Rustwx and Hermes Weather Agent

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Installs the core rustwx and hermes-weather-agent Python packages using pip. Ensure you are using a version of rustwx greater than or equal to 0.5.10.

```bash
pip install -U "rustwx>=0.5.10" "hermes-weather-agent"
```

--------------------------------

### Build Command for native_dataset_plan

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `native_dataset_plan` binary, a training-data plan writer.

```bash
cargo build --release -p rustwx-cli --bin native_dataset_plan
```

--------------------------------

### Build Command for rustwx_grid_export

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `rustwx_grid_export` binary, a dense grid exporter for WxStore.

```bash
cargo build --release -p rustwx-cli --bin rustwx_grid_export
```

--------------------------------

### Generate Full Showcase Gallery

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/README.md

Run this script to exercise every tool against a single canonical run and capture per-call timing. It builds the HTML gallery in outputs/showcase/index.html.

```bash
python examples/showcase_full.py
```

--------------------------------

### Build Command for hrrr_pressure_volume_store

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `hrrr_pressure_volume_store` binary, used for HRRR pressure VolumeStore.

```bash
cargo build --release -p rustwx-cli --bin hrrr_pressure_volume_store
```

--------------------------------

### Run Hermes Weather Agent MCP Server

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/README.md

Start the Message Control Protocol (MCP) server for the Hermes Weather Agent.

```bash
weather-mcp
```

--------------------------------

### Build Command for goes_native_sequence

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `goes_native_sequence` binary, for GOES crop/sequence/GIF generation.

```bash
cargo build --release -p rustwx-cli --bin goes_native_sequence
```

--------------------------------

### Generate HTML Showcase Gallery

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/README.md

This script specifically builds the outputs/showcase/index.html file for the showcase gallery. It is a faster alternative if only the HTML is needed.

```bash
python examples/showcase_html.py
```

--------------------------------

### Get Rustwx Region Presets

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/catalog-and-discovery.md

Use the `regions()` function to retrieve a list of predefined geographical region presets. This function requires an initialized `RustwxEnv` object.

```python
def regions(env: RustwxEnv) -> dict
```

```python
result = regions(env)
for d in result["domains"]:
    print(f"{d['slug']:25s} {d['label']}")
```

--------------------------------

### Render Weather Recipes

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/render-and-maps.md

Demonstrates how to render single or multiple weather recipes, including derived ones. It shows how to specify regions, run strings, forecast hours, and options for background job execution.

```python
from hermes_weather.rustwx import discover
from hermes_weather.tools.render import render_recipe

env = discover()

# Single direct recipe
result = render_recipe(env, direct_recipes=["tmp_2m"], region="conus")
print(result["pngs"])  # ["/path/to/tmp_2m.png"]

# Multi-recipe with derived
result = render_recipe(
    env,
    direct_recipes=["tmp_2m", "wind_10m"],
    derived_recipes=["cape_sbcape", "stp_fixed"],
    region="southern-plains",
    run_str="latest",
    forecast_hour=3,
)

# ECAPE heavy research (background job)
result = render_recipe(
    env,
    derived_recipes=["ecape_mlecape"],
    region="conus",
    forecast_hour=6,
    chunk_large_requests=True,
)
print(result["job_id"])  # If running in background
```

--------------------------------

### Get Single Job Status

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

Retrieves the current status of a specific background job using its unique job ID. Useful for monitoring job progress and outcomes.

```python
from hermes_weather.tools.jobs import job_status

# Submitted job from ecape.grid()
job_id = "abc123def456"

status = job_status(env, job_id=job_id)
print(f"Job state: {status['state']}")
print(f"Elapsed: {status['elapsed_s']:.1f}s")
print(f"Error: {status['error']}")
if status["result"]:
    print(f"Result: {status['result']}")
```

--------------------------------

### Build Command for hrrr_ecape_grid_research

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `hrrr_ecape_grid_research` binary, for full-grid ECAPE swath research.

```bash
cargo build --release -p rustwx-cli --bin hrrr_ecape_grid_research
```

--------------------------------

### WxStore Sample Return Structure

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/wxstore-integration.md

Shows the expected return structure for the wxstore_sample function. It includes the sampled variable's value, units, location, and forecast hour.

```json
{
    "ok": bool,
    "variable": str,
    "value": float,
    "units": str,
    "lat": float,
    "lon": float,
    "forecast_hour": int,
}
```

--------------------------------

### Get Point Forecast Time-Series

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/README.md

Fetches a time-series forecast for a specific location and time range. The meteogram tool is used, and the output includes forecast hour and temperature at 2m.

```python
from hermes_weather.tools.meteogram import meteogram

result = meteogram(env, location="Oklahoma City", forecast_hour_end=12)
if result["ok"]:
    for ts in result["timeseries"]:
        print(f"f{ts['forecast_hour']:02d}: {ts['variables']['tmp_2m']}K")
```

--------------------------------

### wxstore_forecast()

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/wxstore-integration.md

Sample WxStore spatial lanes as Open-Meteo-style point forecasts.

```APIDOC
## wxstore_forecast()

### Description
Sample WxStore spatial lanes as Open-Meteo-style point forecasts.

### Parameters
#### Path Parameters
- `env` (RustwxEnv) - Required - Environment from `discover()`
- `location` (str | tuple | dict | None) - Optional - City name or (lat, lon) tuple
- `lat` (float | None) - Optional - Latitude (if not in location)
- `lon` (float | None) - Optional - Longitude (if not in location)
- `model` (str) - Optional - Model slug. Default: "hrrr"
- `run_str` (str) - Optional - Run string. Default: "latest"
- `forecast_hours` (list[int] | None) - Optional - Forecast hours to sample

### Returns
- `ok` (bool)
- `error` (str | None)
- `location` (dict) - {"lat": float, "lon": float}
- `model` (str)
- `timeseries` (list) - [
    {
        "forecast_hour": int,
        "variables": {...}
    }
]
```

--------------------------------

### Build Command for volume_store_cross_section_render

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `volume_store_cross_section_render` binary, a VolumeStore cross-section renderer.

```bash
cargo build --release -p rustwx-cli --bin volume_store_cross_section_render
```

--------------------------------

### Get Data Pack Tiers

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

Retrieves information about available local storage tiers for HRRR data packs. Useful for understanding storage options without additional downloads.

```python
from hermes_weather.tools.data_packs import data_packs

packs = data_packs(env)
for tier in packs["tiers"]:
    print(f"{tier['name']:10s} {tier['description']}")
    print(f"           CONUS f000-f{tier['includes']['conus']:03d}")
```

--------------------------------

### doctor()

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/catalog-and-discovery.md

Provides a full diagnostic of the rustwx module state, its capabilities, optional binaries, and offers setup advice. It returns a dictionary containing detailed information about the rustwx environment and its availability.

```APIDOC
## doctor()

### Description
Full diagnostic of rustwx module state, capabilities, optional binaries, and advice.

### Returns
- **rustwx_module_available** (bool) - Indicates if the rustwx module is available.
- **rustwx_version** (str | None) - The version of the rustwx module.
- **cache_dir** (str) - The path to the cache directory.
- **out_root** (str) - The output root directory.
- **plot_style** (str) - The plot style configuration.
- **agent_api** (str | None) - The agent API identifier, e.g., "rustwx-agent-v1".
- **models** (list[str]) - A list of available models.
- **domain_count** (int | None) - The number of domains.
- **optional_binaries** (dict) - A dictionary mapping discovered binary names to their paths.
- **specialty_tools** (dict) - A dictionary indicating the availability of various specialty tools (sounding, cross_section, etc.).
- **advice** (str) - Human-readable setup guidance.
- **error** (str | None) - An error message if the module is unavailable.
- **fix** (str | None) - An installation command if the module is needed.

### Example
```python
health = doctor(env)
print(f"rustwx: {health['rustwx_module_available']}")
print(f"version: {health['rustwx_version']}")
print(f"models: {health['models']}")
print(f"specialty tools: {sum(health['specialty_tools'].values())}/9 available")
print(f"advice: {health['advice']}")
```
```

--------------------------------

### Get Cache Status

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

Retrieves a summary of disk usage for the cache directory, including total size and top consuming files. Use this to understand cache size and identify large files.

```python
from hermes_weather.tools.cache import cache_status

status = cache_status(env)
print(f"Total cache: {status['total_gb']:.1f} GB")
print(f"Top consumers:")
for item in status["top_consumers"][:5]:
    print(f"  {item['path']:40s} {item['gb']:6.1f} GB")
```

--------------------------------

### Export, Import, and Plot Data with WxStore

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/README.md

Demonstrates exporting grid data to WxStore, importing it back, and then plotting from the cache. This workflow involves job monitoring for the export step and utilizes wxstore_grid_export, wxstore_grid_import, and wxstore_grid_plot tools.

```python
from hermes_weather.tools.wxstore import (
    wxstore_grid_export, wxstore_grid_import, wxstore_grid_plot
)
from hermes_weather.tools.jobs import get
import time

# Export
export_result = wxstore_grid_export(env,
    products=["cape_mlcape", "stp_fixed"],
    forecast_hours="0-4",
    region="conus",
)
job_id = export_result["job_id"]

# Wait for export
job = get(job_id)
while job.state != "done": time.sleep(2); job = get(job_id)
manifests = job.result["manifest_paths"]

# Import
import_result = wxstore_grid_import(env, manifests=manifests)

# Plot from cache
plots = wxstore_grid_plot(env,
    products=["cape_mlcape"],
    forecast_hours="0-4",
)
print(f"Generated {plots['png_count']} PNGs in {plots['elapsed_s']}s")
```

--------------------------------

### Get Latest Model Run Metadata

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

The `latest` function retrieves metadata for the most recent model run. This is useful for determining the latest available data without downloading it. It requires an initialized `RustwxEnv` object.

```python
def latest(env: RustwxEnv, *, model: str = "hrrr") -> dict
```

--------------------------------

### models()

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/catalog-and-discovery.md

Lists available models along with their supported sources, products, and recipe counts. This function requires an environment object obtained from the `discover()` function.

```APIDOC
## models()

### Description
Lists available models with supported sources, products, and recipe counts.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **env** (`RustwxEnv`) - Required - Environment from `discover()`

### Returns
- **agent_api** (`str`) - The agent API identifier.
- **rustwx_version** (`str` | `None`) - The rustwx version, if available.
- **count** (`int`) - The total number of models available.
- **models** (`list[dict]`) - A list of model objects, each containing details about a specific model.
  - **id** (`str`) - The unique identifier for the model (e.g., "hrrr", "gfs").
  - **default_product** (`str`) - The default product for the model (e.g., "sfc").
  - **default_render_product** (`str`) - The default render product for the model.
  - **products** (`list[str]`) - A list of available products for the model.
  - **sources** (`list[str]`) - A list of data sources for the model (e.g., ["aws", "nomads", "gcs"]).
  - **max_forecast_hour** (`int`) - The maximum forecast hour supported by the model.
  - **direct_recipe_count** (`int`) - The number of direct recipes available for the model.
  - **light_derived_recipe_count** (`int`) - The number of light derived recipes available.
  - **heavy_derived_recipe_count** (`int`) - The number of heavy derived recipes available.
  - **windowed_recipe_count** (`int`) - The number of windowed recipes available.

### Example
```python
from hermes_weather.rustwx import discover
from hermes_weather.tools.catalog import models

env = discover()
catalog = models(env)

for m in catalog["models"]:
    print(f"{m['id']:20s} f{m['max_forecast_hour']:03d} "
          f"({m['light_derived_recipe_count']} derived recipes)")
```
```

--------------------------------

### Get Available Forecast Hours

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/rustwx-integration.md

Retrieves a sorted list of available forecast hours for a specified model, date, and cycle. Defaults to 'hrrr' model, 'sfc' product, and 'nomads' source. Requires date_yyyymmdd and cycle_utc.

```python
hours = available_forecast_hours("hrrr", "20240101", 0, product="sfc")
# [0, 1, 2, ..., 18] for HRRR CONUS
```

--------------------------------

### Build and Monitor Multi-Day Dataset Job

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/README.md

Constructs a multi-day dataset with specified products, regions, and forecast hours, then monitors the job's completion. It uses build_dataset and get tools, with a polling mechanism for job status.

```python
from hermes_weather.tools.dataset import build_dataset
from hermes_weather.tools.jobs import get
import time

result = build_dataset(env,
    task_type="render",
    dates=["20240115", "20240116"],
    cycles=[12],
    forecast_hours=[0, 6, 12],
    products=["ecape_mlecape"],
    region="conus",
)
job_id = result["job_id"]

# Poll for completion
job = get(job_id)
while job.state in ["pending", "running"]:
    time.sleep(2)
    job = get(job_id)
print(job.result)
```

--------------------------------

### Build Command for native_dataset_runner

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `native_dataset_runner` binary, a training-data materializer.

```bash
cargo build --release -p rustwx-cli --bin native_dataset_runner
```

--------------------------------

### Get Subprocess Environment Variables

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/rustwx-integration.md

The `subprocess_env` method returns a copy of the current environment variables, with the `RUSTWX_PLOT_STYLE` variable set according to the `RustwxEnv` configuration. This is essential for ensuring subprocesses launched by the agent use the correct plot style.

```python
env.subprocess_env()
```

--------------------------------

### Handling RustwxBinaryMissing Error

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/errors.md

Catch the RustwxBinaryMissing exception when a required Rust binary is not found. The exception object provides the binary name for debugging. Instructions are printed to guide the user on how to build the binary and set the necessary environment variable.

```python
try:
    exe = env.require_binary("sounding_plot")
except RustwxBinaryMissing as exc:
    print(f"Missing: {exc.binary_name}")
    print(f"Build with: cargo build --release --bin {exc.binary_name}")
    print(f"Then set HERMES_RUSTWX_BIN_DIR")
```

--------------------------------

### Build Command for hrrr_ecape_profile_probe

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/configuration.md

Use this command to build the `hrrr_ecape_profile_probe` binary, for single-point ECAPE diagnostics.

```bash
cargo build --release -p rustwx-cli --bin hrrr_ecape_profile_probe
```

--------------------------------

### Geographic Domain Resolution Examples

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/geographic-utilities.md

Demonstrates various ways to use the `resolve_to_domain` function, including specifying an explicit domain, using a region preset, resolving a city name, creating bounds from a numeric point, and handling cases where the caller should default.

```python
from hermes_weather.geo import resolve_to_domain

env = discover()

# Explicit domain
slug, bounds = resolve_to_domain(env, domain="conus")
# ("conus", None)

# Region preset
slug, bounds = resolve_to_domain(env, region="southern-plains")
# ("southern-plains", None)

# City name (looks up domain)
slug, bounds = resolve_to_domain(env, location="Norman, OK")
# ("norman-ok-metro", None) or similar

# Numeric point (creates custom bounds)
slug, bounds = resolve_to_domain(env, location=(35.2, -97.4))
# (None, [west, east, south, north]) — 400 km box around point

# No input (caller should default)
slug, bounds = resolve_to_domain(env)
# (None, None)
```

--------------------------------

### fetch()

Source: https://github.com/fahrenheitresearch/hermes-weather-agent/blob/master/_autodocs/api-reference/data-and-jobs.md

Downloads GRIB2 files with intelligent selective downloading via .idx metadata. When `variables` is provided and `full=False`, only byte-ranges for those variables are downloaded, dramatically reducing network I/O. Caches all downloads by default.

```APIDOC
## fetch() 

### Description
Selective GRIB2 fetch via idx-first byte-range downloads (HRRR/GFS).

### Parameters

#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Method
```python
def fetch(
    env: RustwxEnv,
    *,
    model: str = "hrrr",
    run: str = "latest",
    forecast_hour: int = 0,
    product: str = "default",
    variables: list[str] | None = None,
    source: str | None = None,
    output: str | None = None,
    cache_dir: str | None = None,
    full: bool = False,
)
```

### Returns
```json
{
    "ok": bool,
    "error": str | None,
    "model": str,
    "date": str,  # YYYYMMDD
    "cycle": int,
    "forecast_hour": int,
    "product": str,
    "source": str | None,
    "url": str | None,
    "output": str,  # Path to downloaded file
    "bytes": int,
    "cache_hit": bool,
    "cache_path": str,
    "selective": bool,  # Whether idx-selective was used
}
```

### Example
```python
from hermes_weather.tools.fetch import fetch

env = discover()

# Selective fetch: just T and wind for 2 m
result = fetch(env,
    model="hrrr",
    forecast_hour=6,
    variables=["TMP:2 m", "UGRD:10 m", "VGRD:10 m"],
)
print(f"Downloaded {result['bytes']} bytes (selective)")

# Full GRIB2 for batch processing
result = fetch(env, model="gfs", forecast_hour=12, full=True)
print(f"Downloaded {result['bytes']} bytes (full)")
```
```