Golem (גּוֹלֶם)

The self-evolving GeoAI Agent — your private GIS analyst.

</div>

Golem is a vertical AI Agent for the geospatial industry, built with Go and Eino. It bridges the gap between natural-language interaction and professional GIS workflows — turning complex GDAL/PostGIS operations into conversational requests accessible from a WebUI, terminal TUI, or any IM channel.

Unlike generic chatbot wrappers, Golem ships with a real agent loop (tool calling up to 20 iterations), workspace-local GDAL/PostGIS tooling, learned pipeline reuse, fabricated tool scaffolding, and skill telemetry loops — all governed by a built-in approval and audit framework.

Golem (גולם): In Jewish folklore, a golem is an animated being made from inanimate matter, created to serve.

Documentation

Why Golem

The geospatial industry suffers from fragmented tooling, steep learning curves, and repetitive workflows. Existing GeoAI solutions are either locked inside desktop GIS platforms (QGIS/ArcGIS plugins), limited to Jupyter notebooks, or lack autonomous execution capabilities.

Golem solves this with a unique combination:

| Pain Point | How Golem Addresses It | | ----------------------------------------- | ---------------------------------------------------------------------- | | GDAL commands are hard to memorize | Natural-language → GDAL command orchestration | | PostGIS spatial SQL is error-prone | Verified Spatial SQL Codebook with pattern matching | | CRS confusion is a daily nightmare | Auto-detection, smart projection selection, common-mistake warnings | | Analysis workflows are repeated manually | Learned pipeline reuse with parameter-aware replay | | Missing tools require custom scripting | Fabricated tool scaffolding — Agent generates new Geo tools at runtime | | GIS tools are inaccessible to non-experts | Three access modes: WebUI / TUI / IM channels (Telegram, Slack, etc.) | | Tool execution risks on production data | Built-in approval gate, policy enforcement, and audit trail |

Core Differentiators

┌─────────────────────────────────────────────────────────────────┐
│                     Golem Architecture                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Layer 4: Self-Evolution                                         │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐     │
│  │ Tool         │ │ Skill        │ │ Pipeline             │     │
│  │ Fabrication  │ │ Telemetry    │ │ Learning             │     │
│  │ (auto-gen    │ │ (track &     │ │ (replay successful   │     │
│  │  new tools)  │ │  improve)    │ │  Geo sequences)      │     │
│  └──────────────┘ └──────────────┘ └──────────────────────┘     │
│                                                                  │
│  Layer 3: Domain Knowledge                                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐     │
│  │ Spatial SQL  │ │ CRS          │ │ Data Catalog         │     │
│  │ Codebook     │ │ Intelligence │ │ Connector            │     │
│  └──────────────┘ └──────────────┘ └──────────────────────┘     │
│                                                                  │
│  Layer 2: GIS Tool Layer                                         │
│  ┌─────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌─────────────────┐      │
│  │GDAL │ │Post  │ │CRS   │ │Format │ │Data Catalog     │      │
│  │/OGR │ │GIS   │ │Detect│ │Convert│ │& SQL Codebook   │      │
│  └─────┘ └──────┘ └──────┘ └───────┘ └─────────────────┘      │
│                                                                  │
│  Layer 1: Agent Engine                                           │
│  ┌──────┐ ┌──────┐ ┌─────┐ ┌──────┐ ┌─────┐ ┌──────────┐      │
│  │Agent │ │Tools │ │Bus  │ │Cron  │ │Mem  │ │Approval  │      │
│  │ Loop │ │Reg   │ │     │ │      │ │     │ │& Audit   │      │
│  └──────┘ └──────┘ └─────┘ └──────┘ └─────┘ └──────────┘      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

1. Geo-Native Toolset

When tools.geo.enabled=true, Golem registers a full workspace-local Geo execution surface:

| Tool | Description | | -------------------- | --------------------------------------------------------------------- | | geo_info | Inspect spatial datasets — format, extent, layer count, feature count | | geo_process | GDAL/OGR processing — clip, merge, reproject, rasterize, etc. | | geo_crs_detect | Auto-detect CRS from coordinate range, metadata, or EPSG inference | | geo_format_convert | Convert between Shapefile, GeoJSON, GeoPackage, GeoTIFF, etc. | | geo_data_catalog | Discover datasets in workspace or remote catalogs | | geo_sql_codebook | Query verified spatial SQL patterns with parameter substitution | | geo_spatial_query | Execute PostGIS spatial SQL (when postgis_dsn is configured) |

Workspace conventions:

geo-codebook/ — reusable spatial SQL patterns
tools/geo/ — fabricated workspace Geo tools and dry-run scaffolds
pipelines/geo/ — learned Geo tool sequences
GDAL is required for file-processing tools; PostGIS is optional.

2. Self-Evolution Capability

No existing GeoAI competitor offers all three of these capabilities simultaneously:

Learned Pipeline Reuse — When a Geo tool sequence succeeds, it is saved as a replay-ready pipeline under pipelines/geo/. On similar future requests, the Agent injects the learned sequence as a parameter-aware reuse candidate, reducing execution time and improving reliability.

Fabricated Tool Scaffolding — When the Agent encounters a spatial task with no matching tool, it generates a dry-run manifest/script bundle under tools/geo/. The scaffold passes validator checks and can be filled in by a human or by the Agent itself, then registered as a first-class Geo tool.

Skill Telemetry — Every Geo skill tracks shown, selected, success, and failure counters. A deterministic report view surfaces underperforming skills first, giving the Agent a local, explainable signal for continuous improvement.

3. Approval, Policy & Security Governance

Golem treats security as a first-class concern, not an afterthought:

| Capability | Description | | ------------------------- | --------------------------------------------------------------------------------------------------- | | Policy modes | strict / relaxed / off — control which tools require approval before execution | | Approval gate | Sensitive tools (e.g. exec, geo_spatial_query) require explicit human approval in strict mode | | Temporary bypass | off_ttl allows time-limited policy relaxation that auto-reverts | | Audit trail | All tool executions are logged to state/audit.jsonl with full request context | | Approval state | Pending/approved/rejected requests tracked in state/approvals.json | | CLI management | golem approval list/approve/reject for out-of-band approval workflows | | Workspace restriction | Geo file operations and shell commands can be confined to workspace boundaries | | PostGIS readonly | Spatial queries default to read-only transactions when supported |

This makes Golem suitable for production environments where spatial data involves privacy, commercial secrets, or regulatory requirements.

4. Three Access Modes — Lower the Barrier

Golem can be accessed through three modes, making professional GIS capabilities available to both technical and non-technical users:

┌──────────┐     ┌──────────┐     ┌──────────────────────────┐
│  WebUI   │     │ Terminal │     │   IM Channels            │
│  /       │     │ TUI      │     │  Telegram, Discord,      │
│  /console│     │ golem    │     │  Slack, Feishu, WhatsApp,│
│          │     │ chat     │     │  QQ, DingTalk, MaixCam   │
└────┬─────┘     └────┬─────┘     └──────────┬───────────────┘
     │                │                       │
     └────────────────┼───────────────────────┘
                      ▼
              ┌───────────────┐
              │  Golem Agent  │
              │  Engine       │
              └───────────────┘

WebUI (golem run) — Landing page at /, chat console at /console. No install required for end users; share a URL and they can start spatial analysis immediately.
Terminal TUI (golem chat) — Full-feature

Golem

Install / Use

README