Skip to content
microsoftPublic

About

GeoFaham is an AI-powered geospatial analysis platform that lets users query complex geospatial workflows in natural language, automatically orchestrating specialized AI agents via a Microsoft AutoGen multi-agent architecture.

Resources

Code of conduct

Contributing

Security policy

Stars

45 stars

Watchers

1 watching

Forks

Repository files navigation

GeoFaham

Multi-Agent Geospatial Analysis

GeoFaham burn-severity demo

Quick start · Demos · Documentation

Overview

GeoFaham combines PostGIS records, OpenStreetMap features, satellite imagery, and raster computation to answer geospatial questions about places, infrastructure, and imagery. Its evaluation focuses on disaster-response tasks, including schools within flood extents, building damage, and pre- and post-fire imagery.

How it works

Four agents handle spatial queries, map features, imagery search, and raster analysis. An Orchestrator maintains a task plan, tracks progress, and revises the plan when execution stalls. The Response Store saves outputs as files; later steps refer to response IDs and metadata rather than passing full geometries or rasters through the model context.

Orchestrator, specialist agents, and Response Store

Static diagram · Agent reference · Response Store

Quick start

Requirements

  • Python 3.11 or later.
  • PostgreSQL and PostGIS; the supplied snapshot requires PostgreSQL 18.
  • API access for your configured models.
  • An Azure Maps subscription key for the web map.

Install

git clone https://github.com/microsoft/GeoFaham.git
cd GeoFaham
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

On Windows, activate the environment with venv\Scripts\activate.

Configure

Edit .env with your credentials and database connection:

OPENAI_API_KEY=your_api_key
AZURE_MAPS_KEY=your_maps_key
GEOFAHAM_DEFAULT_MODEL_CLIENT='{"provider":"autogen_ext.models.openai.OpenAIChatCompletionClient","config":{"model":"gpt-4o","api_key":"$OPENAI_API_KEY"}}'
GEOFAHAM_REASONING_MODEL_CLIENT='{"provider":"autogen_ext.models.openai.OpenAIChatCompletionClient","config":{"model":"gpt-5.1","api_key":"$OPENAI_API_KEY","reasoning_effort":"medium"}}'
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=geofaham
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password

Azure OpenAI, custom endpoints, per-agent models, and path overrides are covered in configuration. The frontend loads AZURE_MAPS_KEY from the server's /api/config endpoint.

Load the disaster data

Place your copy of geofaham_data_v1.sql.gz in data/backups/, then follow database setup to verify and restore them:

python3 scripts/db_init.py --dry-run
python3 scripts/db_init.py

The loader creates the configured database and refuses an existing one. The snapshot includes the schema and data. The Vector Agent and full team require a populated database; Maps, STAC, and Raster can also run individually through the Python API.

Run

python server.py

Before accepting requests, startup checks validate model-client configuration, PostGIS, required tables, metadata files, and writable runtime paths. See startup checks.

Open http://localhost:8010. For development:

uvicorn server:app --reload --host 127.0.0.1 --port 8010

Demos

The demo gallery contains flood-and-schools, building damage, imagery timeline, and burn-severity examples. Recordings are edited to skip waiting and processing time.

Flood-analysis conversation and map outputs

Click the figure for the full-size view. See web interface for controls and rendering details.

Documentation

Topic Reference
Agents and orchestration Agent reference
Model clients and environment variables Configuration
Database restore Database setup
Files and state Data directories
Artifact storage and SQL placeholders Response Store
Raster code execution Raster Agent
Response fields Tool response schemas
Python, HTTP, and tools API reference
Contributing and tests Development

License

MIT License

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Acknowledgments

About

GeoFaham is an AI-powered geospatial analysis platform that lets users query complex geospatial workflows in natural language, automatically orchestrating specialized AI agents via a Microsoft AutoGen multi-agent architecture.

Resources

Code of conduct

Contributing

Security policy

Stars

45 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages