Build a STAC Agricultural Drought Image Retriever — implementation

## Build
Process public STAC earth observation collections to discover imagery over agricultural acreage. Compile optical asset links matching temporal and cloud constraints to enable downstream calculation of vegetative drought anomalies.

## User
Crop Insurance Portfolio Analyst

## Workflow
1. Incorporate field polygon coordinates and historic baseline metadata for target agricultural regions.
2. Query STAC collections for items representing optical surface reflectance imagery over the targeted fields.
3. Filter and extract STAC asset links matching strict cloud cover limits and temporal windows.
4. Compile organized image retrieval dossiers to feed downstream agronomic raster processing pipelines.

## Interface
Command-line interface producing structured JSON dossiers and simple map plots of STAC item footprints.

## Data
Query public Earth Search STAC APIs or download mock STAC Item JSON records from Radiant Earth examples.
Starter examples below are synthetic. They are not downloaded records.

## Source
[STAC specification](https://raw.githubusercontent.com/radiantearth/stac-spec/master/README.md)
Applies STAC standard query parameters for spatial-temporal extents and parses STAC Item properties to extract asset links.

## Tools
llamaindex, pystac, geopandas.
LlamaIndex manages the orchestration of metadata retrieval, filtering conditions, and structuring the final asset link dossiers.
Hosted or local LLM for structuring parameter extraction and formatting final JSON dossiers.

## 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 queries a STAC API utilizing spatial bounding boxes and target temporal windows.
- Filters and discards STAC Items that exceed the specified cloud cover threshold.
- Generates a valid JSON dossier populated with direct optical asset links for downstream consumption.

## Starter Examples
```json
[
  {
    "input": {
      "field_id": "FIELD-SOY-99",
      "target_month": "2023-07",
      "max_cloud_cover_pct": 20
    },
    "expected_output": {
      "field_id": "FIELD-SOY-99",
      "discovered_items": 2,
      "asset_links": [
        "https://example.stac/item1/B04.tif",
        "https://example.stac/item2/B04.tif"
      ],
      "dossier_status": "READY"
    }
  },
  {
    "input": {
      "field_id": "FIELD-SOY-100",
      "target_month": "2023-08",
      "max_cloud_cover_pct": 10
    },
    "expected_output": {
      "field_id": "FIELD-SOY-100",
      "discovered_items": 0,
      "asset_links": [],
      "dossier_status": "NO_CLEAR_IMAGERY"
    }
  }
]
```

## Safety
Retrieves image links for discovery purposes only; does not calculate agronomic losses or automate crop insurance claims.
Use mock external writes. Require human review before any real deployment.