interactive-map-builder

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

interactive-map-builder

★ 121 Open GitHub ↗

Build polished interactive maps and report-ready figures from spatial data with AI agents.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Interactive Map Builder

**Turn existing spatial data into polished, verified map products with an AI agent.**

[![CI](https://github.com/xlbaoxl/interactive-map-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/xlbaoxl/interactive-map-builder/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/xlbaoxl/interactive-map-builder)](https://github.com/xlbaoxl/interactive-map-builder/releases)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://raw.githubusercontent.com/xlbaoxl/interactive-map-builder/main/pyproject.toml)
[![MapSpec 1.1](https://img.shields.io/badge/MapSpec-1.1-0f766e)](https://raw.githubusercontent.com/xlbaoxl/interactive-map-builder/main/references/map-spec.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-2ea44f.svg)](https://raw.githubusercontent.com/xlbaoxl/interactive-map-builder/main/LICENSE)

[Live demos](https://xlbaoxl.github.io/interactive-map-builder/) ·
[中文说明](README.zh-CN.md) ·
[Releases](https://github.com/xlbaoxl/interactive-map-builder/releases) ·
[Changelog](CHANGELOG.md)

</div>

Interactive Map Builder is a **Codex-first Agent Skill** for turning GeoJSON, GeoPackage,
Shapefile, CSV, Excel, and ArcGIS data into portable map products. The Agent recognizes the goal
from ordinary language—even when the user never says GIS, Leaflet, web map, or the Skill name—then
inspects the data, closes only blocking requirements gaps, writes an auditable MapSpec, resolves
a restrained geometry-aware visual starting point, builds a self-contained Leaflet app, verifies
the result, and exports slide or paper figures only when requested.

```text
User intent + spatial data → inspect → confirm → MapSpec → build → verify → HTML + optional PNG/SVG/PDF
```

No frontend build system, no hand-written Folium page, and no hidden cleanup.

## Highlights

- **Intent-based activation** — recognizes requests such as “make this spreadsheet searchable on a
  map” or “combine roads, water, green space, and parking in one presentation page.”
- **Agent-guided setup** — works from the user's question and inspected data instead of requiring
  GIS terminology up front.
- **Deterministic builds** — the Agent writes MapSpec 1.1; the Python engine owns loading,
  normalization, visual resolution, rendering, and validation.
- **Atlas Studio Light defaults** — omitted visual values are resolved from geometry, coarse
  density, and layer role so the first result is coordinated without pretending to finish the
  designer's work.
- **Two polished map products** — a searchable map-and-list explorer and a toggleable multilayer
  explorer for points, lines, and polygons.
- **Portable local delivery** — Leaflet, interface code, and business geometry are embedded in one
  `map.html`; only online basemap tiles require a network connection.
- **Opt-in report exports** — generate 16:9 PNG or publication PNG/SVG/PDF from the same visual
  plan only when those files are explicitly requested.
- **Auditable handoff** — every build records inspection results, repairs, generated IDs,
  performance warnings, source notes, hashes, and portability.
- **Cached, non-mutating release preflight** — Skill tasks check the official Release at most once
  per 24 hours, never modify the running installation, and keep offline work unblocked.
- **Install self-check** — `interactive-map-builder doctor` runs a complete offline build and hash
  verification after installation.
- **Reliable map controls** — multilayer maps open in a neutral overview, use one compact layer
  selector for search focus, keep visibility switches separate, and provide CARTO Positron,
  OpenStreetMap Standard, plus a no-basemap fallback.
- **Cross-agent evaluation** — 40 English and Chinese cases cover activation, optional planning,
  local-versus-public delivery, and out-of-scope requests.

## Live demos

| Search, filter, compare | Explore independent layers |
| --- | --- |
| [![Parcel classification and statistics](https://raw.githubusercontent.com/xlbaoxl/interactive-map-builder/main/assets/screenshots/en-US/map-list.png)](https://xlbaoxl.github.io/interactive-map-builder/en-US/map-list/) | [![Multilayer point-line-polygon explorer](https://raw.githubusercontent.com/xlbaoxl/interactive-map-builder/main/assets/screenshots/en-US/multilayer.png)](https://xlbaoxl.github.io/interactive-map-builder/en-US/multilayer/) |
| **Map + list.** Search addresses and attributes, filter categories and numeric ranges, sort records, watch KPIs update, and inspect a selected parcel. | **Multilayer.** Start from a neutral overview, choose one layer to search and emphasize, toggle visibility independently, switch basemaps, and inspect feature details. |
| [Open live demo →](https://xlbaoxl.github.io/interactive-map-builder/en-US/map-list/) | [Open live demo →](https://xlbaoxl.github.io/interactive-map-builder/en-US/multilayer/) |

Both demos are generated by the repository's deterministic engine from fixed
[NYC Open Data snapshots](assets/examples/SOURCES.md); they are not separate design mockups.

## Ask for the outcome, not the tool

The Skill is designed to activate from requests like these:

```text
This Excel sheet has longitude and latitude. Make a browser page where I can search facilities,
filter by type, click a record, and share the result.
```

```text
Combine the parcel, road, water, green-space, and parking layers into one planning presentation
map with layer switches and object details.
```

```text
My colleagues do not have ArcGIS. Turn these existing layers into one HTML file and export a 16:9
figure for the meeting.
```

The user can still invoke `$interactive-map-builder` explicitly, but naming the Skill is not
required for a matching Agent task.

## Quick start

### 1. Install the Skill in Codex

Open a new Codex task and send:

```text
$skill-installer Install the Skill from https://github.com/xlbaoxl/interactive-map-builder and install its Python dependencies. Run interactive-map-builder doctor and interactive-map-builder update --preflight after installation.
```

Create a new task after installation. Restart Codex once only when the Skill does not appear.
Starting with v0.4.3, a repository-copy install can become update-managed automatically only when
all Release-owned files exactly match the checksum-verified official package.

### 2. Attach spatial data and describe the result

```text
Turn my attached spatial data into a searchable, filterable interactive map. Use English for the map audience and export a 16:9 presentation figure.
```

The Skill first inspects the inputs, then keeps a compact requirements checklist while choices
remain unresolved:

```markdown
- [x] Confirmed: supplied by the user or established by the data
- [~] Inferred: proposed by the Skill and easy to revise
- [ ] Needs confirmation: required before the build can start
```

It asks one consolidated round only for blocking choices such as CRS, template, primary layer,
category meaning, display fields, output formats, and audience locale.

### 3. Verify the installation

```bash
interactive-map-builder doctor
interactive-map-builder update --preflight
```

`doctor` creates a temporary coordinate table, builds a map without network access, verifies the
packaged Leaflet resources and output hashes, prints a JSON result, and removes the temporary
files. It does not download basemaps or send usage telemetry. The update command prints structured
JSON containing the local version, official version when known, source, installation type, and
status.
For a cached status-only query, run `interactive-map-builder update --check`.

Prefer `interactive-map-builder doctor` after installation. In a source checkout where the console
command is not yet available, use `python scripts/cli.py doctor`. The internal
`python scripts/map_builder.py --help` command intentionally lists only build commands and
must not be used to conclude that the package lacks `doctor`.

<details>
<summary><strong>Manual Git installation for zero-touch updates</strong></summary>

Use one active Codex Skill directory rather than keeping duplicate `.codex` and `.agents` copies.
A legacy Windows location may be `$HOME\.agents\skills`; archive it before using the active Codex directory below.

**Windows PowerShell**

```powershell
$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force "$CodexHome\skills" | Out-Null
git clone https://github.com/xlbaoxl/interactive-map-builder.git `
  "$CodexHome\skills\interactive-map-builder"
Set-Location "$CodexHome\skills\interactive-map-builder"
py -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight
```

**macOS or Linux**

```bash
CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_ROOT/skills"
git clone https://github.com/xlbaoxl/interactive-map-builder.git \
  "$CODEX_ROOT/skills/interactive-map-builder"
cd "$CODEX_ROOT/skills/interactive-map-builder"
python3 -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight
```

</details>

<details>
<summary><strong>Install from a versioned Release</strong></summary>

Every v0.3.1+ GitHub Release publishes:

- `interactive-map-builder-skill-vX.Y.Z.zip` — a lean Agent Skill package containing `SKILL.md`,
  Agent metadata, references, the deterministic engine, and its packaged web resources;
- a Python wheel and source archive for conventional package installation;
- `SHA256SUMS.txt` for release-asset verification and managed Skill updates.

The Skill ZIP intentionally excludes demos, screenshots, tests, and CI files. Extract it into an
Agent Skills directory, run `python -m pip install .`, then run `interactive-map-builder doctor`.

</details>

<details>
<summary><strong>Use with Claude Code or another Agent Skills client</strong></summary>

Copy the complete repository or the versioned Skill ZIP into a Skill or rules directory that the
client can read, let it load `SKILL.md`, and install the deterministic engine once:

```bash
python -m pip install .
interactive-map-builder doctor
```

The workflow is client-neutral: inspect data, maintain the requirements checklist, write the
canonical MapSpec, build with the packaged engine, verify, and deliver the complete `dist`
directory.

</details>

## Updates, planning, and public deployment

At the start of a Skill task, the Agent runs `interactive-map-builder update --preflight` from the
Skill root. This is a cached, check-only request: it reuses a valid result for up to 24 hours, never
modifies files, stays silent when the installed version is current, and reports only an available
update or a failed check. Offline access never blocks map construction. Set
`IMB_DISABLE_AUTO_UPDATE=1` to opt out.

Applying an update is a separate maintenance action. `update --apply` and the legacy non-fatal
`update --auto --force` retain checksum, manifest, exact-copy adoption, local-change protection,
duplicate-root refusal, post-install doctor verification, and rollback.

Versions v0.3.2–v0.4.2 do not contain the copy-adoption fix. An already installed unmanaged copy of
one of those versions needs one official v0.4.3 reinstall. Later compatible releases can then be
adopted and applied automatically.

Updates are transactional: after replacing a verified release, the updater reinstalls the engine
and runs the offline doctor. A failed install or doctor check restores the prior Git commit or the
previous manifest-owned files. Confirmed release metadata is preserved when application fails, so
an Agent cannot silently convert “an update is available” into “no update available.” See
[the verified update policy](references/update-policy.md).

For a genuinely complex Codex task—multiple independent layers, several unresolved design choices,
or coordinated HTML/slide/paper outputs—the Agent may suggest Plan mode once as an optional
convenience. It continues inspecting immediately whether or not the user switches, and clear
single-layer requests do not receive the suggestion.

The normal deliverable is a portable local `map.html`. “Share with colleagues” means sending that
file, not publishing embedded data on the internet. A public URL is discussed only when explicitly
requested, after confirming a hosting target and permission to expose the data. Hosting remains a
separate workflow from map construction.

## Atlas Studio Light

Version 0.4 introduces a lightweight visual-default resolver rather than a full automatic design
system. When MapSpec omits low-level visual values, the engine uses geometry family, coarse
feature/coordinate density, template role, and stable draw order to choose a restrained first
render:

- dense point layers use smaller symbols and lower fill intensity;
- lines and polygons receive separate weights, fills, and outlines;
- `map-list` primary layers stay prominent while context layers recede;
- multilayer maps open with all visible layers at their base style, then focus a layer only after the user selects it;
- HTML, legends, cards, PNG, SVG, and PDF consume the same resolved visual plan;
- automatic categorical colors stop at eight distinct classes instead of cycling into a rainbow.

Explicit MapSpec values always win. The goal is a credible, presentation-ready starting point—not
a replacement for a planner or designer. Users can keep refining color, size, opacity, fields, and
hierarchy through natural-language instructions or direct MapSpec edits. Every inferred decision
is recorded in `build_report.json` under `visual` and `visual_system`.

## Choose the right map product

| User goal | Template | Best for | Main interactions |
| --- | --- | --- | --- |
| Find, screen, rank, and compare records | `map-list` | Parcels, buildings, facilities, stores, projects, events, candidate sites | Search, category and numeric filters, sorting, KPI summaries, list-map linkage, detail panel |
| Explore several independent spatial themes together | `multilayer` | Boundaries, roads, routes, facilities, environmental layers, planning context | Layer visibility, layer-specific search, point/line/polygon styling, legends, basemap switching, feature details |

A `map-list` may also include context layers. With multiple inputs, the Skill never guesses the
business intent from geometry type alone; it asks the user to confirm the template and primary
layer.

## Basemaps and multilayer controls

New MapSpec files include two credential-free online basemaps: **CARTO Positron** as the quiet
default and **OpenStreetMap Standard** for detailed street context. The selector also includes
**No basemap**, and repeated tile failures automatically fall back to it, so business layers and
interactions remain usable without tiles. **Esri World Imagery** can be added only when the user
provides an authorized service URL or token and accepts that browser-delivered credentials can be
visible in the generated HTML.

In the multilayer product, visibility switches are kept in a fixed upper section. The legend is
stacked below them, scrolls when long, and starts collapsed at narrow widths, so a large categorical
legend cannot cover the layer controls.

## Supported inputs

| Input | Requirement |
| --- | --- |
| GeoJSON / JSON FeatureCollection | Geometry and CRS must be readable |
| GeoPackage | Select a layer when the package contains more than one candidate |
| Shapefile ZIP | One Shapefile dataset per ZIP; `.cpg`/GDAL encoding detection is preserved |
| CSV | Longitude/latitude columns or WKT geometry plus an explicit source CRS |
| Excel | Longitude/latitude columns or WKT geometry plus an explicit source CRS |
| ArcGIS FeatureServer | Downloaded to a local GeoJSON snapshot before rendering |

The inspection step reports feature count, geometry type, CRS, field samples, likely ID, label,
and category roles, ambiguities, and performance signals before a map is proposed.

## Deliverables

| File | Purpose |
| --- | --- |
| `map.html` | Portable local Leaflet map with embedded business geometry |
| `map_slide_16x9.png` | Presentation-ready 1920×1080 figure when the slide preset is enabled |
| `map_paper.png` / `.svg` / `.pdf` | Publication outputs when the paper preset is enabled |
| `map_spec.json` | Resolved, reusable build contract |
| `inspection.json` | Inputs, CRS, fields, candidate roles, and unresolved choices |
| `build_report.json` | Counts, repairs, warnings, performance metrics, hashes, and portability |
| `DELIVERY_MANIFEST.json` | Managed-file ownership, sizes, and SHA-256 values for transactional verification |
| `README_USAGE.md` | Localized handoff note for the final map recipient |

A normal build keeps source paths relative to the original project and treats `map_spec.json` as a
build record. Use `--bundle-sources` when the deliverable must rebuild independently after it is
moved.

## How it works

```text
User request + spatial files
           │
           ▼
       inspect inputs
  CRS · geometry · fields · scale
           │
           ▼
  confirm unresolved intent once
           │
           ▼
        MapSpec 1.1
           │
           ▼
 Atlas Studio Light resolver
 geometry · density · role · order
           │
           ▼
 deterministic Python engine
 load · normalize · render
           │
           ▼
 verify counts, files, QA hooks,
 provenance, hashes, and browser UI
           │
           ▼
  portable HTML + report figures
```

The packaged [JSON Schema](scripts/mapcore/resources/map-spec.schema.json) is the only
machine-readable MapSpec contract. Canonical keys use `snake_case`; unsupported fields and schema
versions are rejected instead of being silently migrated.

<details>
<summary><strong>Command-line workflow</strong></summary>

For one unambiguous layer:

```bash
interactive-map-builder run data.geojson --locale en-US --output dist
```

For an explicit, reproducible workflow:

```bash
interactive-map-builder inspect sites.geojson districts.geojson \
  --output inspection.json

interactive-map-builder init-spec inspection.json \
  --template map-list \
  --primary-layer sites \
  --locale en-US \
  --output map_spec.json

interactive-map-builder build --spec map_spec.json --out dist --bundle-sources
interactive-map-builder verify --dist dist
```

For independent point, line, and polygon layers, use `--template multilayer` and omit
`--primary-layer`.

</details>

## Scope

Interactive Map Builder focuses on **existing spatial data → finished map product**. It does not
currently provide:

- address geocoding;
- buffers, overlays, routing, site-selection models, or statistical inference;
- vector-tile services or million-feature WebGIS infrastructure;
- offline basemap acquisition;
- CRS guessing from coordinate ranges;
- 3D terrain, buildings, or digital twins;
- general maintenance of an existing custom Leaflet or React application;
- automatic public hosting without an explicit deployment request and data-publication approval.

For large GeoJSON payloads, the build report recommends `light` or `medium` geometry simplification
but does not silently switch rendering engines.

## Project status

The current stable release is **v0.4.4**. This stabilization release makes delivery transactional,
adds a managed-file manifest and strict verification, moves ordinary release preflight to cached
check-only behavior, limits ZIP extraction resources, and restricts manual Release runs to repairing
an existing tag. MapSpec remains 1.1 and cartographic behavior is unchanged.

See the [changelog](CHANGELOG.md) for completed work.

## Development

```bash
python -m pip install -r requirements-dev.txt
python scripts/evaluate_triggers.py validate
python -m pytest -q -m "not browser"
python -m playwright install chromium
python -m pytest -q -m browser
```

Build the localized demo site and lean Skill package:

```bash
python scripts/build_demo_site.py --output _site
python scripts/build_skill_package.py
```

The CI matrix covers Python 3.9, 3.10, and 3.12, trigger-suite validation, Chromium interaction
tests, wheel creation, the offline installation doctor, a clean out-of-repository build, and the
Skill distribution archive. After a new package version passes `main` CI, the Release workflow
creates the tag and assets or repairs an incomplete Release without moving an existing tag.

## License

[MIT](LICENSE)

interactive-map-builder

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README