Metadata-Version: 2.4
Name: aihydro-tools
Version: 1.2.0
Summary: AI-Hydro: 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
Requires-Dist: fastmcp>=2.0.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
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"
Dynamic: license-file

# aihydro-tools

    AI-Hydro — Intelligent Hydrological Computing

  Hydrological research tools as an MCP server for AI agents.

---

## What is aihydro-tools?

`aihydro-tools` is the Python backend for the [AI-Hydro](https://github.com/AI-Hydro/AI-Hydro) platform — a collection of hydrological and geospatial analysis tools exposed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It powers the built-in tools that AI agents use for watershed delineation, streamflow analysis, terrain analysis, differentiable modelling, and more.

---

## Quick Start

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

# Verify
aihydro-mcp --diagnose

# Run the server
aihydro-mcp
```

The [AI-Hydro VS Code extension](https://github.com/AI-Hydro/AI-Hydro) auto-detects `aihydro-mcp` on startup — no manual configuration needed.

---

## Built-in Tools

| Category | Tool | Description |
|----------|------|-------------|
| **Watershed** | `delineate_watershed` | NHDPlus watershed delineation from USGS NLDI given a gauge ID |
| **Streamflow** | `fetch_streamflow_data` | Daily discharge time series from USGS NWIS |
| **Signatures** | `extract_hydrological_signatures` | 15+ flow statistics: BFI, runoff ratio, FDC percentiles, recession constants |
| **Geomorphic** | `extract_geomorphic_parameters` | 28 basin morphometry metrics (area, slope, elevation, shape factors) |
| **Terrain** | `compute_twi` | Topographic Wetness Index from 3DEP 10m DEM |
| **Curve Number** | `create_cn_grid` | NRCS Curve Number grid from NLCD land cover + Polaris soils |
| **Forcing** | `fetch_forcing_data` | Basin-averaged GridMET climate data (prcp, tmax, tmin, PET, srad, wind) |
| **CAMELS** | `extract_camels_attributes` | Full CAMELS-US attribute set (671 gauges) via pygeohydro |
| **Modelling** | `train_hydro_model` | Differentiable HBV-light (PyTorch) or NeuralHydrology LSTM |
| **Modelling** | `get_model_results` | Retrieve cached model performance (NSE, KGE, RMSE) |
| **Session** | `start_session` | Initialize or resume a research session for a gauge |
| **Session** | `get_session_summary` | Overview of computed and pending analysis slots |
| **Session** | `clear_session` | Reset cached results to force re-computation |
| **Session** | `add_note` | Attach research notes to the session |
| **Session** | `export_session` | Export a methods paragraph for manuscripts |
| **Session** | `sync_research_context` | Synchronize session state with the AI context |

Additional tools can be added by the community via the plugin system (see below).

---

## Data Sources

All data is fetched from authoritative federal sources:

- **[USGS NWIS](https://waterdata.usgs.gov/nwis)** — daily streamflow via hydrofunctions
- **[NHDPlus / NLDI](https://waterdata.usgs.gov/blog/nldi-intro/)** — watershed delineation via pynhd
- **[GridMET](https://www.climatologylab.org/gridmet.html)** — climate forcing via pygridmet
- **[3DEP](https://www.usgs.gov/3d-elevation-program)** — DEM and terrain analysis via py3dep
- **[NLCD](https://www.mrlc.gov/)** — land cover classification
- **[POLARIS](https://www.usgs.gov/publications/polaris-properties-30-meter-probabilistic-maps-soil-properties-over-contiguous-united)** — soil properties
- **[CAMELS-US](https://ral.ucar.edu/solutions/products/camels)** — catchment attributes via pygeohydro

---

## Session Persistence

Every tool result is cached in a **HydroSession** (JSON file per gauge at `~/.aihydro/sessions/`). Expensive computations — watershed delineation (~10s), multi-year streamflow downloads (~5s) — are done once and reused across conversations, days, or weeks. The session tracks provenance for reproducibility.

---

## Extending with Plugins

Community packages can register additional tools via Python entry points:

```toml
# In your package's pyproject.toml
[project.entry-points."aihydro.tools"]
my_tool = "my_package.tools:my_tool_function"
```

Install the package, restart the server, and the new tool is automatically available. Plugins get full access to HydroSession and cached data from other tools.

See the [Plugin Guide](https://github.com/AI-Hydro/AI-Hydro/blob/main/PLUGIN_GUIDE.md) for complete walkthroughs of both plugin paths (entry points and standalone MCP servers).

---

## Use as a Python Library

You can use `aihydro-tools` directly in Python scripts without the MCP server:

```python
from ai_hydro.analysis.watershed import delineate_watershed
from ai_hydro.data.streamflow import fetch_streamflow_data
from ai_hydro.analysis.signatures import extract_hydrological_signatures

# Delineate a watershed
ws = delineate_watershed("01031500")
print(f"Watershed area: {ws.data['area_km2']} km2")

# Fetch streamflow
sf = fetch_streamflow_data("01031500", start_date="2015-01-01", end_date="2024-12-31")
print(f"Records: {len(sf.data['dates'])} days")

# Extract signatures
sigs = extract_hydrological_signatures("01031500")
print(f"Baseflow index: {sigs.data['baseflow_index']}")
```

All functions return `HydroResult` objects with `.data` (dict) and `.meta` (provenance metadata).

---

## Installation Details

### Extras

Install only what you need:

| Extra | What it adds | Install command |
|-------|-------------|-----------------|
| `[data]` | Streamflow, forcing, land cover, soil, CAMELS retrieval | `pip install aihydro-tools[data]` |
| `[analysis]` | Watershed, signatures, TWI, geomorphic, curve number | `pip install aihydro-tools[analysis]` |
| `[modelling]` | PyTorch differentiable HBV-light, NeuralHydrology LSTM | `pip install aihydro-tools[modelling]` |
| `[viz]` | Matplotlib, Plotly, Folium visualisations | `pip install aihydro-tools[viz]` |
| `[all]` | Everything above | `pip install aihydro-tools[all]` |

### PATH Troubleshooting

If `aihydro-mcp` is not found after install, pip placed it outside your PATH:

| OS | Typical location |
|----|-----------------|
| **Windows (user)** | `%APPDATA%\Python\Python3XX\Scripts\aihydro-mcp.exe` |
| **Windows (system)** | `C:\Python3XX\Scripts\aihydro-mcp.exe` |
| **macOS/Linux (user)** | `~/.local/bin/aihydro-mcp` |
| **macOS/Linux (system)** | `/usr/local/bin/aihydro-mcp` |
| **Conda** | `~/miniconda3/bin/aihydro-mcp` or `~/anaconda3/bin/aihydro-mcp` |

**Universal fallback**: `python -m ai_hydro.mcp` works regardless of PATH. The AI-Hydro extension auto-detects both the console script and the module fallback.

---

## Contributing

We welcome contributions from the hydrology and geospatial sciences community. See:

- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — Development setup, code style, testing
- **[Plugin Guide](https://github.com/AI-Hydro/AI-Hydro/blob/main/PLUGIN_GUIDE.md)** — Two paths for contributing tools (entry points and standalone servers)

---

## Links

- **AI-Hydro Extension**: [github.com/AI-Hydro/AI-Hydro](https://github.com/AI-Hydro/AI-Hydro)
- **PyPI**: [pypi.org/project/aihydro-tools](https://pypi.org/project/aihydro-tools/)
- **Issues**: [github.com/AI-Hydro/aihydro-tools/issues](https://github.com/AI-Hydro/aihydro-tools/issues)

---

## License

[Apache 2.0](./LICENSE) © 2026 Mohammad Galib, Venkatesh Merwade
