hydrosovereign 6.5.0__tar.gz

hydrosovereign-6.5.0/LICENSE

@@ -0,0 +1,19 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2026 Seifeldin M.G. Alkedir
+ORCID: 0000-0003-0821-2991
+University of Khartoum
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

hydrosovereign-6.5.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: hydrosovereign
+Version: 6.5.0
+Summary: HydroSovereign AI Engine — Python package for hydrological analysis, satellite data, and water sovereignty assessment
+Author-email: "Seifeldin M.G. Alkedir" <saifeldinkhedir@gmail.com>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/saifeldinkhedir-coder/hydrosovereign
+Project-URL: DOI, https://doi.org/10.5281/zenodo.19180160
+Keywords: hydrology,GEE,satellite,water,HSAE,reservoir
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+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
+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: 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: all
+Requires-Dist: hydrosovereign[alerts,gee,server,viz]; extra == "all"
+Dynamic: license-file
+
+# HydroSovereign AI Engine (HSAE)
+
+[![PyPI version](https://badge.fury.io/py/hydrosovereign.svg)](https://pypi.org/project/hydrosovereign/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19180160.svg)](https://doi.org/10.5281/zenodo.19180160)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Author:** Seifeldin M.G. Alkedir · ORCID: [0000-0003-0821-2991](https://orcid.org/0000-0003-0821-2991)  
+**Affiliation:** University of Khartoum  
+**DOI:** [10.5281/zenodo.19180160](https://doi.org/10.5281/zenodo.19180160)
+
+---
+
+## Overview
+
+HydroSovereign AI Engine (HSAE) v6.5.0 is a Python package for:
+
+- **Hydrological basin analysis** — water balance, inflow, outflow, storage
+- **Real satellite data ingestion** — GPM IMERG, GRACE-FO, Sentinel-1/2, SMAP, GloFAS, ERA5
+- **Water sovereignty assessment** — Alkedir Transparency Deficit Index (ATDI)
+- **Forensic hydrology** — closure error, mass balance analysis
+- **HBV rainfall-runoff modelling** — calibration and simulation
+- **AI ensemble forecasting** — Random Forest, ensemble methods
+
+## Installation
+
+```bash
+pip install hydrosovereign
+```
+
+With optional dependencies:
+```bash
+pip install hydrosovereign[gee]      # Google Earth Engine support
+pip install hydrosovereign[viz]      # Plotly + Folium visualizations
+pip install hydrosovereign[all]      # All dependencies
+```
+
+## Quick Start
+
+```python
+import hydrosovereign as hsae
+
+# Analyze a basin
+result = hsae.analyze_basin(
+    basin_id   = "GERD_ETH",
+    start_date = "2024-01-01",
+    end_date   = "2024-12-31",
+)
+
+print(result["nse"])      # Nash-Sutcliffe Efficiency
+print(result["atdi"])     # Alkedir Transparency Deficit Index
+print(result["volume"])   # Reservoir volume (BCM)
+```
+
+```python
+# Fetch real satellite data
+from hydrosovereign.data import fetch_basin_forcing
+
+forcing = fetch_basin_forcing("GERD_ETH", "2024-01-01", "2024-12-31")
+print(forcing["gpm"]["mean_P"])    # GPM precipitation mm/day
+print(forcing["grace"]["tws_cm"])  # GRACE-FO TWS anomaly
+```
+
+```python
+# HBV rainfall-runoff model
+from hydrosovereign.models import HBVModel
+
+model = HBVModel()
+model.fit(P=forcing["P"], T=forcing["T"], Q_obs=forcing["Q"])
+print(f"NSE = {model.nse:.3f}")
+```
+
+## CLI
+
+```bash
+hydrosovereign analyze --basin GERD_ETH --year 2024
+hydrosovereign fetch-gee --basin KAINJI_NGA --start 2023-01-01 --end 2023-12-31
+```
+
+## Live Application
+
+The full HSAE v6.01 Streamlit application:  
+🌐 [https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app](https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app)
+
+## Citation
+
+```bibtex
+@software{alkedir2026hsae,
+  author    = {Alkedir, Seifeldin M.G.},
+  title     = {HydroSovereign AI Engine (HSAE) v6.5.0},
+  year      = {2026},
+  doi       = {10.5281/zenodo.19180160},
+  url       = {https://github.com/saifeldinkhedir-coder/hydrosovereign},
+  orcid     = {0000-0003-0821-2991},
+}
+```
+
+## License
+
+GNU General Public License v3.0 — see [LICENSE](LICENSE)

hydrosovereign-6.5.0/README.md

@@ -0,0 +1,100 @@
+# HydroSovereign AI Engine (HSAE)
+
+[![PyPI version](https://badge.fury.io/py/hydrosovereign.svg)](https://pypi.org/project/hydrosovereign/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19180160.svg)](https://doi.org/10.5281/zenodo.19180160)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Author:** Seifeldin M.G. Alkedir · ORCID: [0000-0003-0821-2991](https://orcid.org/0000-0003-0821-2991)  
+**Affiliation:** University of Khartoum  
+**DOI:** [10.5281/zenodo.19180160](https://doi.org/10.5281/zenodo.19180160)
+
+---
+
+## Overview
+
+HydroSovereign AI Engine (HSAE) v6.5.0 is a Python package for:
+
+- **Hydrological basin analysis** — water balance, inflow, outflow, storage
+- **Real satellite data ingestion** — GPM IMERG, GRACE-FO, Sentinel-1/2, SMAP, GloFAS, ERA5
+- **Water sovereignty assessment** — Alkedir Transparency Deficit Index (ATDI)
+- **Forensic hydrology** — closure error, mass balance analysis
+- **HBV rainfall-runoff modelling** — calibration and simulation
+- **AI ensemble forecasting** — Random Forest, ensemble methods
+
+## Installation
+
+```bash
+pip install hydrosovereign
+```
+
+With optional dependencies:
+```bash
+pip install hydrosovereign[gee]      # Google Earth Engine support
+pip install hydrosovereign[viz]      # Plotly + Folium visualizations
+pip install hydrosovereign[all]      # All dependencies
+```
+
+## Quick Start
+
+```python
+import hydrosovereign as hsae
+
+# Analyze a basin
+result = hsae.analyze_basin(
+    basin_id   = "GERD_ETH",
+    start_date = "2024-01-01",
+    end_date   = "2024-12-31",
+)
+
+print(result["nse"])      # Nash-Sutcliffe Efficiency
+print(result["atdi"])     # Alkedir Transparency Deficit Index
+print(result["volume"])   # Reservoir volume (BCM)
+```
+
+```python
+# Fetch real satellite data
+from hydrosovereign.data import fetch_basin_forcing
+
+forcing = fetch_basin_forcing("GERD_ETH", "2024-01-01", "2024-12-31")
+print(forcing["gpm"]["mean_P"])    # GPM precipitation mm/day
+print(forcing["grace"]["tws_cm"])  # GRACE-FO TWS anomaly
+```
+
+```python
+# HBV rainfall-runoff model
+from hydrosovereign.models import HBVModel
+
+model = HBVModel()
+model.fit(P=forcing["P"], T=forcing["T"], Q_obs=forcing["Q"])
+print(f"NSE = {model.nse:.3f}")
+```
+
+## CLI
+
+```bash
+hydrosovereign analyze --basin GERD_ETH --year 2024
+hydrosovereign fetch-gee --basin KAINJI_NGA --start 2023-01-01 --end 2023-12-31
+```
+
+## Live Application
+
+The full HSAE v6.01 Streamlit application:  
+🌐 [https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app](https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app)
+
+## Citation
+
+```bibtex
+@software{alkedir2026hsae,
+  author    = {Alkedir, Seifeldin M.G.},
+  title     = {HydroSovereign AI Engine (HSAE) v6.5.0},
+  year      = {2026},
+  doi       = {10.5281/zenodo.19180160},
+  url       = {https://github.com/saifeldinkhedir-coder/hydrosovereign},
+  orcid     = {0000-0003-0821-2991},
+}
+```
+
+## License
+
+GNU General Public License v3.0 — see [LICENSE](LICENSE)

hydrosovereign-6.5.0/hydrosovereign/__init__.py

@@ -0,0 +1,41 @@
+"""
+HydroSovereign AI Engine (HSAE) v6.5.0
+========================================
+Author:  Seifeldin M.G. Alkedir · ORCID: 0000-0003-0821-2991
+DOI:     10.5281/zenodo.19180160
+"""
+
+__version__   = "6.5.0"
+__author__    = "Seifeldin M.G. Alkedir"
+__email__     = "saifeldinkhedir@gmail.com"
+__orcid__     = "0000-0003-0821-2991"
+__doi__       = "10.5281/zenodo.19180160"
+__license__   = "GPL-3.0"
+__app_url__   = "https://hydrosovereign-ai-engine-hsae-v601-6euz2zxcmerkzxgordmvxf.streamlit.app"
+
+# Core API — always available
+from .api import analyze_basin, analyze_all_basins
+
+# Models — always available (pure Python + numpy)
+from .models import HBVModel
+
+# Indices — always available
+from .indices import compute_atdi, compute_kge, compute_nse
+
+# Optional imports — only if dependencies installed
+try:
+    from .data import fetch_basin_forcing, fetch_openmeteo
+except ImportError:
+    pass
+
+try:
+    from .viz import plot_water_balance, plot_forcing
+except ImportError:
+    pass
+
+__all__ = [
+    "__version__", "__author__", "__orcid__", "__doi__",
+    "analyze_basin", "analyze_all_basins",
+    "HBVModel",
+    "compute_atdi", "compute_kge", "compute_nse",
+]

hydrosovereign-6.5.0/hydrosovereign/__main__.py

@@ -0,0 +1,6 @@
+"""
+hydrosovereign.__main__ — enables: python3 -m hydrosovereign
+"""
+from hydrosovereign.cli import main
+if __name__ == "__main__":
+    main()

hydrosovereign-6.5.0/hydrosovereign/alerts.py

@@ -0,0 +1,61 @@
+"""
+alerts.py — HSAE v6.01 Alert System
+=====================================
+4-level alert system for ATDI/HIFD thresholds.
+
+Author: Seifeldin M.G. Alkedir · ORCID: 0000-0003-0821-2991
+"""
+
+from __future__ import annotations
+from enum import Enum
+
+
+class AlertLevel(Enum):
+    INFO     = "INFO"
+    ALERT    = "ALERT"
+    WARNING  = "WARNING"
+    CRITICAL = "CRITICAL"
+
+
+def check_atdi_alert(atdi: float) -> AlertLevel:
+    """
+    Return alert level based on ATDI.
+
+    Thresholds:
+    - CRITICAL : ATDI >= 70%
+    - WARNING  : ATDI >= 55%
+    - ALERT    : ATDI >= 40%
+    - INFO     : ATDI < 40%
+    """
+    if atdi >= 70: return AlertLevel.CRITICAL
+    if atdi >= 55: return AlertLevel.WARNING
+    if atdi >= 40: return AlertLevel.ALERT
+    return AlertLevel.INFO
+
+
+def check_hifd_alert(hifd: float) -> AlertLevel:
+    """
+    Return alert level based on HIFD.
+
+    Thresholds:
+    - CRITICAL : HIFD >= 60%
+    - WARNING  : HIFD >= 40%
+    - ALERT    : HIFD >= 25%
+    - INFO     : HIFD < 25%
+    """
+    if hifd >= 60: return AlertLevel.CRITICAL
+    if hifd >= 40: return AlertLevel.WARNING
+    if hifd >= 25: return AlertLevel.ALERT
+    return AlertLevel.INFO
+
+
+def format_alert_message(basin_name: str, atdi: float,
+                          hifd: float, level: AlertLevel) -> str:
+    """Format alert message for Telegram or logging."""
+    emoji = {"CRITICAL":"🔴","WARNING":"🟠","ALERT":"🟡","INFO":"🟢"}[level.value]
+    return (
+        f"{emoji} HSAE Alert — {level.value}\n"
+        f"Basin: {basin_name}\n"
+        f"ATDI: {atdi:.1f}% | HIFD: {hifd:.1f}%\n"
+        f"UNWC Arts: {', '.join(['Art.5','Art.9'] + (['Art.7'] if atdi>=40 else []) + (['Art.20'] if hifd>=25 else []))}"
+    )

hydrosovereign-6.5.0/hydrosovereign/api.py

@@ -0,0 +1,170 @@
+"""
+api.py — HSAE v6.2.0 Unified High-Level API
+=============================================
+Single-call basin analysis as recommended by ChatGPT review:
+  "Add a clear entry point: analyze_basin(data)"
+
+Author: Seifeldin M.G. Alkedir · ORCID: 0000-0003-0821-2991
+"""
+from __future__ import annotations
+import logging
+from typing import Optional, Dict
+
+from .indices  import compute_all_indices
+from .legal    import get_legal_assessment
+from .alerts   import check_atdi_alert, check_hifd_alert, AlertLevel
+from .basins   import BasinRegistry, BASINS_26
+
+logger = logging.getLogger(__name__)
+
+
+def analyze_basin(
+    name: Optional[str] = None,
+    runoff_c: Optional[float] = None,
+    cap_bcm: Optional[float] = None,
+    n_countries: Optional[int] = None,
+    dispute_level: Optional[int] = None,
+    area_km2: Optional[float] = None,
+    wqi_measurements: Optional[Dict] = None,
+    include_negotiation: bool = True,
+    include_legal: bool = True,
+) -> dict:
+    """
+    Full basin analysis in one call — HSAE unified entry point.
+
+    Provide either basin name (auto-loads parameters) or all parameters manually.
+
+    Parameters
+    ----------
+    name : str, optional
+        Basin name from registry (e.g. "Blue Nile (GERD)"). Auto-fills parameters.
+    runoff_c : float, optional
+        Runoff coefficient 0–1. Required if name not given.
+    cap_bcm : float, optional
+        Dam storage capacity BCM.
+    n_countries : int, optional
+        Number of riparian states.
+    dispute_level : int, optional
+        TFDD/ICOW dispute level 0–4.
+    area_km2 : float, optional
+        Catchment area km². Used for conflict sensitivity.
+    wqi_measurements : dict, optional
+        Physicochemical measurements for WQI (ph, do, bod, turbidity...).
+    include_negotiation : bool
+        Include Negotiation AI prediction. Default = True.
+    include_legal : bool
+        Include UNWC legal assessment. Default = True.
+
+    Returns
+    -------
+    dict
+        Complete basin analysis:
+        - indices  : atdi, hifd, wqi, ci, nse, kge
+        - alerts   : atdi_alert, hifd_alert
+        - legal    : articles, recommendation, pathway
+        - ai       : negotiation result
+        - metadata : basin name, parameters used
+
+    Examples
+    --------
+    >>> # From registry
+    >>> result = analyze_basin("Blue Nile (GERD)")
+    >>> print(result["indices"]["atdi"])    # ~53.5
+    >>> print(result["ai"]["p_success"])    # ~0.37
+    >>> print(result["alerts"]["atdi_alert"])  # ALERT
+
+    >>> # Manual parameters
+    >>> result = analyze_basin(runoff_c=0.38, cap_bcm=74, n_countries=3, dispute_level=4)
+    """
+    # Load from registry if name given
+    if name is not None:
+        reg = BasinRegistry()
+        basin = reg.get(name)
+        runoff_c    = runoff_c    or float(basin.get("runoff_c", 0.3))
+        cap_bcm     = cap_bcm    or float(basin.get("cap", basin.get("cap_bcm", 10)))
+        n_countries = n_countries or (len(basin["country"]) if isinstance(basin.get("country"),list) else int(basin.get("n_countries",2)))
+        dispute_level = dispute_level if dispute_level is not None else int(basin.get("dispute_level",0))
+        area_km2    = area_km2    or float(basin.get("eff_cat_km2", basin.get("area_km2",100000)))
+    else:
+        if any(v is None for v in [runoff_c, cap_bcm, n_countries, dispute_level]):
+            raise ValueError("Provide basin name or all of: runoff_c, cap_bcm, n_countries, dispute_level")
+        area_km2 = area_km2 or 100000.0
+
+    # Core indices
+    indices = compute_all_indices(runoff_c, cap_bcm, n_countries, dispute_level,
+                                   wqi_measurements=wqi_measurements)
+
+    # Alerts
+    atdi_alert = check_atdi_alert(indices["atdi"])
+    hifd_alert = check_hifd_alert(indices["hifd"])
+
+    result = {
+        "indices": indices,
+        "alerts": {
+            "atdi_alert": atdi_alert.value,
+            "hifd_alert": hifd_alert.value,
+            "overall":    ("CRITICAL" if AlertLevel.CRITICAL in (atdi_alert,hifd_alert)
+                           else "WARNING" if AlertLevel.WARNING in (atdi_alert,hifd_alert)
+                           else "ALERT"   if AlertLevel.ALERT   in (atdi_alert,hifd_alert)
+                           else "INFO"),
+        },
+        "legal":    None,
+        "ai":       None,
+        "metadata": {
+            "name":          name or "custom",
+            "runoff_c":      runoff_c,
+            "cap_bcm":       cap_bcm,
+            "n_countries":   n_countries,
+            "dispute_level": dispute_level,
+            "area_km2":      area_km2,
+            "package_version": "6.2.0",
+        }
+    }
+
+    if include_legal:
+        result["legal"] = get_legal_assessment(
+            indices["atdi"], indices["hifd"], dispute_level, n_countries)
+
+    if include_negotiation:
+        from .ai.negotiation import NegotiationAI
+        ai  = NegotiationAI()
+        result["ai"] = ai.predict(indices["atdi"], indices["hifd"],
+                                   n_countries, dispute_level)
+
+    logger.info("analyze_basin(%s): ATDI=%.1f HIFD=%.1f CI=%.3f alert=%s",
+                name or "custom", indices["atdi"], indices["hifd"],
+                indices["ci"], result["alerts"]["overall"])
+    return result
+
+
+def analyze_all_basins(include_ai: bool = False) -> list:
+    """
+    Analyze all 26 registered transboundary basins.
+
+    Parameters
+    ----------
+    include_ai : bool
+        Include NegotiationAI for each basin (slower). Default = False.
+
+    Returns
+    -------
+    list of dict, sorted by conflict index descending.
+
+    Examples
+    --------
+    >>> results = analyze_all_basins()
+    >>> for r in results[:5]:
+    ...     print(r["metadata"]["name"], r["indices"]["atdi"])
+    """
+    results = []
+    for basin in BASINS_26:
+        try:
+            r = analyze_basin(
+                name               = basin["name"],
+                include_negotiation= include_ai,
+                include_legal      = True,
+            )
+            results.append(r)
+        except Exception as e:
+            logger.warning("analyze_basin failed for %s: %s", basin.get("name","?"), e)
+    return sorted(results, key=lambda x: x["indices"]["ci"], reverse=True)