Metadata-Version: 2.4
Name: mireye-earth
Version: 0.2.0
Summary: Provenance-tagged geospatial data for US coordinates.
Author: Mireye
License: TBD
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: boto3>=1.34
Requires-Dist: click>=8.1
Requires-Dist: diskcache>=5.6
Requires-Dist: duckdb>=1.0
Requires-Dist: earthengine-api>=1.0
Requires-Dist: fastapi>=0.115
Requires-Dist: geopandas>=1.0
Requires-Dist: google-auth>=2.30
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pyproj>=3.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rasterio>=1.3
Requires-Dist: rio-cogeo>=5.0
Requires-Dist: shapely>=2.0
Requires-Dist: structlog>=24.1
Requires-Dist: tenacity>=8.2
Requires-Dist: uvicorn[standard]>=0.30
Description-Content-Type: text/markdown

# Mireye Earth

Mireye Earth answers geospatial questions about US coordinates with
federal-source citations. Every field returned — elevation, flood-zone
status, wildfire fuel load, nearest power plant, parcel zoning — carries
the source, source URL, fetched timestamp, and a calibrated confidence
bucket. Built for insurance underwriters, lenders, and AI agents that need
an audit trail, not just an answer.

- **`POST /v1/ask`** — natural-language Q&A over any US coordinate, returns answer + per-citation provenance.
- **`POST /v1/fetch`** — deterministic field-level access (47+ catalog fields, 8 use-case presets).
- **`GET /v1/meta/fields`** — public catalog. Versioned, ETag-cached, used by the planner and any third-party client.
- **MCP server** — same two operations exposed as MCP tools for Claude Desktop, Cursor, and custom agents.

Live deployment: <https://mireye-earth.fly.dev>
Interactive Swagger: <https://mireye-earth.fly.dev/v1/docs>
OpenAPI spec: <https://mireye-earth.fly.dev/v1/openapi.json>
Full docs (Mintlify): <https://docs.mireye.earth>

---

## Try it

```bash
curl -s https://mireye-earth.fly.dev/v1/ask \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "question": "What is the elevation here?"
  }' | jq
```

Returns the answer with citations naming the federal source for every value used:

```jsonc
{
  "lat": 40.7128,
  "lng": -74.006,
  "question": "What is the elevation here?",
  "answered_at": "2026-05-24T22:14:03.918Z",
  "answer": "The elevation at 40.7128, -74.0060 is 13.15 meters above NAVD88 (43.1 feet), per the USGS 3D Elevation Program (3DEP).",
  "confidence": "HIGH",
  "citations": [
    {
      "source": "USGS_3DEP",
      "source_url": "https://www.usgs.gov/3d-elevation-program",
      "fields": ["elevation"],
      "fetched_at": "2026-05-24T22:14:01.882Z",
      "confidence": "HIGH"
    }
  ],
  "fields_used": ["elevation"]
}
```

The `/v1/fetch` endpoint is the developer escape hatch — pass named fields
or a preset, get raw structured values back:

```bash
curl -s https://mireye-earth.fly.dev/v1/fetch \
  -H 'content-type: application/json' \
  -d '{"lat": 29.7604, "lng": -95.3698, "preset": "flood_risk"}' | jq
```

---

## At a glance

| Endpoint              | What it does                                                                 | Latency (warm)  |
|-----------------------|------------------------------------------------------------------------------|-----------------|
| `POST /v1/ask`        | LLM planner picks fields → fetches → synthesizes a cited natural-language answer. | 2–6 s           |
| `POST /v1/fetch`      | Returns named fields with full per-field provenance + `partial_failures`.    | 1–3 s           |
| `GET /v1/meta/fields` | Field + preset catalog. 1-hour `Cache-Control`, supports `If-None-Match`.    | <50 ms          |
| MCP `ask` / `fetch`   | Same two operations exposed as MCP tools. stdio transport, ~100 LOC adapter. | +HTTP overhead  |

Coordinates are validated against the US envelope (`lat ∈ [18, 72]`,
`lng ∈ [-180, -65]`). Out-of-bounds requests return `400
coord_out_of_bounds` with structured detail. Unknown field names return
`400 fields_unknown` listing exactly which names failed.

---

## Install

### Use the deployed API

No install. Hit `https://mireye-earth.fly.dev/v1/*` directly. The OpenAPI
spec at `/v1/openapi.json` generates SDKs in any language via
`openapi-generator`.

### Install the MCP server (Claude Desktop / Claude Code / Cursor / agents)

The MCP server is its own slim PyPI package (`mireye-earth-mcp` — two
runtime deps, no GDAL). Run it with `uvx`:

```bash
uvx mireye-earth-mcp
```

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-earth-mcp"]
    }
  }
}
```

For Claude Code, one command:

```bash
claude mcp add mireye-earth -- uvx mireye-earth-mcp
```

Restart Claude Desktop. Two tools — `mireye_ask` and `mireye_fetch` —
appear in the picker. Full install guide and Cursor / custom-agent setup
in [`mcp_server/README.md`](mcp_server/README.md) and
[`docs/mcp/installation.mdx`](docs/mcp/installation.mdx).

### Self-host the API

The HTTP server lives in [`api/`](api/) and is a thin FastAPI app over the
`mireye_earth` Python library. You will need Python 3.11+, ~600 MB of disk
for the bundled bulk-data assets, and an Earth Engine service account if
you want live NDVI / land-cover layers.

```bash
git clone https://github.com/mireye/mireye-earth
cd mireye-earth
uv sync                       # install package + dev deps
cp .env.example .env          # add EARTHDATA_TOKEN + optional EE creds
uv run mireye-earth bootstrap # download static federal assets
uv run uvicorn api.main:app --port 8000
```

See [`api/README.md`](api/README.md) for the full endpoint reference and
self-host deploy guide, and [`api/DEPLOY.md`](api/DEPLOY.md) for the
specific Fly.io configuration we run in production.

---

## Field catalog (sample)

47 fields across 5 layers and 8 presets. Full table at
[`docs/api-reference/field-catalog.mdx`](docs/api-reference/field-catalog.mdx)
or the live JSON at `/v1/meta/fields`.

| Field                             | Layer              | Unit          | Source                  |
|-----------------------------------|--------------------|---------------|-------------------------|
| `elevation`                       | terrain            | meters        | USGS 3DEP               |
| `slope_degrees`                   | terrain            | degrees       | USGS 3DEP               |
| `coast_distance_m`                | terrain            | meters        | NOAA CUSP               |
| `soil_drainage_class`             | terrain            | (enum)        | USDA SSURGO             |
| `within_floodplain_polygon`       | terrain            | (bool)        | USGS NHDPlus HR         |
| `intersects_wetland`              | terrain            | (bool)        | USFWS NWI               |
| `lcms_class`                      | land cover         | (enum)        | USFS LCMS               |
| `tree_canopy_pct`                 | land cover         | percent       | USFS NLCD TCC           |
| `ndvi_current`                    | land cover         | (ratio)       | Sentinel-2 NDVI         |
| `cdl_class`                       | land cover         | (enum)        | USDA CDL                |
| `primary_building_height_m`       | built environment  | meters        | Overture Buildings      |
| `nearest_major_road_distance_m`   | built environment  | meters        | Overture Transportation |
| `nearest_power_plant_distance_m`  | utilities          | meters        | EIA Energy Atlas        |
| `nearest_transmission_line_distance_m` | utilities    | meters        | EIA Energy Atlas        |
| `intersects_conservation_easement`| parcels            | (bool)        | USGS PAD-US             |

Presets (request via `"preset": "<name>"`):

- `terrain` — elevation, slope, aspect, coast, soil, bedrock.
- `flood_risk` — elevation, coast distance, floodplain, wetland, water permanence, nearest waterbody.
- `wildfire_underwrite` — LCMS class, tree canopy, NDVI current, NDVI 5-year change, slope, elevation.
- `land_cover` — LCMS class, land use, tree canopy, CDL class, dominant crop.
- `site_selection` — terrain + LCMS + floodplain + nearest road + nearest transmission + easements.
- `building_lookup` — building class, height, floors, footprint + nearest road / bridge.
- `utilities` — nearest plant / transmission / pipeline / water system / rail / airport / port.
- `boundaries` — region, county, locality, tract GEOID, easements.

---

## Data sources

Mireye Earth queries only authoritative federal datasets. No proprietary
risk models, no third-party data brokers, no "AI-derived" values. Every
field's `source_url` points back to the originating agency so a regulator,
underwriter, or auditor can re-fetch and verify.

- **USGS** — 3D Elevation Program (3DEP), NHDPlus HR (hydrography), Watershed Boundary Dataset (WBD), PAD-US (protected areas / easements).
- **NOAA** — Continually Updated Shoreline (CUSP).
- **USDA** — SSURGO + STATSGO2 (soils), Cropland Data Layer (CDL).
- **USFS** — Landscape Change Monitoring System (LCMS), NLCD Tree Canopy Cover.
- **USFWS** — National Wetlands Inventory (NWI).
- **EPA** — Safe Drinking Water Information System (SDWIS).
- **EIA** — Energy Atlas (power plants, transmission, pipelines).
- **FAA** — National Airspace System Resource (NASR).
- **FHWA** — National Bridge Inventory (NBI).
- **BTS** — National Transportation Atlas Database (NTAD), Ports.
- **US Census Bureau** — Geocoder, TIGER.
- **Overture Maps Foundation** — Buildings, Transportation, Divisions (federation of OSM + Microsoft + others under a permissive license).
- **Copernicus / ESA** — Sentinel-2 (NDVI).
- **JRC** — Global Surface Water.
- **Regrid** — parcel boundaries (free tier via Esri Living Atlas).

---

## Repo layout

```
api/             FastAPI HTTP surface (/v1/ask, /v1/fetch, /v1/meta/fields)
mcp_server/      Source dir for the standalone `mireye-earth-mcp` PyPI package
                 (MCP stdio adapter exposing the same operations as MCP tools)
src/mireye_earth Python library — per-layer orchestrators and source adapters
docs/            Mintlify documentation site (introduction, quickstart, references)
tests/           pytest unit + live integration suite (~50 tests)
scripts/         CLI helpers (bootstrap, benchmark, eval harnesses)
data/            Local bulk-data drop zone (populated by `mireye-earth bootstrap`)
```

For a codebase-level walkthrough of request flows, layers, provenance, caching,
bootstrap assets, and testing, see [`ARCHITECTURE.md`](ARCHITECTURE.md).

---

## License & contact

License: TBD (planning Apache-2.0 for the library + adapter, separate terms
for hosted API beyond the free tier).

Contact: <ansh@mireye.earth>.

For background on the design decisions (why `/ask` + `/fetch`, why the
planner is two-phase, why MCP, why federal-only), see
[`API-DESIGN.md`](API-DESIGN.md) and [`ASK-API-DESIGN.md`](ASK-API-DESIGN.md).
