daedal-map

# DaedalMap

## Use it as a hosted MCP server (no setup)

Most callers do not need to run anything - DaedalMap is a live remote MCP server
(and HTTP API) for geographic data:

- MCP endpoint: `https://app.daedalmap.com/mcp` (streamable HTTP)
- Start with `get_catalog`, then `get_pack` for a pack's metrics and a
  first-query example
- Free packs: currency (FX rates), volcanoes, hurricanes, floods, tornadoes,
  UN SDG, World Factbook, WorldPop
- Paid via x402 on Base mainnet USDC: earthquakes, tsunamis (call unpaid first -
  the server returns the exact price before any charge)
- Agent docs: `https://daedalmap.com/docs/for-agents`

The rest of this README is the self-host / local-runtime path.

---

DaedalMap is a map-first geographic query engine. This repository is the open app/runtime for developers who want to run it locally, self-host it, point it at their own data, or extend it with compatible geographic datasets.

Public surfaces:
- App: `https://app.daedalmap.com`
- Website/docs: `https://daedalmap.com`

There are now two valid ways to approach DaedalMap locally:

- `GitHub/self-host path`
  - use this repo directly
  - best for developers, custom data work, and users who want to control setup
- `Downloadable launcher path`
  - curated wrapper + engine artifact + pack install flow
  - best for users who want the same runtime with less setup friction

These should stay the same product at the runtime/contract level, but they do
not need identical UI on every surface.

If you are using this public GitHub repo as a self-host/local runtime, the practical setup contract right now is:
- a local data location (`DATA_ROOT`, unless you use the default app-data path)
- an LLM API key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`)

Supabase and hosted account wiring are optional for self-host use.

## What This Repo Is For

Use this repo if you want to:
- run the DaedalMap runtime on your own machine or server
- point the runtime at local data or a cloud-backed data plane you control
- inspect or extend the open runtime behavior
- build compatible geographic datasets and pack-style workflows around the engine

Typical use cases:
- show earthquakes, floods, wildfires, storms, volcanoes, or tsunamis for a place and time window
- compare population, economic, and disaster context in the same workflow
- move between local development, self-hosted runtime operation, and hosted-style runtime behavior without changing the basic mental model

DaedalMap itself is built around three ideas:
- ask in plain language instead of assembling GIS workflows first
- keep the map as the primary interface, not an afterthought
- separate runtime delivery from maintained data-pack delivery

This repo is therefore best read as:

- the open runtime engine
- the self-host/developer entry point
- the source of truth for the downloadable engine snapshot users install through
  the launcher

It is not the hosted account, billing, or admin surface. Those product surfaces
are separate from the public runtime and may evolve faster than the
downloadable runtime UI.

## Choosing A Local Path

If you are deciding between this repo and the downloadable launcher, use this
rule of thumb:

- use the GitHub repo when you want:
  - code access
  - self-host setup
  - custom data or custom pack work
  - runtime-level experimentation
- use the downloadable launcher when you want:
  - a curated install/update path
  - a local Research-oriented runtime with less setup work
  - pack installs and local runtime management without treating Git as the main UX

The goal is that both paths converge on the same core runtime behavior even if
their setup UX differs.

## GitHub Vs Downloadable

If you are browsing this repository, treat it as the developer and self-host
entry point.

If you want a more guided local install path, use the downloadable launcher
when it is available through release/distribution channels.

In other words:

- GitHub checkout = source, self-host, customization, local development
- downloadable launcher = curated local install and runtime management

Both paths are intended to lead to the same DaedalMap runtime family.

## Data Coverage

The hosted runtime ships with 40+ curated sources across disasters, demographics, economics, and climate. Coverage below reflects the current maintained pack inventory.

### Global Disasters

| Source | Scale | Time Range |
|--------|-------|------------|
| USGS Earthquakes | 1M+ events | 2150 BC - present |
| IBTrACS Hurricanes/Cyclones | 13K storms | 1842 - present |
| NOAA Tsunamis | 2.6K events | 2000 BC - present |
| Smithsonian Volcanoes | 11K eruptions | Holocene |
| Global Wildfires | 940K events/year | 2002 - 2024 |
| USA/CAN Tornadoes | 81K events | 1950 - present |
| Global Floods | 4.8K events | 1985 - 2019 |
| Global Landslides | 45K events | 1760 - present |

Disaster events include 22M+ geographic location relationships and 566K cross-disaster links (aftershocks, triggered events).

### Global Indicators

| Source | Countries | Years | Category |
|--------|-----------|-------|----------|
| Our World in Data CO2 | 217 | 1750 - 2024 | Environment |
| WHO Health Statistics | 198 | 2015 - 2024 | Health |
| IMF Balance of Payments | 195 | 2005 - 2022 | Economy |
| UN Sustainable Development Goals | 200+ | 2000 - 2023 | SDGs 1-17 |
| Eurostat Demographics | 37 European countries | 2000 - 2024 | Demographics |

### Country-Specific Sources

| Country | Source Count | Examples |
|---------|-------------|---------|
| USA | 15+ | Census, FEMA National Risk Index, NOAA storms |
| Canada | 3 | Statistics Canada, NRCan earthquakes, drought |
| Australia | 2 | ABS population, BOM cyclones |

### Disaster Display

Disasters are displayed with animated, type-specific rendering:
- Point + radius: earthquakes, volcanoes, tornadoes
- Track/trail: hurricanes and cyclones
- Radial wave: tsunamis
- Polygon fill: wildfires, floods

## Current Runtime Shape

DaedalMap now treats runtime behavior as a 2-axis matrix:

- `INSTALL_MODE`
  - `local` = local app/runtime install
  - `cloud` = hosted/server deployment
- `RUNTIME_MODE`
  - `local` = query local data
  - `cloud` = query managed cloud-backed data via local cache + DuckDB httpfs

Supported combinations:
- `local install + local data`
- `local install + cloud data`
- `cloud install + cloud data`

Not supported as a first-class runtime shape:
- `cloud install + local data`

The current hosted/runtime direction is:
- a hosted app runtime
- object storage for runtime data
- optional auth and account services

In `RUNTIME_MODE=cloud`, the runtime:
- eagerly syncs only small metadata files to local cache
- queries parquet directly from object storage via DuckDB `httpfs`
- does not sync the full parquet tree at startup

Hosted deployment topology, release lanes, and operator control-plane details
belong in private deployment notes.

That means the same codebase can be used in:
- full local-data mode
- hosted-style cloud-data mode

## Guest And Logged-In Behavior

Guest users can open the app and try the public workflow without logging in.

Logged-in users currently get:
- authenticated session identity
- user-scoped frontend persistence
- user-scoped backend session cache
- account-owned settings and login on `daedalmap.com`

The public app no longer owns the account/settings UI.
`app.daedalmap.com` stays focused on the runtime and map engine, while `.com`
owns login, account, billing, and admin/runtime control-plane views.

## Quick Start

### 1. Install dependencies

```powershell
cd county-map
pip install -r requirements.txt
```

### 2. Add environment variables

Create a `.env` file for local development. The minimum useful local setup is:

```env
ANTHROPIC_API_KEY=your_key_here
DATA_ROOT=C:/path/to/your/local/data
```

You can use `OPENAI_API_KEY` instead of `ANTHROPIC_API_KEY` if that is your preferred provider.
If you leave `DATA_ROOT` blank, DaedalMap uses the default local app-data path and expects your data to live there.

Hosted-style object-storage configuration is intentionally deployment-specific.
For public self-hosting, start with local data. Operators who run a cloud-backed
deployment should provide their own object-storage bucket, endpoint, and
credentials through environment variables.

Most local users should leave these blank unless they intentionally want overrides:

```env
DATA_ROOT=
APP_URL=
SITE_URL=
```

What they mean:
- `DATA_ROOT`
  only used in `RUNTIME_MODE=local`; leave blank to use the default local app-data folder
- `APP_URL`
  optional advertised app URL; leave blank for normal local runs
- `SITE_URL`
  optional website/docs/account URL override; leave blank for normal local runs

If you are configuring your own hosted deployment, set:

```env
INSTALL_MODE=cloud
RUNTIME_MODE=cloud
PORT=7000
```

If you want optional Supabase-backed auth locally:

```env
SUPABASE_URL=...
SUPABASE_ANON_KEY=...
```

Keep service-role keys server-side only. They are not needed for ordinary local
evaluation.

### 3. Run the app

```powershell
python app.py
```

Open:
- `http://localhost:7000`

## API Discovery

The runtime exposes discovery and query endpoints on your local instance.

Discovery (no auth, no payment):

- `GET /api/v1/guide`
- `GET /api/v1/catalog`
- `GET /api/v1/packs/{pack_id}`

Execution:

- `POST /api/v1/query/dataset`

Self-host instances return `commercial_access_unavailable` for the paid execution lane unless a commercial verifier is configured. Discovery endpoints work without additional setup.

For managed data access via the hosted API or MCP, see [daedalmap.com/docs/for-agents](https://daedalmap.com/docs/for-agents).

## Data Resolution

The runtime resolves behavior from two explicit modes:

1. `INSTALL_MODE`
   controls deployment defaults like writable directories and default URLs
2. `RUNTIME_MODE`
   controls the data plane

Data mode behavior:

1. `RUNTIME_MODE=local`
   uses `DATA_ROOT`
2. `RUNTIME_MODE=cloud`
   uses the hydrated