An Earth Intelligence platform that turns natural-language questions into verifiable geospatial analysis. Ask "Show hospitals within 2 km of Lalbagh Botanical Gardens" and TerraMind answers with real features from your own datasets, computed by PostGIS and drawn on an interactive map.
Basemap © CARTO; map data © OpenStreetMap contributors. Screenshot from the local development build.
Spatial questions are easy to say and tedious to answer: find the dataset, locate the reference place, pick the right predicate, get the units right, then render the result. Language models can read the question, but an answer invented by a model is not an answer anyone can rely on.
TerraMind keeps those two jobs apart. The model only interprets the question into a small, strictly validated structure. Every result is then computed by deterministic PostGIS queries over data you control, so it can be reproduced and checked.
"Show hospitals within 2 km of Lalbagh Botanical Gardens"
│
▼
NLQ panel (React) ── POST /api/v1/projects/{id}/query/natural ──► FastAPI
│
Gemini interprets the question into a SpatialIntent ◄────────┤
(closed schema: nearby | contains | intersects, ≤ 50 km) │
▼
Dataset, category and reference place resolved
against the project's own catalogue
│
Deterministic spatial engine ─► PostGIS │
(ST_DWithin / ST_Contains / ST_Intersects) │
▼
GeoJSON FeatureCollection ─► MapLibre GL renders it
Gemini's only job is to turn the question into that structured intent. It is shown the project's dataset names, feature counts and category names, never the features themselves, and it never writes SQL or computes a result. Validating the intent, resolving the place, checking the category and running the spatial query all happen in deterministic backend code.
If a place name is ambiguous ("Lalbagh" matches a station, a nursing home and the botanical gardens) or a category does not exist in the project, TerraMind asks or explains instead of guessing, and no spatial query is run.
- Natural-language spatial queries. Nearby, contains and intersects questions, interpreted by Google Gemini and validated against a closed Pydantic schema before anything executes. Ambiguous places return candidates; unknown categories are reported, not approximated.
- PostGIS spatial engine. Features are stored as real geometries with a
GiST index. Distances use
::geography, so radii are measured in metres on the WGS-84 ellipsoid. - Interactive map. MapLibre GL with a dataset registry, layer management and colour-coded query results.
- GeoJSON import. Datasets uploaded as GeoJSON become queryable immediately.
- Raster analytics (backend API). NDVI, NDWI and NDBI spectral indices over multi-band rasters opened with rasterio, from a local file or a cloud-optimised GeoTIFF URL.
- Satellite scene search (backend API). STAC scene search through Element 84's Earth Search, with tile templates from a TiTiler instance. Not yet available in the map interface.
- Background jobs. SegFormer segmentation inference and raster-to-vector conversion run on Celery workers with Redis.
- API-key failover. Several Gemini keys can be configured; a request refused for quota moves to the next key. This is failover, not extra quota.
| Capability | Verification |
|---|---|
| Natural-language nearby query | Exercised live in the browser against a fresh clone of main: Gemini interpretation, PostGIS execution and MapLibre rendering. The 75 features returned matched an independent PostGIS query feature for feature. |
| Ambiguous place and unknown category | Exercised live in the browser: both stop before any spatial query and draw nothing. |
| Natural-language contains and intersects | Wired to the same engine primitives and covered by automated tests; not yet exercised against live Gemini. |
| Raster indices, scene search, Celery job tasks | Backend unit and integration tests, with external services mocked; not exercised live in this release. |
| GeoJSON import | No automated test yet. |
| Map interface | Lint, type-check and production build in CI; no automated UI tests. |
| Layer | Location | Technology |
|---|---|---|
| Frontend | frontend/ |
React 19, TypeScript, Vite, MapLibre GL 6, Zustand, TanStack Query, Tailwind CSS |
| API | apps/backend/ |
FastAPI, Pydantic v2, SQLAlchemy 2 (async), GeoAlchemy2, Alembic |
| Language interpretation | apps/backend/src/nlq/ |
Google Gemini via google-genai |
| Database | Docker | PostgreSQL 15 + PostGIS 3.3 |
| Jobs | apps/backend/src/async_processing/ |
Celery workers, Redis broker and job state |
| Raster / ML | apps/backend/src/analytics/, apps/backend/src/ai/ |
rasterio, PyTorch, Transformers (SegFormer, backend only) |
apps/frontend/is a dead Next.js scaffold kept only for history. The active frontend is the root-levelfrontend/directory. Do not build there.
- Node.js 22 (the version CI uses) and pnpm 11, not npm
- Python 3.13
- Docker Desktop
From the repository root, on Windows:
py -3.13 -m venv apps\backend\.venv
apps\backend\.venv\Scripts\python -m pip install -r apps\backend\requirements-dev.txt
pnpm --dir frontend install --frozen-lockfileThe start script expects the virtualenv at exactly apps\backend\.venv.
requirements.txt pulls CPU-only PyTorch from the PyTorch package index, so
the first install is large. If pip fails with "The filename or extension is
too long", clone the repository to a shorter path.
copy .env.example .env
copy apps\backend\.env.example apps\backend\.env
copy frontend\.env.example frontend\.envNatural-language queries need at least one Gemini API key. Where it goes depends on how you run the API:
| API runs | Put the key in | Variables |
|---|---|---|
Natively (start_stack.ps1) |
apps/backend/.env |
GEMINI_API_KEY_1, GEMINI_API_KEY_2, ... (any number), and optionally NLQ_MODEL (default gemini-3.6-flash) |
| In Docker | .env at the repository root |
GEMINI_API_KEY_1 to GEMINI_API_KEY_3, or GEMINI_API_KEY; Docker Compose passes only these through |
Keys stay on the server. Without a key everything else works and
/query/natural returns 503. Never put a key in frontend/.env: every
VITE_ variable is shipped to the browser.
From the repository root:
powershell -ExecutionPolicy Bypass -File scripts\start_stack.ps1This starts PostgreSQL and Redis in Docker, applies migrations, then launches the Celery worker, the API and the Vite dev server natively, verifying each layer before continuing.
| Service | URL |
|---|---|
| Frontend | http://localhost:5273 |
| API docs (OpenAPI) | http://127.0.0.1:8000/docs |
| Health | http://127.0.0.1:8000/api/v1/health |
To stop:
powershell -ExecutionPolicy Bypass -File scripts\stop_stack.ps1Containers are left running so the database keeps its data; pass
-Containers to stop those too.
Celery must run with --pool=solo on Windows or it dies on billiard
permission errors. The start script does this for you.
Docker Compose can also build and run the API and the Celery worker in Linux containers. Use this where the host blocks native raster libraries (for example, Windows Smart App Control blocking rasterio):
docker compose up -d --build
docker compose exec backend python -m alembic upgrade head
pnpm --dir frontend dev --port 5273 --strictPortThe containerised API uses the same host port (8000) as the native one, so run one or the other.
The same three predicates are available directly from the Datasets panel, each rendered in a distinct colour:
| Query | Endpoint | Predicate |
|---|---|---|
| Nearby | GET /api/v1/projects/{project_id}/datasets/{dataset_id}/query/nearby |
ST_DWithin, both sides cast to ::geography |
| Contains | GET /api/v1/projects/{project_id}/datasets/{dataset_id}/query/contains |
ST_Contains from a clicked polygon |
| Intersects | GET /api/v1/projects/{project_id}/datasets/{dataset_id}/query/intersects |
ST_Intersects against a second dataset |
| Natural language | POST /api/v1/projects/{project_id}/query/natural |
One of the above, chosen from the question |
The ::geography cast on ST_DWithin is required: without it the radius is
measured in degrees, not metres. The full API is documented at /docs while
the backend is running.
Backend, from apps/backend/:
pip install -r requirements-dev.txt
ruff check . && ruff format --check .
mypy src/
pytest # deterministic suite; live Gemini tests are deselected
pytest -m live # optional: calls the real Gemini API and uses quotaFrontend, from frontend/:
pnpm install --frozen-lockfile
pnpm lint && pnpm type-check && pnpm buildCI runs all of the above, except the live tests, on every pull request and on
every push to main.
The natural-language pipeline, PostGIS query engine, MapLibre map and dataset import work end to end on a local stack. TerraMind is not yet production software: there is no authentication or multi-user access control, and job state is held in Redis rather than in the database.
Planned next, not yet implemented:
- Authentication and project-level access control
- Persistent job tracking in the database
- Satellite scenes and imagery layers in the map interface (scene search exists in the backend API today)
- Vector tiles for large datasets
Issues and pull requests are welcome. Please open an issue first for significant changes. Pull requests must pass the CI checks above, and new behaviour should come with tests.
Please do not report security vulnerabilities in public issues. Private vulnerability reporting is not yet enabled for this repository; until it is, open an issue asking for a private contact, without including any details of the vulnerability. Never include API keys or other credentials in issues, pull requests or logs.
No licence has been granted for TerraMind AI's own source code. Without one, the code remains protected by default copyright: you may view it here, and GitHub's Terms of Service let you view and fork public repositories on GitHub, but no permission is granted to use, copy, modify or distribute it. This is the default legal position, not a separate proprietary licence.
Third-party software, models, data and services used by TerraMind are not covered by this statement. They remain under their own terms, listed below.
| Component | How TerraMind uses it | Terms |
|---|---|---|
| Python and npm dependencies | Installed from PyPI and npm; not vendored | Each package's own licence, predominantly MIT, BSD and Apache-2.0, with MPL-2.0 for a few packages |
datasets/bangalore_osm.geojson |
Sample dataset derived from OpenStreetMap | © OpenStreetMap contributors, available under the Open Database Licence |
| CARTO Dark Matter basemap | Basemap style loaded by the frontend | Requires the attribution "© OpenStreetMap contributors, © CARTO". CARTO's Basemap Terms tie free use to a CARTO-issued API key and set usage limits; the frontend currently requests the style without a key |
SegFormer weights (nvidia/segformer-b0-finetuned-ade-512-512) |
Downloaded from Hugging Face at runtime; not stored in this repository | NVIDIA Source Code License for SegFormer, which permits non-commercial use (research or evaluation) only |
| Element 84 Earth Search | STAC endpoint used by the backend scene search (EARTH_SEARCH_URL) |
Sentinel-2 data it indexes is Copernicus Sentinel data, provided under the Copernicus Sentinel data terms |
TiTiler at titiler.xyz |
Default tile server for scene tiles (TITILER_URL) |
A publicly hosted third-party instance; no service terms were found. Configure your own instance for production use |
| MapLibre demo terrain tiles | URL present in terrain.config.ts; terrain is disabled, so it is not requested at runtime |
A sample service for MapLibre's examples and tests |
Ruff (ruff-bin/ruff.exe, ruff.zip) |
Copies of the Ruff linter binary committed to the repository | Ruff is MIT-licensed, which requires its licence notice to accompany copies; these copies are committed without it and are due to be removed |
