feat: [OpenAI] Tool Definition and Call Parsing V2 (Incl Execution)

docs/release_notes.md

@@ -12,7 +12,7 @@
 
 ### ✨ New Functionality
 
--
+- [OpenAI] [Add convenience for tool definition, parsing function calls and tool execution](https://sap.github.io/ai-sdk/docs/java/foundation-models/openai/chat-completion#executing-tool-calls)
 
 ### 📈 Improvements
 

foundation-models/openai/pom.xml

@@ -77,6 +77,10 @@
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-annotations</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.module</groupId>
+      <artifactId>jackson-module-jsonSchema</artifactId>
+    </dependency>
     <dependency>
       <groupId>io.vavr</groupId>
       <artifactId>vavr</artifactId>

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

@@ -282,6 +282,19 @@ public OpenAiChatCompletionRequest withToolChoice(@Nonnull final OpenAiToolChoic
     return this.withToolChoice(choice.toolChoice);
   }
 
+  /**
+   * Sets the tools to be used in the request with convenience class {@code OpenAiTool}.
+   *
+   * @param tools the list of tools to be used
+   * @return a new OpenAiChatCompletionRequest instance with the specified tools
+   * @throws IllegalArgumentException if the tool type is not supported
+   * @since 1.7.0
+   */
+  @Nonnull
+  public OpenAiChatCompletionRequest withOpenAiTools(@Nonnull final List<OpenAiTool<?>> tools) {
+    return this.withTools(tools.stream().map(OpenAiTool::createChatCompletionTool).toList());
+  }
+
   /**
    * Converts the request to a generated model class CreateChatCompletionRequest.
    *

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

@@ -26,7 +26,7 @@
 @Setter(value = NONE)
 public class OpenAiChatCompletionResponse {
   /** The original response from the OpenAI API. */
-  @Nonnull final CreateChatCompletionResponse originalResponse;
+  @Nonnull CreateChatCompletionResponse originalResponse;
 
   /**
    * Gets the token usage from the original response.

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

@@ -1,6 +1,12 @@
 package com.sap.ai.sdk.foundationmodels.openai;
 
+import static com.sap.ai.sdk.foundationmodels.openai.OpenAiUtils.getOpenAiObjectMapper;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
 import com.google.common.annotations.Beta;
+import java.lang.reflect.Type;
+import java.util.Map;
 import javax.annotation.Nonnull;
 import lombok.AllArgsConstructor;
 import lombok.Value;
@@ -22,4 +28,50 @@ public class OpenAiFunctionCall implements OpenAiToolCall {
 
   /** The arguments for the function call, encoded as a JSON string. */
   @Nonnull String arguments;
+
+  /**
+   * Parses the arguments, encoded as a JSON string, into a {@code Map<String, Object>}.
+   *
+   * @return a map of the arguments
+   * @throws IllegalArgumentException if parsing fails
+   * @since 1.7.0
+   */
+  @Nonnull
+  public Map<String, Object> getArgumentsAsMap() throws IllegalArgumentException {
+    return parseArguments(new TypeReference<>() {});
+  }
+
+  /**
+   * Parses the arguments, encoded as a JSON string, into an object of type expected by a function
+   * tool.
+   *
+   * @param tool the function tool the arguments are for
+   * @param <T> the type of the class
+   * @return the parsed arguments as an object
+   * @throws IllegalArgumentException if parsing fails
+   * @since 1.7.0
+   */
+  @Nonnull
+  public <T> T getArgumentsAsObject(@Nonnull final OpenAiTool<T> tool)
+      throws IllegalArgumentException {
+
+    return parseArguments(
+        new TypeReference<>() {
+          @Override
+          public Type getType() {
+            return tool.getRequestClass();
+          }
+        });
+  }
+
+  @Nonnull
+  private <T> T parseArguments(@Nonnull final TypeReference<T> typeReference)
+      throws IllegalArgumentException {
+    try {
+      return getOpenAiObjectMapper().readValue(getArguments(), typeReference);
+    } catch (JsonProcessingException e) {
+      throw new IllegalArgumentException(
+          "Failed to parse JSON string to class " + typeReference.getType(), e);
+    }
+  }
 }

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

@@ -0,0 +1,93 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import static com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool.TypeEnum.FUNCTION;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.JsonMappingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.module.jsonSchema.JsonSchema;
+import com.fasterxml.jackson.module.jsonSchema.JsonSchemaGenerator;
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool;
+import com.sap.ai.sdk.foundationmodels.openai.generated.model.FunctionObject;
+import java.util.Map;
+import java.util.function.Function;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.Getter;
+import lombok.experimental.Accessors;
+
+/**
+ * Represents an OpenAI function tool that can be used to define a function call in an OpenAI Chat
+ * Completion request. This tool generates a JSON schema based on the provided class representing
+ * the function's request structure.
+ *
+ * @param <I> the type of the input argument for the function
+ * @see <a href="https://platform.openai.com/docs/guides/gpt/function-calling"/>OpenAI Function
+ * @since 1.7.0
+ */
+@Beta
+@Data
+@Getter(AccessLevel.PACKAGE)
+@Accessors(chain = true)
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class OpenAiTool<I> {
+
+  /** The name of the function. */
+  private @Nonnull String name;
+
+  /** The model class for function request. */
+  private @Nonnull Class<I> requestClass;
+
+  /** An optional description of the function. */
+  private @Nullable String description;
+
+  /** An optional flag indicating whether the function parameters should be treated strictly. */
+  private @Nullable Boolean strict;
+
+  /** The function to be called. */
+  private @Nullable Function<I, ?> function;
+
+  /**
+   * Constructs an {@code OpenAiFunctionTool} with the specified name and a model class that
+   * captures the request to the function.
+   *
+   * @param name the name of the function
+   * @param requestClass the model class for function request
+   */
+  public OpenAiTool(@Nonnull final String name, @Nonnull final Class<I> requestClass) {
+    this(name, requestClass, null, null, null);
+  }
+
+  @Nonnull
+  Object execute(@Nonnull final I argument) {
+    if (getFunction() == null) {
+      throw new IllegalStateException("Function must not be set to execute the tool.");
+    }
+    return getFunction().apply(argument);
+  }
+
+  ChatCompletionTool createChatCompletionTool() {
+    final var objectMapper = new ObjectMapper();
+    JsonSchema schema = null;
+    try {
+      schema = new JsonSchemaGenerator(objectMapper).generateSchema(getRequestClass());
+    } catch (JsonMappingException e) {
+      throw new IllegalArgumentException("Could not generate schema for " + getRequestClass(), e);
+    }
+
+    final var schemaMap =
+        objectMapper.convertValue(schema, new TypeReference<Map<String, Object>>() {});
+
+    final var function =
+        new FunctionObject()
+            .name(getName())
+            .description(getDescription())
+            .parameters(schemaMap)
+            .strict(getStrict());
+    return new ChatCompletionTool().type(FUNCTION).function(function);
+  }
+}

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

@@ -0,0 +1,68 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import static lombok.AccessLevel.PRIVATE;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.common.annotations.Beta;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.annotation.Nonnull;
+import lombok.AllArgsConstructor;
+
+/**
+ * A class for OpenAI tool execution.
+ *
+ * @since 1.7.0
+ */
+@Beta
+@AllArgsConstructor(access = PRIVATE)
+public class OpenAiToolExecutor {
+
+  private static final ObjectMapper JACKSON = new ObjectMapper();
+
+  /**
+   * Executes the given tool calls with the provided tools and returns the results as a list of
+   * {@link OpenAiToolMessage} containing execution results encoded as JSON string.
+   *
+   * @param tools the list of tools to execute
+   * @param toolCalls the list of tool calls with arguments
+   * @return the list of tool messages with the results
+   * @throws IllegalArgumentException if the tool results cannot be serialized to JSON
+   */
+  @Nonnull
+  public static List<OpenAiToolMessage> executeTools(
+      @Nonnull final List<OpenAiTool<?>> tools, @Nonnull final List<OpenAiToolCall> toolCalls)
+      throws IllegalArgumentException {
+
+    final var toolMap = tools.stream().collect(Collectors.toMap(OpenAiTool::getName, tool -> tool));
+
+    return toolCalls.stream()
+        .filter(OpenAiFunctionCall.class::isInstance)
+        .map(OpenAiFunctionCall.class::cast)
+        .filter(functionCall -> toolMap.containsKey(functionCall.getName()))
+        .map(
+            functionCall -> {
+              final var tool = toolMap.get(functionCall.getName());
+              final var result = executeFunction(tool, functionCall);
+              return OpenAiMessage.tool(serializeObject(result), functionCall.getId());
+            })
+        .toList();
+  }
+
+  @Nonnull
+  private static <I> Object executeFunction(
+      @Nonnull final OpenAiTool<I> tool, @Nonnull final OpenAiFunctionCall toolCall) {
+    final I arguments = toolCall.getArgumentsAsObject(tool);
+    return tool.execute(arguments);
+  }
+
+  @Nonnull
+  private static String serializeObject(@Nonnull final Object obj) throws IllegalArgumentException {
+    try {
+      return JACKSON.writeValueAsString(obj);
+    } catch (JsonProcessingException e) {
+      throw new IllegalArgumentException("Failed to serialize object to JSON", e);
+    }
+  }
+}

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

@@ -4,11 +4,13 @@
 
 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.ChatCompletionTool;
 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 java.util.Map;
 import org.junit.jupiter.api.Test;
 
 class OpenAiChatCompletionRequestTest {
@@ -114,4 +116,41 @@ void messageListExternallyUnmodifiable() {
         .as("Modifying the original list should not affect the messages in the request object.")
         .hasSize(1);
   }
+
+  @Test
+  void withOpenAiTools() {
+    record DummyRequest(String param1, int param2) {}
+
+    var request =
+        new OpenAiChatCompletionRequest(OpenAiMessage.user("Hello, world"))
+            .withOpenAiTools(
+                List.of(
+                    new OpenAiTool<>("toolA", DummyRequest.class)
+                        .setDescription("descA")
+                        .setStrict(true),
+                    new OpenAiTool<>("toolB", DummyRequest.class)
+                        .setDescription("descB")
+                        .setStrict(false)));
+
+    var lowLevelRequest = request.createCreateChatCompletionRequest();
+    assertThat(lowLevelRequest.getTools()).hasSize(2);
+
+    var toolA = lowLevelRequest.getTools().get(0);
+    assertThat(toolA).isInstanceOf(ChatCompletionTool.class);
+    assertThat(toolA.getType()).isEqualTo(ChatCompletionTool.TypeEnum.FUNCTION);
+    assertThat(toolA.getFunction().getName()).isEqualTo("toolA");
+    assertThat(toolA.getFunction().getDescription()).isEqualTo("descA");
+    assertThat(toolA.getFunction().isStrict()).isTrue();
+
+    assertThat(toolA.getFunction().getParameters())
+        .isEqualTo(
+            Map.of(
+                "id",
+                    "urn:jsonschema:com:sap:ai:sdk:foundationmodels:openai:OpenAiChatCompletionRequestTest:1DummyRequest",
+                "properties",
+                    Map.of(
+                        "param1", Map.of("type", "string"),
+                        "param2", Map.of("type", "integer")),
+                "type", "object"));
+  }
 }