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

- test improvements

Author: rpanackal

docs/guides/SPRING_AI_INTEGRATION.md

@@ -35,10 +35,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:
 
@@ -53,7 +55,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:
 
@@ -77,7 +79,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.
@@ -93,15 +95,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:
 
@@ -137,3 +139,24 @@ 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).
 
+## OpenAI
+
+### Embedding
+
+With SpringAI integration (_since v1.5.0_), you may now obtain embedding vectors for a list of strings as follows:
+
+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);
+``` 
+
+Then you can invoke `embded` method on the `embeddingModel` object with the text items to embed.
+
+```java
+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

@@ -12,7 +12,7 @@
 
 ### ✨ New Functionality
 
--
+- [OpenAI] [Spring AI integration for embedding calls.](../guides/SPRING_AI_INTEGRATION.md#embedding)
 
 ### 📈 Improvements
 

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

@@ -1,6 +1,5 @@
 package com.sap.ai.sdk.foundationmodels.openai.spring;
 
-import com.google.common.annotations.Beta;
 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;
@@ -24,7 +23,6 @@
  *
  * @since 1.5.0
  */
-@Beta
 public class OpenAiSpringEmbeddingModel implements EmbeddingModel {
 
   private final OpenAiClient client;
@@ -39,9 +37,21 @@ public OpenAiSpringEmbeddingModel(@Nonnull final OpenAiClient client) {
     this.client = client;
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if {@code request.getOptions().getModel()} is not null.
+   */
   @Override
   @Nonnull
-  public EmbeddingResponse call(@Nonnull final EmbeddingRequest request) {
+  public EmbeddingResponse call(@Nonnull final EmbeddingRequest request)
+      throws IllegalArgumentException {
+
+    if (request.getOptions().getModel() != null) {
+      throw new IllegalArgumentException(
+          "Invalid EmbeddingRequest: the model option must be null, as the client already defines the model.");
+    }
+
     final var openAiRequest = createEmbeddingCreateRequest(request);
     final var openAiResponse = client.embedding(openAiRequest);
 
@@ -52,7 +62,7 @@ public EmbeddingResponse call(@Nonnull final EmbeddingRequest request) {
   @Nonnull
   public float[] embed(@Nonnull final Document document) throws UnsupportedOperationException {
     if (document.isText()) {
-      return embed(Objects.requireNonNull(document.getText(), "Document text is null"));
+      return embed(Objects.requireNonNull(document.getText(), "Document is missing text content"));
     }
     throw new UnsupportedOperationException("Only text type document supported for embedding");
   }

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

@@ -2,8 +2,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
-import static org.junit.jupiter.api.Assertions.assertArrayEquals;
-import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.assertArg;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
@@ -12,8 +11,12 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200ResponseDataInner;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200ResponseUsage;
 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.val;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.springframework.ai.chat.metadata.DefaultUsage;
 import org.springframework.ai.document.Document;
@@ -32,55 +35,93 @@ void setUp() {
   }
 
   @Test
-  void callWithValidRequest() {
-    final var request =
-        new EmbeddingRequest(
-            List.of("instructions"), EmbeddingOptionsBuilder.builder().withDimensions(128).build());
+  @DisplayName("Call with embedding request containing valid options")
+  void callWithValidEmbeddingRequest() {
+    val texts = List.of("Some text");
+    val springAiRequest =
+        new EmbeddingRequest(texts, EmbeddingOptionsBuilder.builder().withDimensions(128).build());
+
+    val vector = new float[] {0.0f};
+    val expectedOpenAiResponse =
+        new EmbeddingsCreate200Response()
+            .data(List.of(new EmbeddingsCreate200ResponseDataInner().embedding(vector)))
+            .usage(new EmbeddingsCreate200ResponseUsage().promptTokens(0).totalTokens(0));
+
+    val expectedOpenAiRequest =
+        new EmbeddingsCreateRequest()
+            .input(EmbeddingsCreateRequestInput.create(texts))
+            .dimensions(128);
 
-    final var vector = new float[] {0.0f};
-    final var modelName = ""; // defined by client object and options not honoured
-    final var expectedResponse =
+    when(client.embedding(assertArg(assertRecursiveEquals(expectedOpenAiRequest))))
+        .thenReturn(expectedOpenAiResponse);
+
+    val actualSpringAiResponse = new OpenAiSpringEmbeddingModel(client).call(springAiRequest);
+
+    val modelName = ""; // defined by client object and options not honoured
+    val expectedSpringAiResponse =
         new EmbeddingResponse(
             List.of(new Embedding(vector, 0)),
             new EmbeddingResponseMetadata(modelName, new DefaultUsage(0, null, 0)));
 
-    final var openAiResponse =
-        new EmbeddingsCreate200Response()
-            .data(List.of(new EmbeddingsCreate200ResponseDataInner().embedding(vector)))
-            .usage(new EmbeddingsCreate200ResponseUsage().promptTokens(0).totalTokens(0));
+    assertThat(expectedSpringAiResponse)
+        .usingRecursiveComparison()
+        .isEqualTo(actualSpringAiResponse);
+  }
 
-    when(client.embedding(any(EmbeddingsCreateRequest.class))).thenReturn(openAiResponse);
+  @Test
+  @DisplayName("Call with embedding request with model option set")
+  void callWithModelOptionSetThrowsException() {
+    val springAiRequest =
+        new EmbeddingRequest(
+            List.of("Some text"), EmbeddingOptionsBuilder.builder().withModel("model").build());
 
-    final var actualResponse = new OpenAiSpringEmbeddingModel(client).call(request);
+    val model = new OpenAiSpringEmbeddingModel(client);
 
-    assertThat(expectedResponse).usingRecursiveComparison().isEqualTo(actualResponse);
+    assertThatThrownBy(() -> model.call(springAiRequest))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessage(
+            "Invalid EmbeddingRequest: the model option must be null, as the client already defines the model.");
   }
 
   @Test
+  @DisplayName("Embed document with text content")
   void embedDocument() {
     Document document = new Document("Some content");
 
-    var vector = new float[] {1, 2, 3};
-    var openAiResponse =
+    val vector = new float[] {1, 2, 3};
+    val openAiResponse =
         new EmbeddingsCreate200Response()
             .data(List.of(new EmbeddingsCreate200ResponseDataInner().embedding(vector)))
             .usage(new EmbeddingsCreate200ResponseUsage().promptTokens(0).totalTokens(0));
 
-    when(client.embedding(any(EmbeddingsCreateRequest.class))).thenReturn(openAiResponse);
+    val expectedOpenAiRequest =
+        new EmbeddingsCreateRequest()
+            .input(EmbeddingsCreateRequestInput.create(List.of(document.getText())));
+
+    when(client.embedding(assertArg(assertRecursiveEquals(expectedOpenAiRequest))))
+        .thenReturn(openAiResponse);
 
     float[] result = new OpenAiSpringEmbeddingModel(client).embed(document);
-    assertArrayEquals(new float[] {1, 2, 3}, result);
+
+    assertThat(result).isEqualTo(new float[] {1, 2, 3});
   }
 
   @Test
-  void embedDocumentThrowsException() {
-    var document = mock(Document.class);
+  @DisplayName("Embed document with missing text content")
+  void embedDocumentNonTextThrowsException() {
+    val document = mock(Document.class);
     when(document.isText()).thenReturn(false);
 
-    var model = new OpenAiSpringEmbeddingModel(client);
+    val model = new OpenAiSpringEmbeddingModel(client);
 
     assertThatThrownBy(() -> model.embed(document))
         .isInstanceOf(UnsupportedOperationException.class)
         .hasMessage("Only text type document supported for embedding");
   }
+
+  private static <T> Consumer<T> assertRecursiveEquals(T expected) {
+    return (actual) -> {
+      assertThat(actual).usingRecursiveComparison().isEqualTo(expected);
+    };
+  }
 }