🌊 HydroMind

Open AI-driven Water Intelligence Platform

HydroMind is an open-source Python framework that tackles multi-dimensional water challenges — flood forecasting, drought monitoring, and water quality analysis — using real-world data APIs and locally-runnable AI models. Think of it as an AI agent for water: describe your challenge in plain language and HydroMind fetches the data, recommends the right models, trains them, and returns forecasts.

---

✨ Features

• Natural language interface — describe a water challenge, get a complete analysis plan
• 4 free water data APIs — USGS NWIS, Open-Meteo (ERA5 + GloFAS), EPA WQP, Copernicus
• AI model recommender — maps challenge type → best model, with rationale
• Auto-implemented models — Prophet, ARIMA, SPI, Random Forest, XGBoost, LSTM
• 3 challenge domains — flood forecasting, drought monitoring, water quality
• 100% CPU-friendly — all models run locally without GPU
• Python SDK + CLI — use as a library or from the terminal
• No API keys needed for basic use (USGS, Open-Meteo, EPA are all free & open)

---

🚀 Quickstart

Install

git clone https://github.com/Rekin226/hydromind.git
cd hydromind
pip install -e ".[all]"

Minimum install (no deep learning):

pip install -e .

Python SDK

from hydroai import HydroAgent

agent = HydroAgent()

# Flood forecasting — Niger River
result = agent.solve(
    "Predict flood risk in the Niger River over the next 7 days",
    location_override="13.5,2.1",   # lat, lon
    start_date="2015-01-01",
)
result.show()

# Drought monitoring — Sahel
result = agent.solve(
    "Monitor drought conditions in the Sahel region",
    location_override="15.0,0.0",
)
result.show()

# Water quality — US river station
result = agent.solve(
    "Detect nitrate pollution and water quality anomalies",
    location_override="USGS-01589440",
)
result.show()

CLI

# Solve a water challenge
hydromind solve "predict flood risk in the Niger River over 7 days" --location "13.5,2.1"

# Explain approach without fetching data
hydromind explain "drought forecasting in sub-Saharan Africa"

# List all data sources
hydromind data list

# Fetch streamflow data
hydromind data fetch --source usgs --site 01589440 --variable streamflow --days 365

# Fetch global precipitation
hydromind data fetch --source openmeteo --site "48.85,2.35" --variable precipitation --days 730

# Fetch river discharge from GloFAS
hydromind data fetch --source copernicus --site "13.5,2.1" --variable river_discharge --days 1825

# Search USGS stations
hydromind data search --source usgs --query "Susquehanna" --state PA

# List available models
hydromind models

---

🗄️ Data Sources

Source	Coverage	Variables	Auth Required
USGS NWIS	United States	Streamflow, groundwater, water quality, precipitation	None
Open-Meteo	Global	Precipitation, temperature, ET, soil moisture, GloFAS discharge, 16-day forecasts	None
EPA WQP	United States	pH, nutrients, metals, pathogens, physical parameters	None
Copernicus/GloFAS	Global	River discharge, ERA5 hydrology, flood probability	Optional (free registration)

---

🤖 AI Models

Model	Class	Best For	Uncertainty	Multivariate
Prophet	Statistical	Seasonal streamflow, drought monitoring	✓	✗
ARIMA/SARIMA	Statistical	Short-term discharge, stationary series	✓	✗
SPI Drought Index	Statistical	WMO drought monitoring (1, 3, 6, 12-month)	✗	✗
Random Forest	ML	Multi-input flood risk, water quality	✓	✓
XGBoost	ML	High-accuracy tabular hydrology	✗	✓
Isolation Forest	ML	Water quality anomaly detection	✗	✓
LSTM	Deep Learning	Complex temporal sequences	✗	✓

---

📦 Project Structure

hydromind/
├── hydroai/
│   ├── agent/
│   │   ├── core.py          # HydroAgent — main orchestrator
│   │   ├── planner.py       # Natural language challenge parser
│   │   └── recommender.py   # Model recommendation engine
│   ├── data/
│   │   ├── usgs.py          # USGS NWIS connector
│   │   ├── openmeteo.py     # Open-Meteo connector (ERA5 + GloFAS)
│   │   ├── epa.py           # EPA Water Quality Portal
│   │   ├── copernicus.py    # Copernicus/GloFAS connector
│   │   └── catalog.py       # Unified data catalog + auto-routing
│   ├── models/
│   │   ├── statistical.py   # Prophet, ARIMA, SPI
│   │   ├── ml.py            # Random Forest, XGBoost, Isolation Forest
│   │   └── lstm.py          # Lightweight CPU LSTM (PyTorch)
│   ├── challenges/
│   │   ├── flood.py         # FloodChallenge helper
│   │   ├── drought.py       # DroughtChallenge + SPI
│   │   └── quality.py       # WaterQualityChallenge + WHO guidelines
│   └── cli.py               # CLI entry point
├── examples/
│   ├── 01_flood_forecast.py
│   ├── 02_drought_monitoring.py
│   ├── 03_water_quality.py
│   └── 04_custom_data_fetch.py
└── tests/

---

🌍 Example Challenges HydroMind Can Solve

agent = HydroAgent()

# Flood
agent.solve("Predict flash flood risk in the Sahel during monsoon season", location_override="15.0,0.0")
agent.solve("Forecast 7-day streamflow for the Susquehanna River", location_override="01570500")

# Drought
agent.solve("Compute SPI drought index for East Africa over 20 years", location_override="-1.0,37.0")
agent.solve("Assess water stress in the Colorado River Basin", location_override="36.1,-111.5")

# Water quality
agent.solve("Detect nitrate contamination in the Chesapeake Bay watershed", location_override="USGS-01589440")
agent.solve("Monitor pH and dissolved oxygen in the Rhine River", location_override="51.9,4.5")

# Groundwater
agent.solve("Analyze groundwater level trends in the Central Valley", location_override="36.5,-119.5")

---

📊 Model Skill Metrics

HydroMind reports standard hydrological performance metrics:

• NSE (Nash-Sutcliffe Efficiency): 1.0 = perfect, < 0 = worse than mean
• KGE (Kling-Gupta Efficiency): accounts for correlation, bias, and variability
• RMSE (Root Mean Square Error)
• MAE (Mean Absolute Error)

---

🔭 Roadmap

• HydroLLM: Fine-tuned language model for hydrology question answering
• Chronos integration: Zero-shot time series forecasting for ungauged basins
• WaterGPT-style chatbot: Conversational hydrological analysis
• Global gauge network: Integration with GRDC, HydroShare, and CAMELS datasets
• Satellite data: Integration with Google Earth Engine for NDWI, GRACE groundwater
• Ensemble forecasting: Multi-model weighted ensembles with uncertainty propagation
• Alert system: Automated early warning notifications for flood/drought thresholds
• REST API: FastAPI-based microservice for embedding in decision support systems
• Web UI: Streamlit dashboard for non-technical users

---

🤝 Contributing

HydroMind is open to contributions. Priority areas:

1. Additional data connectors (GRDC, HydroShare, national agencies)
2. Physics-informed model constraints
3. Multilingual challenge parser (French, Arabic, Portuguese)
4. Coverage of ungauged basins in Global South

---

📄 License

MIT License — see LICENSE for details.

---

📚 Scientific Basis

HydroMind builds on the research landscape reviewed in:

• Time-LLM (Jin et al., ICLR 2024) — LLM reprogramming for time series
• Chronos (Ansari et al., 2024) — Pre-trained probabilistic forecasting
• ClimaX (Nguyen et al., 2023) — Foundation model for weather/climate
• GloFAS (Nearing et al., Nature 2024) — Global flood forecasting in ungauged basins
• WMO SPI/SPEI guidelines for drought monitoring

---

Built with ❤️ for the global water community. HydroMind — because every drop of data matters.