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

- OpenAiFunctionTool getter package private
- introduce getArgumentsAsObject(OpenAiFunctionTool)

Author: rpanackal

docs/release_notes.md

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

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

@@ -3,7 +3,9 @@
 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;
@@ -36,25 +38,40 @@ public class OpenAiFunctionCall implements OpenAiToolCall {
    */
   @Nonnull
   public Map<String, Object> getArgumentsAsMap() throws IllegalArgumentException {
-    return getArgumentsAsObject(Map.class);
+    return parseArguments(new TypeReference<>() {});
   }
 
   /**
-   * Parses the arguments, encoded as a JSON string, into an object of the specified type.
+   * Parses the arguments, encoded as a JSON string, into an object of type expected by a function
+   * tool.
    *
-   * @param clazz the class to convert the arguments to
+   * @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 Class<T> clazz) throws IllegalArgumentException {
+  public <T> T getArgumentsAsObject(@Nonnull final OpenAiFunctionTool tool)
+      throws IllegalArgumentException {
+    final var typeRef =
+        new TypeReference<T>() {
+          @Override
+          public Type getType() {
+            return tool.getRequestModel();
+          }
+        };
+    return parseArguments(typeRef);
+  }
+
+  @Nonnull
+  private <T> T parseArguments(@Nonnull final TypeReference<T> typeReference)
+      throws IllegalArgumentException {
     try {
-      return getOpenAiObjectMapper().readValue(getArguments(), clazz);
+      return getOpenAiObjectMapper().readValue(getArguments(), typeReference);
     } catch (JsonProcessingException e) {
       throw new IllegalArgumentException(
-          "Failed to parse JSON string to class " + clazz.getTypeName(), e);
+          "Failed to parse JSON string to class " + typeReference.getType(), e);
     }
   }
 }

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

@@ -15,6 +15,7 @@
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
 import lombok.AllArgsConstructor;
+import lombok.Getter;
 import lombok.Value;
 import lombok.With;
 
@@ -29,14 +30,15 @@
 @Beta
 @Value
 @With
+@Getter(AccessLevel.PACKAGE)
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
 public class OpenAiFunctionTool implements OpenAiTool {
 
   /** The name of the function. */
   @Nonnull String name;
 
   /** The model class for function request. */
-  @Nonnull Class<?> clazz;
+  @Nonnull Class<?> requestModel;
 
   /** An optional description of the function. */
   @Nullable String description;
@@ -45,22 +47,24 @@ public class OpenAiFunctionTool implements OpenAiTool {
   @Nullable Boolean strict;
 
   /**
-   * Constructs an {@code OpenAiFunctionTool} with the specified name and request class.
+   * 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 clazz the model class for the function request
+   * @param requestModel the model class for the function request
    */
-  public <T> OpenAiFunctionTool(@Nonnull final String name, @Nonnull final Class<T> clazz) {
-    this(name, clazz, null, null);
+  public <T> OpenAiFunctionTool(@Nonnull final String name, @Nonnull final Class<T> requestModel) {
+    this(name, requestModel, null, null);
   }
 
   ChatCompletionTool createChatCompletionTool() {
     final var objectMapper = new ObjectMapper();
     JsonSchema schema = null;
     try {
-      schema = new JsonSchemaGenerator(objectMapper).generateSchema(clazz);
+      schema = new JsonSchemaGenerator(objectMapper).generateSchema(requestModel);
     } catch (JsonMappingException e) {
-      throw new IllegalArgumentException("Could not generate schema for " + clazz.getTypeName(), e);
+      throw new IllegalArgumentException(
+          "Could not generate schema for " + requestModel.getTypeName(), e);
     }
 
     schema.setId(null);

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

@@ -11,6 +11,9 @@ class OpenAiToolCallTest {
   private static final OpenAiFunctionCall INVALID_FUNCTION_CALL =
       new OpenAiFunctionCall("1", "functionName", "{invalid-json}");
 
+  private static final OpenAiFunctionTool FUNCTION_TOOL =
+      new OpenAiFunctionTool("functionName", DummyRequest.class);
+
   record DummyRequest(String key) {}
 
   @Test
@@ -28,21 +31,14 @@ void getArgumentsAsMapThrowsOnInvalidJson() {
 
   @Test
   void getArgumentsAsObjectParsesValidJson() {
-    var result = VALID_FUNCTION_CALL.getArgumentsAsObject(DummyRequest.class);
+    var result = (DummyRequest) VALID_FUNCTION_CALL.getArgumentsAsObject(FUNCTION_TOOL);
     assertThat(result).isInstanceOf(DummyRequest.class);
     assertThat(result.key()).isEqualTo("value");
   }
 
   @Test
   void getArgumentsAsObjectThrowsOnInvalidJson() {
-    assertThatThrownBy(() -> INVALID_FUNCTION_CALL.getArgumentsAsObject(DummyRequest.class))
-        .isInstanceOf(IllegalArgumentException.class)
-        .hasMessageContaining("Failed to parse JSON string");
-  }
-
-  @Test
-  void getArgumentsAsObjectThrowsOnTypeMismatch() {
-    assertThatThrownBy(() -> VALID_FUNCTION_CALL.getArgumentsAsObject(Integer.class))
+    assertThatThrownBy(() -> INVALID_FUNCTION_CALL.getArgumentsAsObject(FUNCTION_TOOL))
         .isInstanceOf(IllegalArgumentException.class)
         .hasMessageContaining("Failed to parse JSON string");
   }

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

@@ -4,7 +4,6 @@
 import static com.sap.ai.sdk.foundationmodels.openai.OpenAiModel.GPT_4O_MINI;
 import static com.sap.ai.sdk.foundationmodels.openai.OpenAiModel.TEXT_EMBEDDING_3_SMALL;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.sap.ai.sdk.core.AiCoreService;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiAssistantMessage;
 import com.sap.ai.sdk.foundationmodels.openai.OpenAiChatCompletionDelta;
@@ -29,8 +28,6 @@
 @Service
 @Slf4j
 public class OpenAiServiceV2 {
-  private static final ObjectMapper JACKSON = new ObjectMapper();
-
   /**
    * Chat request to OpenAI
    *
@@ -95,39 +92,33 @@ public OpenAiChatCompletionResponse chatCompletionImage(@Nonnull final String li
   @Nonnull
   public OpenAiChatCompletionResponse chatCompletionToolExecution(
       @Nonnull final String location, @Nonnull final String unit) {
+    final var messages = new ArrayList<OpenAiMessage>();
+    messages.add(OpenAiMessage.user("What's the weather in %s in %s?".formatted(location, unit)));
 
     // 1. Define the function
-    final var openAiTool =
+    final var weatherFunction =
         new OpenAiFunctionTool("weather", WeatherMethod.Request.class)
             .withDescription("Get the weather for the given location");
 
-    final var messages = new ArrayList<OpenAiMessage>();
-    messages.add(OpenAiMessage.user("What's the weather in %s in %s?".formatted(location, unit)));
-
-    // Assistant will call the function
+    // 2. Assistant calls the function
     final var request =
-        new OpenAiChatCompletionRequest(messages).withOpenAiTools(List.of(openAiTool));
-
+        new OpenAiChatCompletionRequest(messages).withOpenAiTools(List.of(weatherFunction));
     final OpenAiChatCompletionResponse response =
         OpenAiClient.forModel(GPT_4O_MINI).chatCompletion(request);
-
-    // 2. Optionally, execute the function.
     final OpenAiAssistantMessage assistantMessage = response.getMessage();
-    messages.add(assistantMessage);
 
+    // 3. Execute the function
     final OpenAiToolCall toolCall = assistantMessage.toolCalls().get(0);
     if (!(toolCall instanceof OpenAiFunctionCall functionCall)) {
       throw new IllegalArgumentException(
           "Expected a function call, but got: %s".formatted(assistantMessage));
     }
+    final WeatherMethod.Request arguments = functionCall.getArgumentsAsObject(weatherFunction);
+    final WeatherMethod.Response currentWeather = WeatherMethod.getCurrentWeather(arguments);
 
-    final WeatherMethod.Request arguments =
-        functionCall.getArgumentsAsObject(WeatherMethod.Request.class);
-    final WeatherMethod.Response weatherMethod = WeatherMethod.getCurrentWeather(arguments);
-
-    messages.add(OpenAiMessage.tool(weatherMethod.toString(), functionCall.getId()));
-
-    // Send back the results, and the model will incorporate them into its final response.
+    // 4. Send back the results, and the model will incorporate them into its final response.
+    messages.add(assistantMessage);
+    messages.add(OpenAiMessage.tool(currentWeather.toString(), functionCall.getId()));
     return OpenAiClient.forModel(GPT_4O_MINI).chatCompletion(request.withMessages(messages));
   }