Metadata-Version: 2.4
Name: aihydro-tools
Version: 1.0.1
Summary: AI-Hydro: 17 hydrological research tools as an MCP server for AI agents
Author-email: Mohammad Galib <mgalib@purdue.edu>
License: Apache-2.0
Project-URL: Homepage, https://github.com/AI-Hydro/aihydro-tools
Project-URL: Documentation, https://github.com/AI-Hydro/AI-Hydro/wiki
Project-URL: Repository, https://github.com/AI-Hydro/aihydro-tools
Project-URL: Issues, https://github.com/AI-Hydro/aihydro-tools/issues
Keywords: hydrology,watershed,geospatial,MCP,agentic,CAMELS,FAIR
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: hydrofunctions>=0.2.0
Provides-Extra: geo
Requires-Dist: geopandas>=0.13.0; extra == "geo"
Requires-Dist: shapely>=2.0.0; extra == "geo"
Requires-Dist: pyproj>=3.6.0; extra == "geo"
Provides-Extra: data
Requires-Dist: aihydro-tools[geo]; extra == "data"
Requires-Dist: pynhd>=0.16.0; extra == "data"
Requires-Dist: pygeohydro>=0.16.0; extra == "data"
Requires-Dist: pygridmet>=0.15.0; extra == "data"
Requires-Dist: xarray>=2023.0.0; extra == "data"
Provides-Extra: analysis
Requires-Dist: aihydro-tools[geo]; extra == "analysis"
Requires-Dist: rioxarray>=0.15.0; extra == "analysis"
Requires-Dist: xarray>=2023.0.0; extra == "analysis"
Requires-Dist: rasterio>=1.3.0; extra == "analysis"
Requires-Dist: py3dep>=0.15.0; extra == "analysis"
Requires-Dist: xrspatial>=0.3.0; extra == "analysis"
Requires-Dist: pysheds>=0.3.0; extra == "analysis"
Requires-Dist: scipy>=1.11.0; extra == "analysis"
Provides-Extra: modelling
Requires-Dist: torch>=2.0.0; extra == "modelling"
Provides-Extra: camels
Requires-Dist: camels-attrs>=0.1.0; extra == "camels"
Provides-Extra: mcp
Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
Provides-Extra: rag
Requires-Dist: sentence-transformers>=2.3.0; extra == "rag"
Requires-Dist: chromadb>=0.4.0; extra == "rag"
Requires-Dist: pyyaml>=6.0.0; extra == "rag"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == "viz"
Requires-Dist: plotly>=5.18.0; extra == "viz"
Requires-Dist: folium>=0.15.0; extra == "viz"
Provides-Extra: all
Requires-Dist: aihydro-tools[analysis,camels,data,mcp,modelling,viz]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: fastmcp>=0.1.0; extra == "dev"
Dynamic: license-file

# aihydro-tools

**17 hydrological research tools as an MCP server for AI agents.**

`aihydro-tools` is the Python backend for [AI-Hydro](https://github.com/AI-Hydro/AI-Hydro), a VS Code extension that gives AI assistants direct access to hydrological analysis tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

## Install

```bash
pip install aihydro-tools[all]
```

Or install only what you need:

```bash
pip install aihydro-tools[data]       # streamflow, forcing, land cover
pip install aihydro-tools[analysis]   # watershed, signatures, TWI, CN
pip install aihydro-tools[modelling]  # differentiable HBV-light, LSTM
pip install aihydro-tools[mcp]        # MCP server only (minimal)
```

## Run the MCP Server

```bash
aihydro-mcp
```

This starts the MCP server on stdio, ready for any MCP client (AI-Hydro extension, Claude Code, Cursor, etc.).

## Register with an IDE

```bash
python setup_mcp.py --ide vscode       # AI-Hydro VS Code extension
python setup_mcp.py --ide claude-code  # Claude Code CLI
python setup_mcp.py --check            # verify 17 tools registered
```

## Tools (17)

| Category | Tools |
|----------|-------|
| **Watershed** | `delineate_watershed` |
| **Streamflow** | `fetch_streamflow_data` |
| **Signatures** | `extract_hydrological_signatures` |
| **Geomorphic** | `extract_geomorphic_parameters` |
| **Terrain** | `compute_twi` |
| **Curve Number** | `create_cn_grid` |
| **Forcing** | `fetch_forcing_data` |
| **CAMELS** | `extract_camels_attributes` |
| **Knowledge** | `query_hydro_concepts` |
| **Modelling** | `train_hydro_model`, `get_model_results` |
| **Session** | `start_session`, `get_session_summary`, `clear_session`, `add_note`, `export_session`, `sync_research_context` |

## Example

```
You: "Delineate the watershed for USGS gauge 01031500 and fetch 10 years of forcing data."

AI-Hydro: [calls delineate_watershed → fetch_forcing_data]
          Watershed: 769 km², Piscataquis River ME
          Forcing: 3,652 days of GridMET data (prcp, tmax, tmin, PET, srad, wind)
```

## Data Sources

- **USGS NWIS** — daily streamflow via hydrofunctions
- **NHDPlus / NLDI** — watershed delineation via pynhd
- **GridMET** — climate forcing via pygridmet
- **3DEP** — DEM and terrain analysis via py3dep
- **NLCD / POLARIS** — land cover and soils
- **CAMELS-US** — catchment attributes via pygeohydro

## Session Persistence

Every tool result is cached in a **HydroSession** (JSON file per gauge at `~/.aihydro/sessions/`). Expensive computations are done once and reused across conversations.

## License

[Apache 2.0](./LICENSE)

## Links

- **AI-Hydro Extension**: [github.com/AI-Hydro/AI-Hydro](https://github.com/AI-Hydro/AI-Hydro)
- **Issues**: [github.com/AI-Hydro/aihydro-tools/issues](https://github.com/AI-Hydro/aihydro-tools/issues)
- **Author**: Mohammad Galib (mgalib@purdue.edu)
