geopandas-ai 0.0.33

GeoPandas AI is an extension of GeoPandas allowing you to interact with your spatial data in natural language.

GeoPandas-AI

GeoPandas-AI is an open-source Python library that enhances geospatial data analysis by turning the GeoDataFrame into a conversational, intelligent assistant. It seamlessly integrates large language models (LLMs) into the geospatial workflow, enabling natural language interaction, iterative refinement, caching, and code generation directly within your Python environment.

View on GitHub →

---

🌍 Motivation

Geospatial data is key to solving complex problems in urban planning, environmental science, and infrastructure development. But tools like GeoPandas require familiarity with both GIS concepts and Python-based workflows.

GeoPandas-AI lowers this barrier by:

• Embedding conversational AI directly into GeoDataFrame
• Enabling plain-language queries and refinements
• Supporting reproducible, scriptable workflows with AI-assisted code
• Caching results to avoid redundant LLM calls

This bridges human interaction with geospatial analysis in a seamless and stateful way.

---

🧠 What’s New?

Based on the arXiv preprint, GeoPandas-AI introduces:

• ✅ A stateful, LLM-augmented GeoDataFrameAI class
• ✅ .chat() and .improve() methods for language-based querying and iteration
• ✅ Built-in caching: repeated prompts reuse cached results (no extra LLM calls)
• ✅ Full compatibility with existing GeoDataFrame workflows
• ✅ Modular backends for execution, injection, caching, and LLM calls
• ✅ A vision of conversational programming for geospatial developers

Read the paper: GeoPandas-AI: A Smart Class Bringing LLM as Stateful AI Code Assistant

---

⚙️ Installation

pip install geopandas-ai

Python 3.8+ required.

---

🚀 Quick Start

Example 1: Read and visualize spatial data interactively

import geopandasai as gpdai

gdfai = gpdai.read_file("cities.geojson")
gdfai.chat("Plot the cities by population")
gdfai.improve("Add a title and a basemap")

---

Example 2: Wrap an existing GeoDataFrame

import geopandas as gpd
from geopandasai import GeoDataFrameAI

gdf = gpd.read_file("parks.geojson")
gdfai = GeoDataFrameAI(
    gdf,
    description="City parks with name, area, and geometry"
)

gdfai.chat("Show the largest 5 parks")

---

Example 3: Work with multiple dataframes

a = gpdai.read_file("zones.geojson")
b = gpdai.read_file("reference.geojson")

a.set_description("Zoning polygons for city planning")
b.set_description("Reference dataset with official labels")

a.chat(
    "Cluster the zones into 3 groups based on geometry size",
    b,
    provided_libraries=["scikit-learn", "numpy"],
    return_type=int
)

---

🔧 Configuration & Caching

GeoPandas-AI uses a flexible dependency-injection architecture (via dependency_injector) to manage:

• LiteLLM settings
• Cache backend (memoizes .chat() and .improve() calls)
• Code executor (trusted or sandboxed)
• Code injector
• Data descriptor
• Allowed return types

Built-in caching

By default, responses and generated code are cached on disk:

from geopandasai.external.cache.backend.file_system import FileSystemCacheBackend

# Default writes to `.gpd_cache/`

Any repeated prompt or improvement will reuse cached results, saving tokens and accelerating workflows.

Customizing configuration

Override defaults with update_geopandasai_config():

from geopandasai import update_geopandasai_config
from geopandasai.external.cache.backend.file_system import FileSystemCacheBackend
from geopandasai.services.inject.injectors.print_inject import PrintCodeInjector
from geopandasai.services.code.executor import TrustedCodeExecutor

update_geopandasai_config(
    cache_backend=FileSystemCacheBackend(cache_dir=".gpd_cache"),
    executor=TrustedCodeExecutor(),
    injector=PrintCodeInjector(),
    libraries=[
      "pandas",
      "matplotlib.pyplot",
      "folium",
      "geopandas",
      "contextily",
    ],
)

Forcing fresh LLM calls

To clear all memory and cache for a fresh start:

gdfai.reset()

---

📚 Learn More

• 📦 PyPI Package
• 📖 arXiv Preprint
• 📘 Example Notebooks
• 🧠 LiteLLM Docs
• 🛠 GitHub Repository

---

📄 Citation

If you use GeoPandas-AI in academic work, please cite:

@misc{merten2025geopandasaismartclassbringing,
  title={GeoPandas-AI: A Smart Class Bringing LLM as Stateful AI Code Assistant}, 
  author={Gaspard Merten and Gilles Dejaegere and Mahmoud Sakr},
  year={2025},
  eprint={2506.11781},
  archivePrefix={arXiv},
  primaryClass={cs.HC},
  url={https://arxiv.org/abs/2506.11781}, 
}

---

🪪 License

MIT License – see LICENSE for details.

GeoPandas-AI: Making geospatial analysis conversational, intelligent, and reproducible.