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,14 @@
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-annotations</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.github.victools</groupId>
+      <artifactId>jsonschema-generator</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.github.victools</groupId>
+      <artifactId>jsonschema-module-jackson</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,20 @@ 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
+  @Beta
+  public OpenAiChatCompletionRequest withToolsExecutable(@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,10 @@
 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.google.common.annotations.Beta;
+import java.util.Map;
 import javax.annotation.Nonnull;
 import lombok.AllArgsConstructor;
 import lombok.Value;
@@ -22,4 +26,35 @@ 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 getArgumentsAsObject(Map.class);
+  }
+
+  /**
+   * Parses the arguments, encoded as a JSON string, into an object of type expected by a function
+   * tool.
+   *
+   * @param type the class reference for requested type.
+   * @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 Class<T> type) throws IllegalArgumentException {
+    try {
+      return getOpenAiObjectMapper().readValue(getArguments(), type);
+    } catch (JsonProcessingException e) {
+      throw new IllegalArgumentException("Failed to parse JSON string to class " + type, e);
+    }
+  }
 }

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

@@ -0,0 +1,192 @@
+package com.sap.ai.sdk.foundationmodels.openai;
+
+import static com.sap.ai.sdk.foundationmodels.openai.generated.model.ChatCompletionTool.TypeEnum.FUNCTION;
+import static java.util.function.UnaryOperator.identity;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.github.victools.jsonschema.generator.Option;
+import com.github.victools.jsonschema.generator.OptionPreset;
+import com.github.victools.jsonschema.generator.SchemaGenerator;
+import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
+import com.github.victools.jsonschema.generator.SchemaVersion;
+import com.github.victools.jsonschema.module.jackson.JacksonModule;
+import com.github.victools.jsonschema.module.jackson.JacksonOption;
+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.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.experimental.Accessors;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Represents an OpenAI 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 <InputT> 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
+ */
+@Slf4j
+@Beta
+@Data
+@Getter(AccessLevel.PACKAGE)
+@Accessors(chain = true)
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class OpenAiTool<InputT> {
+
+  private static final ObjectMapper JACKSON = new ObjectMapper();
+
+  /** The schema generator used to create JSON schemas. */
+  @Nonnull private static final SchemaGenerator GENERATOR = createSchemaGenerator();
+
+  /** The name of the function. */
+  @Nonnull private String name;
+
+  /** The model class for function request. */
+  @Nonnull private Class<InputT> requestClass;
+
+  /** An optional description of the function. */
+  @Nullable private String description;
+
+  /** An optional flag indicating whether the function parameters should be treated strictly. */
+  @Nullable private Boolean strict;
+
+  /** The function to be called. */
+  @Nullable private Function<InputT, ?> 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<InputT> requestClass) {
+    this(name, requestClass, null, null, null);
+  }
+
+  @Nonnull
+  Object execute(@Nonnull final InputT argument) {
+    if (getFunction() == null) {
+      throw new IllegalStateException(
+          "Tool " + name + " is missing a method reference to execute.");
+    }
+    return getFunction().apply(argument);
+  }
+
+  ChatCompletionTool createChatCompletionTool() {
+    final var schema = GENERATOR.generateSchema(getRequestClass());
+    final var schemaMap =
+        OpenAiUtils.getOpenAiObjectMapper()
+            .convertValue(schema, new TypeReference<Map<String, Object>>() {});
+
+    return new ChatCompletionTool()
+        .type(FUNCTION)
+        .function(
+            new FunctionObject()
+                .name(getName())
+                .description(getDescription())
+                .parameters(schemaMap)
+                .strict(getStrict()));
+  }
+
+  private static SchemaGenerator createSchemaGenerator() {
+    final var module =
+        new JacksonModule(
+            JacksonOption.RESPECT_JSONPROPERTY_REQUIRED, JacksonOption.RESPECT_JSONPROPERTY_ORDER);
+    return new SchemaGenerator(
+        new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON)
+            .without(Option.SCHEMA_VERSION_INDICATOR)
+            .with(module)
+            .build());
+  }
+
+  /**
+   * 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 msg the assistant message containing a list of tool calls with arguments
+   * @return a result object that contains the list of tool messages with the results
+   * @throws IllegalStateException if a tool is missing a method reference for function execution.
+   */
+  @Beta
+  @Nonnull
+  public static Execution execute(
+      @Nonnull final List<OpenAiTool<?>> tools, @Nonnull final OpenAiAssistantMessage msg)
+      throws IllegalArgumentException {
+    final var result = new LinkedHashMap<OpenAiFunctionCall, Object>();
+
+    final var toolMap = tools.stream().collect(Collectors.toMap(OpenAiTool::getName, identity()));
+    for (final OpenAiToolCall toolCall : msg.toolCalls()) {
+      if (toolCall instanceof OpenAiFunctionCall functionCall) {
+        final var tool = toolMap.get(functionCall.getName());
+        if (tool == null) {
+          log.warn("Tool not found for function call: {}", functionCall.getName());
+          continue;
+        }
+        final var toolResult = executeFunction(tool, functionCall);
+        result.put(functionCall, toolResult);
+      }
+    }
+    return new Execution(result);
+  }
+
+  @Nonnull
+  private static <I> Object executeFunction(
+      @Nonnull final OpenAiTool<I> tool, @Nonnull final OpenAiFunctionCall toolCall) {
+    final I arguments = toolCall.getArgumentsAsObject(tool.getRequestClass());
+    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);
+    }
+  }
+
+  /**
+   * Represents the result of executing a tool call, containing the results of the function calls.
+   */
+  @RequiredArgsConstructor
+  @Beta
+  public static class Execution {
+    @Getter @Beta @Nonnull private final Map<OpenAiFunctionCall, Object> results;
+
+    /**
+     * Creates a new list of serialized OpenAI tool messages.
+     *
+     * @return the list of serialized OpenAI tool messages.
+     * @throws IllegalArgumentException if the tool results cannot be serialized to JSON
+     */
+    @Beta
+    @Nonnull
+    public List<OpenAiToolMessage> getMessages() {
+      final var result = new ArrayList<OpenAiToolMessage>();
+      for (final var entry : getResults().entrySet()) {
+        final var functionCall = entry.getKey().getId();
+        final var serializedValue = serializeObject(entry.getValue());
+        result.add(OpenAiMessage.tool(serializedValue, functionCall));
+      }
+      return result;
+    }
+  }
+}

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,40 @@ 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"))
+            .withToolsExecutable(
+                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(
+                "properties",
+                Map.of(
+                    "param1", Map.of("type", "string"),
+                    "param2", Map.of("type", "integer")),
+                "type",
+                "object"));
+  }
 }