AI Assistant

The AI Assistant is a “chat with your data” panel that turns plain-English requests into Meratyn’s own operations — Spatial SQL, layer styling, map control, and more — and applies them through the app, the same way you would by hand. Open it from Processing → AI Assistant (top of the menu) or the command palette. It docks as a resizable panel at the bottom of the window (drag its top edge to resize, ✕ to close).

Because the assistant acts through the store rather than poking the map directly, authored project changes recorded by Travels are undoable with Ctrl/Cmd + Z. Host, plugin, and MapLibre fallback side effects are outside that history. Every tool call (including the SQL it generates) is shown in the transcript so you can see exactly what ran.

The assistant is optional and disabled until you configure a provider or the deployment operator enables the managed AI proxy. Meratyn keeps project data local by default; when you send a prompt, the prompt and its scoped context go to the provider or managed proxy you configured.

Setup: choose an AI provider

The assistant runs on the TanStack AI runtime, entirely inside the app: your prompts and data go directly from your device to the provider you configure, with no Meratyn server in between. Configure one or more providers in Settings → AI Providers:

• Ollama runs models on your own machine — no API key and nothing leaves your computer. Point OLLAMA_BASE_URL at your Ollama host (the /v1 suffix is added automatically); set OLLAMA_MODEL to pick which pulled model to use. In the desktop app the host may be any machine on your local network (for example http://192.168.1.20:11434) — you do not have to spell out http://.
• Custom covers any OpenAI-compatible endpoint — LiteLLM, vLLM, OpenRouter, Groq, Together, a local server, etc. — via its chat-completions API.
• Every profile has a Test connection button. It probes the endpoint and, on failure, tells you the exact fix — for Ollama, the precise OLLAMA_ORIGINS value to set; for an HTTPS web app talking to a plain-HTTP server, the mixed-content explanation.

Hosted keys (and AWS credentials) are used directly from your browser to call the provider; they are never sent to Meratyn’s servers. Saving the setting enables the panel immediately — no reload needed.

Using local Ollama from the web app

The hosted Meratyn web app connects directly from your browser to Ollama on your computer. Prompts and responses do not pass through a Meratyn server. Because browser requests include the page origin, Ollama must explicitly allow https://mappview.mapptech.com.co before the web app can call its API.

Set this variable for the Ollama server, then restart Ollama:

OLLAMA_ORIGINS=https://mappview.mapptech.com.co

Keep the Ollama Base URL in Settings → AI Providers → Ollama as:

http://localhost:11434

Configure OLLAMA_ORIGINS for your operating system:

Linux (systemd)

Run sudo systemctl edit ollama.service and add:

[Service]
Environment="OLLAMA_ORIGINS=https://mappview.mapptech.com.co"

Then reload and restart the service:

sudo systemctl daemon-reload
sudo systemctl restart ollama

macOS

Set the variable for the Ollama application, then quit and reopen Ollama:

launchctl setenv OLLAMA_ORIGINS "https://mappview.mapptech.com.co"

Windows

Quit Ollama, create a user environment variable named OLLAMA_ORIGINS with the value https://mappview.mapptech.com.co, and start Ollama again.

Docker

Pass the allowed origin when starting the container:

docker run -d \
  -e OLLAMA_ORIGINS=https://mappview.mapptech.com.co \
  -p 11434:11434 \
  ollama/ollama

For a self-hosted Meratyn URL, replace the value with the exact origin in the Ollama error message, including its scheme and port (for example, http://192.168.1.98:4000). This is an Ollama server permission and cannot be enabled automatically by a web page. See Ollama’s official web-origin configuration guidance.

Managed AI in a password-protected Docker deployment

A deployment operator can provide AI without distributing provider API keys. In this configuration, the browser calls the same-origin /ai route. Docker’s nginx checks the instance’s HTTP Basic Auth username and password when the operator has configured it, then adds a server-only instance token and forwards the request to the configured AI proxy. The browser receives neither the instance token nor the Cloudflare AI Gateway token.

Users only need to sign in to the Meratyn instance; they do not configure an AI provider key. Requests sent directly to the configured proxy without the server-only token receive 401 Unauthorized.

The operator must start the container with all managed-AI variables:

docker run --rm -p 8080:80 \
  -e MAPPVIEW_AUTH_USER=admin \
  -e MAPPVIEW_AUTH_PASSWORD='change-me' \
  -e MAPPVIEW_AI_URL=/ai \
  -e MAPPVIEW_AI_MODEL=openai/gpt-5.6-luna \
  -e MAPPVIEW_AI_PROXY_URL=http://host.docker.internal:8791 \
  -e MAPPVIEW_AI_PROXY_TOKEN="$MAPPVIEW_AI_PROXY_TOKEN" \
  mapptech/mappview:local

If MAPPVIEW_AI_URL is unset, the Docker entrypoint leaves the managed proxy disabled and does not inject any AI proxy URL into the application.

Optional variables:

When more than one provider key is configured, a provider dropdown appears in the panel header; a model dropdown lets you switch models for the selected provider. Your choice is remembered across sessions.

Reading keys from your system environment (desktop)

On the desktop app, Meratyn also reads the assistant’s keys directly from your operating system’s environment variables — the ones you export from your shell profile or set in the Windows Environment Variables dialog. Set a supported variable in your OS environment, restart the app, and the matching provider is configured automatically: you never type the key into Settings, and because it is not entered there, it is never written to the saved .meratyn.json project file. This is the recommended way to keep API keys out of project files that you share or commit.

Only the following allowlisted names are read from your environment — Meratyn never reads any other system variable (your PATH, HOME, and the like never reach the app), and this allowlist is enforced in the native backend, not just the UI:

Precedence: a value you enter in Settings → Environment Variables always wins; the OS environment only fills in the gaps. In the AI settings, any field supplied by the environment shows a note naming the variable backing it — leave that field blank to keep using the environment value.

Generic cloud credentials are never read Variables such as AWS_ACCESS_KEY_ID (and the ambient OLLAMA_HOST) are deliberately excluded from OS-environment reading: developers commonly have AWS credentials exported in their shell for unrelated work, and Meratyn must never silently adopt them as LLM credentials.

Desktop only Reading OS environment variables requires the native backend, so it applies to the desktop app only. The browser and Jupyter builds cannot read the system environment; there, enter keys in Settings → Environment Variables (or bake them in at build time). Changes to OS variables are picked up on the next app launch.

Using it

Type a request and press Enter (or click Send); Shift + Enter inserts a newline, and Ctrl/Cmd + Enter still sends. The assistant streams its reply, runs tools as needed, and reports what it did. While it is working, Send becomes Stop — click it to cancel. Clear (the eraser icon) starts a fresh conversation.

Your conversation is remembered: it is saved on this device per project and restored when you reopen the panel or the app, and switching provider or model keeps the history. Clear is what truly starts over. Only the most recent conversations are kept, so storage stays bounded.

show me all parcels larger than 1 hectare within 500 m of a river
color the counties by population using a graduated red ramp
buffer the roads by 100 m, then clip them to the county boundary
load the latest Sentinel-2 scene over this view
zoom to Africa, then switch to a dark basemap
add an OpenTopoMap basemap

What it can do

Model Builder drafts

Ask the assistant to turn a planned multi-step analysis into a Model Builder workflow. It checks available processing tools, then saves an editable workflow and opens the canvas. Review its tools, connections, input layers, and parameters before running it; creating a draft never executes processing or changes map layers.

The assistant works by calling a fixed set of tools — it cannot invent operations, so its actions stay within Meratyn’s validated surface.

Disaster-news search

For audited disaster and emergency-news lookups, configure the managed /v1/disaster-news route through the existing /ai reverse proxy (configured with MAPPVIEW_AI_PROXY_BASE_URL). The edge service holds the Tavily operator key; it is never sent to the browser, project file, or serializable error. The route fixes Tavily’s news topic, basic search depth, one request per prompt, no raw article body, and at most six summaries. It accepts only a trimmed query up to 512 characters, caps the request body at 2 KiB, times out after 25 seconds, and applies the edge rate limit (10 requests per client per minute by default; operators can lower it). Results are limited to credential-free HTTP(S) URLs and snippets are truncated before returning. If the route is unavailable or not configured, Meratyn reports a safe failure; it does not fall back to an unbounded provider for this audited path.

Sample prompts

Prompts are free-form — these are starting points, not fixed commands. Refer to layers by name; the assistant looks up the rest. You can also chain steps in one message (“buffer the roads by 100 m and then clip to the county boundary”) or keep refining across turns (“now color it by area”).

Explore & query

what layers are loaded, and what fields does the parcels layer have?
how many parcels are larger than 1 hectare?
list the 10 most populous counties with their population
show parcels within 500 m of a river and add them as a layer
count points in each polygon of the districts layer

Geoprocessing & analysis

buffer the roads by 100 meters
buffer the roads by 100 m, then clip the buffer to the county boundary
dissolve the parcels by zoning type
find where the floodplain overlaps the buildings (intersection)
create an H3 hex grid at resolution 8 over the points and count points per cell
compute centroids of the counties and add them as a layer

Symbology

color the counties by population with a graduated red ramp
style the parcels categorized by land-use type
shade the tracts by median income using a viridis ramp with 7 classes

Add data & imagery

load the latest Sentinel-2 scene over this view
add the most recent cloud-free Landsat image for this area
search the Planetary Computer for NAIP imagery here
add an OpenTopoMap basemap
add this GeoJSON: https://example.com/data.geojson

Map control & styling

zoom to the parcels layer
fly to Medellín
switch to a dark basemap
hide the buildings layer and set the parcels opacity to 0.5
remove the temporary buffer layer

Advanced (code fallback)

switch the map to a 3D globe projection
enable terrain with hillshade exaggeration of 1.5
load a CSV from a URL with pandas and summarize its columns

Safety and privacy

• Acts through the store. Layer, style, basemap, and add/remove actions go through the same one-way data flow as the rest of the app, so they are reconciled consistently and covered by undo/redo.
• Auditable. The generated SQL and every tool call appear in the transcript.
• Read-only SQL. The run_sql tool rejects anything that isn’t a SELECT / WITH query.
• Scoped context. Only layer/table names, attribute field names, and the current view are sent to the model — not your feature data.
• What leaves your browser. When you send a prompt, it (plus that scoped context) is sent to your chosen LLM provider using your own key. Don’t enable the assistant on sensitive data you can’t share with that provider.

Code-execution caveat The JavaScript and Python fallbacks execute model-generated code in the app to cover requests no dedicated tool handles. Their direct map changes bypass the store and are not undoable. The code is shown in the transcript.

Limitations

• Requires a provider API key; offline use is not supported.
• Subject to each provider’s cost, rate limits, and your network’s CORS/CSP policy (browser-side calls).
• The unofficial Google Maps tile endpoints are intentionally not included; use the listed officially-supported basemaps or supply your own XYZ URL.