Architecture Overview

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

• Annotations for controlling embedding generation
• Text chunking for handling large content
• Text embedding generation for semantic search

Core Classes

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
• Integrates with VectorDatabase for storage
• Supports both new configuration (@GenerateEmbedding) and legacy configuration (AskAIClient)
• Handles text chunking before embedding generation

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

@GenerateEmbedding

A type-level annotation that marks a class for automatic embedding generation. For example, this is how to make sure that an embedding is generated each time an article is saved:

1
@GenerateEmbedding
2
public class Article extends Content {
3
    private String title;
4
    private String body;
5
}

@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
@GenerateEmbedding
2
public class Article extends Content {
3
    private String title;
4

5
    @ExcludeFromEmbedding
6
    private String internalId;
7
}

Common use cases are:

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

TextChunker

An abstract base class for splitting text into smaller chunks suitable for embedding generation. Typical use might look like:

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

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");

Typical Configuration

Configure the Text Chunker (optional)

1
brightspot/ai/textChunker/class=com.brightspot.ai.chunker.FixedSizeTextChunker
2
brightspot/ai/textChunker/size=512
3
brightspot/ai/textChunker/overlap=0.1

Configure the Text Embedding Generator

1
brightspot/ai/textEmbeddingGenerator/class=com.example.MyTextEmbeddingGenerator