geoai - Moses Yebei

The Problem

Applying AI to geospatial data typically means stitching together model training, raster/vector processing, and visualization across incompatible libraries. GeoAI provides a unified Python API for search/download, dataset preparation, training, inference, and interactive mapping, plus a QGIS plugin for non-programmatic workflows.

What This Does

The core geoai/ package (62 files) exposes high-level modules like auto.py (model loading/inference), train.py (training pipelines), canopy.py (canopy height models), extract.py (dataset preparation), and cli.py (command-line interface). It supports GeoTIFF, JPEG2000, GeoJSON, Shapefile, and GeoPackage formats, with automatic GPU device management.

The repo also contains qgis_plugin/ (31 code files) for desktop integration, agent-harness/ (21 code files) providing a CLI wrapper for AI agents, and geoai-mcp-server/ (15 code files) exposing Model Context Protocol endpoints. Documentation is extensive: 114 Jupyter notebooks and 57 Markdown files.

How It Is Wired

Execution starts at geoai/cli.py:143 (run), reaching 140 functions. The CLI dispatches to geoai/__init__.py (33 modules depend on it, highest blast radius) and geoai/utils/__init__.py (21 dependents, part of a circular import cycle). The geoai/train.py file (4703 lines) is the largest, handling training workflows and model inference.

The geoai-mcp-server/src/geoai_mcp_server/server.py exposes three main endpoints: classify_land_cover (line 519), auto_segment_image (line 281), and detect_and_classify_features (line 400). These reach 67, 50, and 32 functions respectively, with filesystem effects via rasterio.open and full_path.parent.mkdir.

Key functions with widest reach: max (119 callers), min (88), normalize_radiometric (39), load_image (32). The geoai/auto.py module makes outbound network calls (model downloads) and runs inference. geoai/pipeline.py performs cryptographic operations (likely for secure model loading).

The call graph shows 3406 internal edges. The qgis_plugin/geoai/dialogs/deepforest_panel.py is the most-connected file (66 functions, called from 59 files) despite being UI code—a surprising hub that creates coupling between the plugin and core.

How To Use It

Setup: Install via pip or conda (README shows geoai-py on PyPI and conda-forge). No lockfile exists, so pin versions manually. Dockerfile uses quay.io/jupyter/base-notebook:latest (mutable tag).

pip install geoai-py
# or
conda install -c conda-forge geoai

Configuration: No required environment variables found. The MCP server has .env.example in geoai-mcp-server/ for optional configuration.

Running it: Use the CLI or import the library:

geoai download --help
geoai pipeline --config config.yaml

For the MCP server: python -m geoai_mcp_server from geoai-mcp-server/src/.

Real-World Use

Building footprint extraction from satellite imagery:

from geoai import load_image, AutoGeoImageProcessor
from geoai.auto import from_pretrained

image = load_image("naip.tif")
model = from_pretrained("opengeos/building-detection")
processor = AutoGeoImageProcessor.from_pretrained("opengeos/building-detection")
inputs = processor(image, return_tensors="pt")
outputs = model(**inputs)

Code Health & Issues

Static analysis found 166 findings (50 high, 116 medium) across 7 kinds:

High - Deep nesting x25: geoai/train.py, qgis_plugin/geoai/core/venv_manager.py have max indentation depth 6. Fix with early returns.
High - Import cycles x6: geoai/utils/__init__.py, geoai/train.py participate in circular imports. Breaking these requires extracting shared types.
High - Hub modules x2: geoai/__init__.py (33 dependents), geoai/utils/__init__.py (21) are high-blast-radius.
High - Oversized files x13: geoai/train.py (4703 lines), venv_manager.py, raster.py.
Medium - Broad exceptions x11: train.py, venv_manager.py swallow errors indiscriminately.
Medium - File handles x2: raster.py, landcover_utils.py use open() without context manager.
High - Duplication: 1749 repeated 6-line blocks across 87 files.

Security audit: 1 high (unpinned GitHub Actions), 4 medium (no least-privilege token, mutable Docker base, no dependency scan, persist-credentials enabled), 1 low (no job timeouts).

The Bottom Line

GeoAI is a substantial, well-documented library (416 files, 71 tests, CI on 3 OSes) that genuinely simplifies geospatial AI workflows. The main risks are architectural: hub modules and circular imports make changes ripple widely, and the 4703-line train.py is a maintenance liability. Production users should pin dependencies and container images, and expect to refactor if they need to modify core training logic.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

416 files

Python192
Jupyter Notebook114
Markdown57
YAML15
JSON2
TOML2

DockerPyTorch

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["geoai 62 modules"] g1["tests 58 modules"] g2["qgis_plugin 31 modules"] g3["agent-harness 21 modules"] g4["geoai-mcp-server 15 modules"] g5["scripts 5 modules"] g1 -->|69| g0 g3 -->|12| g0 g2 -->|6| g0 g5 -->|4| g0

Module dependencies

The 10 most depended-upon modules of 192, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_geoai___init__["__init__"] n1_geoai_utils___init__["__init__"] n2_geoai_train["train"] n3_ugin_geoai_core_venv_manager["venv_manager"] n4_geoai_utils_device["device"] n5_geoai_utils_raster["raster"] n6_tests_test_fixtures["test_fixtures"] n7_geoai_download["download"] n8_geoai_segment["segment"] n9_i_core_geoai_task_subprocess["geoai_task_subprocess"] n8_geoai_segment --> n4_geoai_utils_device n2_geoai_train --> n1_geoai_utils___init__ n1_geoai_utils___init__ --> n4_geoai_utils_device n1_geoai_utils___init__ --> n5_geoai_utils_raster n9_i_core_geoai_task_subprocess --> n3_ugin_geoai_core_venv_manager classDef cyc stroke:#ef4444,stroke-width:2px; class n1_geoai_utils___init__,n2_geoai_train cyc;

Dependencies

4 of 33 declared dependencies are a major version behind. Resolved 33 of 33 against the registry.

Package	Declared	Latest	Behind
`aiofiles`	>=23.0.0	25.1.0	2 major
`datasets`	>=3.0	5.0.1	2 major
`mcp`	>=1.0.0,<2.0.0	2.0.0	1 major
`transformers`	>=4.57.1	5.15.0	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds geoai-mcp-server/pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

docker/login-action@v4, docker/metadata-action@v6, docker/build-push-action@v7, astral-sh/setup-uv@v7

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/docs-build.yml

3 workflow(s) declare no permissions, 3 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

Dockerfile

quay.io/jupyter/base-notebook:latest (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/docs-build.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/docker-publish.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.