Build a Coastal Digital Elevation Asset Matcher for Inundation Risk — implementation

## Build
Cross-reference coastal digital elevation asset links from STAC collections against simplified commercial property elevation records. Quantify exposure to projected sea level inundation to formulate municipal adaptation plans.

## User
Coastal Infrastructure Engineer

## Workflow
1. Traverse STAC Collection links to discover digital elevation model (DEM) GeoTIFF asset references.
2. Ingest explicitly simplified structural elevation records for high-value coastal facility coordinates.
3. Calculate structural ground elevation margins against tidal surge and erosion hazard planes.
4. Synthesize physical asset vulnerability scorecards for municipal infrastructure adaptation grants.

## Interface
REST API exposing endpoints to submit property elevation records and retrieve inundation vulnerability scorecards.

## Data
Utilize public STAC catalog endpoints for metadata and mock JSON datasets representing explicitly simplified commercial property elevation records.
Starter examples below are synthetic. They are not downloaded records.

## Source
[STAC specification](https://raw.githubusercontent.com/radiantearth/stac-spec/master/README.md)
Parse STAC Collection spatial extents, Item assets, and link relations following STAC specification.

## Tools
qdrant, fastapi, pydantic.
Qdrant stores and searches multidimensional hazard embeddings across thousands of coastal parcels.
Hosted reasoning model for generating narrative coastal engineering adaptation plans.

## 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
- Parses STAC Item asset links for digital elevation assets correctly.
- Computes net freeboard margin by subtracting tidal flood levels from asset base elevations.
- Flags assets with a freeboard margin under 0.6 meters as critical exposure.

## Starter Examples
```json
[
  {
    "input": {
      "asset_id": "PUMP-STATION-03",
      "coordinates": [
        -74.02,
        40.71
      ],
      "asset_base_elevation_m": 1.85,
      "projected_storm_surge_m": 2.1,
      "stac_item_id": "DEM_NY_HARBOR_2022"
    },
    "expected_output": {
      "asset_id": "PUMP-STATION-03",
      "freeboard_margin_m": -0.25,
      "inundation_risk": "CRITICAL_OVERTOPPING",
      "adaptation_recommendation": "CONSTRUCT_DRY_FLOODPROOF_PERIMETER_WALL"
    }
  },
  {
    "input": {
      "asset_id": "SUBSTATION-EAST",
      "coordinates": [
        -74.01,
        40.72
      ],
      "asset_base_elevation_m": 4.5,
      "projected_storm_surge_m": 2.1,
      "stac_item_id": "DEM_NY_HARBOR_2022"
    },
    "expected_output": {
      "asset_id": "SUBSTATION-EAST",
      "freeboard_margin_m": 2.4,
      "inundation_risk": "MINIMAL_EXPOSURE",
      "adaptation_recommendation": "MONITOR_SEASONAL_EROSION_RATES"
    }
  }
]
```

## Safety
Adaptation plans represent advisory engineering proposals rather than certified architectural drawings. Examples are explicitly simplified synthetic app records, not complete official schema files.
Use mock external writes. Require human review before any real deployment.