GRASS logo

NAME

i.ai - AI assistant for GRASS: answers questions and plans validated commands with every installed tool.

KEYWORDS

imagery, AI, LLM, assistant, automation

SYNOPSIS

i.ai
i.ai --help
i.ai [-eyi] [query=string] [operation=string] [backend=string] [api_key_file=name] [model=string] [url=string] [embed_model=string] [session=string] [workdir=name] [from_step=string] [repairs=integer] [author=string] [contact=string] [organization=string] [classification=string] [input=string] [voice_host=string] [voice_user=string] [voice_language=string] [format=string] [max_steps=integer] [timeout=integer] [--help] [--verbose] [--quiet] [--ui]

Flags:

-e
Execute the validated plan, or run the report pipeline
-y
Run steps that change existing data, session state or use the network without asking
-i
Interactive dialog
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

query=string
Question or task for the assistant
operation=string
What to do
Options: ask, report, run, compile, info, index
Default: ask
ask: Answer the query, plan commands, or write a report pipeline, as the request needs
report: Write a report pipeline (scripts and LaTeX report) for the query
run: Run the stored report pipeline, repair failing steps, write the results into the report and compile it
compile: Compile the stored report
info: Print the session context the assistant sees
index: Cache every tool interface and index the manual pages
backend=string
Language model backend
Options: ollama, openai, blablador, claude, opencode
Default: ollama
ollama: Local Ollama server
openai: Any OpenAI-compatible server given by url= (key in api_key_file, IAI_API_KEY or OPENAI_API_KEY)
blablador: Blablador, the Helmholtz AI service for research and teaching (key in api_key_file, BLABLADOR_API_KEY or IAI_API_KEY)
claude: Claude Code CLI on the logged-in account
opencode: OpenCode CLI (default model opencode/big-pickle, guest access)
api_key_file=name
File holding the API key of the openai or blablador backend (default: the key environment variables)
model=string
Model name (default: first Ollama model, Claude Code default, or opencode/big-pickle)
url=string
Server URL (Ollama, OpenAI-compatible base URL, or a running OpenCode server)
embed_model=string
Embedding model for operation=index (ollama and openai backends)
session=string
Name of a dialog session to continue and save
workdir=name
Report workspace directory (default: the session's directory under ~/.local/share/i.ai/sessions)
from_step=string
With operation=run, first pipeline step to run (e.g. 04)
repairs=integer
Repair attempts per failing step or LaTeX compilation
Default: 2
author=string
Report author (default: git user.name)
contact=string
Report contact line (default: git user.email)
organization=string
Organization shown in the report header
classification=string
Classification banner of the report, e.g. RESTRICTED (none by default)
input=string
How requests are entered
Options: typing, voice
Default: typing
typing: Typed in the terminal
voice: Spoken into the microphone, transcribed on a GPU (Enter starts and stops recording)
voice_host=string
IP address or name of a GPU server for transcription (default: IAI_VOICE_HOST, else this machine)
voice_user=string
Login name on the GPU server (default: IAI_VOICE_USER, else the ssh default)
voice_language=string
Spoken language for transcription (en, fr, ..., or auto to detect it)
Default: en
format=string
Output format
Options: plain, json, shell
Default: plain
plain: Answer and plan as text
json: Full result as JSON
shell: Plan as a shell script
max_steps=integer
Maximum number of reasoning steps per request
Default: 10
timeout=integer
Timeout of one language model call in seconds
Default: 300

Table of contents

DESCRIPTION

i.ai is an AI assistant that works inside the running GRASS session. It answers questions about the data, the session, methods and tools. It turns tasks into plans of GRASS commands and command-line steps that are validated before anything runs. It also writes complete report pipelines: numbered scripts, stored per session, that go from the data to a LaTeX report, run end to end, repair their own failing steps and compile the PDF.

Every GRASS tool installed in the session is available to the assistant. This covers core tools and addons, so all of them can be found, read and proposed. The tool catalog is read from the live installation ($GISBASE/bin, $GISBASE/scripts, $GRASS_ADDON_BASE/bin, $GRASS_ADDON_BASE/scripts and GRASS_ADDON_PATH). Each tool's interface comes from its own --interface-description, so the assistant uses the parameters, flags and option values of the installed version.

Every command-line tool on PATH is available as well: GDAL/OGR, LaTeX (latexmk, pdflatex, bibtex, biber), Graphviz, ImageMagick, pandoc, jq, curl and the rest. They are searched through the man page index (apropos, whatis) and described from their man page or --help. The prompt also lists the installed Python packages that scripts may import.

The language model can be:

How it works

The design follows GeoCopilot, an agent framework for 3D scene control, adapted to GRASS:

  1. An intent agent classifies each request as a task (execute), a question (query), an end-to-end report pipeline (pipeline), unclear (clarify), help or chat.
  2. Unclear requests go to a clarification agent. It asks what is missing and suggests complete requests that use real map names.
  3. Questions go to a query agent. Tasks go to an execution agent. Both work in steps. In each step the model either calls one read-only tool, answers, asks for clarification, or (execution agent only) proposes a plan.
  4. Each plan goes through a validation layer (see below). Any errors go back to the agent, which fixes the plan, until the plan is valid or the step budget (max_steps) is spent.
  5. Pipeline requests go to a pipeline agent (see Report pipelines).

The read-only tools available to the model are:

Read-only commands can run on a raster map's own region through a scoped region manager, so the user's computational region never changes. The session context sent to the model holds the project, mapset, CRS, computational region, mask status, the maps in the search path and the installed tools.

Validation and safety

Nothing the model proposes runs unchecked. Each command is checked against the live interface of the installed tool and against the existing maps. The following are errors, reported with suggestions when a close match exists:

Nothing is corrected silently. Each valid command also gets a risk level:

Command-line steps and scripts are validated too. Bash goes through bash -n and Python through its parser. Every command a script calls must be installed, every Python module it imports must be importable, and the GRASS calls inside it are checked like GRASS steps. This covers bash lines, grass_run bash -s <<EOF blocks and gs.run_command(...) calls with literal arguments. Some patterns are refused outright: sudo, recursive removal of /, ~ or ., piping a download into a shell, disk tools, git push, package installs and crontab edits. Scripts also get a risk level: network for downloads and remote copies, modify for removals and moves.

Plans run only with the -e flag. Each step is validated again just before it runs. A modify or network step needs a yes at the terminal, or the -y flag; without either, the plan stops before that step. GRASS steps run directly; command-line steps run with bash in the session's workspace (or the current directory). Interactive tools (such as g.gui or v.digit) are refused. Display tools (d.mon, d.rast, d.legend, ...) get the display risk level: they draw on a monitor and run without confirmation, but never as a read-only lookup while the model works out its answer. --overwrite is never added by the model to GRASS steps; it applies only when the user passes it to i.ai.

The command-line backends cannot touch the session themselves. claude runs with all its built-in tools disabled and a JSON schema for the reply. opencode runs its read-only plan agent in an empty temporary directory, without auto-approved permissions.

Report pipelines

A pipeline request ("write a report on ...", or operation=report) produces a report workspace. The workspace is either workdir or, for a session, ~/.local/share/i.ai/sessions/<session>/, and is laid out like a scripted report:

The pipeline agent first inspects the data and tools and gives an outline: steps, study settings and report sections. It then writes each script, and each one must validate before the next is written. Last, it writes the report body. The report includes every pipeline output with \figorpending and \taborpending, so it compiles before the data exist, with a placeholder box for each missing output. The checks on the report are:

A script may overwrite only the GRASS maps that this pipeline created (recorded in the manifest), never other existing maps.

With -e, or later with operation=run -e, i.ai runs the steps in order and logs each one to logs/. It records the GRASS maps each step created. When a step fails, a repair agent reads its log, inspects files and tools, and rewrites the script, up to repairs times. The rewrite is validated, and the first version is kept as <script>.orig. After the last step, the model rewrites the Executive summary and Results from the real outputs (tables, CSV files, logs and the list of figures). The report is then compiled with latexmk, and LaTeX errors go back to the model for repair. from_step restarts a run at a given step.

A later request in the same session revises the pipeline: unchanged steps are kept, and only new or changed steps are rewritten. The report title block takes author and contact (by default from git config), organization and an optional classification banner.

Voice input

By default, requests are typed. With input=voice, they can also be spoken into the PC microphone. In the dialog (-i), an empty line (Enter) starts recording and Enter stops it. Without -i and without query, one spoken request is taken. The transcription is put on the i.ai> prompt line, where it can be edited before Enter sends it. Typed lines and /commands still work.

Speech is recorded with PipeWire (pw-record, the Debian 13 default; arecord otherwise) as 16 kHz mono WAV, and transcribed by whisper.cpp with the large-v3 model on a GPU, never on a CPU. The recording is deleted after transcription and nothing is stored on the GPU machine. Transcription runs:

The GPU search looks for:

  1. GPU hardware (lspci, /dev/dri/renderD*, /dev/kfd, nvidia-smi);
  2. a whisper-server linked to a GPU backend of ggml (Vulkan, CUDA, HIP, OpenCL, SYCL, Metal, MUSA), in PATH, ~/dev/whisper.cpp, ~/whisper.cpp or the home directory, or at IAI_WHISPER_BIN;
  3. a ggml-large-v3 model, or the one at IAI_WHISPER_MODEL.

whisper-server then starts with the model kept in GPU memory. On a server it is reached through an ssh tunnel on a random port bound to 127.0.0.1. It must report its GPU backend (whisper_backend_init_gpu: using ...), or voice input stops with the reason. The server process is stopped when i.ai exits. voice_language sets the spoken language (en by default; fr, ..., or auto to detect it). Automatic detection is not the default because it is unreliable with an accent: it can pick the speaker's native language and transcribe an English request in French. The prompt passed to whisper holds GRASS terms and the session's map names, so they are heard as such.

API keys and OpenAI-compatible services

The openai and blablador backends need an API key, except for a server on this machine (localhost). The key is read from the file given as api_key_file, else from the environment variables listed above; it is never an option value, so it does not end up in the shell history. i.ai warns when the key file can be read by other users.

At start, i.ai checks the key and the model against the server's model list: a rejected key, refused access, or a model the server does not offer (with the list of those it does) stops it with the reason. Calls refused for the rate limit (HTTP 429) are retried after the wait the server asks for, up to three minutes per call, with a message. Structured output is asked as a JSON schema; a server that does not support it gets JSON mode, then the schema in the prompt, and the level that works is kept for the session. Reasoning output (<think>...</think>) is ignored.

For Blablador, the key is a personal access token of Helmholtz Codebase with the read_user scope, valid for up to a year. Its models are named by alias: alias-large (default, balanced), alias-fast, alias-code and alias-huge; alias-embeddings serves operation=index. Its rate limits are per model and user (for example 10 requests per minute on alias-large for external users); as each request to i.ai takes several model calls, a class may prefer alias-fast.

Sessions and output

With session, the dialog history and the last plan are saved under $XDG_DATA_HOME/i.ai/sessions/ (by default ~/.local/share/i.ai/), so a conversation can continue across calls. The format option prints the answer and plan as text (plain), the full result as JSON (json), or the plan as a shell script to review and run later (shell).

The -i flag starts an interactive dialog. Requests are asked in plain words, typed or spoken. Each plan is offered to run (Run this plan? [y/N]), with or without -e. A short approval of the pending plan, typed or spoken, runs it instead of going back to the model: do it, yes, run it, go ahead, and in French vas-y, oui, lance.

The dialog is also a command line. A line that starts with an installed GRASS tool (d.mon start=wx0, r.info map=elevation) runs that command directly, and a line that starts with ! runs a shell command (!gdalinfo data/dem.tif). Both are validated first, like plan steps, and steps that change existing data or use the network ask for confirmation (or need -y). The dialog commands are /run (execute the last plan), /plan, /context, /reset and /exit.

Operations

NOTES

The answer goes to standard output; messages and progress go to standard error. Plan execution reports its progress through G_percent().

Pipeline scripts run with the user's own permissions. Validation refuses known destructive patterns and asks before network or modifying steps, but it is not a sandbox: read the scripts before running a pipeline on data that matters, or run it in a separate mapset.

Small local models often struggle to follow the JSON step protocol. Models that are good at tool use give the best plans. When the ollama backend has no model, the first installed model is used.

EXAMPLES

Ask a question with Claude Code:

i.ai backend=claude query="Which Landsat bands are in this project, and what is the mean of elevation over its own extent?"

Plan a task with OpenCode Big Pickle, review the plan, then execute it:

i.ai backend=opencode query="Compute slope in degrees from the DEM, then smooth it with a 5x5 average"
i.ai backend=opencode query="Compute slope in degrees from the DEM, then smooth it with a 5x5 average" -e

Write the plan as a shell script:

i.ai backend=claude query="Compute NDVI from the 2002 Landsat 7 bands" format=shell > ndvi.sh

Continue a named dialog:

i.ai backend=claude session=wake query="Delineate the watersheds of the elevation map"
i.ai backend=claude session=wake query="Now keep only basins larger than 1 km2" -e

Use an OpenAI-compatible server, here a local llama.cpp server:

i.ai backend=openai url=http://localhost:8080/v1 model=qwen3 query="..."

Use Blablador, with the key kept in a private file:

chmod 600 ~/.blablador_key
i.ai -i backend=blablador api_key_file=~/.blablador_key
i.ai -i backend=blablador model=alias-fast api_key_file=~/.blablador_key

Write a report pipeline in a dated report folder, run it end to end, and compile the PDF:

i.ai backend=claude operation=report workdir=~/Documents/LaTex/Report/20261017_Terrain \
    query="Terrain analysis report of the elevation map: slope, aspect, streams, maps, figures and tables" -e -y

Run it again later from step 04, after editing a script:

i.ai backend=claude workdir=~/Documents/LaTex/Report/20261017_Terrain operation=run from_step=04 -e

The same pipeline runs without i.ai:

cd ~/Documents/LaTex/Report/20261017_Terrain && make

Speak the requests of a dialog, transcribed on a GPU server:

i.ai backend=claude -i input=voice voice_host=192.0.2.10 voice_user=yann

Or set the server once and speak a single request:

export IAI_VOICE_HOST=192.0.2.10 IAI_VOICE_USER=yann
i.ai backend=claude input=voice

Mix GRASS and command-line steps in a plan:

i.ai backend=claude query="Export the slope map to a Cloud Optimized GeoTIFF and make a 1000 px PNG preview" -e

Show what the assistant sees, and build the caches:

i.ai operation=info
i.ai operation=index

REQUIREMENTS

SEE ALSO

g.search.modules, r.mapcalc, r.univar

GeoCopilot, whose agent architecture i.ai follows.

AUTHORS

Yann Chemin

SOURCE CODE

Available at: i.ai source code (history)

Accessed: Sunday Nov 15 10:56:30 2026


Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual