hydrosovereign 6.7.1

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.6% ⚠️
AHIFD	Alkhedir Human-Induced Flow Deficit	Art. 7 — volumetric downstream harm	19.7%
AFSF	Alkhedir Forensic Signal Factor	Art. 9 — data exchange obligation	0.36
AHLB	Alkhedir HBV-Legal Bridge	Arts. 5,6,7 — HBV-96 → legal triggers	0.436
ASI	Alkhedir Sovereignty Index	Art. 5 — equitable utilisation	0.64
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 (ATDI = 43.6%, AHIFD = 19.7%, ATCI = 70.3) calibrated to NSE = 0.63, KGE = 0.74 against GloFAS ERA5 v4.

---

⚙️ 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.6%  ⚠️  Art. 7 UNWC triggered
ahifd = AHIFD(**params)    # → 19.7%       ~20% of natural flow withheld
afsf  = AFSF(**params)     # → 0.36        Art. 9 data exchange check
ahlb  = AHLB(**params)     # →             HBV-96 → legal bridge
asi   = ASI(**params)      # → 0.64        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}")         # → 0.484

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

# 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.6%	19.7%	70.3	0.484	HIGH	Art. 7
Euphrates-Atatürk	41.8%	19.3%	71.4	0.475	HIGH	Art. 7
Nile-High Aswan	40.8%	19.5%	71.8	0.399	HIGH	Art. 7
Syr Darya-Toktogul	40.6%	19.3%	72.0	0.471	HIGH	Art. 7
Mekong-Xayaburi	36.8%	18.3%	74.3	0.390	MODERATE	Art. 5
Danube-Iron Gates	32.8%	18.7%	76.1	0.250	MODERATE	Art. 5
Rhine	22.3%	10.9%	84.5	0.189	LOW	—

NSE = 0.63 · KGE = 0.74 (pre-calibration, GERD vs GloFAS ERA5 v4) · 51 pytest tests passing

Risk distribution across all 26 basins: HIGH = 4 (GERD, Euphrates-Atatürk, Nile-Aswan, Syr Darya-Toktogul) · MODERATE = 14 · LOW = 8. Legal tiers: CRITICAL ≥ 60% (Art. 33) · HIGH ≥ 40% (Art. 7) · MODERATE ≥ 25% (Art. 5) · LOW < 25%.

---

🏗 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.7.1}},
  year      = {2026},
  publisher = {PyPI + QGIS Plugin Repository + Zenodo},
  version   = {6.7.0},
  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.7.1 · GPL-3.0 · Seifeldin M.G. Alkhedir · ORCID: 0000-0003-0821-2991

University of Khartoum · DOI: 10.5281/zenodo.19180160