feat: [OpenAI] SpringAI integration for embedding calls (#375)

* An initial version for embedding request integration

- Request convenience extended
- client per request (reassess)
- full metadat loading on request
- full metadata loading on response (reassess)

* add test for `call` and use low level api

* Constructor and code quality

- OpenAiSpringEmbeddingModel(client)
- unit tests added
- e2e test added
- java docs

* Sample app controller and minor test update
- make embedding document test response
- add controller for spring open ai
- include in static files of sample app

* Remove drive-by changes

* Provide documentation+release notes and add test for overlapping model setting

- test improvements

* Fix merge

* Fix hard line wrap on html

* Minor test and release note changes

- prefix with "test" on all test method
- update link in release note
- update test display name

* fix type

* Additional constructor that take metadata mode

* Additional constructor that take metadata mode

* Charles preferences

* Update link in static files

* read embedding response from json

* missed model name test

* Enforcer plugin config for optional dependency and replicate import test for spring-ai

- sample app ignored from ban

* Fix enforcer config, ported import check changes to orchestration

---------

Co-authored-by: Roshin Rajan Panackal <[email protected]>
Co-authored-by: Jonas-Isr <[email protected]>
Co-authored-by: I538344 <[email protected]>

Author: 3 people

docs/guides/SPRING_AI_INTEGRATION.md

@@ -3,11 +3,15 @@
 ## Table of Contents
 
 - [Introduction](#introduction)
-- [Orchestration Chat Completion](#orchestration-chat-completion)
-- [Orchestration Masking](#orchestration-masking)
-- [Stream chat completion](#stream-chat-completion)
-- [Tool Calling](#tool-calling)
-- [Chat Memory](#chat-memory)
+- [Orchestration](#orchestration)
+  - [Chat Completion](#chat-completion)
+  - [Masking](#masking)
+  - [Stream chat completion](#stream-chat-completion)
+  - [Tool Calling](#tool-calling)
+  - [Chat Memory](#chat-memory)
+- [OpenAI](#openai)
+  - [Embedding](#embedding)
+
 
 ## Introduction
 
@@ -36,10 +40,12 @@ First, add the Spring AI dependency to your `pom.xml`:
 > [!NOTE]
 > Note that currently no stable version of Spring AI exists just yet.
 > The AI SDK currently uses the [M6 milestone](https://spring.io/blog/2025/02/14/spring-ai-1-0-0-m6-released).
-> 
+>
 > Please be aware that future versions of the AI SDK may increase the Spring AI version.
 
-## Orchestration Chat Completion
+## Orchestration
+
+### Chat Completion
 
 The Orchestration client is integrated in Spring AI classes:
 
@@ -54,7 +60,7 @@ ChatResponse response = client.call(prompt);
 
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/SpringAiOrchestrationService.java).
 
-## Orchestration Masking
+### Masking
 
 Configure Orchestration modules withing Spring AI:
 
@@ -78,7 +84,7 @@ ChatResponse response = client.call(prompt);
 Please
 find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/SpringAiOrchestrationService.java).
 
-## Stream chat completion
+### Stream chat completion
 
 It's possible to pass a stream of chat completion delta elements, e.g. from the application backend
 to the frontend in real-time.
@@ -94,15 +100,15 @@ Prompt prompt =
 Flux<ChatResponse> flux = client.stream(prompt);
 
 // also possible to keep only the chat completion text
-Flux<String> responseFlux = 
+Flux<String> responseFlux =
     flux.map(chatResponse -> chatResponse.getResult().getOutput().getContent());
 ```
 
 _Note: A Spring endpoint can return `Flux` instead of `ResponseEntity`._
 
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/SpringAiOrchestrationService.java).
 
-## Tool Calling
+### Tool Calling
 
 First define a function that will be called by the LLM:
 
@@ -161,3 +167,24 @@ String content2 = cl.prompt(prompt2).call().content();
 ```
 
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/SpringAiOrchestrationService.java).
+
+## OpenAI
+
+### Introduction
+
+Our OpenAI client is integrated in Spring AI classes:
+
+### Embedding
+
+Here is how to obtain embedding vectors for a list of strings:
+
+You first initialize the OpenAI client for your model of choice and attach it  `OpenAiSpringEmbeddingModel` object.
+
+```java
+OpenAiClient client = OpenAiClient.forModel(OpenAiModel.TEXT_EMBEDDING_3_SMALL);
+OpenAiSpringEmbeddingModel embeddingModel = new OpenAiSpringEmbeddingModel(client);
+List<String> texts = List.of("Hello", "World");
+float[] embeddings = embeddingModel.embed(texts);
+```
+
+Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/SpringAiOpenAiService.java).

docs/release-notes/release_notes.md

@@ -16,6 +16,7 @@
 - [Orchestration] [Prompt templates can be consumed from registry.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#Chat-completion-with-Templates)
 - [Orchestration] [Masking is now available on grounding.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#mask-grounding)
 - [Orchestration] [Grounding via *help.sap.com* is enabled.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#grounding)
+- [OpenAI] [Spring AI integration for embedding calls.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/SPRING_AI_INTEGRATION.md#embedding)
 
 ### 📈 Improvements
 

foundation-models/openai/pom.xml

@@ -89,6 +89,11 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.springframework.ai</groupId>
+      <artifactId>spring-ai-core</artifactId>
+      <optional>true</optional>
+    </dependency>
     <!-- scope "provided" -->
     <dependency>
       <groupId>org.projectlombok</groupId>
@@ -121,5 +126,10 @@
       <artifactId>mockito-core</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>com.github.javaparser</groupId>
+      <artifactId>javaparser-core</artifactId>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 </project>

foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/spring/OpenAiSpringEmbeddingModel.java

@@ -0,0 +1,110 @@
+package com.sap.ai.sdk.foundationmodels.openai.spring;
+
+import com.sap.ai.sdk.foundationmodels.openai.OpenAiClient;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200Response;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequest;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequestInput;
+import java.util.Objects;
+import java.util.stream.IntStream;
+import javax.annotation.Nonnull;
+import org.springframework.ai.chat.metadata.DefaultUsage;
+import org.springframework.ai.document.Document;
+import org.springframework.ai.document.MetadataMode;
+import org.springframework.ai.embedding.Embedding;
+import org.springframework.ai.embedding.EmbeddingModel;
+import org.springframework.ai.embedding.EmbeddingRequest;
+import org.springframework.ai.embedding.EmbeddingResponse;
+import org.springframework.ai.embedding.EmbeddingResponseMetadata;
+
+/**
+ * SpringAI integration with {@link OpenAiClient} to generate embeddings.
+ *
+ * <p>This model transforms an {@link EmbeddingRequest} into an Azure OpenAI request, processes the
+ * response, and returns a Spring AI {@link EmbeddingResponse}.
+ *
+ * @since 1.5.0
+ */
+public class OpenAiSpringEmbeddingModel implements EmbeddingModel {
+
+  private final OpenAiClient client;
+  private final MetadataMode metadataMode;
+
+  /**
+   * Constructs an {@code OpenAiSpringEmbeddingModel} with the specified {@link OpenAiClient} of
+   * some model.
+   *
+   * @param client the OpenAI client
+   */
+  public OpenAiSpringEmbeddingModel(@Nonnull final OpenAiClient client) {
+    this(client, MetadataMode.EMBED);
+  }
+
+  /**
+   * Constructs an {@code OpenAiSpringEmbeddingModel} with the specified {@link OpenAiClient} of
+   * some model and metadata mode.
+   *
+   * <p>The metadata mode is used by content formatter to determine which metadata to include in the
+   * resulting content. Currently, the formatter is only effective for calls to {@link
+   * #embed(Document)}.
+   *
+   * @param client the OpenAI client
+   * @param metadataMode the metadata mode
+   */
+  public OpenAiSpringEmbeddingModel(
+      @Nonnull final OpenAiClient client, @Nonnull final MetadataMode metadataMode) {
+    this.client = client;
+    this.metadataMode = metadataMode;
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if {@code request.getOptions().getModel()} is not null.
+   */
+  @Override
+  @Nonnull
+  public EmbeddingResponse call(@Nonnull final EmbeddingRequest request)
+      throws IllegalArgumentException {
+
+    if (request.getOptions().getModel() != null) {
+      throw new IllegalArgumentException(
+          "Do not set a model in EmbeddingOptions, as the OpenAiClient already defines the model.");
+    }
+
+    final var openAiRequest = createEmbeddingsCreateRequest(request);
+    final var openAiResponse = client.embedding(openAiRequest);
+
+    return createSpringAiEmbeddingResponse(openAiResponse);
+  }
+
+  @Override
+  @Nonnull
+  public float[] embed(@Nonnull final Document document) throws UnsupportedOperationException {
+    return embed(
+        Objects.requireNonNull(
+            document.getFormattedContent(this.metadataMode),
+            "Formatted content of the document should not be null."));
+  }
+
+  private EmbeddingsCreateRequest createEmbeddingsCreateRequest(
+      @Nonnull final EmbeddingRequest request) {
+    return new EmbeddingsCreateRequest()
+        .dimensions(request.getOptions().getDimensions())
+        .input(EmbeddingsCreateRequestInput.create(request.getInstructions()));
+  }
+
+  private EmbeddingResponse createSpringAiEmbeddingResponse(
+      @Nonnull final EmbeddingsCreate200Response response) {
+    final var embeddings =
+        IntStream.range(0, response.getData().size())
+            .mapToObj(i -> new Embedding(response.getData().get(i).getEmbedding(), i))
+            .toList();
+
+    final var openAiUsage = response.getUsage();
+    final var usage =
+        new DefaultUsage(openAiUsage.getPromptTokens(), null, openAiUsage.getTotalTokens());
+    final var metadata = new EmbeddingResponseMetadata(response.getModel(), usage);
+
+    return new EmbeddingResponse(embeddings, metadata);
+  }
+}

foundation-models/openai/src/test/java/com/sap/ai/sdk/foundationmodels/openai/spring/EmbeddingModelTest.java

@@ -0,0 +1,109 @@
+package com.sap.ai.sdk.foundationmodels.openai.spring;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.assertArg;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.sap.ai.sdk.foundationmodels.openai.OpenAiClient;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200Response;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequest;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequestInput;
+import java.util.List;
+import java.util.function.Consumer;
+import lombok.SneakyThrows;
+import lombok.val;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.ai.document.Document;
+import org.springframework.ai.embedding.EmbeddingOptionsBuilder;
+import org.springframework.ai.embedding.EmbeddingRequest;
+
+class EmbeddingModelTest {
+  private OpenAiClient client;
+
+  @BeforeEach
+  void setUp() {
+    client = mock(OpenAiClient.class);
+  }
+
+  @SneakyThrows
+  @Test
+  @DisplayName("Call with embedding request containing valid options")
+  void testCallWithValidEmbeddingRequest() {
+    val texts = List.of("Some text");
+    val springAiRequest =
+        new EmbeddingRequest(texts, EmbeddingOptionsBuilder.builder().withDimensions(128).build());
+
+    val expectedOpenAiResponse =
+        new ObjectMapper()
+            .readValue(
+                getClass().getClassLoader().getResource("__files/embeddingResponse.json"),
+                EmbeddingsCreate200Response.class);
+
+    val expectedOpenAiRequest =
+        new EmbeddingsCreateRequest()
+            .input(EmbeddingsCreateRequestInput.create(texts))
+            .dimensions(128);
+
+    when(client.embedding(assertArg(assertRecursiveEquals(expectedOpenAiRequest))))
+        .thenReturn(expectedOpenAiResponse);
+
+    val actualSpringAiResponse = new OpenAiSpringEmbeddingModel(client).call(springAiRequest);
+
+    assertThat(actualSpringAiResponse).isNotNull();
+    assertThat(actualSpringAiResponse.getResult().getOutput())
+        .isEqualTo(new float[] {0.0f, 3.4028235E38f, 1.4E-45f, 1.23f, -4.56f});
+    assertThat(actualSpringAiResponse.getMetadata().getUsage().getPromptTokens()).isEqualTo(2);
+    assertThat(actualSpringAiResponse.getMetadata().getUsage().getTotalTokens()).isEqualTo(2);
+    assertThat(actualSpringAiResponse.getMetadata().getModel()).isEqualTo("ada");
+  }
+
+  @Test
+  @DisplayName("Call with embedding request with model option set throws exception")
+  void testCallWithModelOptionSetThrows() {
+    val springAiRequest =
+        new EmbeddingRequest(
+            List.of("Some text"), EmbeddingOptionsBuilder.builder().withModel("model").build());
+
+    val model = new OpenAiSpringEmbeddingModel(client);
+
+    assertThatThrownBy(() -> model.call(springAiRequest))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessage(
+            "Do not set a model in EmbeddingOptions, as the OpenAiClient already defines the model.");
+  }
+
+  @SneakyThrows
+  @Test
+  @DisplayName("Embed document with text content")
+  void testEmbedDocument() {
+    Document document = new Document("Some content");
+
+    val expectedOpenAiResponse =
+        new ObjectMapper()
+            .readValue(
+                getClass().getClassLoader().getResource("__files/embeddingResponse.json"),
+                EmbeddingsCreate200Response.class);
+
+    val expectedOpenAiRequest =
+        new EmbeddingsCreateRequest()
+            .input(EmbeddingsCreateRequestInput.create(List.of(document.getFormattedContent())));
+
+    when(client.embedding(assertArg(assertRecursiveEquals(expectedOpenAiRequest))))
+        .thenReturn(expectedOpenAiResponse);
+
+    float[] result = new OpenAiSpringEmbeddingModel(client).embed(document);
+
+    assertThat(result).isEqualTo(new float[] {0.0f, 3.4028235E38f, 1.4E-45f, 1.23f, -4.56f});
+  }
+
+  private static <T> Consumer<T> assertRecursiveEquals(T expected) {
+    return (actual) -> {
+      assertThat(actual).usingRecursiveComparison().isEqualTo(expected);
+    };
+  }
+}