chore: Consolidate OpenAI convenience methods to set tool-choice (#351)

* Initial

* Apply suggestion

---------

Co-authored-by: Alexander Dümont <[email protected]>

Author: newtork

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/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/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 =

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

@@ -527,7 +527,7 @@ void chatCompletionTool() {
         new OpenAiChatCompletionRequest(
                 "A pair of rabbits is placed in a field. Each month, every pair produces one new pair, starting from the second month. How many rabbits will there be after 12 months?")
             .withTools(List.of(tool))
-            .withToolChoiceFunction("fibonacci");
+            .withToolChoice(OpenAiToolChoice.function("fibonacci"));
 
     var response = client.chatCompletion(request).getOriginalResponse();
 

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

@@ -14,6 +14,7 @@
 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.OpenAiToolChoice;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.FunctionObject;
 import java.util.List;
@@ -104,7 +105,7 @@ public OpenAiChatCompletionResponse chatCompletionTools(final int months) {
                 "A pair of rabbits is placed in a field. Each month, every pair produces one new pair, starting from the second month. How many rabbits will there be after %s months?"
                     .formatted(months))
             .withTools(List.of(tool))
-            .withToolChoiceFunction("fibonacci");
+            .withToolChoice(OpenAiToolChoice.function("fibonacci"));
 
     return OpenAiClient.forModel(GPT_35_TURBO).chatCompletion(request);
   }