Build a Coastal Surge Declaration Exposure Dossier Generator — implementation

## Build
Cross-reference coastal asset footprints against OpenFEMA disaster declarations to assemble structured claim preparation records. Synthesize localized historical declaration frequencies and administrative exposure summaries for loss adjusters.

## User
Coastal Risk Loss Adjuster

## Workflow
1. Ingest municipal property footprints with coastal elevation values.
2. Query OpenFEMA API for regional coastal flood disaster declarations.
3. Calculate historical disaster declaration frequencies for each asset parcel's county.
4. Generate a structured flood claim preparation dossier indicating administrative exposure history.

## Interface
Web dashboard displaying asset declaration history, frequency metrics, and downloadable claim preparation JSON dossiers.

## Data
Fetch OpenFEMA DisasterDeclarationsSummaries via REST query filtering by state and disaster incident type. Mock local building parcel coordinates in sandbox storage.
Starter examples below are synthetic. They are not downloaded records.

## Source
[FEMA OpenFEMA](https://www.fema.gov/about/openfema/api)
Applies OpenFEMA API endpoint /v2/DisasterDeclarationsSummaries with $filter operators eq and incidentType matching coastal flood declarations.

## Tools
pydantic-ai, FastAPI, httpx.
Enforces rigorous validation on structured claim dossier schemas and historical declaration tally constraints.
Requires an instruction-tuned LLM capable of schema-constrained JSON extraction via API or local execution.

## 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
- OpenFEMA API queries parse HTTP JSON response entities successfully.
- Claim dossiers format declaration frequency metrics with explicit administrative status indicators.
- Output passes Pydantic schema validation without runtime type errors.

## Starter Examples
```json
[
  {
    "input": {
      "asset_id": "ASSET-CST-101",
      "county": "Dare",
      "state": "NC",
      "declared_incidents": [
        {
          "disasterNumber": 4463,
          "incidentType": "Hurricane",
          "declarationDate": "2019-09-04T00:00:00.000Z"
        }
      ],
      "asset_elevation_m": 1.4,
      "_note": "These are simplified synthetic app records, not complete official schema files."
    },
    "expected_output": {
      "asset_id": "ASSET-CST-101",
      "declaration_count": 1,
      "administrative_exposure_level": "HIGH",
      "claim_readiness_status": "READY_FOR_ADJUSTER_REVIEW"
    }
  },
  {
    "input": {
      "asset_id": "ASSET-CST-102",
      "county": "Dare",
      "state": "NC",
      "declared_incidents": [],
      "asset_elevation_m": 6.8,
      "_note": "These are simplified synthetic app records, not complete official schema files."
    },
    "expected_output": {
      "asset_id": "ASSET-CST-102",
      "declaration_count": 0,
      "administrative_exposure_level": "LOW",
      "claim_readiness_status": "INSUFFICIENT_HISTORICAL_DECLARATIONS"
    }
  }
]
```

## Safety
Simulates claim preparation documentation only; does not adjudicate legal coverage or disburse monetary funds.
Use mock external writes. Require human review before any real deployment.