Build a Parametric Crop Drought Trigger Simulator and Basis Risk Auditor — implementation

## Build
Simulate historical payouts for agricultural parametric drought contracts using ERA5 reanalysis precipitation time series. Audit contract basis risk against reported agricultural loss declaration logs.

## User
Parametric Product Structurer

## Workflow
1. Configure parametric contract terms specifying cumulative precipitation triggers and payout schedules.
2. Retrieve ERA5 historical total precipitation grids across multi-year growing cycles using cdsapi.
3. Execute synthetic trigger settlements over historic seasons to quantify false positive and false negative payouts.
4. Produce a basis risk audit dossier highlighting geographic contract trigger mismatches.

## Interface
Analytical workbench with interactive cumulative rainfall curves, trigger strike lines, and historical basis risk heatmaps.

## Data
Fetch ERA5 reanalysis datasets via cdsapi for target agricultural regions; cache normalized monthly rainfall totals in parquet files.
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)
Implements the cdsapi.Client retrieve method for 'reanalysis-era5-single-levels' selecting total_precipitation.

## Tools
evidently-ai, cdsapi, numpy, scipy.
Evaluates data drift and trigger misclassification distributions across distinct historical climate epochs.
Local or hosted LLM to interpret basis risk statistical metrics into actuarial design summaries.

## 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
- Simulates annual parametric trigger payouts accurately based on ERA5 precipitation thresholds.
- Quantifies basis risk rates by identifying seasons with simulated drought declarations but no parametric breach.
- Generates an actionable contract recalibration report for human underwriting review.

## Starter Examples
```json
[
  {
    "input": {
      "contract_id": "PARAM-DROUGHT-WHEAT-01",
      "strike_threshold_mm": 120,
      "seasons": [
        {
          "year": 2021,
          "measured_precip_mm": 95,
          "actual_loss_declared": true
        },
        {
          "year": 2022,
          "measured_precip_mm": 140,
          "actual_loss_declared": false
        },
        {
          "year": 2023,
          "measured_precip_mm": 130,
          "actual_loss_declared": true
        }
      ]
    },
    "expected_output": {
      "contract_id": "PARAM-DROUGHT-WHEAT-01",
      "simulated_triggers": [
        {
          "year": 2021,
          "triggered": true,
          "basis_mismatch": false
        },
        {
          "year": 2022,
          "triggered": false,
          "basis_mismatch": false
        },
        {
          "year": 2023,
          "triggered": false,
          "basis_mismatch": true
        }
      ],
      "basis_risk_summary": {
        "false_negative_rate": 0.5,
        "false_positive_rate": 0,
        "recalibration_advice": "Trigger threshold too restrictive; consider adjusting strike point to 135 mm."
      }
    }
  },
  {
    "input": {
      "contract_id": "PARAM-DROUGHT-SOY-02",
      "strike_threshold_mm": 100,
      "seasons": [
        {
          "year": 2023,
          "measured_precip_mm": 80,
          "actual_loss_declared": true
        }
      ]
    },
    "expected_output": {
      "contract_id": "PARAM-DROUGHT-SOY-02",
      "simulated_triggers": [
        {
          "year": 2023,
          "triggered": true,
          "basis_mismatch": false
        }
      ],
      "basis_risk_summary": {
        "false_negative_rate": 0,
        "false_positive_rate": 0,
        "recalibration_advice": "Current strike threshold exhibits zero basis mismatch on evaluated seasons."
      }
    }
  }
]
```

## Safety
Calculates parametric scenario simulations only; no financial capital is allocated or contractual payout executed.
Use mock external writes. Require human review before any real deployment.