AI Module Upgrade Instructions

This page outlines version-specific changes to the AI modules that you must address when upgrading Bloomreach Content.

Info: Starting with v16.6.0, the AI Module includes Incubating features.

For details, see the Incubating Features Policy.

Changes in v17.3

OpenAI: Temperature No Longer Defaults to 0.0

Before v17.3, the OpenAI provider always sent a temperature of 0.0 when the property was not set, producing near-deterministic output. From v17.3, spring.ai.openai.chat.options.temperature is opt-in: it is sent only when you configure it with a valid value (range 0–2). If you rely on the previous deterministic behavior, set the property explicitly:

spring.ai.openai.chat.options.temperature=0.0

Leave the property empty for OpenAI reasoning models (gpt-5 and later), which reject an explicit temperature.

OpenAI: `max_tokens` Superseded by `max_completion_tokens`

The OpenAI provider now sends the token limit as max_completion_tokens instead of the deprecated max_tokens, as required by reasoning models. A new property spring.ai.openai.chat.options.max-completion-tokens (default 4096) is preferred. The legacy spring.ai.openai.chat.options.max-tokens still works — its value is used when max-completion-tokens is unset — but it is always transmitted to OpenAI as max_completion_tokens. No action is required unless you want to adopt the new property name.

OpenAI: New `reasoning-effort` Option for Reasoning Models

A new optional property spring.ai.openai.chat.options.reasoning-effort configures the reasoning effort for OpenAI reasoning models (gpt-5 and later). It is sent only when configured. Accepted values are model-specific (low/medium/high are common; some models also accept none, minimal, or xhigh). This value must be set (for example none where supported) for the assistant's tool calling — including the Search Agent — to work on reasoning models. Classic models (gpt-4.x) reject this parameter, so leave it empty for them. See Setup via Properties.

New Provider: AWS Bedrock

AWS Bedrock is available as a new built-in model provider (brxm.ai.provider=Bedrock), shipping in the incubating content-ai-service-impl-incubating artifact — no new dependency is required. Chat uses the Bedrock Converse API and embeddings use Amazon Titan or Cohere. Because the AWS SDK is now bundled in the core impl artifact, all deployments include it after upgrading. Bedrock is configured through properties files or the JCR console only; it is not available in the Essentials wizard. For configuration details, see Setup via Properties.

Changes in v17.2

AI Content Assistant Module: Spring AI 2.0 Upgrade

The following configuration changes result from the upgrade to Spring AI 2.0.0. These changes affect projects using the AI Content Assistant. Review each item and update your configuration as needed before upgrading.

PromptLoggerAdvisor Log Level
The log level for PromptLoggerAdvisor has changed from INFO to DEBUG. If your logging configuration does not capture DEBUG logs, update it to ensure these logs remain visible after the upgrade.

Usage Audit Logging
The log level for the UsageLoggingStore logger has changed from INFO to DEBUG. Adjust your logging configuration if you need to continue capturing these logs.

Vertex Provider Renamed
The Vertex AI provider has been renamed from VertexAIGemini to GoogleGenAiVertex. Update any configuration that references the old provider name to use the new name. This change aligns with upstream updates from Google and Spring AI.

Removal of completions-path and embeddings-path
The OpenAI provider no longer supports the completions-path and embeddings-path configuration properties. Remove these properties from your configuration, as they no longer have any effect.

OpenAI API URL Default Changed
The default OpenAI API endpoint (spring.ai.openai.api.url) has changed from https://api.openai.com/v1 to https://api.openai.com. If you use the default value, no action is required. If you have set this property explicitly, verify that it points to your intended endpoint and includes the /v1 path segment required by Spring AI 2.0.

Changes in v16.8

In v16.8.0, the OpenAI provider introduced a change to a configuration property.

Breaking Change: OpenAI Completions Path Property Renamed

If you configure a custom completions path for the OpenAI provider (for example, when using Azure OpenAI or a compatible endpoint), the property name has changed. Update this property in your properties file or JCR configuration before upgrading.

Before	After
`spring.ai.openai.chat.options.completions-path`	`spring.ai.openai.chat.completions-path`

LiteLLM Configuration Change (Optional)

Previously, LiteLLM was configured using the generic OpenAI-compatible connector, which did not allow separate configurations for OpenAI and LiteLLM. LiteLLM now uses a dedicated connector under the spring.ai.litellm.* property namespace. Migrating to this new configuration is optional but recommended if you use LiteLLM.

Changes in v16.6

The following manual changes are required when upgrading to v16.6.

Maven Dependencies

Some dependencies have updated groupId and artifactId values.

GroupId Change

Update the groupId from com.bloomreach.brx.ai to com.bloomreach.xm.ai.

Artifacts

The term -incubating has been added to two artifacts:

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-impl-incubating</artifactId>
</dependency>

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-rest-incubating</artifactId>
</dependency>

For the following modules, only the <groupId> needs to be updated:

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-client-bootstrap</artifactId>
</dependency>

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-client-assistant-angular</artifactId>
</dependency>

Configuration Changes

If you use JCR configuration for the AI module, make the following updates:

Remove the intermediate node with the model provider name (such as /OpenAI). Move all properties from this node up one level, placing them directly under /hippo:configuration/hippo:modules/ai-service/hipposys:moduleconfig.
Rename the property spring.ai.provider to brxm.ai.provider.