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

* feat: add methods to convert function call arguments to Map and specified object type

* feat: introduce OpenAiFunctionTool and enhance OpenAiChatCompletionRequest with tool handling

* docs: enhance OpenAiFunctionTool and related classes documentation

* docs: add @SInCE 1.7.0 annotations to relevant methods for version tracking

* ci

* fix unintentional javadoc change

* test: update Javadoc to include exception details and enhance test coverage for OpenAiFunctionCall and OpenAiFunctionTool

* refactor: enhance JSON parsing methods in OpenAiFunctionCall and remove redundant methods from OpenAiUtils

* refactor: simplify JSON parsing in OpenAiFunctionCall and add unit tests for argument methods

* refactor: update OpenAiFunctionTool to improve argument parsing and enhance type safety

- OpenAiFunctionTool getter package private
- introduce getArgumentsAsObject(OpenAiFunctionTool)

* part done

* finito

* Formatting

* With purely generics

* With purely explicit types

* refactor: enhance response serialization and improve schema generation error handling

* Introduce OpenAiToolExecutor

* CI

* test: OpenAiToolExecutor and improve error messages

* docs: update release notes to include tool execution in OpenAI functionality

* fix: use the same schema generation dependency as in orchestration module

* refactor: rename generic type parameter from I to InputT in OpenAiTool

* fix shadowing problem

* Change `withOpenAiTools` to `withToolsExecutable`; Change `OpenAiToolExecutor.executeTools` to `OpenAiTool.execute`; Change mandatory argument value `assistantMessage.toolCalls()` to `assistantMessage`; Add intermediate API to optionally extract original execution result objects to `getMessages()` convenience method

* Update sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OpenAiServiceV2.java

Co-authored-by: Jonas-Isr <[email protected]>

* Remove generic type argument from OpenAiTool class; Migrate error-prone constructor to builder pattern that enforces required values

* Remove unnecessary throws declaration

* Reverted the intermediate result class; `OpenAiTool#execute` will directly return the tool message list

* Remove unused code

* Add convenience method OpenAiChatCompletionResponse#executeTools

* Formatting

* Hide getter

* Fix PMD

* Fix tests

* Make inaccessible method private

* Reduce visibility of OpenAiTool#execute

---------

Co-authored-by: Roshin Rajan Panackal <[email protected]>
Co-authored-by: I538344 <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: Jonas-Isr <[email protected]>
Co-authored-by: Alexander Dümont <[email protected]>

Author: 6 people

docs/release_notes.md

@@ -12,6 +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)
 - [Orchestration] Added new model DeepSeek-R1: `OrchestrationAiModel.DEEPSEEK_R1`
 - [Orchestration] [Tool execution fully enabled](https://sap.github.io/ai-sdk/docs/java/spring-ai/orchestration#tool-calling)
 

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

@@ -9,6 +9,7 @@
 import com.sap.ai.sdk.foundationmodels.openai.generated.model.CreateChatCompletionRequestAllOfResponseFormat;
 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 java.util.Objects;
@@ -125,6 +126,15 @@ public class OpenAiChatCompletionRequest {
   /** List of tools that the model may invoke during the completion. */
   @Nullable List<ChatCompletionTool> tools;
 
+  /**
+   * List of tools that are executable at runtime of the application.
+   *
+   * @since 1.7.0
+   */
+  @Getter(value = AccessLevel.PACKAGE)
+  @Nullable
+  List<OpenAiTool> toolsExecutable;
+
   /** Option to control which tool is invoked by the model. */
   @With(AccessLevel.PRIVATE)
   @Nullable
@@ -179,6 +189,7 @@ public OpenAiChatCompletionRequest(@Nonnull final List<OpenAiMessage> messages)
         null,
         null,
         null,
+        null,
         null);
   }
 
@@ -226,6 +237,7 @@ public OpenAiChatCompletionRequest withParallelToolCalls(
             this.streamOptions,
             this.responseFormat,
             this.tools,
+            this.toolsExecutable,
             this.toolChoice);
   }
 
@@ -258,6 +270,7 @@ public OpenAiChatCompletionRequest withLogprobs(@Nonnull final Boolean logprobs)
             this.streamOptions,
             this.responseFormat,
             this.tools,
+            this.toolsExecutable,
             this.toolChoice);
   }
 
@@ -312,10 +325,24 @@ CreateChatCompletionRequest createCreateChatCompletionRequest() {
     request.seed(this.seed);
     request.streamOptions(this.streamOptions);
     request.responseFormat(this.responseFormat);
-    request.tools(this.tools);
+    request.tools(getChatCompletionTools());
     request.toolChoice(this.toolChoice);
     request.functionCall(null);
     request.functions(null);
     return request;
   }
+
+  @Nullable
+  private List<ChatCompletionTool> getChatCompletionTools() {
+    final var toolsCombined = new ArrayList<ChatCompletionTool>();
+    if (this.tools != null) {
+      toolsCombined.addAll(this.tools);
+    }
+    if (this.toolsExecutable != null) {
+      for (final OpenAiTool tool : this.toolsExecutable) {
+        toolsCombined.add(tool.createChatCompletionTool());
+      }
+    }
+    return toolsCombined.isEmpty() ? null : toolsCombined;
+  }
 }

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

@@ -11,6 +11,7 @@
 import java.util.List;
 import java.util.Objects;
 import javax.annotation.Nonnull;
+import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import lombok.Setter;
 import lombok.Value;
@@ -26,7 +27,12 @@
 @Setter(value = NONE)
 public class OpenAiChatCompletionResponse {
   /** The original response from the OpenAI API. */
-  @Nonnull final CreateChatCompletionResponse originalResponse;
+  @Nonnull CreateChatCompletionResponse originalResponse;
+
+  /** The original request that was sent to the OpenAI API. */
+  @Getter(NONE)
+  @Nonnull
+  OpenAiChatCompletionRequest originalRequest;
 
   /**
    * Gets the token usage from the original response.
@@ -96,4 +102,16 @@ public OpenAiAssistantMessage getMessage() {
 
     return new OpenAiAssistantMessage(new OpenAiMessageContent(contentItems), openAiToolCalls);
   }
+
+  /**
+   * Execute tool calls that were suggested by the assistant response.
+   *
+   * @return the list of tool messages that were serialized for the computed results. Empty list if
+   *     no tools were called.
+   */
+  @Nonnull
+  public List<OpenAiToolMessage> executeTools() {
+    final var tools = originalRequest.getToolsExecutable();
+    return OpenAiTool.execute(tools != null ? tools : List.of(), getMessage());
+  }
 }

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

@@ -158,8 +158,8 @@ public OpenAiChatCompletionOutput chatCompletion(@Nonnull final String prompt)
   public OpenAiChatCompletionResponse chatCompletion(
       @Nonnull final OpenAiChatCompletionRequest request) throws OpenAiClientException {
     warnIfUnsupportedUsage();
-    return new OpenAiChatCompletionResponse(
-        chatCompletion(request.createCreateChatCompletionRequest()));
+    final var response = chatCompletion(request.createCreateChatCompletionRequest());
+    return new OpenAiChatCompletionResponse(response, request);
   }
 
   /**

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

@@ -0,0 +1,224 @@
+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.fasterxml.jackson.databind.node.ObjectNode;
+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.Getter;
+import lombok.Setter;
+import lombok.Value;
+import lombok.With;
+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.
+ *
+ * @see <a href="https://platform.openai.com/docs/guides/gpt/function-calling"/>OpenAI Function
+ * @since 1.7.0
+ */
+@Slf4j
+@Beta
+@Value
+@With
+@Getter(AccessLevel.PACKAGE)
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+public class OpenAiTool {
+
+  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. */
+  @Setter(AccessLevel.NONE)
+  @Nonnull
+  String name;
+
+  /** The function to execute a string argument to tool result object. */
+  @Setter(AccessLevel.NONE)
+  @Nonnull
+  Function<String, Object> functionExecutor;
+
+  /** schema to be used for the function call. */
+  @Setter(AccessLevel.NONE)
+  @Nonnull
+  ObjectNode schema;
+
+  /** An optional description of the function. */
+  @Nullable String description;
+
+  /** An optional flag indicating whether the function parameters should be treated strictly. */
+  @Nullable Boolean strict;
+
+  /**
+   * Instantiates a OpenAiTool builder instance on behalf of an executable function.
+   *
+   * @param function the function to be executed.
+   * @return an OpenAiTool builder instance.
+   * @param <InputT> the type of the function input-argument class.
+   */
+  @Nonnull
+  public static <InputT> Builder1<InputT> forFunction(@Nonnull final Function<InputT, ?> function) {
+    return inputClass ->
+        name -> {
+          final Function<String, Object> exec =
+              s -> function.apply(deserializeArgument(inputClass, s));
+          final var schema = GENERATOR.generateSchema(inputClass);
+          return new OpenAiTool(name, exec, schema, null, null);
+        };
+  }
+
+  /**
+   * Creates a new OpenAiTool instance with the specified function and input class.
+   *
+   * @param <InputT> the type of the input class.
+   */
+  public interface Builder1<InputT> {
+    /**
+     * Sets the name of the function.
+     *
+     * @param inputClass the class of the input object.
+     * @return a new OpenAiTool instance with the specified function and input class.
+     */
+    @Nonnull
+    Builder2 withArgument(@Nonnull final Class<InputT> inputClass);
+  }
+
+  /** Creates a new OpenAiTool instance with the specified name. */
+  public interface Builder2 {
+    /**
+     * Sets the name of the function.
+     *
+     * @param name the name of the function
+     * @return a new OpenAiTool instance with the specified name
+     */
+    @Nonnull
+    OpenAiTool withName(@Nonnull final String name);
+  }
+
+  @Nullable
+  static <T> T deserializeArgument(@Nonnull final Class<T> cl, @Nonnull final String s) {
+    try {
+      return JACKSON.readValue(s, cl);
+    } catch (JsonProcessingException e) {
+      throw new IllegalArgumentException("Failed to parse JSON string to class " + cl, e);
+    }
+  }
+
+  ChatCompletionTool createChatCompletionTool() {
+    final var schemaMap =
+        OpenAiUtils.getOpenAiObjectMapper()
+            .convertValue(getSchema(), 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 The list of tool messages with the results.
+   */
+  @Beta
+  @Nonnull
+  static List<OpenAiToolMessage> execute(
+      @Nonnull final List<OpenAiTool> tools, @Nonnull final OpenAiAssistantMessage msg) {
+    final var toolResults = executeInternal(tools, msg);
+    final var result = new ArrayList<OpenAiToolMessage>();
+    for (final var entry : toolResults.entrySet()) {
+      final var functionCall = entry.getKey().getId();
+      final var serializedValue = serializeObject(entry.getValue());
+      result.add(OpenAiMessage.tool(serializedValue, functionCall));
+    }
+    return result;
+  }
+
+  /**
+   * 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 map that contains the function calls and their respective tool results.
+   */
+  @Nonnull
+  private static Map<OpenAiFunctionCall, Object> executeInternal(
+      @Nonnull final List<OpenAiTool> tools, @Nonnull final OpenAiAssistantMessage msg) {
+    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 result;
+  }
+
+  @Nonnull
+  private static Object executeFunction(
+      @Nonnull final OpenAiTool tool, @Nonnull final OpenAiFunctionCall toolCall) {
+    final Function<String, Object> executor = tool.getFunctionExecutor();
+    final String arguments = toolCall.getArguments();
+    return executor.apply(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);
+    }
+  }
+}