AI-Hydro¶
Intelligent Hydrological Computing
The first hydrology platform built for reproducibility-first AI research —
every analysis step automatically recorded, citable, and reusable.
Project Status
AI-Hydro is in active beta (v0.1.x). Core APIs are stable; new tools and features are being added regularly. Not yet recommended for production pipelines without pinned versions.
Who Is This For?¶
AI-Hydro is built for hydrology PhD students, computational hydrologists, and research groups who need reproducible, well-documented workflows — without spending half their time writing data-fetching glue code or debugging format mismatches between libraries.
If you work with USGS gauges, CAMELS catchments, or any watershed-scale analysis and want an AI agent that can orchestrate the full pipeline and record everything it does, this is for you.
The Problem¶
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.
This friction compounds a deeper structural failure: fewer than 7% of published computational hydrology studies provide sufficient code, data, and workflow documentation for independent replication, a rate that has barely moved despite a decade of open-science advocacy.
AI-Hydro addresses this directly — not by making AI the hero, but by making reproducibility automatic. Every tool call is recorded with its data source, parameters, and timestamp. The AI agent is the interface; provenance is the product.
What AI-Hydro Can Do¶
Watershed Analysis¶
Delineate watersheds, fetch streamflow, extract hydrological signatures, characterize geomorphology — all from a USGS gauge ID, in one conversation.
Hydrological Modelling¶
Calibrate differentiable conceptual models or train deep learning rainfall-runoff models. Results cached with full provenance.
Project Workspace¶
Organise research across multiple gauges, regions, and topics. Search across all your experiments in one command.
Literature Module¶
Drop your PDFs into a folder. Index them. Ask the agent to synthesise across your own paper collection — no vector database required.
Researcher Profile¶
The agent learns who you are — your expertise, preferred models, active projects — and tailors responses accordingly across every session.
Community Plugins¶
Any Python package can register domain tools via entry points. Flood frequency, sediment transport, groundwater, remote sensing — community-built and auto-discovered.
Quick Example¶
You: Delineate the watershed for USGS gauge 01031500, extract hydrological
signatures, and calibrate a differentiable HBV model on GridMET forcing.
AI-Hydro:
✓ Watershed delineated — 1,247 km² (NHDPlus, NLDI)
✓ Streamflow fetched — 14,975 daily records (2000–2024, USGS NWIS)
✓ Hydrological signatures extracted — BFI: 0.52, runoff ratio: 0.41, ...
✓ HBV-light calibrated — NSE: 0.81, KGE: 0.78 (validation period)
✓ Session saved → ~/.aihydro/sessions/01031500.json
No code written. No data downloaded manually. Full provenance recorded automatically.
Why AI-Hydro?¶
| AI-Hydro | Writing scripts yourself | HydroMT | NeuralHydrology | |
|---|---|---|---|---|
| Reproducibility | Automatic — every step recorded | Manual — only if you remember | Partial — config files | Manual |
| AI-native workflow | Yes — natural language → computation | No | No | No |
| MCP / agent integration | Yes | No | No | No |
| Session persistence | Yes — survives restarts | No | Partial | No |
| Researcher memory | Yes — profile + project state | No | No | No |
| Built-in data access | USGS, GridMET, 3DEP, NLCD, CAMELS | DIY | Config-driven | CAMELS only |
| Community extensible | Yes — Python entry points | N/A | Yes — plugins | No |
| Learning curve | Low — describe intent | High | Medium | High |
AI-Hydro is not a replacement for HydroMT or NeuralHydrology — it can call them as standalone scripts. It is the orchestration and provenance layer that sits above domain tools.
Installation¶
Search AI-Hydro in the VS Code Extensions panel, or install from the Marketplace.
The extension auto-detects aihydro-mcp on startup — no manual server configuration needed.
Supported AI Models¶
AI-Hydro works with any provider that supports tool/function calling. No model-specific code — switching providers is a single setting change.
| Provider | Supported models |
|---|---|
| Anthropic | Claude Sonnet, Claude Opus (any released version) |
| OpenAI | GPT-4o, GPT-4o mini, o3, o4-mini and later |
| Gemini 2.0 Flash, Gemini 2.5 Pro and later | |
| AWS Bedrock | Claude on Bedrock, any Bedrock model with tool use |
| Azure OpenAI | GPT models via Azure endpoint |
| Local | Ollama, LM Studio (models with tool-call support) |
| OpenRouter | Any model via OpenRouter API |
Built on Open Source¶
AI-Hydro is a domain-specific fork of Cline (Apache 2.0). The Python backend is built on the scientific Python ecosystem:
| Package | Role |
|---|---|
| fastmcp | MCP server framework |
| hydrofunctions | USGS NWIS streamflow retrieval |
| pynhd | NHDPlus watershed delineation |
| pygeohydro | NLCD, CAMELS, geospatial data |
| pygridmet | GridMET climate forcing |
| py3dep | 3DEP DEM and terrain analysis |
| pydantic | Data validation |
If you use AI-Hydro in your research, see Citing AI-Hydro for BibTeX entries for the platform and all data sources.