aihydro-data 0.2.0__tar.gz → 0.2.4__tar.gz

{aihydro_data-0.2.0 → aihydro_data-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aihydro-data
-Version: 0.2.0
+Version: 0.2.4
 Summary: Global hydrology dataverse — multi-source, region-aware data fetch (GEE + STAC + HyRiver) for AI agents and humans
 Author-email: Mohammad Galib <mgalib@purdue.edu>
 License-Expression: Apache-2.0
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aihydro-core<0.2,>=0.1.0
+Requires-Dist: aihydro-core<0.3,>=0.2.3
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pydantic>=2.0.0
@@ -43,12 +43,12 @@ Provides-Extra: hyriver
 Requires-Dist: pynhd>=0.16.0; extra == "hyriver"
 Requires-Dist: pygeohydro>=0.16.0; extra == "hyriver"
 Requires-Dist: pygridmet>=0.15.0; extra == "hyriver"
+Requires-Dist: pydaymet>=0.16.0; extra == "hyriver"
 Requires-Dist: py3dep>=0.15.0; extra == "hyriver"
-Requires-Dist: hydrofunctions>=0.2.0; extra == "hyriver"
 Requires-Dist: rioxarray>=0.15.0; extra == "hyriver"
 Requires-Dist: xarray>=2023.0.0; extra == "hyriver"
-Provides-Extra: direct
-Requires-Dist: hydrofunctions>=0.2.0; extra == "direct"
+Provides-Extra: legacy-usgs
+Requires-Dist: dataretrieval>=1.0; extra == "legacy-usgs"
 Provides-Extra: opendap
 Requires-Dist: xarray>=2023.0.0; extra == "opendap"
 Requires-Dist: netCDF4>=1.6.0; extra == "opendap"
@@ -64,6 +64,8 @@ Requires-Dist: s3fs>=2023.0.0; extra == "geoglows"
 Requires-Dist: zarr>=2.14.0; extra == "geoglows"
 Requires-Dist: pyproj>=3.4.0; extra == "geoglows"
 Requires-Dist: shapely>=2.0.0; extra == "geoglows"
+Provides-Extra: pygeoglim
+Requires-Dist: pygeoglim>=1.1.0; extra == "pygeoglim"
 Provides-Extra: cache
 Requires-Dist: diskcache>=5.6.0; extra == "cache"
 Provides-Extra: mcp
@@ -72,11 +74,15 @@ Provides-Extra: viz
 Requires-Dist: matplotlib>=3.7.0; extra == "viz"
 Requires-Dist: folium>=0.15.0; extra == "viz"
 Provides-Extra: all
-Requires-Dist: aihydro-data[cache,direct,gee,geoglows,glofas,hyriver,mcp,opendap,stac,viz]; extra == "all"
+Requires-Dist: aihydro-data[cache,gee,geoglows,glofas,hyriver,mcp,opendap,pygeoglim,stac,viz]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: xarray>=2023.0.0; extra == "dev"
+Requires-Dist: rasterio>=1.3.0; extra == "dev"
+Requires-Dist: pyarrow>=14.0.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: build>=1.0.0; extra == "dev"
@@ -109,6 +115,7 @@ result.next_steps        # agent-facing hints: what to do with this data
 [![PyPI](https://img.shields.io/pypi/v/aihydro-data)](https://pypi.org/project/aihydro-data/)
 [![Python](https://img.shields.io/pypi/pyversions/aihydro-data)](https://pypi.org/project/aihydro-data/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20823443.svg)](https://doi.org/10.5281/zenodo.20823443)
 
 ---
 
@@ -117,7 +124,7 @@ result.next_steps        # agent-facing hints: what to do with this data
 - [Why](#why)
 - [Install](#install)
 - [Quick Start](#quick-start)
-- [Products (32 total)](#products)
+- [Products (49 total)](#products)
 - [Routing System](#routing-system)
 - [Auth Setup](#auth-setup)
 - [MCP Tools](#mcp-tools)
@@ -142,7 +149,7 @@ Before `aihydro-data`, fetching hydrology data meant hard-coding a single CONUS-
 | Land cover | NLCD | ESA WorldCover | Dynamic World |
 | Soil properties | POLARIS | SoilGrids | — |
 | DEM | 3DEP (10 m) | Copernicus GLO-30 | SRTM, MERIT-DEM |
-| Streamflow | USGS NWIS | — | — |
+| Streamflow | USGS Water Data API (NWIS) | GEOGLOWS, Open-Meteo, GloFAS | GEOGLOWS, Open-Meteo |
 | NDVI | MODIS (250 m) | MODIS (250 m) | Sentinel-2 (10 m) |
 | LAI | MODIS | MODIS | — |
 
@@ -157,13 +164,13 @@ Before `aihydro-data`, fetching hydrology data meant hard-coding a single CONUS-
 pip install aihydro-data[all]
 
 # Per-backend
-pip install aihydro-data[gee]        # Google Earth Engine (20 products)
+pip install aihydro-data[gee]        # Google Earth Engine (23 products)
 pip install aihydro-data[hyriver]    # CONUS via HyRiver (10 products)
 pip install aihydro-data[stac]       # STAC catalogues (Planetary Computer)
 pip install aihydro-data[opendap]    # IRI OPeNDAP (CHIRPS auth-free fallback)
 ```
 
-> **Python**: 3.10+ &nbsp;|&nbsp; **GEE auth**: required for 20 GEE products (see [Auth Setup](#auth-setup))
+> **Python**: 3.10+ &nbsp;|&nbsp; **GEE auth**: required for 23 GEE products (see [Auth Setup](#auth-setup))
 
 ---
 
@@ -275,86 +282,159 @@ check = data_validate_request(
 
 ## Products
 
-32 products across 13 variables, live-tested against real backends (v0.2.0).
+57 products across 19 variables (v0.2.0).
 
 ### Precipitation (6 products)
 
 | ID | Source | Coverage | Resolution | Timestep | Notes |
 |---|---|---|---|---|---|
-| `CHIRPS` | GEE | Global | 5 km | Daily | Primary global; GEE auth required |
-| `IMERG_PRECIP` | GEE | Global | 11 km | Daily | NASA GPM V07; GEE auth required |
-| `ERA5L_PRECIP` | GEE | Global | 11 km | Daily | Reanalysis; 1950–present |
-| `GRIDMET_PRECIP` | HyRiver | CONUS | 4 km | Daily | Primary CONUS; no auth |
-| `DAYMET_PRECIP` | HyRiver | N. America | 1 km | Daily | High-res; no auth |
-| `CHIRPS_IRI` | Direct API | Global | 5 km | Daily | **Auth-free fallback** via IRI OPeNDAP |
-
-### Temperature (7 products)
-
-| ID | Source | Coverage | Resolution | Timestep |
-|---|---|---|---|---|
-| `ERA5L_TMAX` | GEE | Global | 11 km | Daily |
-| `ERA5L_TMIN` | GEE | Global | 11 km | Daily |
-| `ERA5L_TMEAN` | GEE | Global | 11 km | Daily |
-| `GRIDMET_TMAX` | HyRiver | CONUS | 4 km | Daily |
-| `GRIDMET_TMIN` | HyRiver | CONUS | 4 km | Daily |
-| `DAYMET_TMAX` | HyRiver | N. America | 1 km | Daily |
-| `DAYMET_TMIN` | HyRiver | N. America | 1 km | Daily |
-
-### Evapotranspiration (5 products)
-
-| ID | Variable | Source | Coverage | Resolution | Timestep |
+| `CHIRPS` | gee | global | 5 km | daily | GEE auth required |
+| `IMERG_PRECIP` | gee | global | 11 km | daily | GEE auth required |
+| `ERA5L_PRECIP` | gee | global | 11 km | daily | GEE auth required |
+| `GRIDMET_PRECIP` | hyriver | CONUS | 4 km | daily | auth-free |
+| `DAYMET_PRECIP` | hyriver | NORTH_AMERICA | 1 km | daily | auth-free |
+| `CHIRPS_IRI` | direct_api | global | 5 km | daily | auth-free |
+
+### Temperature — Tmax (4 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `GRIDMET_TMAX` | hyriver | CONUS | 4 km | daily | auth-free |
+| `DAYMET_TMAX` | hyriver | NORTH_AMERICA | 1 km | daily | auth-free |
+| `ERA5L_TMAX` | gee | global | 11 km | daily | GEE auth required |
+| `OPEN_METEO_TMAX` | direct_api | global | 25 km | daily | auth-free; spatial support: point |
+
+### Temperature — Tmin (4 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `GRIDMET_TMIN` | hyriver | CONUS | 4 km | daily | auth-free |
+| `DAYMET_TMIN` | hyriver | NORTH_AMERICA | 1 km | daily | auth-free |
+| `ERA5L_TMIN` | gee | global | 11 km | daily | GEE auth required |
+| `OPEN_METEO_TMIN` | direct_api | global | 25 km | daily | auth-free; spatial support: point |
+
+### Temperature — Tmean (1 product)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
 |---|---|---|---|---|---|
-| `MOD16_ET` | ET (actual) | GEE | Global | 500 m | 8-day → monthly |
-| `TERRACLIMATE_AET` | ET (actual) | GEE | Global | 4.6 km | Monthly |
-| `MOD16_PET` | PET | GEE | Global | 500 m | 8-day → monthly |
-| `ERA5L_PET` | PET | GEE | Global | 11 km | Daily |
-| `GRIDMET_PET` | PET | HyRiver | CONUS | 4 km | Daily |
+| `ERA5L_TMEAN` | gee | global | 11 km | daily | GEE auth required |
 
-### DEM (4 products)
+### Potential Evapotranspiration (PET) (4 products)
 
-| ID | Source | Coverage | Resolution | Notes |
-|---|---|---|---|---|
-| `GLO30` | GEE | Global | 30 m | Copernicus; primary global DEM |
-| `SRTM` | GEE | 60°S–60°N | 30 m | NASA SRTM v3 |
-| `MERIT_DEM` | GEE | Global | 90 m | Hydrologically conditioned |
-| `DEM3DEP_10M` | HyRiver | CONUS | 10 m | USGS 3DEP; highest resolution |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `MOD16_PET` | gee | global | 500 m | monthly | GEE auth required |
+| `ERA5L_PET` | gee | global | 11 km | daily | GEE auth required |
+| `GRIDMET_PET` | hyriver | CONUS | 4 km | daily | auth-free |
+| `OPEN_METEO_PET` | direct_api | global | 25 km | daily | auth-free; spatial support: point |
+
+### Actual Evapotranspiration (ET) (3 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `MOD16_ET` | gee | global | 500 m | monthly | GEE auth required |
+| `TERRACLIMATE_AET` | gee | global | 4 km | monthly | GEE auth required |
+| `OPENET_ENSEMBLE` | gee | CONUS | 30 m | monthly | GEE auth required |
+
+### DEM (6 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `GLO30` | gee | global | 30 m | static | GEE auth required |
+| `SRTM` | gee | global | 30 m | static | GEE auth required |
+| `DEM3DEP_10M` | hyriver | CONUS | 10 m | static | auth-free |
+| `MERIT_DEM` | gee | global | 90 m | static | GEE auth required |
+| `GLO30_STAC` | stac | global | 30 m | static | auth-free |
+| `GLO30_ELEMENT84` | stac | global | 30 m | static | auth-free |
 
 ### Soil Moisture (1 product)
 
-| ID | Source | Coverage | Resolution | Timestep |
-|---|---|---|---|---|
-| `SMAP_SM` | GEE | Global | 9 km | Daily (2015–present) |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `SMAP_SM` | gee | global | 9 km | daily | GEE auth required |
 
-### Land Cover (3 products)
+### Land Cover (4 products)
 
-| ID | Source | Coverage | Notes |
-|---|---|---|---|
-| `NLCD` | HyRiver | CONUS | NLCD 2021; 30 m |
-| `ESA_WORLDCOVER` | GEE | Global | 10 m; 2020 & 2021 |
-| `DYNAMIC_WORLD` | GEE | Global | 10 m; Sentinel-2 derived |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `NLCD` | hyriver | CONUS | 30 m | static | auth-free |
+| `ESA_WORLDCOVER` | gee | global | 10 m | static | GEE auth required |
+| `DYNAMIC_WORLD` | gee | global | 10 m | static | GEE auth required |
+| `ESA_WORLDCOVER_STAC` | stac | global | 10 m | static | auth-free |
 
 ### Soil Properties (2 products)
 
-| ID | Source | Coverage | Notes |
-|---|---|---|---|
-| `POLARIS` | HyRiver | CONUS | 30 m; 9 properties |
-| `SOILGRIDS` | GEE | Global | 250 m; ISRIC |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `POLARIS` | hyriver | CONUS | 30 m | static | auth-free |
+| `SOILGRIDS` | gee | global | 250 m | static | GEE auth required |
 
-### Vegetation (3 products)
+### NDVI (2 products)
 
-| ID | Variable | Source | Coverage | Resolution | Timestep |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
 |---|---|---|---|---|---|
-| `MODIS_NDVI` | NDVI | GEE | Global | 250 m | 16-day composite |
-| `SENTINEL2_NDVI` | NDVI | GEE | Global | 10 m | ~5 day revisit |
-| `MODIS_LAI` | LAI | GEE | Global | 500 m | 8-day composite |
+| `MODIS_NDVI` | gee | global | 250 m | monthly | GEE auth required |
+| `SENTINEL2_NDVI` | gee | global | 10 m | monthly | GEE auth required |
 
-### Streamflow (1 product)
+### LAI (1 product)
 
-| ID | Source | Coverage | Notes |
-|---|---|---|---|
-| `NWIS_STREAMFLOW` | Direct API | CONUS | USGS daily values; pass gauge ID as geometry |
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `MODIS_LAI` | gee | global | 500 m | monthly | GEE auth required |
 
----
+### Optical (5 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `SENTINEL2_SR` | gee | global | 10 m | composite | GEE auth required |
+| `LANDSAT9_SR` | gee | global | 30 m | composite | GEE auth required |
+| `LANDSAT8_SR` | gee | global | 30 m | composite | GEE auth required |
+| `SENTINEL2_SR_STAC` | stac | global | 10 m | composite | auth-free |
+| `LANDSAT_SR_STAC` | stac | global | 30 m | composite | auth-free |
+
+### Streamflow (4 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `NWIS_STREAMFLOW` | direct_api | CONUS | 0 m | daily | auth-free; spatial support: gauge_point |
+| `GEOGLOWS_RETRO` | geoglows_retro | global | 0 m | daily | auth-free; spatial support: reach |
+| `OPENMETEO_FLOOD` | openmeteo_flood | global | 5 km | daily | auth-free; spatial support: reach |
+| `GLOFAS_STREAMFLOW` | cds_glofas | global | 5 km | daily | spatial support: reach |
+
+### Bedrock Depth (1 product)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `OPENLANDMAP_BEDROCK` | gee | global | 250 m | static | GEE auth required |
+
+### Flood Inundation (1 product)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `GFM_S1_INUNDATION` | direct_api | global | 20 m | event | auth-free |
+
+### Geology (3 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `PYGEOGLIM_ALL` | pygeoglim | global | 0 m | static | auth-free |
+| `GLIM_TILES` | pygeoglim | global | 0 m | static | auth-free |
+| `GLHYMPS_TILES` | pygeoglim | global | 0 m | static | auth-free |
+
+### Impervious (2 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `NLCD_IMPERVIOUS` | hyriver | CONUS | 30 m | static | auth-free |
+| `GHSL_BUILT_UP` | gee | global | 100 m | static | GEE auth required |
+
+### Population (3 products)
+
+| ID | Source | Coverage | Resolution | Timestep | Notes |
+|---|---|---|---|---|---|
+| `GHSL_POP` | gee | global | 100 m | 5-yearly | — |
+| `WORLDPOP` | gee | global | 100 m | annual | — |
+| `GPW_V411` | gee | global | 927 m | 5-yearly | — |
 
 ## Routing System
 
@@ -387,7 +467,7 @@ FetchResult(data, product, source, citation, units, next_steps)
 
 ## Auth Setup
 
-### Google Earth Engine (20 products)
+### Google Earth Engine (23 products)
 
 ```bash
 # 1. Install
@@ -410,13 +490,25 @@ No auth required. Just install:
 pip install aihydro-data[hyriver]
 ```
 
-### CHIRPS IRI / NWIS (2 products)
+### Auth-free global products
 
 No auth required:
 
 ```bash
 pip install aihydro-data[opendap]    # CHIRPS_IRI — needs xarray + netCDF4
-# NWIS_STREAMFLOW works with [hyriver] — no extra auth
+pip install aihydro-data[geoglows]   # GEOGLOWS_RETRO — AWS Zarr; needs s3fs + zarr
+# NWIS_STREAMFLOW, OPEN_METEO_*, *_STAC all work with their respective extras; no auth
+```
+
+### GloFAS (modelled global streamflow)
+
+```bash
+pip install aihydro-data[glofas]
+
+# One-time: create a free Copernicus CDS account at cds.climate.copernicus.eu
+# then add your token to ~/.cdsapirc:
+# url: https://cds-beta.climate.copernicus.eu
+# key: <your-api-key>
 ```
 
 ---
@@ -453,22 +545,31 @@ aihydro_data/
 │
 ├── products/            ← Declarative variable registry (one file per variable)
 │   ├── precipitation.py     6 products
-│   ├── temperature.py       7 products
-│   ├── et.py                5 products
-│   ├── dem.py               4 products
+│   ├── temperature.py       9 products (tmax/tmin/tmean + Open-Meteo)
+│   ├── et.py                6 products (pet 4 + et 2)
+│   ├── dem.py               5 products
 │   ├── soil_moisture.py     1 product
-│   ├── landcover.py         3 products
+│   ├── landcover.py         4 products
 │   ├── soil.py              2 products
-│   ├── vegetation.py        3 products
-│   └── streamflow.py        1 product
+│   ├── vegetation.py        3 products (ndvi 2 + lai 1)
+│   ├── optical.py           5 products
+│   └── streamflow.py        4 products (NWIS + GEOGLOWS + Open-Meteo + GloFAS)
 │
 ├── sources/             ← Backend adapters (lazy imports — safe without extras)
 │   ├── base.py              SourceBackend ABC
-│   ├── gee.py               GEE backend (20 products)
+│   ├── gee/                 GEE backend package (23 products)
+│   │   ├── __init__.py          Backend class + fetch_timeseries/fetch_raster
+│   │   ├── _download.py         raster download helpers
+│   │   └── _composite.py        optical composite + spectral index helpers
 │   ├── hyriver.py           HyRiver backend (10 products)
-│   ├── direct_api.py        NWIS + CHIRPS IRI OPeNDAP (2 products)
-│   ├── stac.py              STAC/Planetary Computer (future)
-│   └── _gee_vendored/       GEE auth + timeseries helpers (vendored from aihydro-tools)
+│   ├── direct_api.py        NWIS + CHIRPS IRI OPeNDAP + Open-Meteo (5 products)
+│   ├── stac.py              STAC/Planetary Computer (4 products)
+│   ├── geoglows_retro.py    GEOGLOWS v2 retrospective via AWS Zarr (1 product)
+│   ├── openmeteo_flood.py   Open-Meteo river discharge (1 product)
+│   ├── cds_glofas.py        GloFAS via Copernicus CDS (1 product)
+│   ├── _common.py           require_import + assert_backend_available helpers
+│   ├── _retry.py            call_with_retry for transient HTTP errors
+│   └── _gee_vendored/       GEE auth + timeseries helpers
 │
 ├── routing/
 │   ├── regions.py           CONUS bbox, Pfafstetter region table
@@ -535,7 +636,7 @@ Every success carries `citation`, `bibtex`, `units`, `license`, and `next_steps`
 # Offline suite (no network, no auth — ~7 seconds)
 pytest -m "not live"
 
-# Live sweep — tests all 32 products against real backends (~13 minutes)
+# Live sweep — tests all 57 products against real backends (~15 minutes)
 # Requires GEE auth + internet
 pytest tests/test_live_sweep.py -v
 ```
@@ -544,9 +645,11 @@ pytest tests/test_live_sweep.py -v
 
 ## Status
 
-**v0.1.5** — Pre-PyPI development. 34 products live-tested; visualization layer (auto-plot, hydrology plots, multi-source compare, folium map preview); STAC backend with auth-free DEM + landcover; cookbook notebook with 10 recipes; multi-OS CI. Versioning stays on `0.1.x` until the first public PyPI release.
+**v0.2.1** — STAC robustness + metadata repair: retry+backoff in STAC backend; `GLO30_ELEMENT84`; impervious + bedrock_depth variables; and corrected `aihydro-core` dependency metadata so downstream `aihydro-watershed`/`aihydro-tools` resolve with `aihydro-core>=0.2`. Shipped with 54 products in 18 variables and 369 offline tests (current counts: see [Products](#products)).
 
-See **[ROADMAP.md](ROADMAP.md)** for what's planned next, and **[examples/cookbook.ipynb](examples/cookbook.ipynb)** for 10 working recipes.
+**v0.2.0** — First public PyPI release. Global streamflow tri-source chain (GEOGLOWS/Open-Meteo/GloFAS); spatial-support honesty (point vs areal vs reach products declared and enforced); verify-on-read cache; `region` and `outlet` kwargs; structural refactor (gee/ package, MCP `@_tool_envelope`); 341 offline tests.
+
+See **[examples/cookbook.ipynb](examples/cookbook.ipynb)** for working recipes.
 
 | Phase | Status | Description |
 |---|---|---|
@@ -557,10 +660,44 @@ See **[ROADMAP.md](ROADMAP.md)** for what's planned next, and **[examples/cookbo
 | 5: Cache + provenance | ✅ | Disk cache, manifest, license tracking |
 | 6: Batch fetching | ✅ | Multi-geometry parallel dispatch |
 | 7: MCP tools | ✅ | 9 tools, help topics, doctor |
-| 8: PyPI publish | 🔲 | v0.2.0 release |
+| 8: PyPI publish | ✅ | v0.2.0 on PyPI (`pip install aihydro-data`) |
+
+---
+
+
+---
+
+## Citation
+
+If you use `aihydro-data` in your research, please cite it:
+
+```bibtex
+@software{galib2025aihydrodata,
+  author    = {Galib, Mohammad},
+  title     = {aihydro-data: Global Hydrology Dataverse for the AI-Hydro Platform},
+  year      = {2025},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.20823443},
+  url       = {https://doi.org/10.5281/zenodo.20823443}
+}
+```
 
 ---
 
 ## License
 
 Apache-2.0. Data products carry their own licenses — always check `result.license` or `data_describe_product(id)`.
+
+### IMERG daily precipitation contract
+
+`IMERG_PRECIP` integrates the native half-hourly rates into complete UTC daily totals. Date-only start/end are inclusive for this product. Missing, duplicate or invalid intervals fail instead of producing partial totals. Returned `interval_count`, `expected_interval_count` and `source_status` columns expose temporal support and product maturity. Provisional or unknown status must not be cited as verified Final data. This check does not establish spatial completeness or observational accuracy. See [the decision and limitations](DECISIONS.md) and [implementation plan](plans/precipitation-contract-2026-09-07.md).
+
+### GFM observational failures and synthetic fixtures
+
+`fetch_gfm_extent` raises on network/asset failures; it never substitutes synthetic polygons. `use_fixture=True` explicitly selects synthetic test data, without an observational citation. Inspect `status`: no acquisitions and no valid pixels are distinct from no flood detected. Per-item acquisition times and assets remain available for review. Automatic model-validation scores are withheld until a jointly valid comparison footprint is established; an extent alone is insufficient. See [the flood-reference decision](DECISIONS.md).
+
+### CHIRPS versions and cached identity
+
+`CHIRPS` currently routes to **v3 daily SAT** on GEE. `CHIRPS_IRI` serves **v2 daily-improved**; fallback between them changes the scientific product. V3 SAT uses IMERG Late V07 for daily partitioning of pentad totals, so comparison with IMERG must account for shared inputs.
+
+Inspect `result.product_identity` (also returned by MCP) for version, variant, derivation, dependencies and interpretation metadata. New caches retain the identity and warnings captured at fetch time. Empty legacy identity means unknown. These are configured-product declarations, not verification of upstream asset bytes or revision. See [the identity decision](DECISIONS.md).