Upgrading the AI plugin

Use the section for the version you are adopting. Upgrading to 4.0 covers removal of the legacy settings and Java APIs. Upgrading to 3.0 describes the earlier move from 1.x and 2.x to the agent platform, including the dependency and vector-index changes.

Upgrading to 4.0

Version 4.0 removes the legacy Create with Esca and Ask Esca client records, their site-settings bridge, and automatic settings relocation. This affects existing 3.x installations as well as projects upgrading from earlier releases. References to removed APIs must be updated and recompiled before deployment.

Preserve configuration before deployment

danger

4.0 does not read or relocate legacy AI settings from Sites & Settings > Integrations. A site without its own AiPluginConfig uses the plugin's Default Config, even if the site still has a legacy client or different legacy enable flags. If no plugin configuration exists, both features are disabled and no chat client is configured.

To prepare an existing installation:

1. While the existing version is still running, record the global and per-site AI settings, including custom client, provider, formatter, and localization behavior. If upgrading from 1.x or 2.x, complete the 3.0 migration first.
2. On 3.x, open Admin > Plugins > AI and compare the plugin settings with the legacy global settings. Configure any missing values using the table below, then click Save. Loading the plugin and seeing relocated values does not establish that those values have been persisted.
3. For each site with settings that differ from the global defaults, open its Plugins tab in Sites & Settings and configure an AiPluginConfig. Include the chat client, both enable flags, and the required agents. The old relocation copied global settings only; it did not migrate each site's overrides.
4. Verify the saved configuration after reloading the plugin and each site's configuration. If configuration is supplied through context properties, verify that those properties supply all required settings, including enable flags and agent settings. Supplying only the chat client and embedding generator does not replace legacy relocation.
5. Update project code, dependencies, and resource overlays as described below, then build the project against 4.0.

Legacy configuration	Destination in 4.0
Create with Esca and Ask Esca enable flags	Create with Esca Enabled and Ask Esca Enabled on Default Config or the site's AiPluginConfig
Create provider and Ask Search Provider	A Chat Client on the selected configuration, shared by both features; reconfigure its model and credentials
Create Brand Guidelines	Brand Guidelines on the Create with Esca Agent (CreateWithAiAgent#getAdditionalInstructions())
Site-wide, content-level, and field-level prompt suggestions	Global Prompt Suggestions and Type Specific Prompt Suggestions on the Create with Esca Agent
Default and other author personas	Default Persona and Other Personas on the Create with Esca Agent
Generation timeout and generated-content detectors	Generation Timeout and Generated Content Detectors on the Create with Esca Agent
Ask vectorizable content types	Additional Types on the plugin, or EmbeddingGeneratable on the content class

A site's AiPluginConfig replaces the default configuration as a whole. Empty agent lists and disabled flags do not inherit values from Default Config. Configure each site's agents explicitly when they need the same settings as the defaults. The agent timeout defaults to 180 seconds; a positive ai/createWithAiTimeoutSeconds context property still overrides it. Without configured detectors, tracking uses DefaultGeneratedTextDetector.

Remove the obsolete com.brightspot.ai.AiPlugin/legacyConfigRelocated context property and any instructions to keep it enabled. The field and relocation hook no longer exist. Complete property-based plugin configuration remains supported.

The removed settings include the ai.chat. fields aiChatEnabled, aiChatClient, askAiEnabled, askAiClient, siteWidePromptSuggestions, contentLevelPromptSuggestions, generatedContentDetectors, and generationTimeoutSeconds. Existing values are no longer consulted; their presence in stored records does not configure 4.0. Legacy shared-provider records are no longer selected through the removed provider options. Reconfigure the active chat client instead of relying on those references.

AuthorPersonaSiteSettings still exposes Default Author Persona and Other Author Personas under Integrations > AI, but Create no longer reads those fields. Select the existing persona records on the agent. User-level default persona preferences remain supported.

Removed APIs and replacements

Unless otherwise qualified, the legacy types below are in com.psddev.ai.cms. Their removal includes their constructors, accessors, and subclass extension points. The replacements live in com.brightspot.ai and its agent, chat, and embedding packages.

Removed or changed API	Migration
AIChatSettings, including getCurrent(), getCurrent(Site), and getCurrentSite()	Resolve AiPluginConfig#get(Site) with the applicable site. Read feature flags and the chat client from that configuration, and feature settings from its agents.
AIChatSettings#TAB_NAME, AIChatSettings#CLUSTER_NAME	Use AiPlugin#SETTINGS_TAB_NAME and AiPlugin#SETTINGS_CLUSTER_NAME; their values are unchanged.
AIChatClient	Use the configured CreateWithAiAgent for Create settings and AiPluginConfig#getChatClient() for the chat client.
AskAIClient, including getCurrent() and getSearchProvider()	Use the configured AskAiAgent and AiPluginConfig#getChatClient().
AIProviderOption, OneOffAIProviderOption, SharedAIProviderOption	Configure a ChatClient in Default Config or the site's AiPluginConfig.
AskAITypesSetting, DefaultAskAITypesSetting	Use EmbeddingGeneratable or the plugin's Additional Types. Custom type-selection and embedded-type exclusion policies need to be reviewed against the embedding pipeline; there is no equivalent types-setting subclass hook. @ExcludeFromEmbedding excludes individual fields.
AIChatProvider#getModelNames(), AIChatProvider#invokeLlm(ChatSession), AIChatProvider#invokeLlmAsync(ChatSession)	Implement ChatClient for custom LLM integrations. Call ChatClient#complete or ChatClient#completeAsync with a ChatRequest instead of invoking the legacy provider.
AIChatProviderModelIdValueGenerator	Remove references to the legacy model selector; configure the model on the chat client.
AIChatClientDynamicField, AskAIClientDynamicField	Remove annotations or custom code using these helpers. They validated the removed client settings and have no direct replacement.
ResponseTextFormatter, NoneResponseTextFormatter, com.brightspot.ai.chat.message.AssistantMessage#setTextFormatter(ResponseTextFormatter)	No configurable formatter replacement. See Response formatting and tracking.
MarkdownToHtmlResponseFormatter construction, subclassing, instance formattedText(String), and protected convertMarkdownToHtml hook	The class is now a final utility with static MarkdownToHtmlResponseFormatter#formattedText(String). Update direct callers and remove subclasses; custom renderer injection is no longer supported.
com.psddev.ai.cms.persona.AIAuthorPersonaProfile#getAiChatClient() and setAiChatClient(AIChatClient)	Remove per-persona client selection. Persona generation already uses the configured chat client; the hidden legacy field is also removed.
com.psddev.ai.cms.persona.GenerateAuthorPersonaTask(AuthorPersona, AIChatProvider)	Use GenerateAuthorPersonaTask(AuthorPersona). The removed provider argument was already ignored.

AiPluginConfig#getAgent(Class) returns the configured agent or a transient default if that agent is absent. Use CreateWithAiAgent#getPromptSuggestions(ObjectType, String) in place of the legacy suggestion-map helpers.

AIChatProvider remains for compatibility with stored audit snapshots, with getModelNameInUse() and templatedContextMessage(UserMessage, Message). Its presence does not preserve the removed completion APIs. Update custom implementations and callers, and replace legacy com.psddev provider artifacts with the com.brightspot.ai provider modules described in the dependency migration.

Prompts, providers, and audit records

warning

Legacy System Prompt values have no equivalent setting that replaces an agent's structural prompt. Agents define that prompt in code. Move any still-required guidance to Brand Guidelines on the Create agent or Additional Instructions on the Ask agent; these append instructions rather than replacing the structural prompt.

The removed Ask client search limits, score thresholds, token budget, and recent-conversation window are not copied to AskAiAgent. Agent tools control retrieval, and there is no one-to-one replacement for those legacy settings. Review custom search behavior separately from the searchable-type configuration.

Both CMS endpoints already ran completions through agents and the configured ChatClient before this removal. However, Create still called the legacy provider's templatedContextMessage() when preparing a prompt. It now uses the built-in template, so custom legacy prompt-templating implementations are no longer called. Move required prompt or request customization to the agent or chat-client integration.

New Ask and Create audit responses use an internal provider adapter. The displayed model name is resolved from the chat client in the viewing context, not captured from the selected legacy provider when generation runs. Changing the configured model or viewing site can therefore change the model name shown for these records. Custom legacy providers no longer supply their metadata for new responses. Existing audit snapshots are not rewritten by this change; retain any project classes needed to read historical records.

Response formatting and tracking

Completed, successful AssistantMessage responses rendered by the Java chat interface use built-in Markdown-to-HTML conversion unless marked as rich-text content. Rich-text responses retain their HTML. Custom formatters and NoneResponseTextFormatter are no longer used, including when existing conversation history is rendered. Incomplete and error responses still display escaped text.

AI tracking also uses the built-in conversion when deriving comparison text from a saved chat response. Projects that supplied raw-text or custom formatting can see different generated-content matches on existing content. Verify both response display and generated-field markers after upgrading.

Dependencies and localization

com.vladsch.flexmark:flexmark changes from an api dependency to an implementation dependency of com.brightspot.ai:ai. It remains available to the plugin at run time, but is no longer exported as a compile dependency. Projects importing Flexmark classes must declare the Flexmark modules they use directly.

The following bundles under com/psddev/ai/cms/ are removed:

• AIChatClientDefault_en.properties and AIChatClientDefault_es.properties.
• AskAIClientDefault_en.properties and AskAIClientDefault_es.properties.

Project overlays for these legacy clients no longer customize their removed UI or prompts. Review overrides of message.defaultSystemPrompt, message.brandGuidelinesPromptPrefix, message.brandGuidelinesPromptPostfix, and the legacy note.* and error keys. Move required prompt guidance to the agents; keeping an overlay file does not restore the old prompt behavior.

Verify the 4.0 upgrade

To verify the deployment:

1. Check Create and Ask visibility and permissions on each site, including sites that previously used legacy overrides. The AI_CHAT_ENABLED JavaScript global keeps its name but now reads the plugin configuration.
2. Generate content from a field and from the rich-text editor. Check suggestions, personas, guidelines, timeout, formatting, and AI-generated field markers against the migrated configuration.
3. Ask about content from each intended searchable type, and verify the answer and citations. This retirement does not itself require rebuilding an existing 3.x vector index; the earlier 1.x/2.x migration does.
4. Verify audit display and export for new Ask and Create responses and for historical records, accounting for the model-name behavior described above.

If the resolved configuration has no chat client, the Create endpoint returns 503 before starting generation. Configure the client on that site's configuration, or on Default Config if the site has no configuration of its own.

Upgrading to 3.0

This section describes the historical 1.x/2.x-to-3.0 migration. Its compatibility bridges and relocation steps apply to 3.x, not to 4.0. After completing this migration, follow Upgrading to 4.0 before deploying 4.x.

Version 3.0 consolidates Create with Esca and Ask Esca onto a unified AI platform built around agents, chat clients, and a shared embedding pipeline. This represents a shift from Create and Ask being standalone products with their own maintenance overhead to being part of a core Brightspot AI offering.

The plugin is now published as multiple modules with the AI provider integrations moved out of Brightspot core and into this plugin, and vector search runs on the com.brightspot.db vector database API.

This section describes how to upgrade a project from 2.x to 3.0.x, including dependency changes, configuration changes, code refactors, and the operational steps required after deployment. For upgrades from 1.x, see the Upgrading from 1.x section at the end of this guide.

What changed in 3.0

Module layout

The plugin is now published as several artifacts under the com.brightspot.ai group, with versions managed by a BOM:

Artifact	Purpose
com.brightspot.ai:bom	Aligns versions of all plugin modules
com.brightspot.ai:ai	Core plugin containing agents, chat, embeddings, CMS integration
com.brightspot.ai:openai	OpenAI chat client and text embedding generator
com.brightspot.ai:bedrock	Amazon Bedrock chat client, guardrails, and text embedding generator
com.brightspot.ai:gemini	Google Gemini chat client and text embedding generator
com.brightspot.ai:mcp	MCP server exposing CMS content tools (optional)

The legacy com.psddev AI artifacts that 1.x and 2.x projects depended on are replaced:

Legacy artifact	Replaced by
com.psddev:ai-chat, com.psddev:dari-ai, com.psddev:dari-ai-db	com.brightspot.ai:ai
com.psddev:openai	com.brightspot.ai:openai
com.psddev:aws-bedrock	com.brightspot.ai:bedrock
com.psddev:google-vertex-ai	com.brightspot.ai:gemini
com.psddev:solr-ai, com.psddev:dari-solr, com.psddev:dari-solr-v6, com.psddev:opensearch	com.brightspot.db search back-end modules

New APIs

• Agents: com.brightspot.ai.agent introduces Agent, AskAiAgent, and CreateWithAiAgent. Agents own feature-specific configuration (prompt suggestions, personas, brand guidelines, search behavior) and run on a tool-calling Engine rather than a single pre-built retrieval pass.
• Chat clients: com.brightspot.ai.chat.ChatClient replaces com.psddev.ai.cms.AIChatProvider as the LLM integration point. Provider implementations (OpenAIChatClient, BedrockChatClient, GeminiChatClient) ship in the provider modules.
• Embedding pipeline: Content opts into vector indexing by implementing com.brightspot.ai.embedding.EmbeddingGeneratable (or by being listed in the AI plugin's Additional Types). Embeddings are chunked by a configurable com.brightspot.ai.chunker.TextChunker and written to the vector database on save.
• Plugin configuration: Global configuration lives on com.brightspot.ai.AiPlugin (Admin > Plugins > AI) instead of the Integrations tab of Sites & Settings. Defaults can be supplied through context properties; CMS settings override them.

New features

• MCP server for exposing CMS content tools to external AI clients (see MCP).
• AI Audit widget for reviewing AI interactions, with links to the content where each interaction occurred ( see AI Audit).
• Guardrail support, including Amazon Bedrock guardrails.
• Google Gemini provider module.
• Create with Esca tracking and AI module flagging for AI-generated content.
• Role permissions for AI features through the ToolPermissions API.

Deprecated, not removed

3.0 keeps the legacy com.psddev.ai.* classes on the classpath as deprecated compatibility bridges, so 2.x project code generally still compiles against 3.0 with deprecation warnings.

The legacy RAG surface (com.psddev.ai.search.*), client records (AIChatClient, AskAIClient), and guardrail types remained available in 3.0. The client records and settings bridge are removed in 4.0; see the removed API table before upgrading beyond 3.x. A small number of internal types were removed in 3.0 itself (for example, Prompt, SystemPrompt, and Response). See Step 3: Update project code.

What carries over and what does not

In 3.x, loading the AI plugin relocates legacy global settings into plugin configuration. Review and save the result in the CMS. Per-site legacy overrides are not copied by this relocation and must be configured separately. This relocation is removed in 4.0.

Data	After upgrade
Create with AI and Ask AI enable flags	Relocated to the plugin's Default Config
Brand guidelines	Relocated to the Create with Esca Agent's Additional Instructions
Site-wide and content-level prompt suggestions	Relocated to the Create with Esca Agent
Author personas (default and others)	Relocated to the Create with Esca Agent
Generation timeout and generated-content detectors	Relocated to the Create with Esca Agent
Ask AI vectorizable content types	Relocated to the plugin's Additional Types
Prompt suggestion, persona, tracking, and usage records	Records are retained. Select the required suggestions and personas in the agent configuration.
Chat client / provider configuration and credentials	Not migrated. The legacy provider records reference classes from the removed com.psddev artifacts. Reconfigure the chat client and text embedding generator.
Ask AI search tuning (max records, score thresholds, token limits, history window)	Not migrated. The agent uses tools for retrieval; these legacy settings have no one-to-one mapping to agent fields.
Legacy system prompts and response formatting	Not migrated to agents. Agents define structural prompts in code. Legacy formatter customization is removed in 4.0.
Chat conversation history	Not migrated. Conversation record types changed packages
Vector embeddings	Not migrated. Rebuild the vector index (see Step 5)

Upgrade process

Before you begin

• Java 21—3.x is compiled to Java 21. The project must build and run on Java 21 (Gradle toolchain, CI, and Tomcat images). This is typically the largest operational prerequisite; complete it before the plugin upgrade.
• Brightspot core—3.0.x is built against com.psddev:brightspot-bom:4.8.14. Upgrade the project's brightspot-bom and brightspot-dependencies to 4.8.14 or later first.
• Vector search back end—Decide where vector search will run: OpenSearch (most common), Solr, or Solr for text with OpenSearch for vectors. If the environment has no OpenSearch cluster and OpenSearch is the chosen back end, provision it before the upgrade.
• Provider credentials—Have the AI provider credentials (for example, the OpenAI API key) available. Provider configuration is not migrated and must be re-entered.

Step 1: Update dependencies

Remove all legacy com.psddev AI dependencies from every module in the project, including any exclude workarounds for com.psddev:ai-chat:

1
// Remove direct and transitive usages of all of these:
2
// com.psddev:ai-chat
3
// com.psddev:dari-ai
4
// com.psddev:dari-ai-db
5
// com.psddev:openai
6
// com.psddev:aws-bedrock
7
// com.psddev:google-vertex-ai
8
// com.psddev:solr-ai
9
// com.psddev:dari-solr
10
// com.psddev:dari-solr-v6
11
// com.psddev:opensearch

Add the 3.0 modules. The example below shows OpenAI as the provider and Solr text search with OpenSearch vector search; see Getting started for the full search back-end matrix and other providers.

1
dependencies {
2
    api platform('com.brightspot.ai:bom:3.0.0')
3
    api platform('com.brightspot.db:bom:2.4.2')
4

5
    api 'com.brightspot.ai:ai'
6
    api 'com.brightspot.ai:openai'
7

8
    api 'com.brightspot.db:db'
9
    api 'com.brightspot.db:vector'
10
    api 'com.brightspot.db:opensearch-vector'
11
    api 'com.brightspot.db:opensearch-aws'
12
}

tip

Use the latest 3.0.x release of com.brightspot.ai:bom. Releases are listed on the platform-ai releases page.

warning

Leftover legacy artifacts on the classpath cause conflicts because 3.0 ships classes in the same com.psddev.ai packages. Verify removal with ./gradlew :site:dependencies (or the equivalent WAR module) before deploying.

Step 2: Update context properties

Vector database configuration keeps the same dari/vectorDatabase key structure but uses the com.brightspot.db implementation classes. Replace legacy values such as com.psddev.solr.ai.SolrVectorDatabase with the new classes. For example, for OpenSearch:

1
dari/defaultVectorDatabase=<name>
2
dari/vectorDatabase/<name>/class=com.brightspot.opensearch.vector.OpenSearchVectorDatabase
3
dari/vectorDatabase/<name>/client/class=com.brightspot.opensearch.common.HttpOpenSearchClientSupplier
4
dari/vectorDatabase/<name>/client/baseServerUrl=<url>
5
dari/vectorDatabase/<name>/index=<index>

Solr, Solr Cloud, and AWS-hosted OpenSearch variants are documented in Getting started.

Provider and plugin defaults can be supplied as context properties so credentials stay out of the database. Settings configured in the CMS override these defaults:

1
com.brightspot.openai.OpenAIPlugin/apiKey=<api-key>
2

3
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator
4
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-3-small
5
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient
6
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=gpt-4o

Step 3: Update project code

When targeting 3.0, many 2.x integration points remain available, so start by building the project and reviewing deprecation warnings. The table below maps common 2.x APIs to their 3.0 replacements; it does not describe 4.0 compatibility.

2.x API	3.0 replacement
com.psddev.ai.cms.AIChatProvider (custom provider implementations)	Implement com.brightspot.ai.chat.ChatClient
com.psddev.ai.chat.Prompt, SystemPrompt, Response, LlmResponseMetadata (removed)	com.brightspot.ai.chat.ChatRequest, ChatSession, and com.brightspot.ai.chat.message types
com.psddev.ai.chat.Chat, Message	Moved to com.brightspot.ai.chat.Chat and com.brightspot.ai.chat.message.Message
com.psddev.ai.cms.AIChatClient, AskAIClient (retained in 3.x; removed in 4.0)	CreateWithAiAgent and AskAiAgent in plugin configuration
com.psddev.ai.search.RecordVectorSerializer (deprecated)	Implement com.brightspot.ai.embedding.EmbeddingGeneratable on the content type
com.psddev.ai.search.chunking chunkers (removed)	com.brightspot.ai.chunker chunkers (FixedLengthTextChunker, RecursiveTextChunker, JsonTextChunker, RecursiveJsonTextChunker)
@ExcludeFromVectorization (deprecated)	@ExcludeFromEmbedding in com.brightspot.ai.embedding
com.psddev.ai.search.contexts.ContextGenerator, com.psddev.ai.search.prompts.* (deprecated)	No direct replacement. The Ask Esca agent performs retrieval through tool calling instead of a directly attached RAG pipeline, for uniformity.
com.psddev.ai.cms.FeatureType	Moved to com.brightspot.ai.chat.FeatureType
@GenerateEmbedding (deprecated for removal)	Implement EmbeddingGeneratable; override EmbeddingGeneratable#shouldGenerateEmbedding() for conditional indexing
Root-package embedding classes from 2.1 (com.brightspot.ai.TextEmbeddingGenerator, TextChunker, ExcludeFromEmbedding)	Moved to com.brightspot.ai.embedding and com.brightspot.ai.chunker

Content types that should be searchable by Ask Esca either implement EmbeddingGeneratable or are selected in the AI plugin's Additional Types field. In 3.x, types selected through the legacy global Ask AI types setting are relocated to Additional Types. Verify and save that selection before upgrading to 4.0.

Step 4: Verify CMS configuration

All AI configuration now lives at Admin > Plugins > AI, with optional per-site overrides on the Plugins tab of each site in Sites & Settings.

To verify the configuration after deploying:

1. Navigate to Admin > Plugins > AI.
2. Confirm the relocated global settings match the previous configuration, and configure per-site overrides on each site's Plugins tab.
3. Set the enable toggles on Default Config, and configure prompt suggestions, personas, and brand guidelines on the Create with Esca Agent.
4. From the Text Embedding Generator list, select a provider and model (required for Ask Esca).
5. Under Default Config, from the Chat Client list, select a provider and configure its model and credentials ( unless supplied through context properties).
6. Under Default Config, add an Ask Esca Agent to the Agents list if Ask Esca is used, and configure its search behavior.
7. Click Save.

Review role permissions for AI features afterward. 3.0 enforces them through the ToolPermissions API. See Configuration.

Step 5: Rebuild the vector index

Existing embeddings were written by the legacy vector pipeline and are not readable by 3.0. After the new vector database is configured, content is chunked and embedded automatically on save, but existing content must be backfilled with a bulk index.

To rebuild the vector index:

1. In a browser, go to /_debug/vectorize-bulk on a CMS host.
2. Select the content types and sites to index.
3. Submit the form. This starts a BulkVectorIndexTask, which writes embeddings concurrently and records progress in BulkVectorIndexLog.
4. Monitor progress at /_debug/task.

warning

Bulk indexing calls the provider's embedding API for every chunk of every eligible asset. For large content sets, plan for API cost and rate limits, and run the task during off-peak hours.

Once the new index is verified, the legacy vector collection (for example, the Solr vectorCollection1 core) can be decommissioned.

Step 6: Verify the upgrade

• Create with Esca generates content on a field and inline in the rich-text editor.
• Ask Esca answers a question about site content and cites sources.
• New or updated content appears in the vector index after publishing (document count grows in the vector back end).
• The AI Audit widget records interactions and links to the related content.
• Roles without AI permissions do not see AI entry points.
• The application log shows no ClassNotFoundException or unknown-type warnings referencing com.psddev.ai or legacy provider classes.

Upgrading from 1.x

Projects on 1.x follow the same steps as 2.x projects, upgrading directly to 3.0.x. The only breaking change introduced in 2.0 was the AI Usage Dashboard widget, which requires no project-side action beyond the dependency update. The legacy artifact removals in Step 1 cover the 1.x dependency set, including the com.psddev:ai-chat exclusion workaround that 1.x installations required.

Release lines

Active development happens on the 4.x line. The 3.x line receives critical fixes only, on the release/3 branch. Bug fixes that ship in 4.x releases are generally not backported. Release notes for every version are published on the platform-ai releases page.