AI Content Assistant Developer Guide

Overview

Info: The AI Content Assistant is available in brXM version 16.4.0 and later, and requires a standard or premium license. Contact Bloomreach for licensing details.

The AI Content Assistant, powered by AI Content Assistant, integrates generative AI capabilities into the Bloomreach Content CMS. It enables automated content creation, editing, and management tasks within the CMS interface.

This guide describes how to configure, initialize, and use the AI chat assistant. The assistant allows developers and content teams to interact with large language models (LLMs) from supported providers. Supported tasks include summarization, translation, and SEO optimization.

Prerequisites

Before you start, ensure you have the following:

• Access to a Bloomreach Content CMS instance (version 16.4 or later).
• Access to the console or project properties files.
• Awareness of your organization’s data privacy and residency requirements.
• An account and API key for a supported AI provider (OpenAI, VertexAI Gemini), or a locally running AI model (Ollama, LiteLLM).
• For Vector Store usage, an operational Redis or Postgres (with Vector extension) instance.

Info:

• To use OpenAI models, create an API key by signing up at OpenAI and generating a key on the API Keys page.
• For VertexAI, configure Application Default Credentials (ADC) as described in the ADC setup guide.
• Ollama can be downloaded and run locally.
• LiteLLM must be installed and configured before use. It can run locally or as a managed cloud service.

Supported LLM Providers

The AI Content Assistant supports the following model providers:

• OpenAI
• VertexAI Gemini
• Ollama
• LiteLLM

Installation

Refer to the Initialize and configure the AI Content Assistant documentation for installation steps.

Technical Architecture Overview

The Content GenAI integration uses a modular architecture that separates the UI, backend AI service, and model providers. The main components are:

• Document editor: The UI where users initiate AI operations.
• AI backend service: Processes AI-related requests from the UI. Initially available as an internal service; a REST API layer is planned for future releases.
• Spring AI bridge: Middleware that connects the backend service to various model providers.
• Model providers: External LLM services such as OpenAI, Gemini, or Ollama.
• Vector Store providers: Local or external vector store implementations for storing content embeddings.
• Ingestion process: A background process that populates the Vector Store with embeddings generated by the configured model provider, triggered on document save or publication.

How the AI Content Assistant Works

1. The user starts an AI operation in the document editor.
2. The UI sends a request to the AI backend service.
3. The backend service prepares and forwards the request to the selected model provider via the Spring AI bridge.
4. The model provider processes the request, may invoke available tools, and returns a response.
5. The backend service returns the result to the UI for display or further action.

This architecture abstracts model integration complexity and ensures that only approved operations are available to users.

Extensibility

The AI module includes several extension points. See the Extensibility Guide for details.

Vector Store Maintenance

You can manage your Vector Store at runtime using Groovy scripts within the CMS interface. This supports administrative tasks for maintaining and updating embeddings. See Maintenance Groovy Scripts for usage information.

Supported Operations

The AI chat assistant supports multiple content operations, which you can trigger from the assistant panel.

For a complete list of supported actions and usage instructions, see the AI Content Assistant User Manual.

Enabling and Disabling the Assistant

You can enable or disable the backend and frontend components of the AI module independently:

• To disable the backend model provider, omit the brxm.ai.provider property. This also disables Vector Store usage. Restart the pod for changes to take effect.
• To disable only the Vector Store, omit the brxm.ai.vectorstore property. This also disables the background ingestion process. Restart the pod for changes to take effect.
• To hide the "Ask AI" button in the CMS, remove the value for the frontend:appPath property at /hippo:configuration/hippo:frontend/cms/cms-static/ai-service-client-perspective.

Conversation History (Available from v16.6.0)

Session and infrastructure details:

• The CMS session is tied to the pod serving your requests. If your session moves to a different pod, the CMS creates a new session and the AI chat history in the UI is cleared.
• Conversation logs are retained in system logs and remain accessible even if the visible chat history is cleared.

Conversation Auto-Naming

The assistant automatically generates a conversation name shortly after the first message. The name may take several messages to appear; until then, "New conversation" is displayed.

Auto-naming is disabled once a name is generated or if the user enters a custom name.

Info: The auto-naming request consumes tokens and is billed to the user's account. The request is logged and can be monitored.

Conversation Logs

All data exchanged with the AI provider is available in your logs. To inspect requests and responses, enable both loggers in your log4j configuration:

• Prompt logger: Logs user messages and AI model responses. Enable with:

  <Logger name="com.bloomreach.xm.ai.service.impl.client.advisors.PromptLoggerAdvisor" level="debug"/>
  copy

• Spring's SimpleLoggerAdvisor: Enable with:

  <Logger name="org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor" level="debug"/>
  copy

Logs are output to the terminal or Humio, depending on your configuration. PromptLoggerAdvisor entries are formatted for identification and traceability. Example:

[DEBUG]  http-nio-8080-exec-4 [PromptLoggerAdvisor.before:88] >>>>> Outgoing message for admin, conversation 559df082-955e-41ad-a1a7-39535ad4b20d (type:USER)  >>>>>
[DEBUG] What do you see in this document
[DEBUG] >>>>>

Log entries include:

• User and conversation IDs
• All outgoing and incoming requests (including document references and auto-naming requests)
• Total tokens consumed by the user after each request

Conversation Token Usage

Token usage per conversation and per user is available in logs by setting the audit logger level:

<Logger name="com.bloomreach.xm.ai.service.impl.audit.UsageLoggingStore" level="debug"/>
copy

Token usage for embeddings generation is also included under this audit logger for all providers.

Example log entries:

DEBUG ... UsageLoggingStore ... AI embedding token usage for user id system-ingestion: total=673, generation=0, prompt=673
DEBUG ... UsageLoggingStore ... AI embedding token usage for user id admin: total=2035, generation=17, prompt=2018

Limitations

• In version 16.4, the AI Content Assistant can access only published and unpublished document content. Draft versions are not supported. Users must save changes for the AI to access the latest content.
  In version 16.4.1 and later, draft versions are supported. The assistant can access the most current document information without requiring a save.
• Assets (fields and document types) are not supported.
• Value list fields and document types are not supported.
• The assistant is only available in the content perspective. Other perspectives are not supported.
• Document-level operations may require users to manually import generated content.
• The Search Agent does not support attribute-based filtering. Results are based solely on semantic similarity across all indexed content. Filtering by locale, document type, folder, or metadata is not available. Attribute-based filtering is planned for a future release.

Important: Incubating Features

Some features are released as "Incubating Features" to accelerate innovation. These features are tested and production-ready, but developer-facing APIs and extension points may change in minor releases based on feedback. The default CMS experience is not affected. If you have custom extensions using incubating APIs, review release notes for each minor release for migration guidance.

See the Incubating Features Policy for details.

Info: As of v16.6.0, the AI Content Assistant includes Incubating features and modules. See Upgrading to 16.6.0 for upgrade instructions.