hydrosovereign 6.6.0

HydroSovereign AI Engine (HSAE) — Automated satellite-driven transboundary water law compliance for 26 globally contested river basins

HydroSovereign AI Engine (HSAE)

HSAE automates the full pipeline from live satellite observation to international water law compliance — in under 2 minutes per basin.

362+ downloads · 20 countries · 5 continents · 100% QGIS security scan · GeoAgent AI · eWaterCycle BMI

---

📋 Table of Contents

• What is HSAE?
• Six Original Scientific Indices (AWSI)
• Installation
• Quick Start
• 26-Basin Coverage
• Key Results
• Architecture
• CLI Usage
• Comparison with Alternatives
• Citation
• Links

---

🌊 What is HSAE?

HydroSovereign AI Engine (HSAE) is a Python package and QGIS plugin for automated transboundary water law compliance assessment. It combines:

• 9 satellite sensors via Google Earth Engine (GPM, GRACE-FO, SMAP, Sentinel-1/2, ERA5, GloFAS, Open-Meteo, MODIS, VIIRS)
• HBV-96 hydrological model with SCE-UA calibration and EnKF digital twin
• 6 original compliance indices (the Alkhedir Water Sovereignty Indices — AWSI)
• AI negotiation pathway trained on 478 historical TFDD/ICOW dispute outcomes
• UNWC 1997 article-by-article trigger logic (Arts. 5, 7, 9, 11, 17, 33)
• eWaterCycle BMI compatible — integrates with the open-science hydrological platform
• GeoAgent AI — natural language queries inside QGIS (opengeos/GeoAgent PR #79)

Covers 26 globally contested transboundary basins across 7 world regions. NSE = 0.63, KGE = 0.74 (pre-calibration, Blue Nile GERD vs GloFAS ERA5 v4).

---

🔬 Six Original Scientific Indices (AWSI)

The Alkhedir Water Sovereignty Indices (AWSI) are the first published quantitative framework connecting hydrological model outputs to UNWC 1997 article triggers:

Index	Full Name	Legal Trigger	GERD Result
ATDI	Alkhedir Transparency Deficit Index	Art. 7 — No Significant Harm (≥40%)	43.5% ⚠️
AHIFD	Alkhedir Human-Induced Flow Deficit	Art. 7 — volumetric downstream harm	20.0%
AFSF	Alkhedir Forensic Signal Factor	Art. 9 — data exchange obligation	0.67
AHLB	Alkhedir HBV-Legal Bridge	Arts. 5,6,7 — HBV-96 → legal triggers	First of kind
ASI	Alkhedir Sovereignty Index	Art. 5 — equitable utilisation	0.58
ATCI	Alkhedir Treaty Compliance Index	Arts. 5,7,9,11,17,33 composite	70/100

All six indices are collectively named AWSI and are validated against the Blue Nile (GERD) basin with RMSE = 4.1% against 14 published benchmark values.

---

⚙️ Installation

# Minimal install
pip install hydrosovereign

# With Google Earth Engine
pip install hydrosovereign[gee]

# With visualisation (Plotly, Folium, Matplotlib)
pip install hydrosovereign[viz]

# With Jupyter notebook support
pip install hydrosovereign[jupyter]

# Everything
pip install hydrosovereign[full]

Requirements: Python ≥ 3.9 · NumPy · Pandas · SciPy · scikit-learn · Requests

---

🚀 Quick Start

from hydrosovereign import ATDI, AHIFD, AFSF, AHLB, ASI, ATCI
from hydrosovereign import ConflictIndex, NegotiationAI

# Define any basin
params = dict(
    runoff_coeff=0.38,       # Blue Nile (GERD)
    dam_capacity_bcm=74.0,
    n_countries=3,
    dispute_level=4,
    basin_area_km2=174000
)

# Compute all 6 AWSI indices
atdi  = ATDI(**params)     # → 43.5%  ⚠️  Art. 7 UNWC triggered
ahifd = AHIFD(**params)    # → 20.0%       20% of natural flow withheld
afsf  = AFSF(**params)     # → 0.67        Art. 9 data exchange check
ahlb  = AHLB(**params)     # →             HBV-96 → legal bridge
asi   = ASI(**params)      # → 0.58        Art. 5 equitable use
atci  = ATCI(**params)     # → 70/100      composite compliance

# Conflict assessment
ci = ConflictIndex(atdi=atdi, ahifd=ahifd, **params)
print(f"Conflict Index: {ci:.3f} HIGH")   # → 0.44 HIGH

# AI negotiation pathway
ai = NegotiationAI()
p  = ai.predict(atdi=atdi, ci=ci, n_countries=3, dispute_level=4)
print(f"P(Negotiation): {p:.0%}")          # → 58% → Art.17 Mediation

# Full basin analysis (one call)
from hydrosovereign.api import analyze_basin
result = analyze_basin("Blue Nile", lat=11.21, lon=35.09)
print(result.summary())

---

🌍 26-Basin Coverage

HSAE covers 26 globally contested transboundary basins across 7 world regions:

Region	Basins
🌍 Africa	Blue Nile (GERD) · Nile-Roseires · Nile-Aswan · Zambezi-Kariba · Congo-Inga · Niger-Kainji
🌏 Middle East	Euphrates-Atatürk · Tigris-Mosul
🌏 Central Asia	Amu Darya-Nurek · Syr Darya-Toktogul
🌏 Asia	Mekong-Xayaburi · Yangtze-Three Gorges · Indus-Tarbela · Brahmaputra-Subansiri · Ganges-Farakka · Salween-Myitsone
🌎 Americas	Amazon-Belo Monte · Paraná-Itaipu · Orinoco-Guri · Colorado-Hoover · Columbia-Coulee · Rio Grande-Amistad
🇪🇺 Europe	Danube-Iron Gates · Rhine · Dnieper-Kakhovka
🌏 Oceania	Murray-Darling-Hume

---

📊 Key Results — Multi-Basin

Sample AWSI results across five continents:

Basin	ATDI	AHIFD	ATCI	CI	Risk	UNWC
Blue Nile (GERD)	43.5%	20.0%	70	0.44	HIGH	Art. 7
Euphrates-Atatürk	58.2%	31.4%	45	0.61	CRITICAL	Arts. 7,9
Mekong-Xayaburi	51.8%	27.6%	52	0.53	HIGH	Art. 7
Amu Darya-Nurek	49.3%	25.1%	58	0.49	HIGH	Art. 7
Dnieper-Kakhovka	62.1%	35.8%	38	0.67	CRITICAL	Arts. 7,33
Danube-Iron Gates	38.7%	18.9%	75	0.39	MEDIUM	Art. 5
Colorado-Hoover	44.1%	22.3%	68	0.45	HIGH	Art. 7

NSE = 0.63 · KGE = 0.74 (pre-calibration) · 56 pytest tests passing · RMSE = 4.1%

---

🏗 Architecture

hydrosovereign/
├── api.py              ← analyze_basin() — one-call entry point
├── indices.py          ← ATDI · AHIFD · AFSF · AHLB · ASI · ATCI
├── hbv.py              ← HBV-96 rainfall-runoff model
├── basins.py           ← 26-basin registry with metadata
├── legal.py            ← UNWC 1997 article trigger logic
├── alerts.py           ← Alert level classification
├── cli.py              ← Command-line interface (hsae / hydrosovereign)
├── py.typed            ← PEP 561 — type hints enabled
├── ai/
│   ├── negotiation.py  ← NegotiationAI (478 TFDD/ICOW cases)
│   ├── conflict.py     ← Conflict Index computation
│   ├── bayesian.py     ← Bayesian uncertainty quantification
│   └── forecast.py     ← Time-series forecasting
├── data/
│   ├── fetchers.py     ← Open-Meteo · GRDC · NASA POWER · GloFAS
│   └── nile_basin_sample.json
├── models/
│   └── hbv.py          ← HBV-96 model class + SCE-UA calibration
└── viz/
    ├── maps.py         ← Folium interactive maps
    └── plots.py        ← Plotly compliance dashboards

---

💻 CLI Usage

# Analyse a basin by coordinates
hsae analyze --lat 11.21 --lon 35.09 --name "Blue Nile"

# Full report for all 26 basins
hsae report --all --format json

# Compare two basins
hsae compare "Blue Nile" "Mekong"

# Check UNWC compliance
hsae compliance --basin "Euphrates" --article 7

---

📊 Comparison with Alternatives

Feature	HSAE	SWAT+	VIC	MRC Models
UNWC compliance (all articles)	✅	❌	❌	Partial
All 6 AWSI indices	✅	❌	❌	❌
Multi-model uncertainty bounds	✅ (eWaterCycle)	❌	❌	❌
Live satellite (9 sensors)	✅	❌	❌	Partial
SHA-256 forensic audit chain	✅	❌	❌	❌
GeoAgent NL queries	✅	❌	❌	❌
QGIS Plugin	✅ (ID 5040)	❌	❌	❌
pip installable	✅	❌	❌	❌
Open-source (GPL-3.0)	✅	Partial	✅	❌
26-basin global coverage	✅	Manual	Manual	6 countries

---

🔗 Links

Resource	URL
🔌 QGIS Plugin (ID 5040)	plugins.qgis.org/plugins/hsae_qgis/
🌐 Live Streamlit App	HSAE v6.0.8
📦 GitHub (Main Repo)	HydroSovereign-AI-Engine-HSAE-v601
🤖 GeoAgent Integration	opengeos/GeoAgent PR #79
🏛️ Zenodo Archive	doi.org/10.5281/zenodo.19180160
📄 Preprint (SSRN)	papers.ssrn.com/abstract=6661396
📰 SoftwareX Paper	SOFTX-D-26-00442 — Under Review
📖 Manual (v6)	Download Guide

---

📝 Citation

@software{alkhedir2026hsae,
  author    = {Alkhedir, Seifeldin M.G.},
  title     = {{HydroSovereign AI Engine (HSAE) v6.5.6}},
  year      = {2026},
  publisher = {PyPI + QGIS Plugin Repository + Zenodo},
  version   = {6.5.6},
  note      = {QGIS Plugin ID: 5040. SoftwareX under review: SOFTX-D-26-00442.
               Preprint: SSRN 6661396. 362+ downloads, 20 countries.},
  url       = {https://pypi.org/project/hydrosovereign/},
  doi       = {10.5281/zenodo.19180160},
  orcid     = {0000-0003-0821-2991}
}

---

hydrosovereign v6.5.6 · GPL-3.0 · Seifeldin M.G. Alkhedir · ORCID: 0000-0003-0821-2991

University of Khartoum · DOI: 10.5281/zenodo.19180160