Getting started

The Brightspot AI plugin adds AI-powered features to Brightspot, including content generation (Create with Esca) and semantic search (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 4.8 or later. -->
<dependency>
    <groupId>com.brightspot.ai</groupId>
    <artifactId>ai</artifactId>
    <version>3.2.0</version>
</dependency>

Gradle

// Requires Brightspot 4.8 or later.
implementation 'com.brightspot.ai:ai:3.2.0'

Gradle (Kotlin DSL)

// Requires Brightspot 4.8 or later.
implementation("com.brightspot.ai:ai:3.2.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.2.0</version>
</dependency>

Gradle

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

Gradle (Kotlin DSL)

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

Amazon Bedrock

Maven

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

Gradle

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

Gradle (Kotlin DSL)

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

Google Vertex AI

Maven

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

Gradle

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

Gradle (Kotlin DSL)

implementation("com.brightspot.ai:gemini:3.2.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>

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.