AI-Hydro

An open platform for AI-driven research automation in hydrology and geospatial sciences.

GitHub · PyPI · Quick Start · Tools Reference · Issues

The Vision

Hydrological research today involves a fragmented cycle: downloading data from scattered federal APIs, wrangling formats, writing processing scripts, calibrating models, and documenting provenance — often spending more time on plumbing than on science. As foundation models become increasingly capable at reasoning over scientific problems, there is an opportunity to fundamentally change how computational hydrology is done.

AI-Hydro is a platform that bridges this gap. It puts foundation models (Claude, GPT-4, Gemini, and others) at the centre of the research workflow and gives them direct access to production-quality hydrological and geospatial tools — not as a chatbot that generates code you then debug, but as an intelligent agent that orchestrates real computations, remembers context across sessions, and adapts its approach when built-in tools fall short by writing standalone scripts leveraging the latest scientific Python ecosystem.

The platform ships with a growing set of built-in tools — from USGS watershed delineation to differentiable HBV-light calibration — but the long-term vision is much larger: a community-driven ecosystem where researchers contribute domain-specific tools (flood frequency analysis, sediment transport, groundwater modelling, remote sensing workflows) that any AI agent can discover and compose into novel research pipelines. Through a simple plugin system, any Python package can register tools that become immediately available to every AI-Hydro user.

This is what the future of computational hydrology and geospatial sciences looks like: researchers describe their intent, and intelligent agents assemble the right data, methods, and models to get it done.

What AI-Hydro Can Do

1. Automated Research via Built-in Tools

When a tool exists for the task, the AI calls it directly — no code generation, no copy-paste, no debugging. Results come back structured and cached.

You: "Delineate the watershed for USGS gauge 01031500, fetch 10 years of
     GridMET forcing, and calibrate a differentiable HBV model."

AI-Hydro: [calls delineate_watershed -> fetch_forcing_data -> train_hydro_model]
          Watershed: 769 km², Piscataquis River ME
          HBV calibration complete: NSE = 0.638, KGE = 0.644

The AI chains multiple tools in a single conversation — delineation, data retrieval, signature extraction, model calibration — building on each step's results.

2. Standalone Script Generation When Tools Don't Exist

AI-Hydro isn't limited to its built-in tools. When the task requires something outside the current toolkit — a custom statistical analysis, a novel visualisation, a niche data format conversion — the AI writes and executes standalone Python scripts, leveraging the full scientific Python ecosystem (NumPy, SciPy, xarray, rasterio, PyTorch, and beyond).

You: "Run a Mann-Kendall trend test on the annual peak flows and plot the
     results with a Sen's slope overlay."

AI-Hydro: [writes and runs a standalone script using pymannkendall + matplotlib]
          Mann-Kendall p = 0.023 (significant), Sen's slope = -1.2 m³/s per year
          Plot saved to session.

This dual capability — structured tools for common tasks, freeform scripting for everything else — means AI-Hydro adapts to the full breadth of research needs.

3. Community-Extensible Tool Ecosystem

AI-Hydro is designed as a platform, not a closed product. Any researcher can package domain-specific tools and make them available to the entire community:

# In your package's pyproject.toml
[project.entry-points."aihydro.tools"]
flood_frequency = "my_package.tools:flood_freq_tool"
sediment_yield  = "my_package.tools:sediment_tool"

Install the package, restart the server, and those tools are immediately available to every AI model connected to AI-Hydro. We envision a growing ecosystem of community-contributed tools spanning:

• Flood frequency and extreme event analysis
• Sediment transport and geomorphology
• Groundwater modelling and well analysis
• Remote sensing and land surface classification
• Water quality and nutrient cycling
• Snow hydrology and glaciology
• Irrigation scheduling and water resources management

Built-in Tools

See docs/tools-reference.md for full parameters, examples, and return schemas.

Key Capabilities

Research Session Memory

Every tool result is cached in a HydroSession (JSON per gauge). Expensive computations — watershed delineation (~10s), multi-year streamflow downloads (~5s) — are done once and reused across conversations, days, or weeks. The session tracks provenance so you can export a methods paragraph for your paper.

Session 01031500  [updated 2026-03-06]
  Computed (7): watershed, streamflow, signatures, geomorphic, camels, forcing, model
  Pending  (1): twi

  Watershed area:    769.0 km²  (HUC-02: 01)
  Streamflow record: 3,652 days
  Baseflow index:    0.61
  HBV differentiable: NSE=0.638, KGE=0.644

Differentiable HBV-Light

A pure-PyTorch differentiable HBV-light is built in:

• 12 physically-meaningful calibrated parameters
• Multi-restart Adam optimiser with cosine annealing
• Automatic CAMELS streamflow via pygeohydro for 671 CONUS gauges
• Typical performance: NSE 0.55-0.80

Model Context Protocol (MCP)

All tools communicate via the Model Context Protocol — an open standard for connecting AI models to external capabilities. This means AI-Hydro tools work with any MCP-compatible client, not just the bundled extension.

Works with Any AI Provider

Installation

Prerequisites

• VS Code 1.84+
• Python 3.10+ (Miniconda or system)
• An API key for at least one AI provider

Step 1 — Install the Python Tools

pip install aihydro-tools[all]

This installs all hydrological tools and the aihydro-mcp server command. The extension auto-detects it on startup.

pip install aihydro-tools[data]       # streamflow, forcing, land cover, soil, CAMELS
pip install aihydro-tools[analysis]   # watershed, signatures, TWI, geomorphic, CN
pip install aihydro-tools[modelling]  # PyTorch HBV-light, NeuralHydrology LSTM
pip install aihydro-tools[viz]        # matplotlib, plotly, folium

Step 2 — Install the VS Code Extension

Option A — VS Code Marketplace

Search for "AI-Hydro" in VS Code Extensions, or install from the Marketplace page.

Option B — Install from .vsix

1. Download the latest .vsix from Releases
2. In VS Code: Extensions > ... > Install from VSIX...

Option C — Build from source

git clone https://github.com/AI-Hydro/AI-Hydro.git
cd AI-Hydro
npm run install:all
npm run package          # produces ai-hydro-*.vsix

Step 3 — Configure Your AI Provider

1. Click the AI-Hydro icon in the VS Code sidebar
2. Open Settings (gear icon)
3. Select your provider and enter your API key
4. Click Save

Step 4 — Verify

aihydro-mcp  # should start and list all registered tools

The extension auto-registers the MCP server on startup. If you need manual registration:

python setup_mcp.py --ide vscode
python setup_mcp.py --ide claude-code   # for Claude Code CLI

See docs/installation.md for detailed platform-specific instructions.

Quick Start

Once installed, open the AI-Hydro chat panel and try:

Start a research session for USGS gauge 01031500 and delineate its watershed.

Then continue naturally:

Fetch 10 years of GridMET forcing data and extract hydrological signatures.

Train a differentiable HBV model and show me the performance metrics.

Export the full session methods paragraph for my paper.

See docs/quickstart.md for a complete walkthrough.

Architecture

+------------------------------------------------------+
|  VS Code Extension  (TypeScript / React)              |
|   Chat · Settings · Map · File editing · Terminal      |
+---------------------------+--------------------------+
                            |
              Model Context Protocol (stdio)
                            |
              +-------------+-------------+
              |                           |
              v                           v
+---------------------------+  +---------------------+
| Built-in MCP Tools        |  | Standalone Scripts   |
| aihydro-tools on PyPI     |  | AI writes & executes |
| + Community plugin tools  |  | full Python ecosystem |
+-------+--------+----+----+  +---------------------+
        |        |    |
   USGS NWIS  GridMET  pygeohydro
   NHDPlus    3DEP     CAMELS
   NLDI       MODIS    PyTorch HBV

The extension acts as an MCP client: when the AI decides to call delineate_watershed, it sends a JSON-RPC request to the Python server, which fetches real data from USGS/GridMET/etc. and returns structured results. When no tool exists for the task, the AI writes a standalone Python script and executes it through the integrated terminal — combining the reliability of structured tools with the flexibility of general-purpose programming.

Full architecture details: docs/architecture.md

Documentation

Contributing Tools

We welcome contributions from the hydrology and geospatial sciences community. There are two paths depending on your goals:

Path A: Standalone MCP Server — Build an independent MCP server for a full sub-domain toolkit (flood frequency analysis, hydraulic modelling, etc.). Your server runs as its own process with its own dependencies and gets registered alongside the core ai-hydro server. Best for complex toolkits or when you need full dependency isolation.

Path B: Entry Point Plugin — Extend the existing aihydro-tools server by registering tool functions via Python entry points. Your tools load into the same process with full access to HydroSession, cached data, and shared helpers. Best for single tools or small extensions.

# Path B — just add this to your pyproject.toml
[project.entry-points."aihydro.tools"]
my_tool = "my_package.tools:my_tool_function"

Install, restart the server, and your tool is immediately available to every AI model.

See PLUGIN_GUIDE.md for complete walkthroughs of both paths, including the data contract, session integration, and testing.

High-Priority Contribution Areas

We're actively looking for community tools in these domains:

• Flood frequency analysis and extreme event statistics
• Sediment transport and reservoir sedimentation
• Groundwater modelling, well analysis, and recharge estimation
• Remote sensing workflows (MODIS snow cover, Landsat ET, SAR soil moisture)
• Water quality and nutrient cycling
• Snow hydrology and glaciology
• Irrigation scheduling and water resources management
• Hydraulic modelling and 2D flood mapping

See CONTRIBUTING.md for the step-by-step new tool guide and python/CONTRIBUTING.md for Python-specific development setup.

Citation

If you use AI-Hydro in your research, please cite:

@software{aihydro2026,
  title   = {AI-Hydro: An Intelligent Computational Research Platform
             for Hydrology and Geospatial Sciences},
  author  = {Galib, Mohammad and Merwade, Venkatesh},
  year    = {2026},
  url     = {https://github.com/AI-Hydro/AI-Hydro},
  version = {1.0.0}
}

Built on Open Source

AI-Hydro is a domain-specific fork of Cline (Apache 2.0). We are grateful to the Cline team for building the agentic VS Code framework that made this possible.

Python data access is powered by HyRiver (pygeohydro, pynhd, py3dep, pygridmet) and PyTorch.

License

Apache 2.0 © 2026 Mohammad Galib, Venkatesh Merwade

Support

• Bugs / questions: GitHub Issues
• Ideas: GitHub Discussions
• Email: mgalib@purdue.edu