MapSmith

# MapSmith

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22213091.svg)](https://doi.org/10.5281/zenodo.22213091)

[![CI](https://github.com/mapsmith-ai/MapSmith/actions/workflows/ci.yml/badge.svg)](https://github.com/mapsmith-ai/MapSmith/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mapsmith)](https://pypi.org/project/mapsmith/)
[![Container](https://img.shields.io/badge/ghcr.io-mapsmith--ai%2Fmapsmith-2496ED?logo=docker&logoColor=white)](https://github.com/mapsmith-ai/MapSmith/pkgs/container/mapsmith)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-654FF0)](https://modelcontextprotocol.io)
[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

**Ask a question about your data. Get an analysis — and the record that proves it.**

Most GIS servers hand an agent a tool to run. MapSmith takes the question, works out the
*analysis* — usually several operations, in an order that has to be right — validates the
plan before a single file is touched, runs it, and leaves a record of every step — which
bytes went in, with which parameters and CRS decisions, and which checks ran — that somebody
else can read afterwards and rerun to confirm.

### Try it

Point any MCP client at MapSmith ([one JSON block](#quickstart)) and ask, in your own words:

> Which parcels lie within 1.5 km of the river and sit at 120 m or lower? Give me the mean
> elevation and the ground area of each.

That is five operations, two coordinate systems and forty-eight checks. **[What actually
happens is below](#a-whole-analysis-start-to-finish)** — the plan, the step that gets
rejected for reading something a later step produces, the CRS decision behind every metric
step, and an answer you can work out on paper before MapSmith sees the files. That
rejection is structural, and so is every other one: a plan that is well formed and answers
the wrong question runs instead, which is
[measured and written down further down this page](#plans-reject-malformed-analyses-before-they-run).

The operations are executed by GeoPandas, DuckDB Spatial, exactextract and Whitebox
Workflows — never by the model that asked for them. Every dataset lands on disk next to a
lineage manifest: inputs with checksums, the exact parameters, the CRS decisions and *why*,
engine versions, and the deterministic checks that ran on the result.

**[mapsmith.dev](https://mapsmith.dev)** — a real terrain analysis and the manifest that came
with it. Both are build products: the figure is rendered from GeoTIFFs MapSmith writes, so the
page cannot drift from what the software does.

The manifest is a [specified format](https://github.com/mapsmith-ai/manifest-spec), not
MapSmith's private output: JSON Schema, a toolchain-free validator, a conformance suite, and a
hundred-line emitter that never imports MapSmith. Records carry `spec_version`, and CI validates
real MapSmith output against the spec's own validator. The specification is archived and citable
as [10.5281/zenodo.22205213](https://doi.org/10.5281/zenodo.22205213), a concept DOI that
resolves to the latest *archived* draft. Records written by 0.8.0 declare `1.0.0-draft.10`, and
0.7.x's declare `1.0.0-draft.8`; if the DOI shows an earlier one, the archive has not caught up, and the
[repository](https://github.com/mapsmith-ai/manifest-spec) holds the text they are written against. The names MapSmith puts
in a record beyond the ones the specification defines — every extension check name, and every
extension field in `crs_decisions` with the reason it is not a synonym of a key the specification
already has — are listed in [`docs/manifest-vocabulary.md`](docs/manifest-vocabulary.md),
generated from the source rather than maintained by hand.

Evidence before promises. A correctness suite in its own organisation,
[**Argleton**](https://argleton.org), grades MapSmith on thirty-one traps whose answers are
computed on paper before any system runs: **0.00 silent errors, nothing skipped**, against
0.9032 for the obvious way of writing the same code. The runs from 2026-08-30 to 2026-09-15 said
0.00 too, and on one trap they were wrong: its truth was wrong in MapSmith's favour for 26 days, the error was ours
twice over, and the [erratum](https://github.com/argleton/argleton/blob/main/results/README.md#erratum-2026-09-25-trap-024) says so. Every run since 2026-09-26, the current one
included, is scored against the corrected truth. Getting here cost seven defects the suite sent back, and they are listed. Alongside it: an [A/B on GABench](docs/benchmarks.md) whose
headline is a null result — with the analysis that took our own positive number apart —
[notebooks](examples/) on a real USGS DEM of Mount St. Helens, an
[in-chat map panel](#see-results-inside-the-chat) that shows the verification status of
every layer it draws, and a
[measurement of our own tool discovery](#finding-the-right-operation) that retracted two numbers
this page had already published — including the one in the bullet list below.

## A whole analysis, start to finish

This is the thing MapSmith is for, and it is not a single tool call. One question — six
parcels, a river, an elevation grid — becomes a plan of five operations chosen out of 77,
validated before anything runs, executed step by step, and recorded: the search that
narrowed the catalogue, the arguments that mattered, the CRS decision behind each metric
step, and the checks that ran on every result.

Nothing in this section is drawn. `benchmarks/worked_example.py` builds fixtures whose answer can
be worked out on paper, asks the catalogue in the words of the problem, validates and runs the
plan, reads the manifests, and writes what follows; `tests/test_worked_example.py` fails if this
page and that script disagree. The position column is BM25's rather than the default engine's,
because a published figure should not depend on whether a model download succeeded on the machine
that built the page — the narrowing, which is the point, is identical on both. Two things worth watching: the middle column, where the catalogue
goes from 77 operations to a handful the caller can read; and the CRS column, where every
metric operation says which coordinate system it moved the data into and why.

<!-- worked-example:start -->

```mermaid
flowchart TB
  ASK["<b>Parcels within 1.5 km of the river whose mean ground elevation is at most 120 m, with the elevation and the ground area of each</b>"]
  ASK --> PLAN{{"plan validated<br/>before anything runs"}}
  PLAN -. "rejected: FORWARD_REFERENCE" .-> BAD["'mask_path' references '$buffer' which runs later — move step 'buffer' before 'near'"]
  BAD:::bad
  BUFFER["<b>buffer_layer</b><br/>77 operations &rarr; 27 candidates &rarr; chosen<br/>CRS EPSG:32610<br/>9/9 checks"]
  PLAN --> BUFFER
  NEAR["<b>clip_layer</b><br/>77 operations &rarr; 12 candidates &rarr; chosen<br/>CRS EPSG:4326<br/>12/12 checks"]
  BUFFER --> NEAR
  HEIGHT["<b>zonal_statistics</b><br/>77 operations &rarr; 2 candidates &rarr; chosen<br/>CRS EPSG:4326<br/>7/7 checks"]
  NEAR --> HEIGHT
  AREA["<b>measure_area</b><br/>77 operations &rarr; 24 candidates &rarr; chosen<br/>CRS WGS 84 &#40;ellipsoidal&#41;<br/>10/10 checks"]
  HEIGHT --> AREA
  FILTER["<b>select_features</b><br/>77 operations &rarr; 24 candidates &rarr; chosen<br/>CRS EPSG:4326<br/>10/10 checks"]
  AREA --> FILTER
  OUT[["3 parcels, each with elevation and ground area"]]
  FILTER --> OUT
  classDef bad stroke-dasharray: 4 3
```

| what the agent asks for | it declares | candidates | picked | at position |
|---|---|---|---|---|
| “everything within one and a half kilometres of the river” | vector, dataset:vector, 1 dataset(s), line | **27** of 77 | `buffer_layer` | 2 |
| “keep only the parcels that fall inside that strip” | vector, dataset:vector, 2 dataset(s), polygon | **12** of 77 | `clip_layer` | 1 |
| “how high is the ground under each of these parcels” | raster, dataset:vector, 2 dataset(s), polygon | **2** of 77 | `zonal_statistics` | 2 |
| “how big is each one on the ground” | vector, dataset:vector, 1 dataset(s), polygon | **24** of 77 | `measure_area` | 1 |
| “drop the ones where the ground is above 120 metres” | vector, dataset:vector, 1 dataset(s), polygon | **24** of 77 | `select_features` | 2 |

| step | operation | arguments that mattered | CRS decision, recorded | checks |
|---|---|---|---|---|
| buffer | `buffer_layer` | `distance_meters=1500` | `EPSG:32610` — estimated UTM zone for metric buffering on a geographic CRS | 9/9 |
| near | `clip_layer` | `mask_path=$buffer` | `EPSG:4326` — the mask is already in the input layer's CRS; nothing was reprojected | 12/12 |
| height | `zonal_statistics` | `zones_path=$near`, `stats=['mean', 'min']` | `EPSG:4326` — zones and raster share the same CRS | 7/7 |
| area | `measure_area` | `input_path=$height`, `method=geodesic` | `WGS 84 (ellipsoidal)` — ground area computed on the WGS 84 ellipsoid, which is where the coordinates are put first; no map plane is involved, so no projection distortion enters | 10/10 |
| filter | `select_features` | `input_path=$area`, `by=field_between`, `field=mean`, `maximum=120` | `EPSG:4326` — no CRS change: selecting rows does not touch coordinates | 10/10 |

Every step is inside the plan, the last one included: `select_features` took 4 rows and returned 3, with a manifest like every other write. This step used to run outside the plan, because the only operation that could answer it was run_sql — which takes its inputs inside a SQL string, declares zero datasets, and therefore cannot join the plan's dataflow. That boundary is deliberate and has not moved: substituting `$step` into arbitrary strings would be a grammar in which a planner assembles a path out of text. What changed is that it is no longer the only way to ask.

**The answer**, which can be worked out on paper before MapSmith sees the files: the parcels are squares of 0.0015° at 46.2°N, so each is about 119 m by 167 m, and the elevation ramps