GeoContra: From Fluent GIS Code to Verifiable Spatial Analysis with Geography-Grounded Repair

Abstract: Reliable spatial analysis in GIScience requires preserving coordinate semantics, topology, units, and geographic plausibility. Current LLM-based GIS systems generate fluent scripts but rarely enforce these geographic rules at scale. We present GeoContra, a verification and repair framework for LLM-driven Python GIS workflows. It represents each task as an executable geospatial contract-including natural-language questions, schemas, CRS metadata, expected outputs, spatial predicates, topology, metrics, required operations, and forbidden shortcuts. Generated programs undergo static rule inspection, runtime validation, and semantic verification, with violations fed back into a bounded repair loop. Evaluated on 7,079 real geospatial tasks across 15 Boston-area zones, 9 task families, and 11 open-source models (600 runs each), GeoContra improves spatial correctness on closed models from 47.6% to 77.5% for DeepSeek-V4 and from 57.7% to 81.5% for Kimi-K2.5. Across 11 open models, average correctness rises by 26.6%. GeoContra turns fluent code production into verifiable spatial analysis, catching negative travel times, CRS/field-schema violations, missing predicates, and brittle output casts that otherwise yield executable but geographically invalid results.

• The paper demonstrates a contract-enforced framework for GIS analysis that integrates task contracts, layered verification, and targeted repair for improved spatial correctness.
• It details a methodology using static, runtime, and semantic checks that increase spatial-correctness from 47.6% to over 80% across various models.
• The approach enhances trustworthiness and reproducibility in automated spatial analysis by offering actionable insights and establishing a benchmark for GeoAI.

GeoContra: Contract-Guided Verification and Repair in LLM-Based GIS Automation

Introduction

GeoContra presents a paradigm shift in geospatial artificial intelligence by redefining the assurance framework for LLM-driven geographic information system (GIS) code. Contrary to prevalent approaches that emphasize code fluency and tool invocation, GeoContra enforces rigorous preservation of geographic semantics via contract-grounded generation, multilayered verification, and bounded repair. The framework explicitly encodes spatial analysis intent and validity, operationalizing metric, topological, and semantic GIS rules as executable constraints in both code production and validation. This essay provides a detailed technical analysis of the method, its empirical evaluation, and the implications for reliable spatial analysis in algorithmic geography.

Methodological Framework

Contractual Formulation of GIS Tasks

GeoContra models each GIS task as a tuple $$\tau = (q, \mathcal{D}, \mathcal{Y}, \mathcal{C}, \mathcal{M}^+, \mathcal{M}^-)$$, with the natural-language query $q$, datasets $\mathcal{D}$ (with schema details and CRS), output specifications $\mathcal{Y}$, spatial constraints $\mathcal{C}$, required operations $\mathcal{M}^+$, and forbidden shortcuts $\mathcal{M}^-$. This task contract formalizes not only input/output specifications but enforces alignment to spatial support, geometric validity, row preservation, measurement units, and analytic procedure fidelity.

The system pipeline (Figure 1) begins with natural-language task specification and local geospatial context, constructing a detailed contract. The LLM then generates Python GIS code, which undergoes three sequential validation layers: static analysis, runtime checking, and semantic verification. Any detected violations trigger precise, evidence-rich repair prompts until the artifact is both executable and geographically valid, or until a repair budget is exhausted.

Figure 1: Pipeline from GIS task and local data to contract formation, code generation, multilayered verification, and violation-driven repair.

Multilayer Verification and Repair

The verification stack comprises:

• Static analysis: Inspects code ASTs for CRS-unit correctness, field-schema adherence, spatial predicate directionality, topology-sensitive methods, and forbidden operations.
• Runtime checking: Validates successful execution, artifact existence and readability, required columns and rows, duplicate identifiers, and metric plausibility (e.g., non-negative distances, bounded ratios).
• Semantic verification: Confirms presence and correctness of GIS operations (buffers, spatial joins, shortest paths, overlays, raster procedures) as required by the contract.

Concrete violation payloads, containing type, severity, evidence, and actionable suggestions, are serialized into repair prompts. The LLM is required to amend only the relevant failure surfaces, preserving the original task semantics at each repair iteration (Figure 2).

Figure 2: Static, runtime, and semantic check layers with structured evidence and targeted repair orchestration.

Benchmark Construction

GeoContra-Real, the paired evaluation benchmark, comprises 7,079 local GIS tasks across 15 subregions of Greater Boston, spanning 9 task categories including buffer, spatial join, nearest neighbor, network accessibility, raster, topology, overlay, and multi-step workflows. Each task is instantiated as an executable contract, making this dataset both statistically robust and operationally reflective of heterogeneous, real-world GIS analysis contexts.

Empirical Evaluation

Closed and Open Model Performance

On both closed-source (DeepSeek-V4, Kimi-K2.5) and open LLM families (11 models), GeoContra delivers substantial improvements over LLM-only baselines. Spatial-correctness rates for DeepSeek-V4 increase from 47.6% to 77.5%, and for Kimi-K2.5 from 57.7% to 81.5%. In the open-model suite, average correctness rises by 26.6 percentage points (from 18.3% to 44.9%) across 11 models. The improvements are driven not only by increased executability but—crucially—by a reduction in geographically invalid outputs that are otherwise syntactically complete.

Spatial-correctness gains are quantifiable across all task families (Figure 3), with the largest deltas realized on complex, multi-op, and metric-sensitive workflows. Some persistent challenges remain for topology-quality and hard multi-step tasks, where reference-solution comparison or richer semantic contracts may be required.

Figure 3: Per-task-family correction gains under GeoContra by model, quantifying contract-driven verification improvements.

Open-model family results demonstrate that even smaller, less robust LLMs benefit from contract prompting and structured violation repair, provided minimal code synthesis abilities and adherence to feedback exist (Figure 4). Notably, models with low raw executability (e.g., Qwen2.5-32B) achieve >40% spatial correctness post-GeoContra, compared to negligible performance in LLM-only settings.

Figure 4: Open-model per-family spatial correctness for LLM-only versus contract-guided GeoContra settings.

Violation Reduction and Failure Modes

Average static, runtime, and semantic contract violations decrease sharply under the GeoContra regime (Figure 5), especially for metric, CRS, and row-preservation contract errors. Case analysis reveals that key correction mechanisms include invalid metric usage (e.g., negative travel times), shortcut detection (e.g., Euclidean instead of network paths), enforcement of output schemas, and required operation proofs (e.g., buffer, spatial join, overlay logic), directly addressing failure surfaces missed by code-only evaluation or syntactic test suites.

Figure 5: Reduction in average violations per task after repair, showing the impact of contract-enforced feedback.

Practical and Theoretical Implications

GeoContra advances GIS automation along multiple axes:

• Trustworthiness: By enforcing contract-grounded semantics, results are not only executable but preserve geographic intent, spatial support, metric realism, and topological soundness.
• Robustness: The repair loop regime addresses a spectrum of failures (from API misuse to semantic drift), providing actionable, interpretable feedback at each round.
• Reproducibility: Executable task contracts and contract-encoded validation offer a reproducible framework for benchmarking and extending automated spatial analyses.
• Extensibility: While current verifiers focus on lightweight, interpretable checks, the underlying architecture is agnostic to GIS modality and can be extended with richer semantic ontologies, reference-solution scoring, and domain-specific plausibility diagnostics.

The framework underscores that advances in GeoAI reliability will depend not solely on scaling foundation models, but on integrating formal geographic knowledge, verifiability, and feedback structures into the automation stack. The contract-annotated benchmark also sets a precedent for sharing tasks and outputs in a form amenable to external audit and reproducibility.

Future Directions

Key research directions include:

• Integration of oracle-based or learned semantic verifiers for topology, spatial distribution, and autocorrelation plausibility.
• Adaptive repair mechanisms with uncertainty quantification and budgeted interaction policies.
• Expansion of contract corpora to non-Western, rural, informal, and hazard-prone geographies.
• Layered ontologies that distinguish multiple analytically valid solution spaces from outright contract violations.

Expanding the scope of contract-enforced verification and introducing domain-general spatial diagnostics can enable robust, trustworthy, and reproducible geospatial intelligence in operational and scientific contexts.

Conclusion

GeoContra operationalizes a GIScience-centered approach to LLM-driven spatial analysis, moving beyond code fluency to enforce verifiable geographic correctness. Through contract-grounded prompting, layered verification, and violation-driven repair, GeoContra achieves substantial improvements in spatial correctness and robustness across diverse models and tasks. The results underscore the necessity of explicit analytic contracts and structured feedback for trustworthy GeoAI and highlight fundamental directions for future work in automated reproducible spatial analysis.