mapsmith 0.2.0__tar.gz → 0.2.1__tar.gz

{mapsmith-0.2.0 → mapsmith-0.2.1}/.gitignore

@@ -22,6 +22,12 @@ venv/
 *.provenance.json
 data/
 
+# Scratch databases: probing the DuckDB sandbox (ATTACH, COPY) drops these in
+# the repo root, and one of them reached a public commit before we noticed.
+*.db
+*.duckdb
+*.wal
+
 # OS / editors
 .DS_Store
 Thumbs.db

mapsmith-0.2.1/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to MapSmith are documented here, in the format of
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows
+[semantic versioning](https://semver.org/).
+
+## [0.2.1] — 2026-08-20
+
+Three fixes you would rather not find yourself. All came from reviewing 0.2.0
+*after* it shipped, and all were reproduced through the real MCP tools instead
+of read off a diff.
+
+### Fixed
+
+- **An empty spatial join no longer crashes before writing its manifest.**
+  DuckDB writes no GeoParquet `geo` metadata for a zero-row result, so reading
+  the output back raised — on the default engine path, for exactly the case the
+  verification checks exist to explain, while the tool description promised a
+  warning. A zero-row result is now written as a valid empty GeoParquet with the
+  analysis CRS and the joined schema, and the join goes through the same audited
+  writer as everything else, so the manifest exists even when a check fails.
+- **A GeoParquet declaring `crs: null` is no longer read as CRS84.** MapSmith
+  invented a coordinate system and recorded it in the manifest as fact, with
+  `verified: true` — the worst class of bug a provenance tool can have. The
+  GeoParquet spec distinguishes an *absent* `crs` field, which does mean CRS84,
+  from an explicit null, which means unknown; so does MapSmith now, and an
+  unknown CRS is refused by the preconditions like any other missing CRS.
+- **The DuckDB sandbox locks its configuration in every mode.** The lock used to
+  apply only under `MAPSMITH_WORKSPACE`, so a multi-statement call could switch
+  extension autoloading back on, and an explicit `LOAD httpfs` was never blocked
+  at all. Locking is now unconditional and DuckDB's HTTP and S3 filesystems are
+  disabled, while local reads keep working.
+- **The security documentation no longer claims that unconfined mode blocks
+  network egress.** It does not, and it never did: GDAL carries its own HTTP
+  client, so `ST_Read('/vsicurl/https://…')` in raw SQL reads whatever the host
+  can reach — internal services and metadata endpoints included — and the URL it
+  names can carry data out. Remote reads are deliberately available while the
+  server is unconfined, because cloud-native data is a feature; the claim that
+  the network was closed anyway was the bug. README and SECURITY.md now state
+  the price of that choice, and two tests pin both halves of it: without a
+  workspace the read succeeds, and with one it is refused *before any request
+  leaves*, asserted by counting requests at a loopback server instead of
+  matching an error message. If you do not trust your `run_sql` input, set a
+  workspace.
+- **The multi-layer guard fails closed.** A container whose layer list could not
+  be read looked like a single-layer file, and mechanical geometry repair would
+  then have destroyed the other layers while recording success.
+- **`execute_plan` reports `repairs` per step.** Geometry MapSmith rewrote was
+  visible in a single-operation result and invisible at plan level.
+- **Manifests record `EPSG:32632`, not 2.5 KB of PROJJSON**, when a GeoParquet
+  input carries its CRS as an embedded projection object.
+- **The example `docker-compose.yml` binds MinIO to loopback.** It published
+  ports 9000/9001 on every interface with the documented development
+  credentials.
+
+### Changed
+
+- **The provenance badge has three states instead of two.** "All critical checks
+  passed" is vacuously true when no critical check ran — a `run_sql` manifest,
+  for one — so an output whose only check had *failed* rendered with the same
+  green tick as a verified buffer. `provenance_summary` now reports `verified`,
+  `failed` or `unchecked`, with the reason, and the map panel renders all three.
+  The `verified` boolean stays in the payload, computed correctly, so a client
+  reading it gets a fix rather than a breaking change.
+- **The README says when *not* to use MapSmith**, and the
+  [benchmark results](docs/benchmarks.md) are linked from it — they were public
+  for a day with nothing pointing at them.
+
+## [0.2.0] — 2026-08-20
+
+The first release you can point an agent at and trust the answer: results are
+verified on the way in and on the way out, plans are checked before anything
+runs, and the server can be confined to a single directory.
+
+### Added
+
+- **Interactive map inside the chat.** `preview_map` renders your layers on a
+  pan/zoom map panel in any client implementing the
+  [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
+  extension (field-tested on Claude Desktop), with an OpenStreetMap backdrop
+  and a provenance card per layer showing operation, engine and one of three
+  states: `verified ✓`, `verification failed`, or `not verifiable` when no
+  critical check ran. Fully self-contained; on clients without MCP Apps the
+  same call returns structured data.
+- **Typed plans.** `validate_plan` statically checks a multi-step analysis —
+  operations exist and are installed, arguments complete and well-typed,
+  `$step` references resolve backwards, input files exist, outputs don't
+  collide, and the CRS of every intermediate is simulated from the real
+  inputs — and returns machine-actionable error codes. `execute_plan` then
+  runs the validated plan with per-step provenance plus a plan-level manifest
+  fingerprinting the exact plan that produced the result.
+- **Terrain and hydrology** on the Whitebox Workflows engine (`[whitebox]`
+  extra): `hillshade`, `flow_accumulation` (D8, with depression filling) and
+  `watershed` (many pour points at once).
+- **Zonal statistics** with exact fractional pixel coverage via exactextract
+  (`[raster]` extra).
+- **A searchable operation catalog.** `list_operations` ranks capabilities by
+  relevance (BM25) so an agent can discover what exists — including what is
+  planned but not yet available — instead of guessing from a wall of tools.
+- **Workspace confinement.** Set `MAPSMITH_WORKSPACE` and every path argument
+  must resolve inside it, `run_sql`'s DuckDB connection is sandboxed to that
+  directory with extension loading refused and memory/temp-disk capped, and
+  UNC hosts and NTFS alternate data streams are refused in every mode.
+- **Verification on the way in.** Operations check their inputs for the
+  failures that produce plausible junk: a missing CRS is refused outright, and
+  empty inputs or extents that cannot possibly intersect come back as named
+  warnings with hints — in the tool result, not only in the manifest.
+- **Bounded deterministic repair.** Mechanically broken output geometry is
+  repaired (`make_valid`, at most two rounds, written atomically) and every
+  attempt is recorded in the manifest: a repaired output never looks like one
+  that was right the first time.
+- **A notebook gallery** (`examples/`) and a
+  [benchmarks page](docs/benchmarks.md) with the harness that produced it.
+
+### Fixed
+
+- **Wrong terrain results from ordinary compressed rasters.** Whitebox
+  Workflows 2.x does not undo the TIFF predictor when reading, so any DEM
+  saved with `PREDICTOR=2` or `3` — the standard encoding for elevation data —
+  produced hillshades and flow accumulations that looked like terrain and were
+  not. MapSmith now detects the predictor and converts the input first,
+  recording it in the manifest.
+  ([upstream report](https://github.com/jblindsay/whitebox_next_gen/issues/32))
+- **GeoParquet outputs from the vector engines** were written through a GDAL
+  path that produced unreadable files.
+- `run_sql` materialisations and the DuckDB/SedonaDB join fast paths now run
+  the same deterministic verification as every other writer, and record their
+  CRS decisions.
+
+### Changed
+
+- `spatial_join` with `engine="auto"` falls back to GeoPandas when the inputs'
+  CRS differ or are unknown, instead of joining mismatched coordinates.
+- The planning-failure figure quoted in the docs is stated as the upper bound
+  it is ("up to ~47%"), since the underlying study counts errors multi-label.
+
+## [0.1.0] — 2026-08-18
+
+First public release: the engine dispatcher (SedonaDB / DuckDB / GeoPandas),
+`run_sql`, the job ledger, stateless Streamable HTTP transport, and provenance
+manifests with deterministic verification on every writer.

{mapsmith-0.2.0 → mapsmith-0.2.1}/CLAUDE.md

@@ -19,6 +19,10 @@ MapSmith gives AI agents professional-grade geoprocessing via MCP, with **verifi
 - Version pins are deliberate: `mcp>=1.26,<2` (1.26 is the floor for resource `meta`, needed by the MCP Apps map panel; v2 renamed FastMCP→MCPServer; migration planned with MCP Tasks), `ruff>=0.16,<0.17` (new ruff minors add default rules and break CI).
 - Tests use closed-form expected values (e.g., a known 5×5 raster block → mean=22, sum=550) plus rejection-path tests; `pytest.importorskip` for extras.
 - Run `python -m ruff check .` before committing; CI runs lint + tests on Python 3.10/3.12 + Docker build.
+- **The floor is Python 3.10**, and local runs happen on a newer interpreter, so stdlib added
+  after 3.10 breaks only in CI: no `tomllib`, `datetime.UTC`, `StrEnum`, `contextlib.chdir`,
+  `ExceptionGroup` (3.11), no `itertools.batched`, `typing.override` (3.12). Ruff's
+  `target-version` catches too-new *syntax*; too-new *modules* are on you.
 - Docker (or `uvx` where wheels work) is the only supported install path — keep it true in docs.
 - Verify external-library APIs against primary documentation before coding against them; this repo has already been bitten by from-memory APIs three times.
 

{mapsmith-0.2.0 → mapsmith-0.2.1}/MANIFESTO.md

@@ -12,7 +12,7 @@ name under. These are the commitments that follow from taking that seriously.
 ## 1. Engines compute. Models orchestrate.
 
 Every geometry and every number in a MapSmith result comes from executing a
-deterministic engine — GDAL, GeoPandas, DuckDB Spatial, WhiteboxTools,
+deterministic engine — GDAL, GeoPandas, DuckDB Spatial, Whitebox Workflows,
 SedonaDB. None
 of it is generated by a model, ever. The model's job is to decide *what* to
 run; it is never asked to produce a coordinate. This is the line that
@@ -38,8 +38,9 @@ that passed.
 
 ## 4. Coordinate systems are stated, never assumed.
 
-Silent CRS mismatch is the largest single cause of confidently wrong
-geospatial analysis. MapSmith refuses inputs without a CRS, never runs metric
+A silent CRS mismatch is the classic way a geospatial analysis comes out
+confidently wrong: the arithmetic succeeds, the map looks plausible, and the
+numbers mean nothing. MapSmith refuses inputs without a CRS, never runs metric
 operations on degrees without a declared reprojection, and writes the reason
 for every transformation into the manifest.
 
@@ -71,14 +72,15 @@ engine actually ran goes in the manifest.
 ## 7. Your data stays on your machine.
 
 No telemetry, no phoning home, no dataset uploads: MapSmith runs beside your
-data — on a laptop, in a container, on your own infrastructure. Two outbound
-requests exist and we would rather name them than have you find them: the
-in-chat map panel fetches OpenStreetMap background tiles (which reveals the
-map view you are looking at, and falls back to a plain background when the
-host blocks it), and the SQL engine downloads its spatial extension once per
-environment. Neither carries your datasets, and both are avoidable — skip the
-panel, pre-install the extension. The
-provenance manifests it produces belong to you, and they happen to be exactly
+data — on a laptop, in a container, on your own infrastructure. MapSmith itself
+makes two outbound requests, and we would rather name them than have you find
+them: the in-chat map panel fetches OpenStreetMap background tiles (which
+reveals the map view you are looking at, and falls back to a plain background
+when the host blocks it), and the SQL engine downloads its spatial extension
+once per environment. Neither carries your datasets, and both are avoidable —
+skip the panel, pre-install the extension. What an *agent* can reach through
+the SQL engine is a separate question, answered precisely in `SECURITY.md`.
+The provenance manifests MapSmith produces belong to you, and they happen to be exactly
 the kind of record an audit asks for: what ran, on what inputs, with what
 parameters, verified how. The EU AI Act's traceability obligations for
 high-risk systems are not a burden if your tooling produces that trail as a

mapsmith-0.2.1/PKG-INFO

@@ -0,0 +1,410 @@
+Metadata-Version: 2.5
+Name: mapsmith
+Version: 0.2.1
+Summary: Professional-grade geoprocessing for AI agents via MCP, with verifiable provenance
+Project-URL: Homepage, https://github.com/mapsmith-ai/MapSmith
+Project-URL: Repository, https://github.com/mapsmith-ai/MapSmith
+Author-email: MapSmith <mapsmith@proton.me>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: ai-agents,geoprocessing,geospatial,gis,mcp,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=1.4
+Requires-Dist: geopandas>=1.1.2
+Requires-Dist: mcp<2,>=1.26
+Requires-Dist: pyarrow>=17
+Requires-Dist: pyogrio>=0.9
+Requires-Dist: pyproj>=3.6
+Requires-Dist: shapely>=2.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Provides-Extra: raster
+Requires-Dist: exactextract>=0.2; extra == 'raster'
+Requires-Dist: rasterio>=1.3; extra == 'raster'
+Provides-Extra: sedona
+Requires-Dist: apache-sedona[db]>=1.9; extra == 'sedona'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'test'
+Provides-Extra: whitebox
+Requires-Dist: whitebox-workflows<3,>=2.0.6; extra == 'whitebox'
+Description-Content-Type: text/markdown
+
+# MapSmith
+
+[![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)
+
+**Professional-grade geoprocessing for AI agents — with provenance you can verify.**
+
+MapSmith is an open-source [MCP](https://modelcontextprotocol.io) server that gives an AI
+agent real GIS analysis — buffers, overlays, reprojections, zonal statistics, terrain and
+hydrology — executed by GeoPandas, DuckDB Spatial, exactextract and Whitebox Workflows,
+never written by the model. Every dataset it produces 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.
+
+> Ask for the result. The agent picks the tools. You can check the work afterwards.
+
+Evidence before promises: 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, and an
+[in-chat map panel](#see-results-inside-the-chat) that shows the verification status of
+every layer it draws.
+
+## Quickstart
+
+Add MapSmith to any MCP client over stdio (Claude Desktop, Claude Code, Cursor, VS Code):
+
+```json
+{
+  "mcpServers": {
+    "mapsmith": {
+      "command": "uvx",
+      "args": ["mapsmith"]
+    }
+  }
+}
+```
+
+Docker is the supported path, and confines the server to the directory you mount:
+
+```json
+{
+  "mcpServers": {
+    "mapsmith": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm",
+               "-v", "/absolute/path/to/your/data:/data",
+               "-e", "MAPSMITH_WORKSPACE=/data",
+               "ghcr.io/mapsmith-ai/mapsmith"]
+    }
+  }
+}
+```
+
+One-click installs:
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=mapsmith&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtYXBzbWl0aCJdfQ%3D%3D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MapSmith-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mapsmith&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mapsmith%22%5D%7D)
+
+or from a terminal: `code --add-mcp '{"name":"mapsmith","command":"uvx","args":["mapsmith"]}'`
+
+To check it runs before wiring a client, `uvx mapsmith` starts the server on stdio
+(Ctrl-C to quit) — it speaks MCP, not a CLI, so a silent prompt means it is working.
+
+Then ask your agent things like:
+
+> "Take parcels.gpkg, keep only the parcels within 300 m of the river in rivers.gpkg, and
+> give me the result with the analysis lineage."
+
+The Docker image includes the `[raster]` and `[whitebox]` extras. With `uvx`, pick your
+own: `uvx --from "mapsmith[raster,whitebox]" mapsmith`. **Docker — or `uvx` on a machine
+with working wheels — is the only supported installation path**: geospatial native
+dependencies across three OSes are a support black hole, and issues about broken local
+environments will be redirected here.
+
+## What you get back
+
+Every dataset comes with the file below, written next to it as
+`<output>.provenance.json` — enough to re-run the analysis without the model that asked
+for it:
+
+```json
+{
+  "mapsmith_version": "0.2.1",
+  "operation": "buffer_layer",
+  "parameters": {"distance_meters": 300.0},
+  "inputs": [{"path": "rivers.gpkg", "sha256": "9f2c…", "crs": "EPSG:4326"}],
+  "crs_decisions": {"analysis_crs": "EPSG:32632", "reason": "estimated UTM zone for metric buffering"},
+  "engine": {"name": "geopandas", "version": "1.0.1"},
+  "started_at": "2026-08-18T10:15:03Z",
+  "finished_at": "2026-08-18T10:15:04Z"
+}
+```
+
+The full manifest also carries the verification checks that ran, and any geometry MapSmith
+had to repair. `get_provenance` returns it for any output.
+
+## Why MapSmith
+
+- **Real geoprocessing, not map CRUD.** Built on the proven open geospatial stack: GDAL,
+  GeoPandas, Shapely, DuckDB Spatial, Whitebox Workflows and exactextract ship today
+  (more to come: PDAL, QGIS Processing via sidecar).
+- **Provenance by design.** Every layer MapSmith produces ships with a machine-readable
+  lineage manifest — source datasets with checksums, tools executed, exact parameters, CRS
+  decisions, software versions, timestamps. Everything needed to re-run the analysis
+  without the LLM is in there. No AI slop.
+- **The engines compute, the model orchestrates.** Geometry and numbers only ever come
+  from deterministic tool executions — never from model output.
+- **Semantic tools, not a tool dump.** 16 goal-level tools plus a searchable operation
+  catalog (progressive discovery), because agent accuracy collapses when you expose
+  hundreds of raw tools.
+- **Model-agnostic infrastructure.** Claude, GPT, Qwen, Kimi, GLM — anything that speaks
+  MCP, cloud or local. The leverage is better contracts (typed plans, actionable error
+  codes, a searchable catalog), not weights we would have to maintain. See
+  [the manifesto](MANIFESTO.md).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `describe_dataset` | CRS, geometry types, schema, extent, feature count of any vector dataset |
+| `buffer_layer` | Metric buffer with automatic UTM estimation for geographic CRS |
+| `clip_layer` | Clip a layer with a mask layer |
+| `reproject_layer` | Reproject to any CRS (EPSG code or WKT) |
+| `spatial_join` | Join by spatial predicate, auto-routed to the fastest engine (SedonaDB > DuckDB > GeoPandas) |
+| `run_sql` | Spatial SQL (DuckDB dialect) over GeoParquet and GDAL formats |
+| `zonal_statistics` | Raster statistics per vector zone with exact fractional pixel coverage (`[raster]` extra) |
+| `hillshade` | Shaded relief from a DEM, in-memory Whitebox engine (`[whitebox]` extra) |
+| `flow_accumulation` | D8 flow accumulation with automatic depression filling (`[whitebox]` extra) |
+| `watershed` | Watershed delineation from a DEM and pour points (`[whitebox]` extra) |
+| `preview_map` | Interactive in-chat map (MCP Apps) of any datasets, with a provenance card and verification status per layer |
+| `validate_plan` | Statically validate a multi-step plan before running anything: operations, arguments, references, input files, simulated CRS flow |
+| `execute_plan` | Validate then run a plan step by step, with per-step provenance and a plan-level manifest |
+| `get_provenance` | Return the full lineage manifest of any MapSmith output |
+| `list_operations` | BM25-ranked catalog search; `detail=true` returns parameters and worked examples |
+| `server_info` | Version, license, available engines |
+
+## Verification, in and out
+
+Every tool that writes a dataset also writes `<output>.provenance.json` beside it and
+verifies its own work — CRS agreement, geometry validity, raster dimensions, count and
+extent invariants — recording the results in the manifest *before* raising anything, so
+the audit trail survives the error.
+
+Verification runs on the way in as well. Before an operation touches your data, MapSmith
+checks the failures that produce *plausible* junk: an input with no CRS is refused
+outright, because metric maths on unknown units is how a confidently wrong answer gets
+made; an empty input, or two layers whose extents cannot possibly overlap, comes back as
+a named warning with a hint — in the tool result, not only in the manifest, so the agent
+sees it instead of assuming success. (The join fast paths, DuckDB and SedonaDB, only ever
+receive inputs that already share a known CRS; they verify their output and diagnose an
+empty join.)
+
+An output whose geometry is *mechanically* broken — typically invalidity inherited from an
+invalid input — is repaired deterministically: `make_valid`, at most two rounds, written
+to a temporary file and swapped in only once it is complete, and skipped rather than
+risked where a rewrite could drop data (a multi-layer GeoPackage is refused, not
+rewritten). Every attempt lands in the manifest *and* in the tool result, because a
+repaired output must never look like one that was right the first time. Failures that need
+judgement are never "fixed": an empty result, or geometries eroded away by a wrong
+distance, come back as warnings with hints for the agent to act on.
+
+## See results inside the chat
+
+![MapSmith's interactive map panel rendered inside Claude Desktop: OSM basemap, buffer and zone layers, and per-layer provenance cards with verification status](docs/images/map-panel.png)
+
+`preview_map` renders your layers on an interactive map panel *inside* the chat — pan,
+zoom, toggle layers, and read each layer's provenance card (operation, engine, and one of
+three honest states: `verified ✓`, `verification failed`, or `not verifiable` when no
+critical check ran) right next to the geometry it explains. Field-tested on Claude
+Desktop; it renders in any client that implements the official
+[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) extension, and on
+clients without it the same call returns the preview as structured data.
+
+The panel is self-contained — no CDN, no bundled libraries, no telemetry — with one
+outbound request named here rather than buried: the OpenStreetMap background tiles, which
+reveal the map view you are looking at (never your data) and which the panel drops to a
+plain backdrop when the host blocks them. The preview is deliberately lossy (simplified
+geometry, capped feature counts): the dataset of record stays on disk with its manifest.
+
+## Plans: reject wrong analyses before they run
+
+In [GISAgentBench](https://arxiv.org/abs/2608.01645) — 349 practitioner-sourced tasks over
+128 GIS APIs — the best frontier agent completes 32.7% of tasks under strict scoring, and
+planning defects dominate the failures: missing operations in 28.3% of failed runs and
+wrong operation order in 18.4% (multi-label, so up to ~47% involve a planning mistake),
+against 7.8% for parameter errors. MapSmith attacks this where it is cheapest: the agent
+submits a **typed plan**, and static validation rejects unknown operations (with
+suggestions), missing arguments, forward references, absent input files and CRS-unsuitable
+steps **before anything executes** — with machine-actionable error codes the agent can
+repair.
+
+```json
+{
+  "goal": "buildings within 300 m of rivers",
+  "steps": [
+    {"id": "buf", "operation": "buffer_layer",
+     "arguments": {"input_path": "rivers.gpkg", "distance_meters": 300,
+                   "output_path": "rivers_300m.parquet"}},
+    {"id": "cut", "operation": "clip_layer",
+     "arguments": {"input_path": "buildings.parquet", "mask_path": "$buf",
+                   "output_path": "at_risk.parquet"}}
+  ]
+}
+```
+
+`"$buf"` consumes the output of step `buf`; references may only point backwards, so plans
+are acyclic by construction. `validate_plan` also simulates the CRS of every intermediate
+dataset from the real input files. `execute_plan` then runs the chain with per-step
+provenance plus a plan-level manifest (`<output>.plan.json`) fingerprinting the exact plan
+that produced the result.
+
+## Confinement
+
+UNC hosts and NTFS alternate data streams are refused in every path *argument* of every
+tool call, before anything touches the filesystem (on Windows even an existence check on a
+UNC path talks to an attacker-chosen host). Remote and virtual forms — GDAL `/vsi*`,
+`https://` COGs — stay available while the server is unconfined, because cloud-native data
+is a feature, and are refused once a workspace is set. Validated plans are stricter by
+design and reject every non-local form.
+
+Set `MAPSMITH_WORKSPACE=/data` to confine the server to one directory:
+
+- every path argument of every tool must resolve inside the workspace (checked at the MCP
+  boundary, and again by plan validation with stable error codes);
+- the `run_sql` DuckDB connection is sandboxed in the engine itself, because SQL text is
+  out of reach of a textual path check: filesystem whitelisted to the workspace
+  (`allowed_directories` + external access off, which also covers GDAL-backed `ST_Read`),
+  extension install and load refused, memory and temp disk capped
+  (`MAPSMITH_DUCKDB_MEMORY`, default 4GB; `MAPSMITH_DUCKDB_TEMP_LIMIT`, default 8GB),
+  configuration locked. SQL can name any path it likes; the engine refuses to open it.
+
+Without a workspace, *file* access is deliberately unconfined — fine for a local stdio
+server on your own files — and plan validation flags `run_sql` steps with a
+`SQL_NOT_SANDBOXED` warning. Code execution is still closed: extension autoloading and
+community extensions are off (`shellfs` turns a filename into a shell command), unsigned
+extensions are refused, DuckDB's HTTP and S3 filesystems are disabled, and the
+configuration is locked, so untrusted SQL cannot turn file access into code execution.
+
+**The network is not closed in that mode, by the same decision that keeps cloud-native
+data working**: GDAL carries its own HTTP client, so `ST_Read('/vsicurl/https://…')` in raw
+SQL reads whatever the host can reach — internal services and link-local metadata
+endpoints included — and the URL is chosen by whoever wrote the SQL, so it can also carry a
+string out. Setting `MAPSMITH_WORKSPACE` closes all of it, GDAL included, and the test
+suite asserts both halves (`tests/test_duckdb_sandbox.py`). If your `run_sql` input is not
+trusted and your host sits somewhere interesting, set a workspace. The full threat model —
+and what is explicitly *not* covered — is in [SECURITY.md](SECURITY.md).
+
+Fine print, because it changes how you deploy this: the path jail assumes a single trusted
+writer of the workspace filesystem (paths are resolved at check time, so a symlink swap by
+another local process is out of scope); the DuckDB spatial extension is fetched once per
+environment, so on air-gapped machines pre-install it (`python -c "import duckdb;
+duckdb.connect().install_extension('spatial')"`) before locking the network down; and the
+HTTP transport has no authentication in this release, so keep it on loopback or a trusted
+network. For real isolation, run the container and mount only the data you want it to see.
+
+## We measured whether this actually helps
+
+Claims about agent performance are cheap, so
+[**docs/benchmarks.md**](docs/benchmarks.md) reports an A/B on
+[GABench](https://github.com/GeoX-Lab/GABench) — 57 executable GIS tasks over a
+133-tool server, scored by its deterministic evaluator — where the *only*
+variable is whether the agent's typed plan is validated before the solver runs.
+
+The honest headline is a **null result**, on a frontier model and on a small
+one, and the interesting part is why:
+
+| | Arm A (no gate) | Arm B (gate) |
+|---|---|---|
+| Sonnet 5 — TAO / PEA | 0.824 / 0.430 | 0.781 / 0.425 |
+| Haiku 4.5 — TAO / PEA | 0.660 / 0.320 | 0.714 / 0.366 |
+
+Haiku looks like a clean win until you notice the gate only fired on 4 of 57
+plans, and that the 53 tasks it never touched moved by just as much: the
+aggregate delta is run-to-run variance, and measuring that noise floor
+(2–5 points per metric on a single repetition) is the reusable result. What
+survives is narrower — on the plans it did repair, tool selection improved by
++0.19 TAO — and it points at where the failures actually are: PEA around 0.4
+in every arm, i.e. wrong parameters and missing outputs at *execution* time,
+which is why MapSmith enforces its plans at the execution boundary and verifies
+inputs and outputs at runtime rather than advising an agent that improvises.
+
+The harness is in [`benchmarks/gabench-ab/`](benchmarks/gabench-ab/), including
+the `split_analysis.py` that took our own win apart.
+
+## Notebook gallery
+
+Three executable walkthroughs in [`examples/`](examples/): verified buffer+clip with
+provenance manifests, terrain and hydrology on a real 520×520 USGS DEM of **Mount St.
+Helens**, and a deliberately wrong plan rejected before execution and then repaired. The
+terrain notebook also shows what happens when reality bites: that DEM is stored with the
+standard TIFF predictor, which Whitebox Workflows 2.x does not undo when reading
+([upstream report](https://github.com/jblindsay/whitebox_next_gen/issues/32)), so MapSmith
+detects it, converts the input first, and discloses the workaround in the manifest.
+
+## Architecture
+
+```
+ AI agent (Claude / ChatGPT / Copilot / your app)
+        │  MCP (stdio local · Streamable HTTP remote)
+        ▼
+ ┌─────────────────────────────────────────────┐
+ │ MapSmith server                             │
+ │  · semantic tools + operation catalog       │
+ │  · parameter validation, CRS discipline     │
+ │  · provenance recorder (lineage manifests)  │
+ ├─────────────────────────────────────────────┤
+ │ Engines                                     │
+ │  · vector: GeoPandas/Shapely (built-in)     │
+ │  · SQL/analytics: DuckDB Spatial (built-in) │
+ │  · heavy joins: SedonaDB ([sedona] extra)   │
+ │  · zonal stats: exactextract ([raster])     │
+ │  · terrain/hydro: Whitebox NG ([whitebox])  │
+ │  · qgis_process / GRASS sidecar (roadmap,   │
+ │    GPL-isolated via subprocess)             │
+ └─────────────────────────────────────────────┘
+```
+
+## When not to use MapSmith
+
+- **You need an authenticated remote server today.** The Streamable HTTP transport has no
+  authentication in this release: anyone who can reach the endpoint can run every tool
+  against everything the process can see. Loopback or a trusted network only
+  ([SECURITY.md](SECURITY.md)).
+- **You want a sandbox for arbitrary agent code.** MapSmith confines paths and the SQL
+  engine; there is no code-execution tool yet, and a path jail is not a container.
+- **You need cartography.** No styling, no layouts, no print composer. Outputs are
+  datasets, plus a lossy read-only preview panel — not maps you publish.
+- **Your data lives in a database.** MapSmith reads and writes files (GeoParquet,
+  GeoPackage, anything GDAL opens). There is no PostGIS engine and no database catalog —
+  the `[postgres]` extra is for the optional job ledger, not for data.
+- **You want the full breadth of a desktop GIS.** 16 tools plus a catalog that tells the
+  agent what does *not* exist yet. The ~900 QGIS Processing algorithms are on the roadmap,
+  not in the box.
+- **You expect plan validation to make a weak model strong.** Our own A/B says advisory
+  validation upstream of an improvising solver does approximately nothing at aggregate
+  level; MapSmith's answer is enforcement at the execution boundary, and that hypothesis
+  is not measured yet.
+- **You want us to debug your local geospatial toolchain.** Docker, or `uvx` where the
+  wheels work, are the only supported paths; a hand-built native GDAL stack is not, on
+  purpose.
+
+## Roadmap
+
+- [x] Zonal statistics (exactextract, exact fractional coverage)
+- [x] Whitebox Next Gen adapter: hillshade, flow accumulation, watershed (in-memory, open tier)
+- [x] Typed analysis plans: static validation against the operation registry + simulated CRS flow before execution
+- [x] Runtime verification: input preconditions, warnings with hints in the tool result, bounded deterministic repair recorded in the manifest
+- [x] MCP Apps in-chat map panel with provenance cards (self-contained, works under the default host sandbox)
+- [ ] Agent-loop repair: hand verification failures back to the agent for a bounded number of retries
+- [ ] More terrain & hydrology: slope/aspect, stream network extraction
+- [ ] QGIS Processing sidecar (subprocess-isolated): ~900 algorithms
+- [ ] Sandboxed code-execution tool for the long tail
+- [ ] Map panel: MapLibre vector rendering and shareable viewer URLs (raster OSM tiles already ship)
+- [ ] Authenticated remote mode (OAuth on the existing Streamable HTTP transport) and long-job progress via MCP Tasks
+
+## License and project
+
+- MapSmith server and engines: **AGPL-3.0-or-later** (see [LICENSE](LICENSE))
+- Client SDK and tool-schema definitions (future `sdk/`): **Apache-2.0**
+
+You can self-host MapSmith freely, forever. If you modify it and offer it as a service, the
+AGPL asks you to share your changes — or [talk to us](mailto:mapsmith@proton.me) about a
+commercial license.
+
+Release notes are in [CHANGELOG.md](CHANGELOG.md), how to contribute in
+[CONTRIBUTING.md](CONTRIBUTING.md), how to report a vulnerability in
+[SECURITY.md](SECURITY.md). "MapSmith" is a trademark of the MapSmith project — see
+[TRADEMARKS.md](TRADEMARKS.md). Updates: [@mapsmith_ai](https://x.com/mapsmith_ai) ·
+[Bluesky](https://bsky.app/profile/mapsmith.bsky.social).
+
+<!-- mcp-name: io.github.mapsmith-ai/mapsmith -->