DaedalMap

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

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

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

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

Global Indicators

Country-Specific Sources

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

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:

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:

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:

INSTALL_MODE=cloud
RUNTIME_MODE=cloud
PORT=7000

If you want optional Supabase-backed auth locally:

SUPABASE_URL=...
SUPABASE_ANON_KEY=...

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

3. Run the app

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.

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 local cloud cache as DATA_ROOT

Default local writable folders on Windows:

• CONFIG_DIR=%LOCALAPPDATA%\DaedalMap\config

• STATE_DIR=%LOCALAPPDATA%\DaedalMap\state

• CACHE_DIR=%LOCALAPPDATA%\DaedalMap\cache

• LOG_DIR=%LOCALAPPDATA%\DaedalMap\logs

• PACKS_ROOT=%LOCALAPPDATA%\DaedalMap\packs

• DATA_ROOT=%LOCALAPPDATA%\DaedalMap\data

In hosted/cloud mode:

• metadata is cached locally

• parquet is queried remotely from object storage

That makes local cloud-mode testing useful for reproducing hosted-runtime behavior before deploy.

Important note:

• the current public repo does not include a bundled data/ demo tree

• a source checkout therefore needs either DATA_ROOT in local mode, or RUNTIME_MODE=cloud with cloud storage configured

• for a usable chat experience, you should also set OPENAI_API_KEY or ANTHROPIC_API_KEY

Data And Pack Direction

The old “demo data folder plus converters” framing is no longer the whole story.

The current direction is:

• the engine stays open

• maintained data is packaged as packs

• packs are validated and promoted with explicit release gates

• runtime catalogs eventually depend on pack availability, installation, and entitlement state

Key concepts:

• available packs

• installed packs

• entitled packs

• active runtime catalog

These are intentionally distinct.

Explore And Research Contract

Explore chat and Research chat use different discovery paths:

• Explore starts from the runtime catalog, then selects sources.

• Research starts from the active corpus manifest or loaded artifacts, then selects sources.

After a specific source is selected, they should follow the same source contract:

• source-level temporal_coverage is discovery guidance

• metric-level metrics.{metric_id}.years is the execution truth

• default year windows, slider bounds, and metric year ranges should clamp to the selected metric when available

That shared source-specific logic now lives in mapmover/source_time_contract.py. Use that helper module for metric-aware year bounds instead of re-implementing time-range logic separately in Explore or Research code paths.

Settings Page

/settings now behaves differently depending on mode:

• hosted/account-aware mode: redirects to the paired account surface

• self-host/local mode: shows local runtime setup guidance

For self-host users, /settings is the in-app reminder page for:

• required LLM key setup

• current runtime/data/config paths

• the current state of local data vs future pack install flow

Useful Paths In This Repo

Important files and folders:

• app.py - FastAPI app entrypoint

• mapmover/ - runtime logic, routes, path helpers, DuckDB helpers

• static/ - frontend app modules and styles

• templates/ - app HTML shell

• supabase_client.py - auth/control-plane integration

• docs/ - local documentation for schemas, runtime notes, and reference material

Documentation In This Repo

Public runtime docs live in docs/README.md.

Recommended starting points:

• docs/LOCAL_AND_HOSTED.md - runtime mode selection and self-host basics

• docs/DATA_SCHEMAS.md - schema and loc_id conventions

• docs/APP_OVERVIEW.md - higher-level runtime/app overview

Local Development Modes

Useful local modes:

1. Full local-data mode

• points at your local DATA_ROOT

• best current self-host mode for GitHub users

2. Hosted-style S3 mode

• local server, but object-storage-backed data path

• best for reproducing hosted runtime behavior before deploy

3. Installed/runtime-pack mode

• planned product direction beyond raw source checkout

• engine/runtime installed separately from data packs

• pack selection and updates handled outside the repo clone flow

Contact

Questions, feedback, or self-host issues: support@daedalmap.com

License

MIT

If an agent or tool was pointed at this README for programmable access, use:

• Agent docs: https://daedalmap.com/docs/for-agents

• Machine-readable entry: https://daedalmap.com/llms.txt