Skip to main content

What is stacgis-ai?

stacgis-ai is a harness for building geospatial AI agents. It wires LLMs, MCP tools and GIS data together behind a single FastAPI service and a ready-made React chat UI. Give the agent a question — "find 10 cafés near Central Park and buffer them by 500 m" — and it plans, calls tools (geocoding, routing, Overpass POI search, buffer generation…), streams its reasoning in real time, and can pause for human approval when needed.

How it fits together​

┌────────────┐  SSE stream   ┌──────────────────────────────────────────┐
│            │◄──────────────│              FastAPI Router              │
│  React UI  │──────────────►│  POST /agent/chat    (blocking)         │
│ (stacgis-ai-│   multipart  │  POST /agent/stream (SSE, ReAct steps)  │
│   react)   │  form-data    │  POST /agent/approval/{id} (human-in-l) │
└────────────┘               └──────────────┬───────────────────────────┘
                                            │
                                   ┌────────▼────────┐
                                   │    AgentLoop    │  ReAct: think → act →
                                   │ (ReAct engine)  │  observe → respond
                                   └──┬─────────┬────┘
                            ┌─────────┘         └────────┐
                   ┌────────▼────────┐          ┌────────▼────────┐
                   │   LLM Provider  │          │    MCPClient    │
                   │  (Ollama/OpenAI)│          │ (in-memory/HTTP)│
                   └────────────────┘          └────────┬────────┘
                                            ┌─────────▼──────────┐
                                            │  Geospatial tools  │
                                            │ geocode · route ·  │
                                            │ POI · buffers …    │
                                            └────────────────────┘

The two packages​

PackageLanguageWhat it gives you
stacgis-ai (import stacgis_ai)PythonReAct AgentLoop, MCP client, LLM providers, tool registry with circuit breakers & retries, conversation memory, human-in-the-loop approvals, drop-in FastAPI routers (SSE streaming), WebSocket, OpenAPI generation, hooks & metrics
stacgis-ai-reactTypeScript / React<AgentChat /> — a complete themeable chat UI with live ReAct reasoning feed, geometry attachment, approval modal; plus the headless useAgent hook, GeometryInput, typed GeoJSON helpers

Repository layout​

PathWhat it is
backend/stacgis-ai — the Python agent harness (installable package)
backend/examples/Runnable FastAPI example with geospatial MCP tools
backend/docs/Raw markdown source of the backend docs
frontend/stacgis-ai-react — React components + useAgent hook (npm library)
frontend/example/Demo web app showcasing the chat UI against the backend example
docs-site/This Docusaurus documentation site
deploy/nginx.confnginx config used by the frontend Docker image

Features​

  • ReAct agent loop — think → act → observe → respond, with step budgets, cancellation and parallel tool execution
  • MCP tooling — plug in any FastMCP server (in-memory or HTTP transport)
  • LLM-agnostic — Ollama (streaming, text tool-calling fallback) and OpenAI-compatible providers behind one interface
  • FastAPI-native — streaming SSE chat, blocking chat, tool endpoints, WebSocket support, OpenAPI generation
  • Human-in-the-loop — sensitive tool calls pause the loop and wait for a user approve/reject decision (with timeout)
  • Frontend tools — server-side tools that emit UI events (zoom_to, draw_geometry, show_toast, …) handled by the React hook
  • Modern React UI — glassmorphic chat component with live reasoning feed, geometry attachment, approval modal, suggested prompts, chat history, voice input, read-aloud / PDF export, capacity queueing, dark/light themes
  • Production extras — circuit breakers, retries, hooks & metrics, structured logging