AI in JEO

JEO includes built-in AI capabilities for georeferencing posts, generating maps, and suggesting editorial content. This page explains the underlying concepts so you can understand what happens behind the scenes and how to get the best results.

Overview

JEO's AI features are powered by a configurable external AI provider. The plugin never runs its own AI model — instead, it sends requests to the provider you choose (such as OpenAI, Google Gemini, or a local Ollama instance) and processes the results.

All AI features are optional. They activate only after you configure a provider in Jeo → AI (see AI Settings).

The key idea is that each AI feature is a specialized agent — an AI assistant with a specific role, a set of tools it can use, and access to your site's content through a knowledge base.

AI providers

JEO supports multiple AI providers through NeuronAI. Most providers run in the cloud and require an API key, while others (such as Ollama) run locally on your own server — meaning no data ever leaves your server.

You select a provider and model in Jeo → AI → Provider. The same provider is used across all AI features. The list of available providers is shown on the settings page and may grow over time as NeuronAI adds new integrations.

Knowledge Base (RAG)

RAG stands for Retrieval-Augmented Generation. It is a technique that lets the AI search your own content before answering, so its responses are grounded in your site's data rather than generic knowledge.

How it works

JEO maintains two separate knowledge bases (called vector stores):

Knowledge base Content Used by
Posts (jeo_knowledge) Your published posts — titles and body text Context Assistant
Layers (jeo_layers_knowledge) Your map layers — titles, types, legends, and descriptions Minimap

Each item is converted into a numerical representation (an embedding) and stored in a local file-based index. When an AI feature needs context, it:

  1. Converts the query into an embedding using the same model.
  2. Searches the index for the most similar entries.
  3. Passes the matching content to the AI along with the original request.

This means the AI can reference your actual articles and layers when generating results.

Indexing

Content is added to the knowledge base through indexing. You control this in Jeo → AI → Knowledge Base:

  • Auto-indexing runs in the background via WordPress cron and picks up new or updated posts and layers.
  • Manual indexing lets you trigger a full or partial re-index from the settings page.
  • WP-CLI is also available for large-scale indexing: wp jeo ai vectorize --store=posts --batch_size=20.

Embedding models

Embeddings are generated by a separate model from your AI provider. You configure the embedding model in the Knowledge Base tab. Common choices include text-embedding-3-small (OpenAI), text-embedding-004 (Gemini), or nomic-embed-text (Ollama).

Once a knowledge base is created with a specific embedding model, that model is locked — changing it requires clearing and rebuilding the store, because embeddings from different models are not comparable.

Search results (topK)

The topK setting (in Knowledge Base tab, range 1–50, default 10) controls how many documents are returned per search. Higher values give the AI more context but increase token usage. For most use cases, 10 is a good default.

How each feature uses RAG

Feature Uses RAG? Knowledge base Purpose
AI Georeferencing Optional — Can include taxonomy context; does not use the vector store directly
Minimap Yes Layers (jeo_layers_knowledge) Searches for relevant map layers to include in the generated map
Context Assistant Yes Posts (jeo_knowledge) Finds related articles to reference in suggestions
AI Bulk Geolocation No — Processes posts individually without RAG
Minilayer No — Uses MCP instead (see below)

Structured output

When the AI returns data — such as geolocation points or map configurations — JEO needs to parse it reliably. Structured output is a mechanism where the AI provider enforces a specific JSON schema at the API level, guaranteeing the response matches the expected format.

This is enabled by default and used by:

  • Georeferencing — returns locations with name, coordinates, confidence score, and primary/secondary classification.
  • Minimap — returns the complete map configuration (layers, center, zoom, pins).
  • Context Assistant — returns paragraphs and references.

If your provider does not support structured output, or if it fails for any reason, JEO automatically falls back to a free-text mode that extracts the data using pattern matching. You don't need to configure anything — the fallback is transparent.

Agents and tools

Each AI feature is built around an agent — an AI assistant configured for a specific task. Agents are given a system prompt (instructions), a set of tools they can call, and optionally access to sub-agents for delegated work.

The tools

Tool What it does Used by
search_layers Searches the layer knowledge base for relevant layers Minimap
geocode Converts a location name into latitude/longitude coordinates Minimap
retrieve_knowledge Searches the post knowledge base for related articles Context Assistant
get_post_content Retrieves a post's title, content, categories, tags, and geolocations Minimap, Context Assistant
generate_layer Creates a new Mapbox style and layer CPT from a description Minimap (requires Mapbox key)

When you ask the Minimap to "show deforestation data in the Amazon," the agent might:

  1. Use get_post_content to understand the current article.
  2. Use search_layers to find layers about deforestation.
  3. Use geocode to locate the Amazon region.
  4. Return a complete map configuration.

Sub-agents

Some agents delegate work to specialized sub-agents. Both Minimap and Context Assistant use a post analyzer sub-agent that reads the post content and extracts topics, locations, tone, and suggested search queries. This analysis guides the main agent's decisions.

Conversation memory

AI features that support chat (Minimap, Context Assistant, and Georeferencing) maintain conversation history per post. This means:

  • You can refine results through back-and-forth chat without repeating context.
  • Conversations persist across page reloads — closing the editor and returning later resumes where you left off.
  • Each post has its own independent conversation.

Learning and user memory

The Minimap and Context Assistant agents can learn from interactions. Over time, they accumulate knowledge about patterns and preferences. They also store per-user memory (e.g., preferred writing style), so suggestions become more personalized the more you use them.

MCP (Model Context Protocol)

MCP is a protocol that connects AI agents to external services. In JEO, it is used exclusively by the Minilayer feature to communicate with the Mapbox MCP DevKit — an external service that generates Mapbox map styles.

When you ask the AI to create a custom layer (e.g., "generate a deforestation heatmap for the Amazon"), the Minilayer agent:

  1. Connects to the Mapbox MCP server using your Mapbox API key.
  2. Uses Mapbox's tools to build, validate, and preview the style.
  3. Creates a new layer post in WordPress with the generated style.

MCP requires a Mapbox API key configured in Jeo → Settings. It is not used by any other feature.

Privacy and data

Understanding what data is sent where:

Data point Sent to Stored
Post content (for analysis) Your configured AI provider No — used transiently
Geolocation queries Your configured AI provider No
Embeddings (knowledge base) Your configured AI provider (during indexing) Yes — stored locally in wp-content/uploads/jeo-ai-store/
Conversation history Not sent to AI provider after initial call Yes — stored in WordPress post meta
User preferences (memory) Not sent externally Yes — stored in WordPress user meta
Mapbox styles (MCP only) Mapbox MCP DevKit Yes — stored as layer posts in WordPress

If you use a local provider (Ollama), no data leaves your server at all.

Token usage

JEO tracks AI token usage in Jeo → AI Debug Logs. Each log entry records the provider, model, input and output tokens, and the prompt and response. Use this to monitor costs and troubleshoot results.

Feature — concept matrix

A quick reference for which concepts apply to each feature:

Provider RAG Structured output Tools Conversation memory MCP
AI Georeferencing ✓ — ✓ — ✓ —
AI Bulk Geolocation ✓ — ✓ — — —
Minimap ✓ ✓ ✓ ✓ ✓ —
Context Assistant ✓ ✓ ✓ ✓ ✓ —
Minilayer ✓ — — — — ✓

Next steps