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 making geographic references interoperable:

- MCP endpoint: `https://app.daedalmap.com/mcp` (streamable HTTP)
- Start with `help` for guided onboarding, then use the free geography tools to
  identify reference systems, transform coordinates or boundaries, build
  crosswalks, and assign stable `loc_id` values
- Bring your own data, make its geography `loc_id` compatible, and join it to
  other prepared data or DaedalMap's maintained data packs
- Download geometry and work locally, call the hosted MCP, or self-host this
  open runtime
- Discover current data packs with `get_catalog` and current geometry coverage
  with `read_geometry_catalog`; coverage can grow without changing the MCP entry
  point or workflow
- Some execution lanes are free and licensed commercial lanes challenge through
  x402 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)
- optionally, an LLM API key for the built-in local chat UI

Hosted account wiring and private verifier endpoints are optional
for self-host use. Hosted collector scheduling and scheduled-jobs hosts such as
the private DigitalOcean nightly box are not part of this public repo.

## 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

For the smallest GitHub/local setup:

```powershell
Copy-Item .env.example .env
```

Then edit `DATA_ROOT`. The minimum local configuration is:

```env
DEPLOYMENT=local
INSTALL_MODE=local
RUNTIME_MODE=local
DATA_ROOT=C:/path/to/your/local/data
```

If you leave `DATA_ROOT` blank, DaedalMap uses the default local app-data path and expects your data to live there.
No S3, R2, AWS, database, account, or hosted-control-plane configuration is
needed for this path.

No model API key is required for local data operations. Set
`OPENAI_API_KEY` or `ANTHROPIC_API_KEY` only for the built-in local chat UI.
For research using the model from an MCP-capable subscription client, see
[docs/RESEARCH_MCP.md](docs/RESEARCH_MCP.md).

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 hosted account behavior, connect this runtime to your own auth,
database, and analytics stack or to a separate private control plane you
operate. Those business-side services are intentionally not bundled here.

### 3. Run the app

```powershell
python app.py