Architecture overview

🚧Documentation Under Construction

We are actively working to improve this documentation. The content you see here may be incomplete, subject to change, or may not fully reflect the current state of the feature. We appreciate your understanding as we continue to enhance our docs.

AI plugin provides the fundamental building blocks for AI-powered features, including:

• Chat conversations with AI assistants
• Annotations for controlling embedding generation
• Text chunking for handling large content
• Text embedding generation for semantic search
• Site-specific plugin configuration

Plugin configuration

AiPlugin

The main plugin entry point that provides global AI configuration.

• Configures the TextEmbeddingGenerator and TextChunker used for embedding generation
• Defines additional content types for AI indexing
• Provides system instructions for Create with AI and Ask AI features
• Handles legacy configuration migration

AiPluginConfig

Site-specific configuration for the AI plugin.

• Configures the ChatClient for AI conversations
• Enables/disables Create with AI and Ask AI features
• Defines brand guidelines, prompt suggestions, and author personas
• Configures generation timeout and AI-generated content detectors
• Sets Ask AI search parameters (max records, min similarity score, max tokens)

Embedding generation

EmbeddingGeneratable

An interface that marks content types for automatic embedding generation. For example:

1
public class Article extends Content implements EmbeddingGeneratable {
2
    private String title;
3
    private String body;
4
}

The default shouldGenerateEmbedding() method returns true when the record is visible, but can be overridden for custom logic.

@ExcludeFromEmbedding

A field-level annotation that excludes specific fields from embedding generation. For example, this is how to exclude sensitive data from an embedding:

1
public class Article extends Content implements EmbeddingGeneratable {
2
    private String title;
3

4
    @ExcludeFromEmbedding
5
    private String internalId;
6
}

Common use cases are:

• Personally identifiable information (PII)
• Internal system identifiers
• Administrative metadata (creation dates, flags)
• Large binary data or encoded content

TextEmbeddingGenerator

An abstract base class for generating text embeddings (vector representations of text). Typical use might look like:

1
TextEmbeddingGenerator generator = TextEmbeddingGenerator.get();
2
int tokens = generator.countTokens("This is some text");
3
float[] embedding = generator.generate("This is some text");

Implementations must provide getModel(), getMaxTokens(), getDimension(), and generate(List<String>).

AiRecordData

A modification class that adds AI-specific data and behaviors to all Brightspot records.

• Automatically generates embeddings when records are saved
• Deletes embeddings when records are deleted
• Extracts embedding-ready content by filtering excluded fields
• Extracts filterable metadata for vector records

Whenever a record is saved, it follows these steps to generate an embedding:

1. Checks if the record type should generate embeddings
2. Chunks the content using TextChunker
3. Generates embeddings for each chunk using TextEmbeddingGenerator
4. Saves embeddings to the vector database

AiFieldData

A modification class for field-level AI configuration. Tracks whether a field should be excluded from embedding generation.

Text chunking

TextChunker

An abstract base class for splitting text into smaller chunks suitable for embedding generation. Part of the RAG pipeline for improved precision in semantic search. Typical use might look like:

1
List<String> chunks = TextChunker.get().chunk(
2
    "This is a very long piece of text that needs to be split...",
3
    countTokens,
4
    10);

If not configured, defaults to RecursiveJsonTextChunker.

FixedLengthTextChunker

Splits text into fixed-length chunks with configurable overlap (default 10%).

RecursiveTextChunker

Splits text using a recursive document splitter (via LangChain4j) with configurable overlap (default 10%).

JsonTextChunker

An abstract base class for chunkers that work on JSON data directly.

RecursiveJsonTextChunker

Recursively splits large JSON data while preserving context. Uses a two-stage approach: small fields serve as context, large fields are individually split and combined with context to create chunks. Configurable context ratio (default 40%) and string chunker (default RecursiveTextChunker).

Chat

ChatClient

An abstract base class for clients that facilitate chat conversations with an AI assistant.

1
ChatClient client = ChatClient.get();
2
AssistantMessage response = client.complete(request, delta -> System.out.print(delta));

ChatRequest

Encapsulates a chat request with system instructions, conversation history, and the current user message. Built using a fluent builder pattern:

1
ChatRequest request = ChatRequest.builder()
2
    .instructions("You are a helpful assistant.")
3
    .history(previousMessages)
4
    .message(userMessage)
5
    .build();

ChatSession

Manages a complete AI conversation session with configuration options including:

• Token limits and temperature settings
• Chat history windowing
• System instructions
• Request and response guardrails
• Request cancellation

Chat

A container for an ordered list of Message objects that make up a conversation thread.

Message

Abstract base class for chat messages. Supports both raw text and templated text content. Subclasses:

• UserMessage — represents a user-generated prompt
• AssistantMessage — represents an AI-generated response, with metadata for timing, token usage, completion status, and error tracking

FeatureType

An enum distinguishing between CREATE_WITH_AI and ASK_AI features.

ChatSessionStatus

An enum representing chat completion status: COMPLETE, ERROR, or STOP.