feat: [OpenAI] Full Tool call Convenience (#396)

* Tool call full e2e unverified

* CI

* Reuse tool

* Remove unnecessary line inserts

* Create schema with jackson

* First version
- Mostly tested
- API design complete
- Function Call as message content item
- Non nullability of `Message.content()`

* Formatting

* Testing and javadocs

* improve test clarity

* Remove strict tool invocation config

* Fix maven dependency scope issue

* Fix maven dependency scope issue + 1

* Refactor. toolCalls get dedicated field in assistant message

- OpenAiAssistantMessage().content() may contain empty list

* minor fixes
- final keyword
- remove redundant assertion
- variable naming

* minor fixes
- final keyword
- variable naming

* Test message list in request externally unmodifiable

* Test message list in request externally unmodifiable

* minor javadoc update

* Remove sample app changes

* @beta annotation

* Update foundation-models/openai/src/main/java/com/sap/ai/sdk/foundationmodels/openai/OpenAiChatCompletionResponse.java

Co-authored-by: Charles Dubois <[email protected]>

* Apply suggestions from code review

javadoc and naming

Co-authored-by: Charles Dubois <[email protected]>

* update getMessage method impl readability

* Move test to generated client test class

* Extend tests

* Reduce test

* Refactor test

* Formatting

* import statement

---------

Co-authored-by: Roshin Rajan Panackal <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>
Co-authored-by: Charles Dubois <[email protected]>

Author: 3 people

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

@@ -3,8 +3,12 @@
 import static lombok.AccessLevel.PACKAGE;
 
 import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionMessageToolCall;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionMessageToolCallFunction;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestAssistantMessage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestAssistantMessageContent;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ToolCallType;
+import java.util.Collections;
 import java.util.List;
 import javax.annotation.Nonnull;
 import lombok.AllArgsConstructor;
@@ -15,29 +19,48 @@
 /**
  * Represents a chat message as 'assistant' to OpenAI service.
  *
+ * <p>When {@link OpenAiAssistantMessage} is received from {@link OpenAiChatCompletionResponse}, it
+ * may contain tool calls that need to be executed. The tool calls are represented as {@link
+ * OpenAiToolCall}.
+ *
  * @since 1.4.0
  */
 @Beta
 @Value
 @Accessors(fluent = true)
 @AllArgsConstructor(access = PACKAGE)
-class OpenAiAssistantMessage implements OpenAiMessage {
+public class OpenAiAssistantMessage implements OpenAiMessage {
 
   /** The role associated with this message. */
   @Nonnull String role = "assistant";
 
-  /** The content of the message. */
+  /**
+   * The content of the message.
+   *
+   * <p>May contain an empty list of {@link OpenAiContentItem} when tool calls are present.
+   */
   @Getter(onMethod_ = @Beta)
   @Nonnull
   OpenAiMessageContent content;
 
   /**
-   * Creates a new assistant message with the given single message.
+   * The tool calls associated with this message if present.
+   *
+   * @since 1.6.0
+   */
+  @Getter(onMethod_ = @Beta)
+  @Nonnull
+  List<OpenAiToolCall> toolCalls;
+
+  /**
+   * Creates a new assistant message with the given single message as text content.
    *
    * @param singleMessage the message.
    */
   OpenAiAssistantMessage(@Nonnull final String singleMessage) {
-    this(new OpenAiMessageContent(List.of(new OpenAiTextItem(singleMessage))));
+    this(
+        new OpenAiMessageContent(List.of(new OpenAiTextItem(singleMessage))),
+        Collections.emptyList());
   }
 
   /**
@@ -47,9 +70,31 @@ class OpenAiAssistantMessage implements OpenAiMessage {
    */
   @Nonnull
   ChatCompletionRequestAssistantMessage createChatCompletionRequestMessage() {
-    final var textItem = (OpenAiTextItem) this.content().items().get(0);
-    return new ChatCompletionRequestAssistantMessage()
-        .role(ChatCompletionRequestAssistantMessage.RoleEnum.fromValue(role()))
-        .content(ChatCompletionRequestAssistantMessageContent.create(textItem.text()));
+    final var message =
+        new ChatCompletionRequestAssistantMessage()
+            .role(ChatCompletionRequestAssistantMessage.RoleEnum.fromValue(role()));
+
+    final var items = content().items();
+    if (!items.isEmpty() && items.get(0) instanceof OpenAiTextItem textItem) {
+      message.content(ChatCompletionRequestAssistantMessageContent.create(textItem.text()));
+    }
+
+    for (final var item : toolCalls()) {
+      if (item instanceof OpenAiFunctionCall functionItem) {
+        final var functionCall =
+            new ChatCompletionMessageToolCallFunction()
+                .name(functionItem.getName())
+                .arguments(functionItem.getArguments());
+
+        final var toolCall =
+            new ChatCompletionMessageToolCall()
+                .type(ToolCallType.FUNCTION)
+                .id(functionItem.getId())
+                .function(functionCall);
+
+        message.addToolCallsItem(toolCall);
+      }
+    }
+    return message;
   }
 }

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

@@ -149,8 +149,19 @@ public OpenAiChatCompletionRequest(@Nonnull final String message) {
   @Tolerate
   public OpenAiChatCompletionRequest(
       @Nonnull final OpenAiMessage message, @Nonnull final OpenAiMessage... messages) {
+    this(Lists.asList(message, messages));
+  }
+
+  /**
+   * Creates an OpenAiChatCompletionPrompt with a list of messages.
+   *
+   * @param messages the list of messages to be added to the prompt
+   * @since 1.6.0
+   */
+  @Tolerate
+  public OpenAiChatCompletionRequest(@Nonnull final List<OpenAiMessage> messages) {
     this(
-        Lists.asList(message, messages),
+        List.copyOf(messages),
         null,
         null,
         null,

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

@@ -8,6 +8,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CompletionUsage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionResponse;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionResponseChoicesInner;
+import java.util.List;
 import java.util.Objects;
 import javax.annotation.Nonnull;
 import lombok.RequiredArgsConstructor;
@@ -50,6 +51,9 @@ public CreateChatCompletionResponseChoicesInner getChoice() {
   /**
    * Gets the content of the first choice.
    *
+   * <p>The content may be empty {@code ""} if the assistant did not return any content i.e. when
+   * tool calls are present.
+   *
    * @return the content of the first choice
    * @throws OpenAiClientException if the content is filtered by the content filter
    */
@@ -61,4 +65,35 @@ public String getContent() {
 
     return Objects.requireNonNullElse(getChoice().getMessage().getContent(), "");
   }
+
+  /**
+   * Gets the {@code OpenAiAssistantMessage} for the first choice.
+   *
+   * @return the assistant message
+   * @throws OpenAiClientException if the content is filtered by the content filter
+   * @since 1.6.0
+   */
+  @Nonnull
+  public OpenAiAssistantMessage getMessage() {
+    final var toolCalls = getChoice().getMessage().getToolCalls();
+
+    if (toolCalls == null) {
+      return OpenAiMessage.assistant(getContent());
+    }
+
+    final List<OpenAiContentItem> contentItems =
+        getContent().isEmpty() ? List.of() : List.of(new OpenAiTextItem(getContent()));
+
+    final var openAiToolCalls =
+        toolCalls.stream()
+            .<OpenAiToolCall>map(
+                toolCall ->
+                    new OpenAiFunctionCall(
+                        toolCall.getId(),
+                        toolCall.getFunction().getName(),
+                        toolCall.getFunction().getArguments()))
+            .toList();
+
+    return new OpenAiAssistantMessage(new OpenAiMessageContent(contentItems), openAiToolCalls);
+  }
 }

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

@@ -0,0 +1,25 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import com.google.common.annotations.Beta;
+import javax.annotation.Nonnull;
+import lombok.AllArgsConstructor;
+import lombok.Value;
+
+/**
+ * Represents a function type tool called by an OpenAI model.
+ *
+ * @since 1.6.0
+ */
+@Beta
+@Value
+@AllArgsConstructor(access = lombok.AccessLevel.PACKAGE)
+public class OpenAiFunctionCall implements OpenAiToolCall {
+  /** The unique identifier for the function call. */
+  @Nonnull String id;
+
+  /** The name of the function to be called. */
+  @Nonnull String name;
+
+  /** The arguments for the function call, encoded as a JSON string. */
+  @Nonnull String arguments;
+}

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

@@ -60,8 +60,8 @@ static OpenAiSystemMessage system(@Nonnull final String message) {
   /**
    * A convenience method to create a tool message.
    *
-   * @param message the message content.
-   * @param toolCallId identifier of the tool call this message is responding to.
+   * @param message response of the executed tool call.
+   * @param toolCallId identifier of the tool call that the assistant expected.
    * @return the tool message.
    */
   @Nonnull

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

@@ -0,0 +1,11 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Represents a tool called by an OpenAI model.
+ *
+ * @since 1.6.0
+ */
+@Beta
+public sealed interface OpenAiToolCall permits OpenAiFunctionCall {}

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

@@ -25,17 +25,17 @@ public class OpenAiToolMessage implements OpenAiMessage {
   /** The role associated with this message. */
   @Nonnull String role = "tool";
 
-  /** The content of the message. */
+  /** Response of the executed tool call. */
   @Nonnull OpenAiMessageContent content;
 
   /** The tool call id associated with this message. */
   @Nonnull private final String toolCallId;
 
   /**
-   * Creates a new tool message from a string and tool call id.
+   * Creates a new tool message from a tool execution response and tool call id.
    *
-   * @param message the first message.
-   * @param toolCallId identifier of the tool call this message is responding to.
+   * @param message response of the executed tool call.
+   * @param toolCallId identifier of the tool call that the assistant expected.
    */
   OpenAiToolMessage(@Nonnull final String message, @Nonnull final String toolCallId) {
     this(new OpenAiMessageContent(List.of(new OpenAiTextItem(message))), toolCallId);

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

@@ -34,6 +34,8 @@ static ChatCompletionRequestMessage createChatCompletionRequestMessage(
       return assistantMessage.createChatCompletionRequestMessage();
     } else if (message instanceof OpenAiSystemMessage systemMessage) {
       return systemMessage.createChatCompletionRequestMessage();
+    } else if (message instanceof OpenAiToolMessage toolMessage) {
+      return toolMessage.createChatCompletionRequestMessage();
     } else {
       throw new IllegalArgumentException("Unknown message type: " + message.getClass());
     }

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

@@ -1,6 +1,7 @@
 package com.sap.ai.sdk.foundationmodels.openai;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatNoException;
 
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestAssistantMessage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestAssistantMessageContent;
@@ -13,6 +14,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestToolMessageContent;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestUserMessage;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionRequestUserMessageContent;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ToolCallType;
 import java.net.URI;
 import java.util.List;
 import java.util.stream.Stream;
@@ -194,6 +196,22 @@ void assistantMessageToDto() {
             ((ChatCompletionRequestAssistantMessageContent.InnerString) requestMessage.getContent())
                 .value())
         .isEqualTo(validText);
+
+    var messageWithFunctionCall =
+        new OpenAiAssistantMessage(
+            new OpenAiMessageContent(List.of()),
+            List.of(new OpenAiFunctionCall("id", "name", "arguments")));
+    var requestMessageWithFunctionCall =
+        messageWithFunctionCall.createChatCompletionRequestMessage();
+
+    assertThat(requestMessageWithFunctionCall.getToolCalls()).hasSize(1);
+    assertThat(requestMessageWithFunctionCall.getToolCalls().get(0).getType())
+        .isEqualTo(ToolCallType.FUNCTION);
+    assertThat(requestMessageWithFunctionCall.getToolCalls().get(0).getId()).isEqualTo("id");
+    assertThat(requestMessageWithFunctionCall.getToolCalls().get(0).getFunction().getName())
+        .isEqualTo("name");
+    assertThat(requestMessageWithFunctionCall.getToolCalls().get(0).getFunction().getArguments())
+        .isEqualTo("arguments");
   }
 
   @Test
@@ -220,4 +238,11 @@ void throwOnSystemMessageWithImage() {
         .hasMessageContaining(
             "Unknown content type for class com.sap.ai.sdk.foundationmodels.openai.OpenAiImageItem messages.");
   }
+
+  @ParameterizedTest
+  @MethodSource("provideValidTextMessageByRole")
+  void testCreateChatCompletionRequestMessage(OpenAiMessage message) {
+    assertThatNoException()
+        .isThrownBy(() -> OpenAiUtils.createChatCompletionRequestMessage(message));
+  }
 }

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

@@ -7,6 +7,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionToolChoiceOption;
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionRequestAllOfStop;
 import java.math.BigDecimal;
+import java.util.ArrayList;
 import java.util.List;
 import org.junit.jupiter.api.Test;
 
@@ -94,4 +95,23 @@ void withToolChoiceFunction() {
     assertThat(choice.getType().getValue()).isEqualTo("function");
     assertThat(choice.getFunction().getName()).isEqualTo("functionName");
   }
+
+  @Test
+  void messageListExternallyUnmodifiable() {
+    var originalList = new ArrayList<OpenAiMessage>();
+    OpenAiUserMessage user = OpenAiMessage.user("Initial message");
+    originalList.add(user);
+
+    var request = new OpenAiChatCompletionRequest(originalList);
+
+    var generatedRequest = request.createCreateChatCompletionRequest();
+    assertThat(generatedRequest.getMessages()).hasSize(1);
+
+    originalList.add(OpenAiMessage.user("Another message"));
+
+    var generatedRequestAfter = request.createCreateChatCompletionRequest();
+    assertThat(generatedRequestAfter.getMessages())
+        .as("Modifying the original list should not affect the messages in the request object.")
+        .hasSize(1);
+  }
 }