Nimbus Weather Model API

Agent-first, machine-readable weather model data access via GRIB2 byte-range fetching.

High-performance API for accessing numerical weather prediction models (HRRR, RAP, GFS, NAM, GEFS) with:

• ⚡ Efficient byte-range GRIB2 access via IDX files
• 🤖 Agent-optimized with comprehensive grounding/provenance
• � Intelligent weather scanning - Automatically finds interesting weather patterns across CONUS
• 📊 Multi-model synthesis (near/short/long term forecasts)
• 🔬 Meteorological analysis (soundings, severe weather, hodographs, ensemble stats)
• 🌍 Synoptic pattern detection (ridges, troughs, jets, fronts)
• 📡 Real-time ingestion monitoring with NCEP-observed latencies

📚 View Complete Documentation | 👤 Human Guide | 🤖 AI Agent Guide

Design Philosophy

This API is designed specifically for AI agents (particularly OpenClaw) to efficiently process and communicate weather model data.

Key Features for AI Agents

• Interest-driven scanning - /scan/synoptic-patterns automatically finds noteworthy weather across CONUS (severe wx, heavy precip, winter wx, fire wx, tropical, etc.)
• Efficient JSON - All responses optimized for programmatic parsing
• Progressive detail - Scan broadly → prioritize by interest_level → drill down with specialized endpoints
• Grounding metadata - Every response includes model/cycle/valid_time for transparency

Recommended AI Agent Workflow

1. Scan - GET /scan/synoptic-patterns to find interesting weather nationwide
2. Prioritize - Focus on areas with interest_level: "high"
3. Analyze - Use specialized endpoints for details:
   • /analysis/severe-wx - Severe weather parameters (STP, SCP, EHI, shear, storm motion)
   • /analysis/hodograph - Wind profile for storm motion analysis
   • /analysis/sounding - Full atmospheric profile
   • /ensemble/stats - Forecast uncertainty quantification
4. Communicate - Present findings with appropriate detail level

Quick Start

Installation

# Create virtual environment
python -m venv .venv
.venv\\Scripts\\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Install package in editable mode
pip install -e .

⚠️ Optional: Install ecCodes for Real GRIB2 Data

The API works fully without ecCodes using high-quality synthetic data. To use real NOMADS GRIB2 data:

Windows (Choose One):

Option 1: Install Miniconda (Recommended)

# 1. Download Miniconda from https://docs.conda.io/en/latest/miniconda.html
# 2. Install it, then run:
conda install -c conda-forge eccodes
python -c "import cfgrib; print('✅ ecCodes working')"

Option 2: Use WSL (Windows Subsystem for Linux)

# If you have WSL installed:
wsl
sudo apt-get update
sudo apt-get install libeccodes-dev
pip install --force-reinstall cfgrib

Option 3: Use Synthetic Data (No Installation)

• API is fully functional without ecCodes
• Returns high-quality synthetic weather data
• Perfect for development, testing, and many production use cases
• Check grounding.data_source field - shows "synthetic_fallback"

Linux (Ubuntu/Debian):

sudo apt-get install libeccodes-dev
pip install --force-reinstall cfgrib

Linux (RHEL/CentOS):

sudo yum install eccodes eccodes-devel
pip install --force-reinstall cfgrib

macOS:

brew install eccodes
pip install --force-reinstall cfgrib

Run Server

# Development server with auto-reload
uvicorn app.main:app --reload --port 8000

# Production server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Run Tests

pytest -v                    # Verbose output
pytest -q                    # Quiet mode
pytest --cov=app            # With coverage

Documentation

Choose the guide that fits your needs:

• 📖 Documentation Index - Start here to navigate all documentation

• 👤 Human User Guide - For developers using the API directly

  • Getting started tutorial
  • Endpoint reference with examples
  • Meteorological concepts explained
  • Common workflows (storm chasing, winter weather, etc.)
  • Troubleshooting guide

• 🤖 AI Agent Usage Guide - For building AI weather agents

  • Optimized scan → prioritize → analyze → communicate workflow
  • Complete code examples with decision trees
  • Communication templates
  • Error handling and performance optimization

• 🔬 Meteorological Enhancements - Technical deep-dive

  • Severe weather parameters (STP, SCP, EHI) explained
  • Hodograph analysis and storm motion
  • Ensemble statistics interpretation

• 📊 Workflow Diagrams - Visual guides

  • ASCII diagrams of API workflows
  • Data flow architecture
  • Decision trees

API Endpoints

Forecast Endpoints

• GET /v1/forecast/point - Point forecast with auto-model selection

  • Parameters: lat, lon, model, cycle, f_hour, units
  • Auto-selects: RAP (<1h), HRRR (1-18h), GFS (18h+)

• GET /v1/forecast/summary/{lat}/{lon} - Multi-model summary

  • Returns: near (RAP@0h), short (HRRR@6h), long (GFS@48h)

System Endpoints

• GET /v1/system/status - Model ingestion status

  • Real-time data availability based on NCEP observations
  • Latencies: RAP (27min), HRRR (47min), NAM (1.5h), GFS (3.5h), GEFS (4.5h)

• GET /v1/system/health - Service health check

• GET /v1/system/metrics - Prometheus metrics

Analysis Endpoints

• GET /v1/analysis/sounding - Vertical atmospheric profile

  • Returns: Temperature, dewpoint, wind at standard levels (1000-200mb)
  • Includes: CAPE, CIN, LCL, LFC stability indices

• GET /v1/analysis/severe-wx - Comprehensive severe weather diagnostics

  • Parameters: STP (Significant Tornado Parameter), SCP (Supercell Composite), EHI (Energy Helicity Index)
  • Shear: Bulk shear at 0-1km, 0-3km, 0-6km levels
  • Storm motion: Bunkers right/left vectors, mean wind
  • Interpretation: Tornado threat level (low/moderate/high), supercell potential
  • Use case: AI can identify tornado/supercell threats from scan, then get detailed parameters here

• GET /v1/analysis/hodograph - Wind profile for storm motion analysis (SounderPy-like)

  • Returns: u/v wind components at 11 height levels (0-10km AGL)
  • Use case: Plot hodograph, analyze wind shear, determine storm motion
  • Interpretation: Hodograph curvature, low-level turning, shear vectors

• GET /v1/analysis/precip-type - Precipitation type determination

  • Uses: 1000-500mb thickness + wet-bulb temperature
  • Returns: Rain, Snow, Sleet, Freezing Rain, or Mixed

• GET /v1/analysis/compare - Model run comparison

  • Modes: model_diff or cycle_diff
  • Returns: Agreement metrics, max differences, sample points

Ensemble Endpoints

• GET /v1/ensemble/stats - GEFS ensemble statistics (31 members)
  • Returns: Mean, median, std dev, min, max
  • Probabilities: Threshold exceedance (e.g., below freezing)
  • Spread assessment: Low/moderate/high confidence categories
  • Use case: Quantify forecast uncertainty for 3-10 day forecasts

Scan Endpoints

• GET /v1/scan/synoptic-patterns - Comprehensive CONUS weather scan ("Interesting Weather Finder")

  • Purpose: AI agent's starting point - scans entire CONUS for meteorologically interesting patterns
  • Returns 7 categories:
    • synoptic_features - Ridges, troughs, jet streaks with 4-quadrant forcing, fronts
    • heavy_precipitation - Significant rainfall (>0.5 in/hr) or snowfall (>1 in/hr) areas
    • severe_weather - Tornado risk (STP), supercell potential (SCP), damaging winds
    • winter_weather - Heavy snow, ice accumulation, extreme cold
    • fire_weather - Critical fire conditions (high winds + low RH)
    • tropical - Development potential in Atlantic/Caribbean
    • temperature_extremes - Extreme heat or cold events
  • Each area includes:
    • interest_level: "high", "moderate", "low" (for AI prioritization)
    • centroid or bbox: Location for follow-up queries
    • description: Human-readable context
  • AI workflow: Scan → filter by interest_level → drill down with analysis endpoints

• POST /v1/scan/anomalies - Enqueue anomaly detection job

  • Returns: Job ID and status URL

• GET /v1/scan/jobs/{job_id} - Job status polling

  • Status: queued → running → finished

Data & Metadata

• GET /v1/data/grib - NOMADS/AWS GRIB2 URLs

  • Supports: HTTP byte-range via IDX files
  • Models: HRRR, RAP, GFS, NAM

• GET /v1/metadata/variables - Variable catalog

  • Returns: Units, descriptions, GRIB2 parameter names

Documentation

• GET /v1/openapi.yaml - OpenAPI 3.0.3 specification
• GET /v1/agent-manifest - Agent discovery manifest

GRIB2 Data Access

The API provides efficient byte-range access to GRIB2 files:

import httpx

# 1. Get GRIB URLs
response = httpx.get("http://localhost:8000/v1/data/grib", 
    params={"model": "HRRR", "cycle": "12Z", "f_hour": 6})
urls = response.json()

# 2. Fetch IDX file to find variable offset
idx_text = httpx.get(urls["idx_url"]).text

# 3. Parse IDX for specific variable (e.g., temperature)
for line in idx_text.splitlines():
    if "TMP:2 m" in line:
        parts = line.split(":")
        start_byte = int(parts[1])
        # Calculate end_byte from next line...
        break

# 4. Fetch only that variable using Range header
headers = {"Range": f"bytes={start_byte}-{end_byte}"}
grib_data = httpx.get(urls["grib_url"], headers=headers).content

# 5. Parse with cfgrib/xarray (when installed)
# import xarray as xr
# ds = xr.open_dataset(BytesIO(grib_data), engine='cfgrib')

Architecture

Data Flow

Agent/Client Request
  ↓
FastAPI Endpoint (app/main.py)
  ↓
Weather Module (app/weather.py)
  ↓
GRIB2 Fetching (fetch_grib_section)
  ↓
  ├→ IDX File Parsing (parse_idx_for_variable)
  ├→ HTTP Range Request
  └→ GRIB2 Byte Section
  ↓
Response with Grounding Metadata

Key Modules

• app/main.py - FastAPI application with all endpoints
• app/weather.py - GRIB2 data fetching and meteorological analysis
• docs/openapi.yaml - Comprehensive OpenAPI 3.0.3 spec
• agent-manifest.json - Machine-readable endpoint catalog
• tests/test_endpoints.py - Full endpoint integration tests

Agent Integration

For AI agents, the API provides:

1. Discovery: Start with /agent-manifest for endpoint catalog
2. Grounding: All responses include provenance metadata
3. Error Handling: RFC 7807 problem details format
4. Documentation: Machine-readable OpenAPI spec

See docs/agent_integration.md for detailed workflows.

Development Roadmap

Completed ✓

• ✅ All 14+ endpoint implementations with realistic data
• ✅ GRIB2 byte-range fetching infrastructure
• ✅ Multi-model forecast synthesis (RAP/HRRR/GFS tiering)
• ✅ Meteorological analysis endpoints
• ✅ Comprehensive OpenAPI 3.0.3 documentation
• ✅ Real-time ingestion status (NCEP-observed latencies)
• ✅ Full test coverage (7 passing tests)

Planned 🚧

• ⏳ Real GRIB2 parsing with cfgrib/xarray
• ⏳ Authentication and rate limiting
• ⏳ Job queue workers for async processing
• ⏳ Docker containerization
• ⏳ CI/CD workflow
• ⏳ Python SDK generation
• ⏳ Prompt templates for agents

Technology Stack

• FastAPI 0.128.7 - Modern async web framework
• Pydantic 2.12.5 - Data validation
• httpx 0.28.1 - HTTP client for GRIB2 fetching
• pytest 9.0.2 - Testing framework
• cfgrib (planned) - GRIB2 parsing
• xarray (planned) - Scientific data arrays

License

MIT License - See LICENSE file for details

Support

• Documentation: docs/ directory
• Issues: GitHub Issues
• API Spec: http://localhost:8000/v1/openapi.yaml