Merge remote-tracking branch 'refs/remotes/origin/main' into chore/openai-embedding-float

Author: rpanackal

.github/workflows/pr-lint.yaml

@@ -23,6 +23,7 @@ jobs:
             OpenAI
             Orchestration
             DevOps
+            PromptRegistry
           headerPattern: '^(\w.+): (?:\[(\w.+)\] )?(.+)$'
           headerPatternCorrespondence: type, scope, subject
           # for available types, check:

.github/workflows/spec-update.yaml

@@ -11,6 +11,7 @@ on:
           - core
           - grounding
           - orchestration
+          - prompt-registry
         default: orchestration
       file-ref:
         description: "Branch or tag to checkout the spec file from"
@@ -78,6 +79,10 @@ jobs:
               API_URL="$API_BASE_URL/AI/llm-orchestration/contents/src/spec/api.yaml?ref=$REF"
               FILE_PATH='orchestration/src/main/resources/spec/orchestration.yaml'
               ;;
+            prompt-registry)
+              API_URL="$API_BASE_URL/AI/prompt-registry/contents/src/spec/prompt-registry.yaml?ref=$REF"
+              FILE_PATH='prompt-registry/src/main/resources/spec/prompt-registry.yaml'
+              ;;
           esac
           
           echo "Downloading $CHOICE specification file from $API_URL ..."
@@ -187,4 +192,4 @@ jobs:
             echo "| Client Testing | ${{ steps.compile.outputs.test_result == 'success' && '✅' || steps.compile.outputs.test_result == 'skipped' && '⏩' || '❌' }} ${{ steps.compile.outputs.test_result }}" >> $GITHUB_STEP_SUMMARY
             echo "| Branch Creation | ${{ steps.push.outcome == 'success' && '✅ [Branch Link]($DIFF_URL)' || '❌ failure' }}" >> $GITHUB_STEP_SUMMARY
             echo "| Pull Request Creation | ${{ env.CREATE_PR == 'false' && '⏩ skipped' || '' }}${{ env.CREATE_PR == 'true' && steps.push.outcome == 'success' && '✅ [PR Link]($PR_URL)' || '' }}" >> $GITHUB_STEP_SUMMARY
-          fi
+          fi

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

@@ -2,8 +2,6 @@
 
 import com.google.common.annotations.Beta;
 import com.google.common.collect.Lists;
-import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionNamedToolChoice;
-import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionNamedToolChoiceFunction;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionStreamOptions;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionToolChoiceOption;
@@ -253,48 +251,24 @@ public OpenAiChatCompletionRequest withLogprobs(@Nonnull final Boolean logprobs)
   }
 
   /**
-   * Only message generation will be performed without calling any tool.
+   * Define the model behavior towards calling functions.
    *
-   * @return the current OpenAiChatCompletionRequest instance.
-   */
-  @Nonnull
-  public OpenAiChatCompletionRequest withToolChoiceNone() {
-    return this.withToolChoice(ChatCompletionToolChoiceOption.create("none"));
-  }
-
-  /**
-   * The model may decide whether to call a (one or more) tool.
-   *
-   * @return the current OpenAiChatCompletionRequest instance.
-   */
-  @Nonnull
-  public OpenAiChatCompletionRequest withToolChoiceOptional() {
-    return this.withToolChoice(ChatCompletionToolChoiceOption.create("auto"));
-  }
-
-  /**
-   * The model must call one or more tools as part of its processing.
+   * <p>Example:
    *
-   * @return the current OpenAiChatCompletionRequest instance.
-   */
-  @Nonnull
-  public OpenAiChatCompletionRequest withToolChoiceRequired() {
-    return this.withToolChoice(ChatCompletionToolChoiceOption.create("required"));
-  }
-
-  /**
-   * The model must call the function specified by {@code functionName}.
+   * <ul>
+   *   <li><code>.withToolChoice(OpenAiToolChoice.NONE)</code>
+   *   <li><code>.withToolChoice(OpenAiToolChoice.OPTIONAL)</code>
+   *   <li><code>.withToolChoice(OpenAiToolChoice.REQUIRED)</code>
+   *   <li><code>.withToolChoice(OpenAiToolChoice.function("fibonacci")</code>
+   * </ul>
    *
-   * @param functionName the name of the function that must be called.
+   * @param choice the generic tool choice.
    * @return the current OpenAiChatCompletionRequest instance.
    */
   @Nonnull
-  public OpenAiChatCompletionRequest withToolChoiceFunction(@Nonnull final String functionName) {
-    return this.withToolChoice(
-        ChatCompletionToolChoiceOption.create(
-            new ChatCompletionNamedToolChoice()
-                .type(ChatCompletionNamedToolChoice.TypeEnum.FUNCTION)
-                .function(new ChatCompletionNamedToolChoiceFunction().name(functionName))));
+  @Tolerate
+  public OpenAiChatCompletionRequest withToolChoice(@Nonnull final OpenAiToolChoice choice) {
+    return this.withToolChoice(choice.toolChoice);
   }
 
   /**

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/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiToolChoice.java

@@ -0,0 +1,45 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionNamedToolChoice;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionNamedToolChoiceFunction;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionToolChoiceOption;
+import javax.annotation.Nonnull;
+import lombok.AccessLevel;
+import lombok.RequiredArgsConstructor;
+
+/**
+ * OpenAi ToolChoice to specify whether to call which tool.
+ *
+ * @since 1.4.0
+ */
+@RequiredArgsConstructor(access = AccessLevel.PROTECTED)
+public class OpenAiToolChoice {
+  @Nonnull final ChatCompletionToolChoiceOption toolChoice;
+
+  /** Only message generation will be performed without calling any tool. */
+  public static final OpenAiToolChoice NONE =
+      new OpenAiToolChoice(ChatCompletionToolChoiceOption.create("none"));
+
+  /** The model may decide whether to call a (one or more) tool. */
+  public static final OpenAiToolChoice OPTIONAL =
+      new OpenAiToolChoice(ChatCompletionToolChoiceOption.create("auto"));
+
+  /** The model must call one or more tools as part of its processing. */
+  public static final OpenAiToolChoice REQUIRED =
+      new OpenAiToolChoice(ChatCompletionToolChoiceOption.create("required"));
+
+  /**
+   * The model must call the function specified by {@code functionName}.
+   *
+   * @param functionName the name of the function that must be called.
+   * @return the OpenAI tool choice.
+   */
+  @Nonnull
+  public static OpenAiToolChoice function(@Nonnull final String functionName) {
+    return new OpenAiToolChoice(
+        ChatCompletionToolChoiceOption.create(
+            new ChatCompletionNamedToolChoice()
+                .type(ChatCompletionNamedToolChoice.TypeEnum.FUNCTION)
+                .function(new ChatCompletionNamedToolChoiceFunction().name(functionName))));
+  }
+}

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/OpenAiChatCompletionRequestTest.java

@@ -50,7 +50,7 @@ void createWithExistingRequest() {
   @Test
   void withToolChoiceNone() {
     OpenAiChatCompletionRequest request =
-        new OpenAiChatCompletionRequest("message").withToolChoiceNone();
+        new OpenAiChatCompletionRequest("message").withToolChoice(OpenAiToolChoice.NONE);
 
     var lowLevelRequest = request.createCreateChatCompletionRequest();
     var choice =
@@ -61,7 +61,7 @@ void withToolChoiceNone() {
   @Test
   void withToolChoiceOptional() {
     OpenAiChatCompletionRequest request =
-        new OpenAiChatCompletionRequest("message").withToolChoiceOptional();
+        new OpenAiChatCompletionRequest("message").withToolChoice(OpenAiToolChoice.OPTIONAL);
 
     var lowLevelRequest = request.createCreateChatCompletionRequest();
     var choice =
@@ -72,7 +72,7 @@ void withToolChoiceOptional() {
   @Test
   void withToolChoiceRequired() {
     OpenAiChatCompletionRequest request =
-        new OpenAiChatCompletionRequest("message").withToolChoiceRequired();
+        new OpenAiChatCompletionRequest("message").withToolChoice(OpenAiToolChoice.REQUIRED);
 
     var lowLevelRequest = request.createCreateChatCompletionRequest();
     var choice =
@@ -83,7 +83,8 @@ void withToolChoiceRequired() {
   @Test
   void withToolChoiceFunction() {
     OpenAiChatCompletionRequest request =
-        new OpenAiChatCompletionRequest("message").withToolChoiceFunction("functionName");
+        new OpenAiChatCompletionRequest("message")
+            .withToolChoice(OpenAiToolChoice.function("functionName"));
 
     var lowLevelRequest = request.createCreateChatCompletionRequest();
     var choice =