Upgrading to AI plugin v3

Version 3.0 consolidates Create with AI and Ask AI 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 guide 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 AI 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.*), the legacy client records (AIChatClient, AskAIClient), and the legacy guardrail types are all deprecated and will be removed in a future major release. A small number of internal types were removed outright (for example, Prompt, SystemPrompt, and Response). See Step 3: Update project code.

What carries over and what does not

The first time the AI plugin loads, it relocates legacy site settings into the new plugin configuration automatically. Review the result in the CMS after the upgrade.

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 AI Agent's Additional Instructions
Site-wide and content-level prompt suggestions	Relocated to the Create with AI Agent
Author personas (default and others)	Relocated to the Create with AI Agent
Generation timeout and generated-content detectors	Relocated to the Create with AI Agent
Ask AI vectorizable content types	Relocated to the plugin's Additional Types
Prompt suggestion, persona, tracking, and usage records	Retained these. Record types are unchanged
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, response formatting)	Not migrated. Reconfigure on the Ask AI Agent
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

Most 2.x integration points are deprecated rather than removed, so start by building the project and reviewing deprecation warnings. The table below maps the common 2.x APIs to their 3.0 replacements.

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 (deprecated)	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 AI 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 AI either implement EmbeddingGeneratable or are selected in the AI plugin's Additional Types field. Types selected in the legacy Ask AI client settings are relocated to Additional Types automatically.

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 settings match the previous configuration.
3. Enable toggles, prompt suggestions, personas, and brand guidelines on the Create with AI Agent.
4. From the Text Embedding Generator list, select a provider and model (required for Ask AI).
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 AI Agent to the Agents list if Ask AI 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 AI generates content on a field and inline in the rich-text editor.
• Ask AI 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 3.x line. The 2.x line receives critical fixes only, on the release/2 branch; bug fixes that ship in 3.x releases are generally not backported. Release notes for every version are published on the platform-ai releases page.