Getting started
The Brightspot AI plugin adds AI-powered features to Brightspot, including content generation (Create with Esca) and an agent that finds, creates, edits, and deletes content (Ask Esca). This guide covers the dependencies and configuration required to enable these features.
Prerequisites
- Brightspot 5.0.12 or later
- Java 21
Dependencies
Plugin version
Brightspot manages the plugin's version. Its brightspot-dependencies BOM imports the plugin's BOM, which sets one version for every module the plugin publishes under the com.brightspot.ai group: ai, the provider modules (bedrock, gemini, openai), and the MCP modules (mcp, mcp-client, mcp-server, mcp-theme). Declare the com.brightspot.ai dependencies in this guide without a version. Upgrading Brightspot upgrades the plugin.
Do not set a com.brightspot.ai version in the project, whether on an individual dependency, in dependencyConstraints, or by importing com.brightspot.ai:bom. Brightspot enforces its own BOM, so a version set in the project often has no effect, and a partial one leaves the project on a mix of plugin releases.
Add each of the plugin's modules, leaving out only the ones the project does not use.
Core AI plugin
Every setup requires the core AI plugin dependency:
- Maven
- Gradle
- Gradle (Kotlin DSL)
<!-- Requires Brightspot 5.0 or later. -->
<!-- Version supplied by the imported BOM. -->
<dependency>
<groupId>com.brightspot.ai</groupId>
<artifactId>ai</artifactId>
</dependency>
// Requires Brightspot 5.0 or later.
// Version supplied by the imported BOM.
implementation 'com.brightspot.ai:ai'
// Requires Brightspot 5.0 or later.
// Version supplied by the imported BOM.
implementation("com.brightspot.ai:ai")
To expose content to external AI tools over MCP, also add the optional com.brightspot.ai:mcp artifact (see MCP).
AI provider
Each AI provider for chat completions and text embeddings is a separate module. Leave out the providers the project does not use.
OpenAI
- Maven
- Gradle
- Gradle (Kotlin DSL)
<!-- Version supplied by the imported BOM. -->
<dependency>
<groupId>com.brightspot.ai</groupId>
<artifactId>openai</artifactId>
</dependency>
// Version supplied by the imported BOM.
implementation 'com.brightspot.ai:openai'
// Version supplied by the imported BOM.
implementation("com.brightspot.ai:openai")
Amazon Bedrock
- Maven
- Gradle
- Gradle (Kotlin DSL)
<!-- Version supplied by the imported BOM. -->
<dependency>
<groupId>com.brightspot.ai</groupId>
<artifactId>bedrock</artifactId>
</dependency>
// Version supplied by the imported BOM.
implementation 'com.brightspot.ai:bedrock'
// Version supplied by the imported BOM.
implementation("com.brightspot.ai:bedrock")
Google Vertex AI
- Maven
- Gradle
- Gradle (Kotlin DSL)
<!-- Version supplied by the imported BOM. -->
<dependency>
<groupId>com.brightspot.ai</groupId>
<artifactId>gemini</artifactId>
</dependency>
// Version supplied by the imported BOM.
implementation 'com.brightspot.ai:gemini'
// Version supplied by the imported BOM.
implementation("com.brightspot.ai:gemini")
Google Vertex AI requires a GCP project and service account credentials configured through the GCP plugin.
Search back end
The search back end determines how Brightspot indexes and queries content. The text search back end handles standard keyword queries, while the vector search back end handles semantic/AI-powered queries used by Ask Esca.
Which search back end to use depends on your operational environment—specifically, whether your infrastructure runs Solr, OpenSearch, or both. You can mix and match Solr and OpenSearch for text and vector search independently. Use the following table to identify your configuration, then add the corresponding dependencies. The com.brightspot.db modules are declared without a version because Brightspot's brightspot-dependencies BOM supplies it.
| Configuration | Text search | Vector search | Use case |
|---|---|---|---|
| Solr + OpenSearch vector | Solr | OpenSearch | Keep existing Solr infrastructure, add AI search |
| OpenSearch full | OpenSearch | OpenSearch | Unified OpenSearch for all search |
| Solr full | Solr | Solr | Unified Solr for all search |
Solr text search with OpenSearch vector search
Solr handles text search. OpenSearch handles vector search only.
1api 'com.brightspot.db:db'2api 'com.brightspot.db:vector'3api 'com.brightspot.db:opensearch-vector'4api 'com.brightspot.db:opensearch-aws'
Do not add the com.brightspot.db:opensearch dependency in this configuration. Solr handles all text queries.
OpenSearch text and vector search
OpenSearch handles both text indexing and vector search. Solr is not required.
1api 'com.brightspot.db:db'2api 'com.brightspot.db:vector'3api 'com.brightspot.db:opensearch'4api 'com.brightspot.db:opensearch-vector'5api 'com.brightspot.db:opensearch-aws'
Solr text and vector search
Solr handles both text search and vector search.
1api 'com.brightspot.db:db'2api 'com.brightspot.db:vector'3api 'com.brightspot.db:solr'4api 'com.brightspot.db:solr-vector'
Provider configuration
The AI provider can be configured using environment properties. These properties set the configuration that the plugin uses until the AI plugin is saved in the CMS. A plugin saved in the CMS replaces these properties as a whole, and the CMS does not show the values they set (see Example environment configuration).
The following examples show typical configurations—adjust the model and token values to match your requirements. maxTokens is not a response limit; it is the maximum number of tokens per chunk when an asset is embedded on save (default 500), and must fit within the embedding model's context window. For details, see Chunker settings.
OpenAI
1com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator2com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-3-small3com.brightspot.ai.AiPlugin/maxTokens=4004com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient5com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=gpt-6-luna6com.brightspot.openai.OpenAIPlugin/apiKey=<api-key>
Azure OpenAI
Azure OpenAI serves OpenAI models through Azure infrastructure. It uses the same plugin as OpenAI, switched with the provider setting.
Azure offers two API surfaces; the configured endpoint selects which one is used. An endpoint ending with /openai/v1 reaches the v1 API, which is OpenAI-compatible and sends no API version. Omitting that suffix reaches the dated API, which addresses deployments through the request path and requires an API version.
1com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator2com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=<embedding-deployment-name>3com.brightspot.ai.AiPlugin/maxTokens=4004com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient5com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=<chat-deployment-name>6com.brightspot.openai.OpenAIPlugin/provider=AZURE_OPENAI7com.brightspot.openai.OpenAIPlugin/apiKey=<api-key>8com.brightspot.openai.OpenAIPlugin/baseUrl=https://<resource-name>.openai.azure.com
To use the v1 API instead, change the last line:
1com.brightspot.openai.OpenAIPlugin/baseUrl=https://<resource-name>.openai.azure.com/openai/v1
The model values are deployment names, not model names—whatever each deployment was called when it was created in the Azure portal. This holds on both surfaces.
apiVersion is optional. On the dated API it defaults to the SDK's latest stable version; on the v1 API it is omitted entirely. Override it with com.brightspot.openai.OpenAIPlugin/apiVersion=<version>.
Native structured output stays off unless the chat client's Structured Output Supported setting is turned on. On the dated API it also requires an API version of 2024-08-01-preview or later.
urlPathMode defaults to AUTO, which reads the surface from the endpoint on a recognized Azure host: .openai.azure.com, .services.ai.azure.com, .cognitiveservices.azure.com, or .azure-api.net. Set com.brightspot.openai.OpenAIPlugin/urlPathMode=LEGACY only for a dated-API resource behind a gateway on a domain outside that set—AUTO cannot recognize those and would strip the deployment path and API version. A v1 endpoint on a custom domain needs no override.
Amazon Bedrock
1com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.aws.bedrock.BedrockTextEmbeddingGenerator2com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=amazon.titan-embed-text-v2:03com.brightspot.ai.AiPlugin/maxTokens=4004com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.aws.bedrock.BedrockChatClient5com.brightspot.ai.AiPlugin/defaultConfig/chatClient/inferenceProfile=us.openai.gpt-6-luna
Amazon Bedrock is only available in certain AWS regions. Ensure the IAM role used by the environment has permission to call the Bedrock API. Prompt caching is on by default; see Chat client.
To set the same values in the CMS, see Configuring Amazon Bedrock.
Google Vertex AI
1com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.gcp.gemini.GeminiTextEmbeddingGenerator2com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-0053com.brightspot.ai.AiPlugin/maxTokens=4004com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.gcp.gemini.GeminiChatClient5com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=gemini-2.5-flash
The default location is us-central1. To override it, add com.brightspot.ai.AiPlugin/defaultConfig/chatClient/location=<region> and com.brightspot.ai.AiPlugin/textEmbeddingGenerator/location=<region>.
Gemini 2.5 and newer cache repeated prompt prefixes automatically on Vertex AI, and cached tokens appear in the AI Audit token count. Which models cache, and from what prompt size, is listed in the Vertex AI context caching documentation.
Vector database configuration
If you are using vector search (required for Ask Esca's semantic search; without it, Ask Esca searches by keyword only), configure the vector database connection using environment properties. For Brightspot Managed Services customers, this configuration can be handled by the Managed Services team—open a support ticket to request vector database provisioning.
Solr
1dari/defaultVectorDatabase=<name>2dari/vectorDatabase/<name>/class=com.brightspot.solr.vector.SolrVectorDatabase3dari/vectorDatabase/<name>/client/class=com.brightspot.solr.common.HttpSolrClientSupplier4dari/vectorDatabase/<name>/client/baseServerUrl=<url>5dari/vectorDatabase/<name>/collection=<collection>
For Solr Cloud deployments, use CloudSolrClientSupplier:
1dari/defaultVectorDatabase=<name>2dari/vectorDatabase/<name>/class=com.brightspot.solr.vector.SolrVectorDatabase3dari/vectorDatabase/<name>/client/class=com.brightspot.solr.common.CloudSolrClientSupplier4dari/vectorDatabase/<name>/client/zooKeeperHosts/1=<host-1>5dari/vectorDatabase/<name>/client/zooKeeperHosts/2=<host-2>6dari/vectorDatabase/<name>/collection=<collection>
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>
OpenSearch on AWS
1dari/defaultVectorDatabase=<name>2dari/vectorDatabase/<name>/class=com.brightspot.opensearch.vector.OpenSearchVectorDatabase3dari/vectorDatabase/<name>/client/class=com.brightspot.opensearch.aws.AwsOpenSearchClientSupplier4dari/vectorDatabase/<name>/client/host=<host>5dari/vectorDatabase/<name>/client/service=es6dari/vectorDatabase/<name>/client/region=<region>7dari/vectorDatabase/<name>/index=<index>
Troubleshooting
Legacy dependency conflicts
If your project previously used the older com.psddev AI dependencies, remove them to prevent classpath conflicts. The following artifacts have been replaced by the com.brightspot.ai and com.brightspot.db dependencies listed above:
com.psddev:ai-chatcom.psddev:aws-bedrockcom.psddev:dari-aicom.psddev:dari-ai-dbcom.psddev:dari-solrcom.psddev:dari-solr-v6com.psddev:google-vertex-aicom.psddev:openaicom.psddev:opensearchcom.psddev:solr-ai
Remove both direct and transitive usages from all modules in your project.
Next steps
After completing the dependency and infrastructure setup, configure AI features in the CMS:
- Configuration—Enable and configure Create with Esca, Ask Esca, prompt suggestions, author personas, and permissions.
- AI Audit—Track and monitor AI usage across your site.