Build an ERA5 Drought Soil Moisture Parametric Simulator — implementation

## Build
Simulate parametric multi-layer soil moisture triggers for rainfed pastureland using ECMWF ERA5 reanalysis datasets. Model index basis risk and calculate payout frequencies under historical drought conditions.

## User
Agricultural Actuarial Modeler

## Workflow
1. Generate CDS API requests for volumetric soil water layer parameters across multiple agricultural seasons.
2. Ingest daily soil moisture time series and compute cumulative dry-anomaly duration indexes.
3. Model synthetic parametric trigger mechanics against historical regional crop yield losses.
4. Quantify trigger false positives and false negatives to evaluate contract basis risk.

## Interface
JupyterLab dashboard and CLI exporting synthetic payout curves and trigger diagnostic tables.

## Data
Use ECMWF CDS API client sandbox with cached volumetric soil water reanalysis test records.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Copernicus Climate Data Store client](https://raw.githubusercontent.com/ecmwf/cdsapi/master/README.rst)
Structure cdsapi requests specifying reanalysis datasets, dates, and volumetric soil variables.

## Tools
optuna, cdsapi, numpy, pandas.
Optuna optimizes parametric trigger thresholds to minimize basis risk against loss indicators.
Local Python script with LLM assistance for actuarial summary documentation.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- CDS API script contains valid variable and date range parameters.
- Calculates cumulative soil moisture deficit across consecutive dry days.
- Outputs optimized trigger threshold and simulated historical payout frequency.

## Starter Examples
```json
[
  {
    "input": {
      "zone_id": "KANSAS_ZONE_4",
      "target_moisture_m3_m3": 0.15,
      "consecutive_days_trigger": 14,
      "daily_soil_moisture": [
        0.18,
        0.14,
        0.13,
        0.12,
        0.11,
        0.1,
        0.12,
        0.11,
        0.13,
        0.12,
        0.11,
        0.1,
        0.09,
        0.08,
        0.07,
        0.16
      ]
    },
    "expected_output": {
      "zone_id": "KANSAS_ZONE_4",
      "max_consecutive_dry_days": 14,
      "trigger_activated": true,
      "simulated_payout_rate": 1,
      "basis_risk_score": 0.12
    }
  },
  {
    "input": {
      "zone_id": "KANSAS_ZONE_5",
      "target_moisture_m3_m3": 0.15,
      "consecutive_days_trigger": 14,
      "daily_soil_moisture": [
        0.22,
        0.2,
        0.18,
        0.17,
        0.16,
        0.15,
        0.14,
        0.16,
        0.17,
        0.18
      ]
    },
    "expected_output": {
      "zone_id": "KANSAS_ZONE_5",
      "max_consecutive_dry_days": 1,
      "trigger_activated": false,
      "simulated_payout_rate": 0,
      "basis_risk_score": 0.04
    }
  }
]
```

## Safety
Simulations are academic and actuarial models, not authorized insurance contract commitments.
Use mock external writes. Require human review before any real deployment.