feat: [OpenAI] Embedding Request Convenience (#331)

* OpenAI Embedding convenience response and request

* refactor imports

* change method name and remove `@With`

* Remove single token constructor in embedding request

* Remove single token constructor in embedding request

---------

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

Author: rpanackal

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

@@ -341,12 +341,29 @@ private void warnIfUnsupportedUsage() {
   }
 
   /**
-   * Get a vector representation of a given request with input that can be easily consumed by
-   * machine learning models and algorithms.
+   * Get a vector representation of a given request that can be easily consumed by machine learning
+   * models and algorithms using high-level request object.
+   *
+   * @param request the request with input text.
+   * @return the embedding response convenience object
+   * @throws OpenAiClientException if the request fails
+   * @see #embedding(EmbeddingsCreateRequest) for full confgurability.
+   * @since 1.4.0
+   */
+  @Beta
+  @Nonnull
+  public OpenAiEmbeddingResponse embedding(@Nonnull final OpenAiEmbeddingRequest request)
+      throws OpenAiClientException {
+    return new OpenAiEmbeddingResponse(embedding(request.createEmbeddingsCreateRequest()));
+  }
+
+  /**
+   * Get a vector representation of a given inputs using low-level request.
    *
    * @param request the request with input text.
    * @return the embedding output
    * @throws OpenAiClientException if the request fails
+   * @see #embedding(OpenAiEmbeddingRequest) for conveninece api
    * @since 1.4.0
    */
   @Beta

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

@@ -0,0 +1,48 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequest;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequestInput;
+import java.util.Collections;
+import java.util.List;
+import javax.annotation.Nonnull;
+import lombok.Value;
+
+/**
+ * Represents a request to create embeddings using OpenAI's API.
+ *
+ * <p>A high-level wrapper over the generated model class {@code EmbeddingsCreateRequest}, *
+ * improving API usability for common use cases such as creation from a list of tokens.
+ *
+ * @since 1.4.0
+ */
+@Beta
+@Value
+public class OpenAiEmbeddingRequest {
+  /** List of tokens to be embedded. */
+  @Nonnull private final List<String> tokens;
+
+  /**
+   * Constructs an OpenAiEmbeddingRequest from a list of strings.
+   *
+   * @param tokens a list of tokens to be embedded
+   */
+  public OpenAiEmbeddingRequest(@Nonnull final List<String> tokens) {
+    this.tokens = Collections.unmodifiableList(tokens);
+  }
+
+  /**
+   * Converts this request to an EmbeddingsCreateRequest.
+   *
+   * @return an EmbeddingsCreateRequest with the tokens to be embedded
+   */
+  @Nonnull
+  EmbeddingsCreateRequest createEmbeddingsCreateRequest() {
+    if (tokens.size() == 1) {
+      return new EmbeddingsCreateRequest()
+          .input(EmbeddingsCreateRequestInput.create(tokens.get(0)));
+    }
+
+    return new EmbeddingsCreateRequest().input(EmbeddingsCreateRequestInput.create(tokens));
+  }
+}

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

@@ -0,0 +1,52 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import static lombok.AccessLevel.NONE;
+import static lombok.AccessLevel.PACKAGE;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200Response;
+import java.util.ArrayList;
+import java.util.List;
+import javax.annotation.Nonnull;
+import lombok.AllArgsConstructor;
+import lombok.Setter;
+import lombok.Value;
+
+/**
+ * Represents a response from the OpenAI Embedding API.
+ *
+ * <p>A high-level wrapper over the generated model class {@code EmbeddingsCreate200Response},
+ * improving API usability for common use cases, such as extracting embeddings.
+ *
+ * @since 1.4.0
+ */
+@Beta
+@Value
+@AllArgsConstructor(access = PACKAGE)
+@Setter(value = NONE)
+public class OpenAiEmbeddingResponse {
+
+  /** The original response from the OpenAI Embedding API. */
+  @Nonnull EmbeddingsCreate200Response originalResponse;
+
+  /**
+   * Read the embeddings from the response as a list of float arrays.
+   *
+   * @return a list of float arrays
+   */
+  @Nonnull
+  public List<float[]> getEmbeddingVectors() {
+    final var embeddings = new ArrayList<float[]>();
+    for (final var container : originalResponse.getData()) {
+
+      final var embeddingDecimals = container.getEmbedding();
+      final var embeddingFloats = new float[embeddingDecimals.size()];
+
+      for (int i = 0; i < embeddingDecimals.size(); i++) {
+        embeddingFloats[i] = embeddingDecimals.get(i).floatValue();
+      }
+      embeddings.add(embeddingFloats);
+    }
+    return embeddings;
+  }
+}

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

@@ -0,0 +1,40 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.github.tomakehurst.wiremock.junit5.WireMockTest;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreate200Response;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequestInput;
+import java.util.List;
+import lombok.SneakyThrows;
+import org.junit.jupiter.api.Test;
+
+@WireMockTest
+class EmbeddingConvenienceTest {
+
+  @Test
+  void createEmbeddingRequestWithMultipleTokens() {
+    var request = new OpenAiEmbeddingRequest(List.of("token1", "token2", "token3"));
+    var lowLevelRequest = request.createEmbeddingsCreateRequest();
+
+    assertThat(((EmbeddingsCreateRequestInput.InnerStrings) lowLevelRequest.getInput()).values())
+        .containsExactly("token1", "token2", "token3");
+  }
+
+  @SneakyThrows
+  @Test
+  void getEmbeddings() {
+    var originalResponse =
+        OpenAiUtils.getOpenAiObjectMapper()
+            .readValue(
+                getClass().getClassLoader().getResource("__files/embeddingResponse.json"),
+                EmbeddingsCreate200Response.class);
+
+    var embeddings = new OpenAiEmbeddingResponse(originalResponse).getEmbeddingVectors();
+
+    assertThat(embeddings).isInstanceOf(List.class);
+    assertThat(embeddings).hasSize(1);
+    assertThat(embeddings)
+        .containsExactly(new float[] {0.0f, 3.4028235E38f, 1.4E-45f, 1.23f, -4.56f});
+  }
+}

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

@@ -30,8 +30,6 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ContentFilterPromptResults;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionRequest;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionStreamResponseChoicesInner;
-import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequest;
-import com.sap.ai.sdk.foundationmodels.openai.generated.model.EmbeddingsCreateRequestInput;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.FunctionObject;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.PromptFilterResult;
 import io.vavr.control.Try;
@@ -244,21 +242,19 @@ void history() {
   void embedding() {
     stubForEmbedding();
 
-    final var result =
-        client.embedding(
-            new EmbeddingsCreateRequest()
-                .input(EmbeddingsCreateRequestInput.create("Hello World")));
+    final var response =
+        client.embedding(new OpenAiEmbeddingRequest(List.of("Hello World"))).getOriginalResponse();
 
-    assertThat(result).isNotNull();
-    assertThat(result.getModel()).isEqualTo("ada");
-    assertThat(result.getObject()).isEqualTo("list");
+    assertThat(response).isNotNull();
+    assertThat(response.getModel()).isEqualTo("ada");
+    assertThat(response.getObject()).isEqualTo("list");
 
-    assertThat(result.getUsage()).isNotNull();
-    assertThat(result.getUsage().getPromptTokens()).isEqualTo(2);
-    assertThat(result.getUsage().getTotalTokens()).isEqualTo(2);
+    assertThat(response.getUsage()).isNotNull();
+    assertThat(response.getUsage().getPromptTokens()).isEqualTo(2);
+    assertThat(response.getUsage().getTotalTokens()).isEqualTo(2);
 
-    assertThat(result.getData()).isNotNull().hasSize(1);
-    var embeddingData = result.getData().get(0);
+    assertThat(response.getData()).isNotNull().hasSize(1);
+    var embeddingData = response.getData().get(0);
     assertThat(embeddingData).isNotNull();
     assertThat(embeddingData.getObject()).isEqualTo("embedding");
     assertThat(embeddingData.getIndex()).isZero();

sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/controllers/OpenAiV2Test.java

@@ -9,6 +9,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiClient;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiMessage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CompletionUsage;
+import java.util.ArrayList;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
 import lombok.extern.slf4j.Slf4j;
@@ -86,9 +87,13 @@ void chatCompletionTools() {
   void embedding() {
     final var embedding = service.embedding("Hello world");
 
-    assertThat(embedding.getData().get(0).getEmbedding()).hasSizeGreaterThan(1);
-    assertThat(embedding.getModel()).isEqualTo("ada");
-    assertThat(embedding.getObject()).isEqualTo("list");
+    assertThat(embedding.getOriginalResponse().getData().get(0).getEmbedding())
+        .hasSizeGreaterThan(1);
+    assertThat(embedding.getEmbeddingVectors()).isInstanceOf(ArrayList.class);
+    assertThat(embedding.getEmbeddingVectors().get(0)).isInstanceOf(float[].class);
+
+    assertThat(embedding.getOriginalResponse().getModel()).isEqualTo("ada");
+    assertThat(embedding.getOriginalResponse().getObject()).isEqualTo("list");
   }
 
   @Test

sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/services/OpenAiServiceV2.java

@@ -10,12 +10,11 @@
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiChatCompletionRequest;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiChatCompletionResponse;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiClient;
+import com.sap.ai.sdk.foundationmodels.openai.OpenAiEmbeddingRequest;
+import com.sap.ai.sdk.foundationmodels.openai.OpenAiEmbeddingResponse;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiImageItem;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiMessage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool;
-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 com.sap.ai.sdk.foundationmodels.openai.generated.model.FunctionObject;
 import java.util.List;
 import java.util.Map;
@@ -117,9 +116,8 @@ public OpenAiChatCompletionResponse chatCompletionTools(final int months) {
    * @return the embedding response
    */
   @Nonnull
-  public EmbeddingsCreate200Response embedding(@Nonnull final String input) {
-    final var request =
-        new EmbeddingsCreateRequest().input(EmbeddingsCreateRequestInput.create(input));
+  public OpenAiEmbeddingResponse embedding(@Nonnull final String input) {
+    final var request = new OpenAiEmbeddingRequest(List.of(input));
 
     return OpenAiClient.forModel(TEXT_EMBEDDING_ADA_002).embedding(request);
   }