# geoagent/tools/hsae.py

@geo_tool(category="hydrology",
          description="Run full HSAE compliance analysis on a transboundary river basin")
def analyze_basin_compliance(basin_name: str) -> dict:
    """Analyze UNWC 1997 compliance for a named basin (e.g. 'Blue Nile', 'Mekong').
    Returns all 6 indices + legal status + triggered UN articles."""
    ...

# ── Index 1: ATDI ─────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute Alkhedir Transparency Deficit Index (ATDI) — primary legal index")
def compute_atdi(basin_name: str) -> float:
    """ATDI = mean(TDI) × 100 [%]. Triggers Art.7 UNWC when ATDI ≥ 40%."""
    ...

# ── Index 2: AFSF ─────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute Alkhedir Forensic Signal Factor (AFSF) — peak legal trigger")
def compute_afsf(basin_name: str) -> float:
    """AFSF = max(rolling₃₀(TDI)) × 100 [%].
    Captures worst-case 30-day deficit window — used in ICJ dossier evidence."""
    ...

# ── Index 3: AHIFD ────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute Alkhedir Human-Induced Flow Deficit (AHIFD) — downstream harm")
def compute_ahifd(basin_name: str) -> float:
    """AHIFD = % of natural downstream flow withheld by upstream operations.
    Blue Nile (GERD) = 20.0% — exceeds Art.5 equitable utilization threshold."""
    ...

# ── Index 4: ATCI ─────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute Alkhedir Treaty Compliance Index (ATCI) — institutional score")
def compute_atci(basin_name: str) -> float:
    """ATCI = GBM-derived composite score [0–100] combining treaty ratification,
    data-sharing behavior, and institutional cooperation indicators.
    Blue Nile (GERD) = 70% — partial compliance with UNWC obligations."""
    ...

# ── Index 5: CI ───────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute HSAE Composite Conflict Index (CI) — multi-factor risk score")
def compute_conflict_index(basin_name: str) -> dict:
    """CI = 0.40·TDI_score + 0.20·N_states + 0.25·dispute_level + 0.15·UN_articles.
    Returns score [0–100], level (MINIMAL/LOW/MEDIUM/HIGH/CRITICAL),
    triggered UN articles, and relevant ICJ/TFDD precedents.
    Blue Nile (GERD): CI = 44 → HIGH."""
    ...

# ── Index 6: ADTS ─────────────────────────────────────────────────────────────
@geo_tool(category="hydrology",
          description="Compute Alkhedir Digital Transparency Score (ADTS) — positive compliance metric")
def compute_adts(basin_name: str) -> float:
    """ADTS = 100 − ATDI [%]. Measures data-sharing achievement under Art.9 UNWC.
    Complementary framing to ATDI — useful for reporting cooperative basins."""
    ...

# ── Composite tool 1: UNWC compliance screen ─────────────────────────────────
@geo_tool(category="hydrology",
          description="Run UNWC 1997 compliance screen for all 10 key obligations")
def run_unwc_compliance(basin_name: str) -> dict:
    ...

# ── Composite tool 2: AI negotiation recommendation ──────────────────────────
@geo_tool(category="hydrology",
          description="Get AI-based negotiation pathway recommendation (Art.17 vs Art.33)",
          confirmation_required=True)
def get_negotiation_recommendation(basin_name: str) -> dict:
    """Returns P(Negotiation) [%], recommended pathway (Art.17 vs Art.33),
    and precedent cases from 478 TFDD/ICJ training cases.
    Blue Nile (GERD): P(Negotiation) = 58%."""
    ...