Build an Agricultural Drought Soil Moisture Trigger Simulator — implementation

## Build
Evaluate agricultural drought parametric contracts by processing ERA5 volumetric soil water layer parameters. Quantify seasonal dry spell anomalies against baseline historical quantiles to evaluate index basis risk.

## User
Agricultural Parametric Modeler

## Workflow
1. Parse field parcel polygons and defined root-zone depth specifications.
2. Retrieve ERA5 volumetric soil water layer data over target growing seasons.
3. Calculate soil moisture deficit percentiles relative to multi-year baselines.
4. Synthesize simulated parametric trigger payouts and contract basis risk.

## Interface
Jupyter Notebook workflow with interactive ipywidgets for setting soil moisture thresholds and viewing deficit histograms.

## Data
Download monthly averaged reanalysis soil water layers via cdsapi or load synthetic NetCDF grids representing topsoil moisture.
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)
Employs cdsapi retrieval parameters for ERA5 surface variables focusing on volumetric soil water layers.

## Tools
dspy, xarray, pandas.
DSPy compiles structured diagnostic prompts that reason over anomalous soil moisture sequences and flag basis risk caveats.
Local Llama 3 or hosted Claude model for generating qualitative risk syntheses from tabular drought indices.

## 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
- Correctly integrates layer 1 and layer 2 soil moisture into an effective root zone index.
- Identifies consecutive days below contract dry threshold.
- Outputs contract trigger ratio without invoking actual financial disbursement.

## Starter Examples
```json
[
  {
    "input": {
      "parcel_id": "FIELD-IA-44",
      "consecutive_days_trigger": 14,
      "moisture_threshold": 0.18,
      "daily_records": [
        {
          "date": "2023-07-01",
          "swvl1": 0.15
        },
        {
          "date": "2023-07-02",
          "swvl1": 0.14
        },
        {
          "date": "2023-07-03",
          "swvl1": 0.16
        }
      ]
    },
    "expected_output": {
      "parcel_id": "FIELD-IA-44",
      "consecutive_deficit_days": 3,
      "trigger_met": false,
      "mean_moisture": 0.15
    }
  },
  {
    "input": {
      "parcel_id": "FIELD-IA-45",
      "consecutive_days_trigger": 2,
      "moisture_threshold": 0.2,
      "daily_records": [
        {
          "date": "2023-08-01",
          "swvl1": 0.12
        },
        {
          "date": "2023-08-02",
          "swvl1": 0.11
        }
      ]
    },
    "expected_output": {
      "parcel_id": "FIELD-IA-45",
      "consecutive_deficit_days": 2,
      "trigger_met": true,
      "mean_moisture": 0.115
    }
  }
]
```

## Safety
Emphasizes that trigger simulations are exploratory models and cannot be used as binding agricultural loss adjustments.
Use mock external writes. Require human review before any real deployment.