🌍 GEOStudio Core

License
TerraStackAI
Built With
Deployment

🚀 Overview

The Geospatial Exploration and Orchestration Studio (GEOStudio) is an integrated platform for fine-tuning, inference, and orchestration of geospatial AI models. It combines a no-code UI, low-code SDK, and APIs to make working with geospatial data and AI accessible to everyone, from researchers to developers.

GEOStudio Core provides the unified API platform that orchestrates the entire geospatial machine learning workflow — from dataset onboarding and model training to model deployment for inferencing. It's codebase provides API endpoints for three core components:

• Inference APIs for running ML model predictions on models trained on geospatial imagery.
• Dataset Factory APIs for onboarding and managing labeled training datasets.
• Fine-Tuning APIs for orchestrating Kubernetes-based model training jobs with experiment tracking.

For details on deployment of the GEOStudio to a local or managed K8 cluster, see here.

🏗 Architecture

---

🏁 Getting Started

Prerequisites

Before running GEOStudio Core locally or inside a containerized environment, ensure that all required backend services are installed, configured, and reachable. GEOStudio Core depends on both a relational database and an in-memory datastore for full functionality.

The following services must be available before the application can start:

Service	Supported Version(s)	Purpose	Installation / Setup
Python	3.11	Required runtime for GEOStudio Core application, tooling, and CLI scripts.	Python Installation Guide Recommended: Use pyenv for version management.
PostgreSQL	15.x	Primary datastore for GEOStudio core metadata.	PostgreSQL Installation Guide Alternatively: Use a managed PostgreSQL service such as IBM Cloud Databases for PostgreSQL.
Redis	8.x	In-memory datastore used for: Caching Message queuing for async/long-running tasks	Redis Installation Guide Alternatively: Use a managed Redis instance.

Service Configuration Requirements

To ensure the application starts successfully:

1. PostgreSQL must be running and accessible (local instance or cloud-hosted).

2. Your .env file must contain a valid DATABASE_URL in the following format:

   DATABASE_URL=postgresql+psycopg://username:password@hostname:5432/database_name

3. If running Redis locally, ensure the default port 6379 is reachable, or update REDIS_URL in .env.

🖥️ Run Locally (with uv)

This project uses uv for environment management, dependency resolution, and running commands. Follow the installation instructions from the official uv docs.

After installing uv, you can proceed with these GEOStudio core setup instructions 👇

# Clone the repo
git clone git@github.com:terrastackai/geospatial-studio-core.git
cd geospatial-studio-core

# Install dependencies
uv sync
source .venv/bin/activate

# Make a copy of the environment variables file and replace values where necessary
cp .env.example .env

# Run migrations to setup the database
alembic upgrade head && alembic -n auth upgrade head

# Add seed data to your database.
# TODO: Convert to a task
python scripts/load_data.py
# Create user and api key
python scripts/create_user.py

# Start the server
uv run geostudio-core dev

Visit: http://localhost:3300/docs

Important

Developers: Make sure to enable pre-commit hooks. See the full workflow in CONTRIBUTING.md.

🦭 Run with Podman

Make a copy of the environment variables file for docker/podman and replace values where necessary

cp .env.docker.example .env.docker

Build and run the app using Podman:

podman build --platform linux/amd64 -t us.icr.io/gfmaas/gfmstudio-gateway --load .
podman run -p 3300:8080 --env-file .env.docker us.icr.io/gfmaas/gfmstudio-gateway:latest

Visit: http://localhost:3300/docs

🐳 Run with Docker

Make a copy of the environment variables file for docker/podman and replace values where necessary

cp .env.docker.example .env.docker

Build and run the app using Docker:

docker build --platform linux/amd64 -t us.icr.io/gfmaas/gfmstudio-gateway --load .
docker run -p 3300:8080  --env-file .env.docker us.icr.io/gfmaas/gfmstudio-gateway:latest

Visit: http://localhost:3300/docs

---

📁 Project Structure

geospatial-model-gateway/
├── gfmstudio/
│   ├── main.py              # Entry point for the app
│   ├── auth/                # Authentication definitions
│   ├── db_migrations/       # Alembic Database files
│   │   ├── seed_data/       # Seed data to setup your intial db data.   
│   │   ├── versions/        # Alemic database schema changes
│   │   └── env.py           # Alembic config file to include sqlaclhemy models
│   ├── fine_tuning/         # FineTuning and DatasetFactory APIs
│   │   ├── core/
│   │   ├── scripts/
│   │   ├── templates/
│   │   ├── models.py        # Database models/table definition in SqlAlchemy
│   │   ├── schemas.py       # Endpoint payload/response schema definitions
│   │   └── api.py           # Endpoints/Route definitions
│   ├── inference/           # Inference APIs
│   │   ├── v2/
│   │   │   ├── api.py       # Endpoints/Route definitions
│   │   │   ├── models.py    # Database models/table definition in SqlAlchemy
│   │   │   ├── schemas.py   # Endpoint payload/response schema definitions
│   │   │   └── services.py
│   │   └── v1/
│   ├── Jira/                # JIRA Issue Endpoints
├── tests/                   # Unit and integration tests
│   ├── integration/
│   └── unit/
├── tools/                   # Supporting tools and services
│   ├── geoserver/           # Geoserver dockerfile
│   └── mlflow/              # Dockerfile to sync mlflow and studio
│   ├── terratorch/          # Terratorch dockerfiles
│   │   ├── caikit-base/     # Terratorch dockerfile for caikit (used for permanently deployed inference)
│   │   ├── pytorch-base/    # Terratorch dockerfile for pytorch (used for run inference pipeline)
│   │   ├── ubi-base/        # Terratorch dockerfile for ubi (used for finetuning job)
│   │   ├── vllm-base/       # Terratorch dockerfile (TBA)
├── Dockerfile
├── docker-compose.yml       # For local dev
├── tiltfile                 # Tilt dev config
├── alembic.ini              # Alembic DB config
├── requirements.txt
└── README.md

---

🧪 Testing & Coverage

GEOStudio Core includes a full testing toolchain based on pytest, coverage, and static analysis tooling.
These tests are executed locally and in CI/CD pipelines to maintain code quality, stability, and reliability.

🔬 Running the Test Suite

To execute all unit tests:

pytest tests/

🧹 Static Analysis & Code Quality

This project uses pre-commit hooks to ensure code quality and consistent formatting before commits are made.

Run these commands to setup pre-commit hooks. The pre-commit hooks will automatically lint, format and check your changes for commited credentials.

pip install -r requirements-dev.txt
pre-commit install

You could also Lint your changes with:

ruff check gfmstudio/ tests/

and to format with black:

# Format code
black gfmstudio/ tests/

---

🔌🧩 Using Generic Python Processors

See this ReadMe for more detailed information.

🤝 Contributing

We welcome contributions from the community! See the CONTRIBUTING docs for full guidelines.