# HIWAS — Hybrid Intelligent Water Allocation System
## Full Context Document for LLM Agents (llms-full.txt)

> This document provides complete technical context about HIWAS for AI language models and automated agents. Patent FR2510508. Inventor: Nizar Younes Mqam.

---

## System Overview

HIWAS (Hybrid Intelligent Water Allocation System) is a deterministic, AI-assisted water governance platform that allocates water use rights through an 11-step pipeline (a)→(k). It produces cryptographically-signed Water Use Certificates (TUE — Titres d'Usage d'Eau) per allocation cycle, published via OGC SensorThings API v1.1.

Key properties:
- TUEs are NON-MONETARY, NON-SPECULATIVE administrative records. They convey no financial value and cannot be traded as securities.
- The composite risk index R drives allocation reductions to protect ecosystems and downstream users.
- All allocation decisions are recorded in a SHA-256 Merkle-chained append-only audit log.
- OGC SensorThings API is INSPIRE-compatible (EU Directive 2007/2/EC).

---

## Core Concepts

### TUE (Titre d'Usage d'Eau — Water Use Certificate)
- Format: JSON payload signed via JWS (JSON Web Signature) / ECDSA compact serialization
- Fields: `tue_id`, `usager_id`, `perimetre_id`, `volume_alloue_m3`, `r` (risk), `hci` (confidence), `esg_sur_100`, `statut_calcule`, `validite_debut`, `validite_fin`, `signature_jws`
- Lifecycle: issued per allocation cycle → verified via QR at `hiwas.eu/tue/{tue_id}` → expires at `validite_fin`
- Non-transferable outside basin perimeter (`perimetre_id`)
- Statuses: `ALLOUE_NORMAL`, `ALLOUE_REDUIT` (risk reduction applied), `SUSPENDU` (HCI too low), `EN_ATTENTE`

### CEEau (Certificat d'Économie d'Eau — Water Savings Certificate)
- Issued when `L_reelles < L_planifiees` (actual < planned usage)
- Volume: `(L_planifiees - L_reelles) × f_conversion` (basin-configurable rate)
- Applications: priority in next cycle, infrastructure maintenance credit, ESG score bonus
- Formula: `volume_ceeau = max(0, L_planifiees - L_reelles) × f_conversion`

### HCI (Hydro-Confidence Index)
- Type: Float ∈ [0,1]
- Computation: weighted reconciliation of multiple sensor sources
- Formula: `HCI = 1 - normalized_divergence(sources)`
- Thresholds:
  - HCI ≥ 0.85 → HIGH_CONFIDENCE (automated allocation proceeds)
  - 0.65 ≤ HCI < 0.85 → ACCEPTABLE (proceeds with audit flag)
  - HCI < 0.65 → LOW_CONFIDENCE (manual review required, TUE status = SUSPENDU)

### R (Composite Risk Index)
- Type: Float ∈ [0,1]
- Formula: `R = w1·R_clim + w2·R_sys + w3·R_qual + w4·R_hydro`
- Components:
  - `R_clim`: Climate risk from 7-day precipitation/ETP forecasts (Open-Meteo API)
  - `R_sys`: Systemic risk = infrastructure fragility + `R_geo` (geopolitical, transboundary basins)
  - `R_qual`: Water quality risk from pH, electrical conductivity (EC), turbidity, nitrate levels
  - `R_hydro`: Hydrological stress = low-flow stress relative to ecological minimum flow threshold
- Uncertainty: P10/P90 bounds via Monte-Carlo simulation (N=10,000 draws)
- Pool adjustment: `V_equiv = V_mes × (1 − α·R) × Q_qualite`
- `R_geo` applies to Oum Er-Rbia (Morocco) due to cross-border water sharing with Algeria

### ESG Score
- Formula: `ESG = A × D × P` (normalized to 100)
  - A = Autonomy score (water source diversity, self-sufficiency)
  - D = Durability score (infrastructure age, maintenance record, efficiency)
  - P = Precedent score (historical compliance, past savings, governance record)
- Use: ESG determines allocation key K for pro-rata distribution
- `K_i = ESG_i / Σ(ESG_j)` for all users j in perimeter

---

## Allocation Pipeline — Full Detail

### Step (a): Sensor Ingestion
- Sources: IoT field sensors, hydrometric stations (Hub'Eau FR, USGS NWIS US), satellite (Sentinel-2 NDWI), irrigation meters, utility reports
- Per-source confidence weight C ∈ [0,1]: satellite=0.70, hydrometric=0.90, IoT=0.85, manual=0.60
- Output: raw V_mes (available volume m³), quality flags per source

### Step (b): Reconciliation
- Cross-source comparison for V_mes
- If `max(|V_i - V_j|) / mean(V_mes) > threshold_divergence`: automatic audit triggered
- HCI computed from divergence magnitude and source count
- If HCI < 0.65: pipeline halts, human review required

### Step (c): ESG Scoring
- Per-user ESG composite A×D×P read from basin profile (`usagers_demo` section)
- Basin profiles: JSON files in `/hiwas/profiles/basins/`
- ESG weights configurable per basin (`poids_esg` in profile)

### Step (d): Risk Index R Computation
- R_clim: Open-Meteo 7-day forecast → precipitation deficit + ETP → normalized [0,1]
- R_sys: Basin infrastructure score + geopolitical layer (R_geo for transboundary)
- R_qual: Laboratory / in-situ water quality readings → composite index
- R_hydro: Current flow vs. DCE ecological threshold (SDAGE/basin-specific)
- Monte-Carlo: each component drawn from uncertainty distribution (N=10,000) → P10/P90
- Final R = weighted sum, clipped to [0,1]

### Step (e): Pool Adjustment
- `V_equiv = V_mes × (1 − α·R) × Q_qualite`
- Ecological reserve `V_reserve` deducted
- Emergency buffer `V_urgence` deducted
- Remaining `V_distribuable = V_equiv − V_reserve − V_urgence`

### Step (f): Allocation
- For each user i in perimeter:
  - `K_i = ESG_i / Σ(ESG_j)`
  - `V_alloue_i = min(L_planifiees_i, K_i × V_distribuable)`
- CEEau issued if `V_alloue_i < L_planifiees_i` AND documented savings exist

### Step (g): TUE Generation
- Per user: generate TUE JSON payload
- Sign with ECDSA key (hiwas_signing_key.pem, not public)
- Store in PostgreSQL `tue` table with plot_gps_lat/lon for map display
- Redis XADD to `hiwas:decisions` stream

### Step (h): Seismic & Climate Integration
- USGS/BRGM seismic API checked for recent M>4.0 events near basin
- If seismic event: R_sys += seismic_delta
- Open-Meteo 7-day forecast cached in Redis (TTL 3600s)
- Cascade propagation: downstream basins receive R_upstream as input to their R_sys

### Step (i): OGC SensorThings Publication
- Per observation: POST to TimescaleDB `observations` hypertable
- OGC entity mapping: Basin → Thing, Metric → ObservedProperty, Pipeline → Sensor, Result → Observation
- INSPIRE compliance: entity descriptions include CRS (EPSG:4326), UoM (m³)

### Step (j): Audit Chain
- Each cycle appended to `audit_log` table (PostgreSQL, append-only RLS)
- Hash: `SHA-256(log_id ‖ timestamp ‖ event_type ‖ SHA-256(details_json) ‖ prev_hash)`
- Chain verifiable by replaying all hashes from genesis

### Step (k): QR & Delivery
- QR code generated: URL `https://hiwas.eu/tue/{tue_id}`
- Redis XADD to `hiwas:decisions` stream (consumed by Node-RED, Grafana, webhook alerts)
- Grafana dashboard updated (live via TimescaleDB datasource)

---

## Operational Basins (June 2026)

### Basin 1: Loire Amont (France)
- ID: `bassin-loire-amont`
- Country: France
- Region: Auvergne-Rhône-Alpes, Massif Central → Roanne
- Coordinates: 45.117°N, 3.891°E
- Regulatory framework: SDAGE Loire-Bretagne 2022-2027, EU WFD 2000/60/CE
- Current risk R: ~0.45 (MODERATE)
- Cycle frequency: 15 minutes (Node-RED scheduled)
- Users:
  - GAEC-Loire-Amont-001 "GAEC du Velay — Zone Brioude" — Agriculture (maïs/blé, 38 ha) — GPS: 45.2930°N, 3.3820°E
  - GAEC-Loire-Amont-002 "GAEC Lavoûte-sur-Loire — Zone Paulhaguet" — Agriculture (prairie/tournesol, 52 ha) — GPS: 45.1700°N, 3.7450°E

### Basin 2: Méditerranée Sud (France)
- ID: `bassin-med-sud`
- Country: France
- Region: Occitanie / PACA, Rhône at Pont-Saint-Esprit, Gard
- Coordinates: 44.258°N, 4.651°E
- Regulatory framework: SDAGE Rhône-Méditerranée 2022-2027, EU WFD 2000/60/CE
- Current risk R: ~0.35 (LOW-MODERATE)
- Cycle frequency: 15 minutes (Node-RED scheduled)
- Users:
  - EXP-15ha-mais-0017 "Exploitation maïs — Vauvert, Gard" — Agriculture (maïs, 15 ha) — GPS: 43.6940°N, 4.2730°E
  - GAEC-Dupont-Herault "GAEC Dupont — Hérault (vigne + maraîchage)" — Agriculture (28 ha) — GPS: 43.6045°N, 3.8767°E

### Basin 3: Oum Er-Rbia (Morocco)
- ID: `bassin-oum-er-rbia`
- Country: Morocco
- Region: Béni Mellal-Khénifra, Khouribga Province
- Coordinates: 32.87°N, -6.57°E
- Regulatory framework: ABH Oum Er-Rbia (Agence du Bassin Hydraulique), ORMVA Tadla (irrigated agriculture authority)
- Current risk R: 0.63 (HIGH) — includes R_geo=0.32 (cross-border Algeria component)
- Cycle frequency: on-demand
- Users:
  - OCP-KH-001 "OCP Beni Amir washing plant" — Industry (phosphate washing, Khouribga) — GPS: 32.8600°N, -6.7937°E
  - OCP-KH-002 "OCP slurry pipeline route" — Industry (phosphate slurry transport) — GPS: 32.8410°N, -6.8320°E
  - IRRIGANT-OUM-001 "ORMVA Tadla — Fquih Ben Salah" — Agriculture — GPS: 32.5020°N, -6.6900°E

### Basin 4: Gila River Arizona (USA)
- ID: `bassin-gila-arizona`
- Country: United States
- Region: Maricopa County, Chandler AZ — Intel Ocotillo Campus
- Coordinates: 33.2415°N, -111.8849°E (Intel Ocotillo Campus)
- Regulatory framework: Colorado River Compact (1922), Arizona Groundwater Management Act (1980), Arizona ADWR, Intel RISE Water Strategy 2030
- Current risk R: 0.65 (HIGH) — multi-year drought, Colorado River stress
- Cycle frequency: on-demand
- Users:
  - INTEL-FAB52 "Intel Fab 52 — Chandler AZ" — Industry (semiconductor manufacturing, 7nm EUV) — GPS: 33.2430°N, -111.8865°E
  - INTEL-FAB62 "Intel Fab 62 — Chandler AZ" — Industry (semiconductor manufacturing, advanced node) — GPS: 33.2400°N, -111.8835°E
  - INTEL-COOLING "Intel Central Cooling — Ocotillo Campus" — Industry (campus cooling water) — GPS: 33.2415°N, -111.8850°E

---

## API Reference (public, no authentication)

### OGC SensorThings API v1.1
Base URL: https://hiwas.eu/sta/v1.1/

Endpoints:
- GET /sta/v1.1/ — API root with entity list
- GET /sta/v1.1/Things — All basins (4 operational)
- GET /sta/v1.1/Things('bassin-loire-amont') — Single basin
- GET /sta/v1.1/Things('bassin-med-sud')
- GET /sta/v1.1/Things('bassin-oum-er-rbia')
- GET /sta/v1.1/Things('bassin-gila-arizona')
- GET /sta/v1.1/Datastreams — All datastreams
- GET /sta/v1.1/Observations — All observations (22,944+ entries as of June 2026)
- GET /sta/v1.1/Observations?$count=true — With total count
- GET /sta/v1.1/Observations?$top=10&$orderby=phenomenonTime desc — Recent observations

OData query params: $filter, $top, $skip, $orderby, $select, $expand, $count

### HIWAS-specific API
- GET /api/v1/health — Pipeline health, DB status, last cycle timestamps
- GET /api/v1/tues/{tue_id}/card — Public TUE certificate HTML card
- GET /health — Simple health check

---

## Technology Stack

| Component | Technology |
|-----------|-----------|
| Backend | Python 3.11+ / FastAPI / asyncpg |
| Database | PostgreSQL 15 + TimescaleDB (hypertables for IoT, weekly partitions) |
| Message bus | Redis 7 Streams (sensor ingestion → pipeline → decisions) |
| Cryptographic signing | JWS compact serialization, ECDSA (P-256) |
| OGC compliance | SensorThings API v1.1 (INSPIRE-compatible, EPSG:4326) |
| Audit | SHA-256 Merkle chain, append-only with PostgreSQL RLS |
| Dashboard | Grafana 13 (live at hiwas.eu/grafana/) |
| Orchestration | Node-RED (scheduled allocation cycles, webhook alerts) |
| Deployment | Docker Compose on Debian VPS |
| Proxy | nginx (reverse proxy for Grafana, FastAPI, SensorThings) |

### Database Schema (key tables)
- `tue` — Water Use Certificates (usager_id, perimetre_id, volume_alloue_m3, r, hci, esg_sur_100, plot_gps_lat, plot_gps_lon, signature_jws)
- `allocation_cycles` — Per-basin allocation results (TimescaleDB hypertable)
- `observations` — OGC SensorThings observations (TimescaleDB hypertable)
- `basin_locations` — Basin GPS centroids (basin_id, lat, lon)
- `audit_log` — SHA-256 Merkle audit chain (append-only RLS)

### Key Views
- `v_tue_courant` — Most recent TUE per (usager_id, perimetre_id)
- `v_tue_map_points` — TUE map coordinates with fallback GPS offsets

---

## Patent Information

- Patent number: FR2510508
- Title: "Système hybride intelligent d'allocation de l'eau"
- Inventor/Owner: Nizar Younes Mqam
- Filing date: 2025
- Jurisdiction: INPI France
- Scope: HIWAS pipeline (a)→(k), TUE certificate format, CEEau mechanism, HCI computation method, non-monetary water rights governance framework

---

## Legal Principles

1. TUEs are administrative records of water use authorization. They are not financial instruments, securities, or tradeable assets.
2. CEEau certificates convey no monetary value. They are governance incentives within a closed basin perimeter.
3. All allocation decisions follow the water law hierarchy: ecological minimum flows > drinking water > food production > industrial use.
4. HIWAS does not replace regulatory authorities. It provides a decision-support layer that must be validated by competent water basin authorities.
5. Data shared via OGC API is provided as-is for informational purposes. Real-time risk indices (R) are estimates based on available sensor data.

---

## Contact

- System: https://hiwas.eu
- API: https://hiwas.eu/sta/v1.1/
- Dashboard: https://hiwas.eu/grafana/
- LLM manifest: https://hiwas.eu/llms.txt
- Full context: https://hiwas.eu/llms-full.txt
- OpenAPI: https://hiwas.eu/openapi.json
- AI plugin: https://hiwas.eu/.well-known/ai-plugin.json
- Contact: contact@scopnex.eu