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

• Java 21

Dependencies

Core AI plugin

Every setup requires the core AI plugin dependency:

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.ai</groupId>
    <artifactId>ai</artifactId>
    <version>3.3.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.ai:ai:3.3.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.ai:ai:3.3.0")

AI provider

Choose an AI provider for chat completions and text embeddings. Add the corresponding dependency.

OpenAI

Maven

<dependency>
    <groupId>com.brightspot.ai</groupId>
    <artifactId>openai</artifactId>
    <version>3.3.0</version>
</dependency>

Gradle

implementation 'com.brightspot.ai:openai:3.3.0'

Gradle (Kotlin DSL)

implementation("com.brightspot.ai:openai:3.3.0")

Amazon Bedrock

Maven

<dependency>
    <groupId>com.brightspot.ai</groupId>
    <artifactId>bedrock</artifactId>
    <version>3.3.0</version>
</dependency>

Gradle

implementation 'com.brightspot.ai:bedrock:3.3.0'

Gradle (Kotlin DSL)

implementation("com.brightspot.ai:bedrock:3.3.0")

Google Vertex AI

Maven

<dependency>
    <groupId>com.brightspot.ai</groupId>
    <artifactId>gemini</artifactId>
    <version>3.3.0</version>
</dependency>

Gradle

implementation 'com.brightspot.ai:gemini:3.3.0'

Gradle (Kotlin DSL)

implementation("com.brightspot.ai:gemini:3.3.0")

note

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.

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.

1
api 'com.brightspot.db:db'
2
api 'com.brightspot.db:vector'
3
api 'com.brightspot.db:opensearch-vector'
4
api 'com.brightspot.db:opensearch-aws'

note

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.

1
api 'com.brightspot.db:db'
2
api 'com.brightspot.db:vector'
3
api 'com.brightspot.db:opensearch'
4
api 'com.brightspot.db:opensearch-vector'
5
api 'com.brightspot.db:opensearch-aws'

Solr text and vector search

Solr handles both text search and vector search.

1
api 'com.brightspot.db:db'
2
api 'com.brightspot.db:vector'
3
api 'com.brightspot.db:solr'
4
api 'com.brightspot.db:solr-vector'

Provider configuration

The AI provider can be configured using environment properties. These properties set the default configuration that the plugin uses unless overridden in the CMS (see Configuration). Settings configured in the CMS take precedence, but the property-based defaults are not visible or editable from within the CMS UI.

The following examples show typical configurations—adjust the model and token values to match your requirements.

OpenAI

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-3-small
3
com.brightspot.ai.AiPlugin/maxTokens=400
4
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient
5
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=gpt-4o
6
com.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.

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.openai.OpenAITextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=<embedding-deployment-name>
3
com.brightspot.ai.AiPlugin/maxTokens=400
4
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.openai.OpenAIChatClient
5
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=<chat-deployment-name>
6
com.brightspot.openai.OpenAIPlugin/provider=AZURE_OPENAI
7
com.brightspot.openai.OpenAIPlugin/apiKey=<api-key>
8
com.brightspot.openai.OpenAIPlugin/baseUrl=https://<resource-name>.openai.azure.com

To use the v1 API instead, change the last line:

1
com.brightspot.openai.OpenAIPlugin/baseUrl=https://<resource-name>.openai.azure.com/openai/v1

note

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

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.aws.bedrock.BedrockTextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=amazon.titan-embed-text-v2:0
3
com.brightspot.ai.AiPlugin/maxTokens=400
4
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.aws.bedrock.BedrockChatClient
5
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/inferenceProfile=us.anthropic.claude-sonnet-4-20250514-v1:0

note

Amazon Bedrock is only available in certain AWS regions. Ensure the IAM role used by the environment has permission to call the Bedrock API.

Google Vertex AI

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.brightspot.gcp.gemini.GeminiTextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/model=text-embedding-005
3
com.brightspot.ai.AiPlugin/maxTokens=400
4
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/class=com.brightspot.gcp.gemini.GeminiChatClient
5
com.brightspot.ai.AiPlugin/defaultConfig/chatClient/model=gemini-2.5-flash

note

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>.

Vector database configuration

If you are using vector search (required for Ask Esca), 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

1
dari/defaultVectorDatabase=<name>
2
dari/vectorDatabase/<name>/class=com.brightspot.solr.vector.SolrVectorDatabase
3
dari/vectorDatabase/<name>/client/class=com.brightspot.solr.common.HttpSolrClientSupplier
4
dari/vectorDatabase/<name>/client/baseServerUrl=<url>
5
dari/vectorDatabase/<name>/collection=<collection>

For Solr Cloud deployments, use CloudSolrClientSupplier:

1
dari/defaultVectorDatabase=<name>
2
dari/vectorDatabase/<name>/class=com.brightspot.solr.vector.SolrVectorDatabase
3
dari/vectorDatabase/<name>/client/class=com.brightspot.solr.common.CloudSolrClientSupplier
4
dari/vectorDatabase/<name>/client/zooKeeperHosts/1=<host-1>
5
dari/vectorDatabase/<name>/client/zooKeeperHosts/2=<host-2>
6
dari/vectorDatabase/<name>/collection=<collection>

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>

OpenSearch on AWS

1
dari/defaultVectorDatabase=<name>
2
dari/vectorDatabase/<name>/class=com.brightspot.opensearch.vector.OpenSearchVectorDatabase
3
dari/vectorDatabase/<name>/client/class=com.brightspot.opensearch.aws.AwsOpenSearchClientSupplier
4
dari/vectorDatabase/<name>/client/host=<host>
5
dari/vectorDatabase/<name>/client/service=es
6
dari/vectorDatabase/<name>/client/region=<region>
7
dari/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-chat
• com.psddev:dari-ai
• com.psddev:dari-ai-db
• com.psddev:dari-solr
• com.psddev:dari-solr-v6
• com.psddev:openai
• com.psddev:opensearch
• com.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.