Metadata-Version: 2.4
Name: hydrosovereign
Version: 6.5.6
Summary: HydroSovereign AI Engine (HSAE) — Automated satellite-driven transboundary water law compliance for 26 globally contested river basins
Author-email: "Seifeldin M.G. Alkhedir" <saifeldinkhedir@gmail.com>
Maintainer-email: "Seifeldin M.G. Alkhedir" <saifeldinkhedir@gmail.com>
License: GPL-3.0
Project-URL: Homepage, https://github.com/saifeldinkhedir-coder/hydrosovereign
Project-URL: Repository, https://github.com/saifeldinkhedir-coder/HydroSovereign-AI-Engine-HSAE-v601
Project-URL: PyPI, https://pypi.org/project/hydrosovereign/
Project-URL: Documentation, https://github.com/saifeldinkhedir-coder/HydroSovereign-AI-Engine-HSAE-v601/raw/main/hsae_qgis/HSAE_v601_QGIS_Plugin_Manual_v6.docx
Project-URL: QGIS Plugin, https://plugins.qgis.org/plugins/hsae_qgis/
Project-URL: Preprint, https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6661396
Project-URL: DOI, https://doi.org/10.5281/zenodo.19180160
Project-URL: Bug Tracker, https://github.com/saifeldinkhedir-coder/HydroSovereign-AI-Engine-HSAE-v601/issues
Project-URL: Changelog, https://github.com/saifeldinkhedir-coder/hydrosovereign/blob/main/CHANGELOG.md
Keywords: hydrology,water-law,transboundary,UNWC,satellite,remote-sensing,GEE,Google-Earth-Engine,HBV96,SCE-UA,ATDI,AHIFD,AFSF,AHLB,ASI,ATCI,AWSI,eWaterCycle,BMI,GeoAgent,water-sovereignty,water-diplomacy,GERD,Blue-Nile,Mekong,Euphrates,QGIS,water-resources,rainfall-runoff,NSE,KGE,ICJ,PCA,water-conflict,river-basin,dam
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: requests>=2.31
Provides-Extra: gee
Requires-Dist: earthengine-api>=0.1.400; extra == "gee"
Provides-Extra: viz
Requires-Dist: plotly>=5.18; extra == "viz"
Requires-Dist: folium>=0.16; extra == "viz"
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.27; extra == "server"
Provides-Extra: alerts
Requires-Dist: python-telegram-bot>=20.0; extra == "alerts"
Provides-Extra: jupyter
Requires-Dist: jupyter>=1.0; extra == "jupyter"
Requires-Dist: ipykernel>=6.0; extra == "jupyter"
Requires-Dist: ipywidgets>=8.0; extra == "jupyter"
Provides-Extra: full
Requires-Dist: hydrosovereign[alerts,gee,jupyter,server,viz]; extra == "full"
Dynamic: license-file

# HydroSovereign AI Engine (HSAE)

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/hydrosovereign?style=for-the-badge&color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/hydrosovereign/)
[![PyPI downloads](https://img.shields.io/pypi/dm/hydrosovereign?style=for-the-badge&color=3775A9)](https://pypi.org/project/hydrosovereign/)
[![Python](https://img.shields.io/pypi/pyversions/hydrosovereign?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/hydrosovereign/)
[![CI](https://img.shields.io/github/actions/workflow/status/saifeldinkhedir-coder/hydrosovereign/ci_publish.yml?style=for-the-badge&label=CI&logo=githubactions&logoColor=white)](https://github.com/saifeldinkhedir-coder/hydrosovereign/actions)
[![QGIS Plugin](https://img.shields.io/badge/QGIS_Plugin-ID_5040-589632?style=for-the-badge&logo=qgis&logoColor=white)](https://plugins.qgis.org/plugins/hsae_qgis/)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19180160-1682D4?style=for-the-badge&logo=zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.19180160)
[![Preprint](https://img.shields.io/badge/Preprint-SSRN_6661396-B31B1B?style=for-the-badge)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6661396)
[![SoftwareX](https://img.shields.io/badge/SoftwareX-Under_Review-005A8E?style=for-the-badge)](https://www.sciencedirect.com/journal/softwarex)
[![License](https://img.shields.io/github/license/saifeldinkhedir-coder/hydrosovereign?style=for-the-badge)](LICENSE)
[![ORCID](https://img.shields.io/badge/ORCID-0000--0003--0821--2991-a6ce39?style=for-the-badge&logo=orcid&logoColor=white)](https://orcid.org/0000-0003-0821-2991)

**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

</div>

---

## 📋 Table of Contents

- [What is HSAE?](#-what-is-hsae)
- [Six Original Scientific Indices (AWSI)](#-six-original-scientific-indices-awsi)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [26-Basin Coverage](#-26-basin-coverage)
- [Key Results](#-key-results)
- [Architecture](#-architecture)
- [CLI Usage](#-cli-usage)
- [Comparison with Alternatives](#-comparison-with-alternatives)
- [Citation](#-citation)
- [Links](#-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

```bash
# 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

```python
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

```bash
# 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/](https://plugins.qgis.org/plugins/hsae_qgis/) |
| 🌐 Live Streamlit App | [HSAE v6.0.8](https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app) |
| 📦 GitHub (Main Repo) | [HydroSovereign-AI-Engine-HSAE-v601](https://github.com/saifeldinkhedir-coder/HydroSovereign-AI-Engine-HSAE-v601) |
| 🤖 GeoAgent Integration | [opengeos/GeoAgent PR #79](https://github.com/opengeos/GeoAgent/pull/79) |
| 🏛️ Zenodo Archive | [doi.org/10.5281/zenodo.19180160](https://doi.org/10.5281/zenodo.19180160) |
| 📄 Preprint (SSRN) | [papers.ssrn.com/abstract=6661396](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6661396) |
| 📰 SoftwareX Paper | [SOFTX-D-26-00442](https://www.sciencedirect.com/journal/softwarex) — Under Review |
| 📖 Manual (v6) | [Download Guide](https://github.com/saifeldinkhedir-coder/HydroSovereign-AI-Engine-HSAE-v601/raw/main/hsae_qgis/HSAE_v601_QGIS_Plugin_Manual_v6.docx) |

---

## 📝 Citation

```bibtex
@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}
}
```

---

<div align="center">

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

*University of Khartoum · DOI: 10.5281/zenodo.19180160*

</div>
