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:

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

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
com.brightspot.ai.AiPlugin/textChunker/class=com.example.MyTextChunker
2
com.brightspot.ai.AiPlugin/textChunker/option=...

Configure the text embedding generator

1
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/class=com.example.MyTextEmbeddingGenerator
2
com.brightspot.ai.AiPlugin/textEmbeddingGenerator/option=...