mapsmith 0.1.0__py3-none-any.whl

mapsmith/__init__.py

@@ -0,0 +1,3 @@
+"""MapSmith — professional-grade geoprocessing for AI agents via MCP, with verifiable provenance."""
+
+__version__ = "0.1.0"

mapsmith/catalog.py

@@ -0,0 +1,98 @@
+"""Operation catalog for progressive discovery.
+
+Agent accuracy collapses when hundreds of raw tools are exposed. MapSmith keeps
+a small set of semantic MCP tools and lets agents *search* this catalog to find
+what exists. Entries marked ``planned`` document the roadmap so the agent can
+say "not yet" instead of hallucinating a capability.
+"""
+
+from __future__ import annotations
+
+OPERATIONS: list[dict[str, str]] = [
+    {
+        "name": "describe_dataset",
+        "status": "available",
+        "category": "inspection",
+        "summary": "CRS, geometry types, schema, extent and feature count of a vector dataset",
+    },
+    {
+        "name": "buffer_layer",
+        "status": "available",
+        "category": "vector",
+        "summary": "Metric buffer with automatic UTM estimation on geographic CRS",
+    },
+    {
+        "name": "clip_layer",
+        "status": "available",
+        "category": "vector",
+        "summary": "Clip a layer with a mask layer (CRS-aligned automatically)",
+    },
+    {
+        "name": "reproject_layer",
+        "status": "available",
+        "category": "vector",
+        "summary": "Reproject a layer to a target CRS (EPSG code or WKT)",
+    },
+    {
+        "name": "spatial_join",
+        "status": "available",
+        "category": "vector",
+        "summary": "Join by spatial predicate (intersects/within/contains); auto-routed to "
+        "SedonaDB or DuckDB for speed, GeoPandas fallback",
+    },
+    {
+        "name": "run_sql",
+        "status": "available",
+        "category": "sql",
+        "summary": "Spatial SQL (DuckDB dialect, ST_* functions) over GeoParquet and GDAL "
+        "formats; materializes GeoParquet outputs with provenance",
+    },
+    {
+        "name": "get_provenance",
+        "status": "available",
+        "category": "provenance",
+        "summary": "Full lineage manifest of any MapSmith output",
+    },
+    {
+        "name": "zonal_statistics",
+        "status": "planned",
+        "category": "raster",
+        "summary": "Statistics of a raster within vector zones (Rasterio engine)",
+    },
+    {
+        "name": "hillshade",
+        "status": "planned",
+        "category": "raster",
+        "summary": "Terrain hillshading from a DEM",
+    },
+    {
+        "name": "watershed",
+        "status": "planned",
+        "category": "hydrology",
+        "summary": "Watershed delineation (WhiteboxTools engine)",
+    },
+    {
+        "name": "isochrone",
+        "status": "planned",
+        "category": "network",
+        "summary": "Travel-time polygons (Valhalla engine)",
+    },
+    {
+        "name": "qgis_processing",
+        "status": "planned",
+        "category": "bridge",
+        "summary": "~900 QGIS/GRASS/SAGA algorithms via GPL-isolated subprocess sidecar",
+    },
+]
+
+
+def search(query: str = "") -> list[dict[str, str]]:
+    """Case-insensitive substring search across name, category and summary."""
+    q = query.strip().lower()
+    if not q:
+        return OPERATIONS
+    return [
+        op
+        for op in OPERATIONS
+        if q in op["name"].lower() or q in op["category"].lower() or q in op["summary"].lower()
+    ]

mapsmith/engines/__init__.py

@@ -0,0 +1 @@
+"""Deterministic geoprocessing engines. The LLM orchestrates; these compute."""

mapsmith/engines/dispatch.py

@@ -0,0 +1,64 @@
+"""Engine dispatcher: route each workload class to the fastest available engine.
+
+The 2025-2026 benchmarks are unambiguous (see docs in the repo wiki):
+- SedonaDB wins heavy joins/KNN by 10-180x, in-process, optional dependency.
+- DuckDB spatial wins filters/aggregations/point-in-polygon (~2M rows/sec).
+- GeoPandas/Shapely stays as the long-tail lane (<~1M features).
+
+Engines are optional imports: the dispatcher degrades gracefully and the
+provenance manifest always records which engine actually ran.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from functools import cache
+
+
+class Workload(str, Enum):
+    SQL = "sql"                # filters, aggregations, ad-hoc SQL
+    HEAVY_JOIN = "heavy_join"  # polygon overlay, distance joins, KNN
+    SMALL_VECTOR = "small_vector"  # long-tail ops on small data
+
+
+# Preference order per workload class; first available wins.
+_PREFERENCES: dict[Workload, list[str]] = {
+    Workload.SQL: ["duckdb", "geopandas"],
+    Workload.HEAVY_JOIN: ["sedonadb", "duckdb", "geopandas"],
+    Workload.SMALL_VECTOR: ["geopandas"],
+}
+
+
+@cache
+def available_engines() -> dict[str, bool]:
+    """Probe optional engines once per process."""
+    status: dict[str, bool] = {"geopandas": True}  # hard dependency
+    try:
+        import duckdb  # noqa: F401
+
+        status["duckdb"] = True
+    except ImportError:
+        status["duckdb"] = False
+    try:
+        import sedona.db  # noqa: F401
+
+        status["sedonadb"] = True
+    except ImportError:
+        status["sedonadb"] = False
+    return status
+
+
+def pick(workload: Workload, requested: str = "auto") -> str:
+    """Pick the engine for a workload. `requested` may force a specific engine."""
+    engines = available_engines()
+    if requested != "auto":
+        if not engines.get(requested, False):
+            raise RuntimeError(
+                f"Engine '{requested}' is not available in this installation. "
+                f"Available: {[k for k, v in engines.items() if v]}"
+            )
+        return requested
+    for name in _PREFERENCES[workload]:
+        if engines.get(name, False):
+            return name
+    raise RuntimeError(f"No engine available for workload {workload}")

mapsmith/engines/duckdb_engine.py

@@ -0,0 +1,103 @@
+"""DuckDB spatial engine: SQL, filters, aggregations, point-in-polygon joins.
+
+Benchmarks (2025-26): DuckDB's SPATIAL_JOIN operator does point-in-polygon at
+~2M rows/sec on a laptop. The spatial extension is NOT bundled in the wheel:
+we install it on first use (needs network once per environment).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import duckdb
+
+from ..provenance import InputRecord, ProvenanceRecord
+
+_PREVIEW_ROWS = 50
+
+
+def _engine_info() -> dict[str, str]:
+    return {"name": "duckdb", "version": duckdb.__version__}
+
+
+def _connect() -> duckdb.DuckDBPyConnection:
+    con = duckdb.connect()
+    try:
+        con.install_extension("spatial")
+    except duckdb.Error:
+        pass  # already installed in this environment, or offline with a cached copy
+    con.load_extension("spatial")
+    return con
+
+
+def _quote(path: str) -> str:
+    return str(path).replace("'", "''")
+
+
+def _rel(path: str) -> str:
+    """SQL relation for a dataset file: GeoParquet natively, other formats via GDAL."""
+    if str(path).lower().endswith(".parquet"):
+        return f"read_parquet('{_quote(path)}')"
+    return f"ST_Read('{_quote(path)}')"
+
+
+def run_sql(query: str, output_path: str | None = None) -> dict[str, Any]:
+    """Run spatial SQL. With output_path, materialize the result as GeoParquet."""
+    con = _connect()
+    record = ProvenanceRecord(
+        operation="run_sql",
+        parameters={"query": query},
+        inputs=[],
+        engine=_engine_info(),
+    )
+    if output_path:
+        con.sql(f"COPY ({query}) TO '{_quote(output_path)}' (FORMAT parquet)")
+        count = con.sql(
+            f"SELECT count(*) FROM read_parquet('{_quote(output_path)}')"
+        ).fetchone()[0]
+        manifest = record.finish().write_for(output_path)
+        return {"output": str(output_path), "row_count": int(count), "provenance": str(manifest)}
+    result = con.sql(query)
+    rows = result.fetchmany(_PREVIEW_ROWS)
+    return {
+        "columns": [d[0] for d in result.description],
+        "rows": [[repr(v) if isinstance(v, (bytes, bytearray)) else v for v in r] for r in rows],
+        "truncated_at": _PREVIEW_ROWS,
+    }
+
+
+def spatial_join(
+    left_path: str, right_path: str, output_path: str, predicate: str = "intersects"
+) -> dict[str, Any]:
+    """Attribute join by spatial predicate. GeoParquet-native fast path."""
+    predicates = {"intersects": "ST_Intersects", "within": "ST_Within", "contains": "ST_Contains"}
+    if predicate not in predicates:
+        raise ValueError(f"predicate must be one of {sorted(predicates)}, got {predicate!r}")
+    con = _connect()
+    record = ProvenanceRecord(
+        operation="spatial_join",
+        parameters={"predicate": predicate, "engine": "duckdb"},
+        inputs=[InputRecord.from_path(left_path), InputRecord.from_path(right_path)],
+        engine=_engine_info(),
+    )
+    fn = predicates[predicate]
+    query = f"""
+        SELECT l.*, r.* EXCLUDE (geometry)
+        FROM {_rel(left_path)} AS l
+        JOIN {_rel(right_path)} AS r
+          ON {fn}(l.geometry, r.geometry)
+    """
+    con.sql(f"COPY ({query}) TO '{_quote(output_path)}' (FORMAT parquet)")
+    count = con.sql(f"SELECT count(*) FROM read_parquet('{_quote(output_path)}')").fetchone()[0]
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "feature_count": int(count),
+        "provenance": str(manifest),
+    }
+
+
+def supports_inputs(*paths: str) -> bool:
+    """The DuckDB fast path expects GeoParquet inputs with a 'geometry' column."""
+    return all(Path(p).suffix.lower() == ".parquet" for p in paths)

mapsmith/engines/sedona_engine.py

@@ -0,0 +1,62 @@
+"""SedonaDB engine: heavy overlays, distance joins, KNN — 10-180x on benchmarks.
+
+Optional dependency (`pip install mapsmith[sedona]`). In-process Rust engine
+(Arrow/DataFusion). API is pre-1.0: this wrapper stays deliberately thin.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..provenance import InputRecord, ProvenanceRecord
+
+
+def _engine_info() -> dict[str, str]:
+    import sedonadb  # the wheel behind apache-sedona[db]
+
+    return {"name": "sedonadb", "version": getattr(sedonadb, "__version__", "unknown")}
+
+
+def spatial_join(
+    left_path: str, right_path: str, output_path: str, predicate: str = "intersects"
+) -> dict[str, Any]:
+    """Spatial join on SedonaDB. Keeps left columns (right attributes omitted).
+
+    Note: inner join semantics — a left feature is repeated once per match,
+    like GeoPandas sjoin. Recorded in the provenance manifest.
+    """
+    import sedona.db
+
+    predicates = {"intersects": "ST_Intersects", "within": "ST_Within", "contains": "ST_Contains"}
+    if predicate not in predicates:
+        raise ValueError(f"predicate must be one of {sorted(predicates)}, got {predicate!r}")
+
+    sd = sedona.db.connect()
+    record = ProvenanceRecord(
+        operation="spatial_join",
+        parameters={"predicate": predicate, "engine": "sedonadb", "columns": "left-only"},
+        inputs=[InputRecord.from_path(left_path), InputRecord.from_path(right_path)],
+        engine=_engine_info(),
+    )
+
+    def _load(path: str, view: str) -> None:
+        if str(path).lower().endswith(".parquet"):
+            sd.read_parquet(path).to_view(view)
+        else:
+            sd.read_pyogrio(path).to_view(view)
+
+    _load(left_path, "l")
+    _load(right_path, "r")
+    fn = predicates[predicate]
+    result = sd.sql(f"SELECT l.* FROM l JOIN r ON {fn}(l.geometry, r.geometry)")
+    result.to_parquet(output_path)
+    count = sd.sql(
+        "SELECT count(*) FROM l JOIN r ON " + f"{fn}(l.geometry, r.geometry)"
+    ).to_pandas()
+    feature_count = int(count.iloc[0, 0])
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "feature_count": feature_count,
+        "provenance": str(manifest),
+    }

mapsmith/engines/vector.py

@@ -0,0 +1,156 @@
+"""Vector operations on the permissive GeoPandas/Shapely stack.
+
+Design rules:
+- Metric operations on geographic CRS are never silent: we estimate a UTM CRS,
+  record the decision in provenance, and reproject back.
+- Every writer emits a provenance manifest next to the output.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import geopandas as gpd
+
+from ..provenance import InputRecord, ProvenanceRecord
+
+
+def _engine_info() -> dict[str, str]:
+    return {"name": "geopandas", "version": gpd.__version__}
+
+
+def describe(path: str) -> dict[str, Any]:
+    gdf = gpd.read_file(path)
+    bounds = gdf.total_bounds
+    return {
+        "path": str(path),
+        "crs": str(gdf.crs) if gdf.crs else None,
+        "feature_count": len(gdf),
+        "geometry_types": sorted(gdf.geom_type.dropna().unique().tolist()),
+        "fields": {c: str(t) for c, t in gdf.dtypes.items() if c != gdf.geometry.name},
+        "extent": {
+            "minx": float(bounds[0]),
+            "miny": float(bounds[1]),
+            "maxx": float(bounds[2]),
+            "maxy": float(bounds[3]),
+        },
+    }
+
+
+def buffer(input_path: str, distance_meters: float, output_path: str) -> dict[str, Any]:
+    gdf = gpd.read_file(input_path)
+    if gdf.crs is None:
+        raise ValueError(
+            f"{input_path} has no CRS. Refusing to buffer without knowing the units — "
+            "assign a CRS first (see reproject_layer)."
+        )
+    record = ProvenanceRecord(
+        operation="buffer_layer",
+        parameters={"distance_meters": distance_meters},
+        inputs=[InputRecord.from_path(input_path, crs=str(gdf.crs))],
+        engine=_engine_info(),
+    )
+    original_crs = gdf.crs
+    if original_crs.is_geographic:
+        analysis_crs = gdf.estimate_utm_crs()
+        record.crs_decisions = {
+            "analysis_crs": str(analysis_crs),
+            "reason": "estimated UTM zone for metric buffering on a geographic CRS",
+        }
+        buffered = gdf.to_crs(analysis_crs)
+        buffered["geometry"] = buffered.geometry.buffer(distance_meters)
+        buffered = buffered.to_crs(original_crs)
+    else:
+        record.crs_decisions = {
+            "analysis_crs": str(original_crs),
+            "reason": "input CRS is already projected; distance interpreted in its units",
+        }
+        buffered = gdf.copy()
+        buffered["geometry"] = buffered.geometry.buffer(distance_meters)
+    buffered.to_file(output_path)
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "feature_count": len(buffered),
+        "provenance": str(manifest),
+    }
+
+
+def clip(input_path: str, mask_path: str, output_path: str) -> dict[str, Any]:
+    gdf = gpd.read_file(input_path)
+    mask = gpd.read_file(mask_path)
+    record = ProvenanceRecord(
+        operation="clip_layer",
+        parameters={},
+        inputs=[
+            InputRecord.from_path(input_path, crs=str(gdf.crs)),
+            InputRecord.from_path(mask_path, crs=str(mask.crs)),
+        ],
+        engine=_engine_info(),
+    )
+    if gdf.crs != mask.crs:
+        mask = mask.to_crs(gdf.crs)
+        record.crs_decisions = {
+            "analysis_crs": str(gdf.crs),
+            "reason": "mask reprojected to the input layer CRS before clipping",
+        }
+    clipped = gpd.clip(gdf, mask)
+    clipped.to_file(output_path)
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "feature_count": len(clipped),
+        "provenance": str(manifest),
+    }
+
+
+def reproject(input_path: str, target_crs: str, output_path: str) -> dict[str, Any]:
+    gdf = gpd.read_file(input_path)
+    record = ProvenanceRecord(
+        operation="reproject_layer",
+        parameters={"target_crs": target_crs},
+        inputs=[InputRecord.from_path(input_path, crs=str(gdf.crs))],
+        engine=_engine_info(),
+    )
+    reprojected = gdf.to_crs(target_crs)
+    reprojected.to_file(output_path)
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "crs": str(reprojected.crs),
+        "provenance": str(manifest),
+    }
+
+
+def spatial_join(
+    left_path: str, right_path: str, output_path: str, predicate: str = "intersects"
+) -> dict[str, Any]:
+    allowed = {"intersects", "within", "contains"}
+    if predicate not in allowed:
+        raise ValueError(f"predicate must be one of {sorted(allowed)}, got {predicate!r}")
+    left = gpd.read_file(left_path)
+    right = gpd.read_file(right_path)
+    record = ProvenanceRecord(
+        operation="spatial_join",
+        parameters={"predicate": predicate},
+        inputs=[
+            InputRecord.from_path(left_path, crs=str(left.crs)),
+            InputRecord.from_path(right_path, crs=str(right.crs)),
+        ],
+        engine=_engine_info(),
+    )
+    if left.crs != right.crs:
+        right = right.to_crs(left.crs)
+        record.crs_decisions = {
+            "analysis_crs": str(left.crs),
+            "reason": "right layer reprojected to the left layer CRS before joining",
+        }
+    joined = gpd.sjoin(left, right, predicate=predicate, how="inner")
+    joined = joined.drop(columns=[c for c in ("index_right",) if c in joined.columns])
+    joined.to_file(output_path)
+    manifest = record.finish().write_for(output_path)
+    return {
+        "output": str(output_path),
+        "feature_count": len(joined),
+        "provenance": str(manifest),
+    }

mapsmith/jobs.py

@@ -0,0 +1,87 @@
+"""Durable job ledger on Postgres (optional).
+
+Every tool call is modeled as a job row from day one (id, operation, params,
+status, artifact, manifest). Execution stays in-process for now; the same
+table will back the MCP Tasks extension and a worker queue later — designed-in
+seam, deferred infrastructure.
+
+If DATABASE_URL is unset (or psycopg is not installed) the ledger is a no-op:
+local/stdio users need zero infrastructure.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from contextlib import contextmanager
+from typing import Any
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS mapsmith_jobs (
+    id UUID PRIMARY KEY,
+    operation TEXT NOT NULL,
+    params JSONB NOT NULL DEFAULT '{}'::jsonb,
+    status TEXT NOT NULL DEFAULT 'running',
+    error TEXT,
+    artifact TEXT,
+    manifest JSONB,
+    started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    finished_at TIMESTAMPTZ
+);
+"""
+
+_schema_ready = False
+
+
+def _connect():
+    url = os.environ.get("DATABASE_URL")
+    if not url:
+        return None
+    try:
+        import psycopg
+    except ImportError:
+        return None
+    try:
+        return psycopg.connect(url, autocommit=True)
+    except Exception:  # noqa: BLE001 — the ledger must never take the server down
+        return None
+
+
+def _ensure_schema(conn) -> None:
+    global _schema_ready
+    if not _schema_ready:
+        conn.execute(_DDL)
+        _schema_ready = True
+
+
+@contextmanager
+def job(operation: str, params: dict[str, Any]):
+    """Record a tool execution as a durable job row (no-op without DATABASE_URL)."""
+    conn = _connect()
+    job_id = str(uuid.uuid4())
+    if conn is not None:
+        _ensure_schema(conn)
+        conn.execute(
+            "INSERT INTO mapsmith_jobs (id, operation, params) VALUES (%s, %s, %s)",
+            (job_id, operation, json.dumps(params, default=str)),
+        )
+    try:
+        result: dict[str, Any] = {}
+        yield job_id, result
+    except Exception as exc:
+        if conn is not None:
+            conn.execute(
+                "UPDATE mapsmith_jobs SET status='failed', error=%s, finished_at=now() "
+                "WHERE id=%s",
+                (str(exc)[:2000], job_id),
+            )
+            conn.close()
+        raise
+    if conn is not None:
+        conn.execute(
+            "UPDATE mapsmith_jobs SET status='completed', artifact=%s, finished_at=now() "
+            "WHERE id=%s",
+            (result.get("output"), job_id),
+        )
+        conn.close()

mapsmith/provenance.py

@@ -0,0 +1,75 @@
+"""Lineage manifests for every MapSmith output.
+
+Every operation that writes a dataset also writes ``<output>.provenance.json``
+next to it. The manifest is the product's core promise: any result can be
+audited and re-run bit-identical without an LLM in the loop.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def sha256_of(path: str | Path, chunk_size: int = 1 << 20) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(chunk_size):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@dataclass
+class InputRecord:
+    path: str
+    sha256: str
+    crs: str | None = None
+
+    @classmethod
+    def from_path(cls, path: str | Path, crs: str | None = None) -> InputRecord:
+        return cls(path=str(path), sha256=sha256_of(path), crs=crs)
+
+
+@dataclass
+class ProvenanceRecord:
+    operation: str
+    parameters: dict[str, Any]
+    inputs: list[InputRecord]
+    crs_decisions: dict[str, str] = field(default_factory=dict)
+    engine: dict[str, str] = field(default_factory=dict)
+    mapsmith_version: str = __version__
+    started_at: str = field(default_factory=_utcnow)
+    finished_at: str | None = None
+
+    def finish(self) -> ProvenanceRecord:
+        self.finished_at = _utcnow()
+        return self
+
+    def write_for(self, output_path: str | Path) -> Path:
+        """Write the manifest next to the output it describes."""
+        manifest_path = Path(f"{output_path}.provenance.json")
+        manifest_path.write_text(
+            json.dumps(asdict(self), indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+        return manifest_path
+
+
+def read_provenance(output_path: str | Path) -> dict[str, Any]:
+    """Read the lineage manifest of a MapSmith output, if present."""
+    manifest_path = Path(f"{output_path}.provenance.json")
+    if not manifest_path.exists():
+        raise FileNotFoundError(
+            f"No provenance manifest found for {output_path}. "
+            "Either it was not produced by MapSmith or the manifest was moved."
+        )
+    return json.loads(manifest_path.read_text(encoding="utf-8"))