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.
Before you begin
- Java 21—4.0 is compiled to Java 21.
- Brightspot core—4.0 is built against
com.psddev:brightspot-bom:5.0.10, and Brightspot 5.0.12 and later import it throughbrightspot-dependencies. Upgrade the project'sbrightspot-bomandbrightspot-dependenciesto 5.0.12 or later.
In 4.0, agents can read files attached to assets, including files in embedded records and on directly referenced
assets, and send them to the AI provider or MCP client. This needs no opt-in and is available as soon as 4.0 is
deployed. Before deploying, review Multimodal Allowed MIME Types and Multimodal Maximum File Size on Default
Config and on each site's AiPluginConfig. See Multimodal input.
Preserve configuration before deployment
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:
- 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.
- 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.
- 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. - 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.
- 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.
Update the plugin version
Brightspot manages the plugin's version: its brightspot-dependencies BOM imports the plugin's BOM, so upgrading
Brightspot to 5.0.12 or later upgrades every com.brightspot.ai module to 4.x. The project does not set the version
itself (see Plugin version).
Remove everything in the project that sets a com.brightspot.ai version: entries in dependencyConstraints, versions
on individual dependencies, and imports of com.brightspot.ai:bom. A leftover pin holds its module at the pinned
release while Brightspot moves the rest, such as mcp-server, which mcp adds at run time, and the project ends up
with a mix of plugin releases.
Confirm the result with ./gradlew :site:dependencies (or the equivalent .war module): every com.brightspot.ai
module resolves to the same 4.x release.
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. |
The com.psddev.ai.search RAG answer path: ContextGenerator, com.psddev.ai.search.prompts.*, ConversationResponseData, ConversationResponseMetadata, and the answer and context templates under ai/prompts | Ask Esca retrieves through tool calling. Conversation remains only as chat history |
@GenerateEmbedding in com.brightspot.ai.embedding, and its processor | EmbeddingGeneratable#shouldGenerateEmbedding() |
com.psddev.ai.search.RecordVectorSerializer and the vector serialization stack, including VectorizationFormatter, DefaultVectorizationFormatter, and VectorData | EmbeddingGeneratable |
@ExcludeFromVectorization in com.psddev.ai.search, ExcludeFromVectorizationData, and ExcludeFromVectorizationProcessor | @ExcludeFromEmbedding in com.brightspot.ai.embedding |
| The platform guardrail package, its assessment records, and the guard columns of the AI Audit widget and CSV export | Bedrock Guardrail Chat Client, or the Guardrail field on Bedrock Chat Client |
com.brightspot.ai.mcp.McpApiEndpoint | A Custom API endpoint with the MCP handler (see MCP) |
com.psddev.ai.chat.ChatPageResponses (/cms/ai/responses) | Create with Esca uses /cms/ai/api/create-with-ai/chat |
Handlebars prompt templates, including com.psddev.ai.cms.persona.GenerateAuthorPersonaPrompt and GenerateAuthorPersonaSamplePrompt | The author persona prompts use plain placeholder substitution |
Types that relied on @GenerateEmbedding are no longer embedded unless they implement EmbeddingGeneratable or are
listed in Additional Types; set this up before deploying. Vectors already stored for a type that is no longer
embedded are not updated or removed when its assets are saved or deleted. A bulk index
deletes every stored vector before it reindexes the indexed types, which removes them.
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.
Renamed tools
4.0 consolidates several agent and MCP tools. Integrations that call a 3.x tool by name must use its replacement:
| 3.x tool | 4.0 replacement |
|---|---|
Content_searchType, Content_getType, Content_describeRichTextToolbar | Content_describeType |
Content_searchTextually, Content_searchSemantically | Content_search, with mode set to TEXT or SEMANTIC |
Content_get | Content_read |
Theme_getCurrent, Theme_describeType | Theme_inspect |
The replacements take different parameters and return different results. MCP clients must refresh tools/list and
any cached tool schemas after the upgrade. The com.brightspot.ai:mcp-experimentation artifact and its
Experimentation tool group are no longer part of this plugin; see
Plugin-owned tool groups.
Prompts, providers, and audit records
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.
Export CSV on the AI Audit widget no longer saves a copy of each export to storage, as 3.x did; the file downloads directly.
The AI Audit widget and its CSV export now show only records from sites the viewing user can access, using a new index on the record's site. Records saved before the upgrade have no entry in that index. Until they are reindexed, site-restricted users see none of them, and users with access to global content see all of them, including records from sites they cannot access.
To reindex existing audit records:
- Navigate to
/_debug/db-bulk. - Under Index, select the Chat Session type (
com.brightspot.ai.chat.ChatSession). - Click Start, and wait for the task to finish.
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.
com.brightspot.ai:ai no longer exports com.psddev:dari-util or com.psddev:dari-web as compile dependencies. It
exports com.brightspot.util:util, com.brightspot.util:web-common, and com.brightspot.util:web-util instead.
Projects that compiled against classes from the removed modules through the plugin must declare the modules they need.
com.brightspot.ai:mcp no longer exports com.brightspot.db:db, com.psddev:cms-db-internal, com.psddev:dari-web,
or org.jspecify:jspecify. Declare the modules the project compiles against directly. It adds
com.brightspot.ai:mcp-server at run time only, so code that references McpApiHandler or other MCP server classes
must depend on com.brightspot.ai:mcp-server.
The MCP modules use version 2.0.1 of the MCP Java SDK (io.modelcontextprotocol.sdk:mcp-bom), a new major version;
3.x used 1.1.2. Projects that also use the SDK directly must be compatible with 2.0.
The following bundles under com/psddev/ai/cms/ are removed:
AIChatClientDefault_en.propertiesandAIChatClientDefault_es.properties.AskAIClientDefault_en.propertiesandAskAIClientDefault_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:
- Check Create and Ask visibility and permissions on each site, including sites that previously used legacy overrides.
The
AI_CHAT_ENABLEDJavaScript global keeps its name but now reads the plugin configuration. - 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.
- 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.
- Verify audit display and export for new Ask and Create responses and for historical records, accounting for the model-name behavior and the reindex 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.
4.0 evaluates Use Ask Esca? on Ask Esca Permission through Brightspot's standard permission check for the
current user and site (ToolRequest#hasPermission("ask-ai")), for both the launcher and Ask Esca requests. 3.x instead
showed the launcher when Use Ask Esca? was on in the additional permissions of any of the user's roles, or when the
user had no role permissions. Users can therefore gain or lose Ask Esca after the upgrade; check the launcher for each
role on each site.
To verify a 4.0 upgrade:
- The left navigation (the header in the v4 UI) shows the Ask Esca launcher; the panel opens, lists recent conversations, and closes.
- Admin > Plugins > AI loads and saves.
- Toggling off Ask Esca Enabled on a site's own AI Plugin Config hides the launcher on that site.
- Create with Esca opens from a text field and shows the configured prompt suggestions and personas without calling the provider.
- A role without the AI permissions sees neither the launcher nor the Create with Esca links.
- Export CSV on the AI Audit widget produces the columns listed in AI Audit.
- The content search offers the Contains AI? filter.
- An MCP endpoint answers
401without credentials and advertises theContent_*tools ontools/listwith credentials. - The application log shows no
ClassNotFoundExceptionorSEVEREentries from the plugin.
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.agentintroducesAgent,AskAiAgent, andCreateWithAiAgent. Agents own feature-specific configuration (prompt suggestions, personas, brand guidelines, additional instructions) and run on a tool-callingEnginerather than a single pre-built retrieval pass. - Chat clients:
com.brightspot.ai.chat.ChatClientreplacescom.psddev.ai.cms.AIChatProvideras 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 configurablecom.brightspot.ai.chunker.TextChunkerand 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 Brand Guidelines |
| 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. Brightspot releases from 5.0.8 up to, but not including, 5.0.12 import a 3.x release of the plugin throughbrightspot-dependencies; upgrade the project'sbrightspot-bomandbrightspot-dependenciesto one of those releases 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-chat3// com.psddev:dari-ai4// com.psddev:dari-ai-db5// com.psddev:openai6// com.psddev:aws-bedrock7// com.psddev:google-vertex-ai8// com.psddev:solr-ai9// com.psddev:dari-solr10// com.psddev:dari-solr-v611// com.psddev:opensearch
Add the 3.0 modules without versions. Brightspot's brightspot-dependencies BOM supplies the versions of the
com.brightspot.ai and com.brightspot.db modules, so the project sets neither (see
Plugin version). 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.
1dependencies {2api 'com.brightspot.ai:ai'3api 'com.brightspot.ai:openai'45api 'com.brightspot.db:db'6api 'com.brightspot.db:vector'7api 'com.brightspot.db:opensearch-vector'8api 'com.brightspot.db:opensearch-aws'9}
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:
1dari/defaultVectorDatabase=<name>2dari/vectorDatabase/<name>/class=com.brightspot.opensearch.vector.OpenSearchVectorDatabase3dari/vectorDatabase/<name>/client/class=com.brightspot.opensearch.common.HttpOpenSearchClientSupplier4dari/vectorDatabase/<name>/client/baseServerUrl=<url>5dari/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:
1com.brightspot.openai.OpenAIPlugin/apiKey=<api-key>23com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator4com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-3-small5com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient6com.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:
- Navigate to Admin > Plugins > AI.
- Confirm the relocated global settings match the previous configuration, and configure per-site overrides on each site's Plugins tab.
- Set the enable toggles on Default Config, and configure prompt suggestions, personas, and brand guidelines on the Create with Esca Agent.
- From the Text Embedding Generator list, select a provider and model (required for Ask Esca's semantic search).
- Under Default Config, from the Chat Client list, select a provider and configure its model ( unless supplied through context properties). Credentials are configured on the provider's own plugin, not on the chat client; see Configuring OpenAI.
- Under Default Config, add an Ask Esca Agent to the Agents list if Ask Esca needs Additional Instructions; it works with built-in defaults otherwise.
- 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. The same bulk index is needed after changing the text embedding generator's Model or Dimension, because stored embeddings are not regenerated.
To rebuild the vector index:
- In a browser, go to
/_debug/vectorize-bulkon a CMS host. - (Optional) Change # Of Writers (the number of concurrent writers, default 2) and Commit Size (the number of
items written per batch, default 10). There is no type or site selection; the task reindexes every type that
implements
EmbeddingGeneratableor is selected in Additional Types, on all sites. - Click Start. This starts a
BulkVectorIndexTask, which writes embeddings concurrently and records progress inBulkVectorIndexLog. - Monitor progress at
/_debug/task. Running tasks are also listed under Ongoing Tasks on/_debug/vectorize-bulk.
BulkVectorIndexLog holds the run's status, the number of items vectorized and failed, and any errors. It is hidden in
the CMS and is not shown on the debug page.
Starting a bulk index first deletes every record in the default vector database, then reindexes. Semantic search is incomplete until the task finishes, and vectors for types that are no longer indexed are not restored.
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
ClassNotFoundExceptionor unknown-type warnings referencingcom.psddev.aior 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 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.