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

Author: a-d

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

@@ -292,7 +292,7 @@ public OpenAiChatCompletionRequest withToolChoice(@Nonnull final OpenAiToolChoic
    */
   @Nonnull
   @Beta
-  public OpenAiChatCompletionRequest withToolsExecutable(@Nonnull final List<OpenAiTool<?>> tools) {
+  public OpenAiChatCompletionRequest withToolsExecutable(@Nonnull final List<OpenAiTool> tools) {
     return this.withTools(tools.stream().map(OpenAiTool::createChatCompletionTool).toList());
   }
 

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

@@ -6,6 +6,7 @@
 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;
@@ -26,74 +27,114 @@
 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.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.
  *
- * @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
+@Value
+@With
 @Getter(AccessLevel.PACKAGE)
-@Accessors(chain = true)
 @AllArgsConstructor(access = AccessLevel.PRIVATE)
-public class OpenAiTool<InputT> {
+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. */
-  @Nonnull private String name;
+  @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;
 
-  /** The model class for function request. */
-  @Nonnull private Class<InputT> requestClass;
+  /** schema to be used for the function call. */
+  @Setter(AccessLevel.NONE)
+  @Nonnull
+  ObjectNode schema;
 
   /** An optional description of the function. */
-  @Nullable private String description;
+  @Nullable String description;
 
   /** An optional flag indicating whether the function parameters should be treated strictly. */
-  @Nullable private Boolean strict;
+  @Nullable Boolean strict;
 
-  /** The function to be called. */
-  @Nullable private Function<InputT, ?> function;
+  /**
+   * 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);
+        };
+  }
 
   /**
-   * Constructs an {@code OpenAiFunctionTool} with the specified name and a model class that
-   * captures the request to the function.
+   * Creates a new OpenAiTool instance with the specified function and input class.
    *
-   * @param name the name of the function
-   * @param requestClass the model class for function request
+   * @param <InputT> the type of the input class.
    */
-  public OpenAiTool(@Nonnull final String name, @Nonnull final Class<InputT> requestClass) {
-    this(name, requestClass, null, null, null);
+  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);
   }
 
-  @Nonnull
-  Object execute(@Nonnull final InputT argument) {
-    if (getFunction() == null) {
-      throw new IllegalStateException(
-          "Tool " + name + " is missing a method reference to execute.");
+  /** 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
+  private 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);
     }
-    return getFunction().apply(argument);
   }
 
   ChatCompletionTool createChatCompletionTool() {
-    final var schema = GENERATOR.generateSchema(getRequestClass());
     final var schemaMap =
         OpenAiUtils.getOpenAiObjectMapper()
-            .convertValue(schema, new TypeReference<Map<String, Object>>() {});
+            .convertValue(getSchema(), new TypeReference<Map<String, Object>>() {});
 
     return new ChatCompletionTool()
         .type(FUNCTION)
@@ -128,7 +169,7 @@ private static SchemaGenerator createSchemaGenerator() {
   @Beta
   @Nonnull
   public static Execution execute(
-      @Nonnull final List<OpenAiTool<?>> tools, @Nonnull final OpenAiAssistantMessage msg)
+      @Nonnull final List<OpenAiTool> tools, @Nonnull final OpenAiAssistantMessage msg)
       throws IllegalArgumentException {
     final var result = new LinkedHashMap<OpenAiFunctionCall, Object>();
 
@@ -148,10 +189,11 @@ public static Execution execute(
   }
 
   @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);
+  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

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

@@ -125,12 +125,16 @@ record DummyRequest(String param1, int param2) {}
         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)));
+                    OpenAiTool.<DummyRequest>forFunction(r -> "result")
+                        .withArgument(DummyRequest.class)
+                        .withName("toolA")
+                        .withDescription("descA")
+                        .withStrict(true),
+                    OpenAiTool.<DummyRequest>forFunction(r -> "result")
+                        .withArgument(DummyRequest.class)
+                        .withName("toolB")
+                        .withDescription("descB")
+                        .withStrict(true)));
 
     var lowLevelRequest = request.createCreateChatCompletionRequest();
     assertThat(lowLevelRequest.getTools()).hasSize(2);

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

@@ -8,7 +8,6 @@
 import java.util.Map;
 import java.util.function.Function;
 import lombok.EqualsAndHashCode;
-import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
 class OpenAiToolTest {
@@ -31,13 +30,6 @@ record Response(String toolMsg) {}
         request -> new Dummy.Response(request.key());
   }
 
-  private OpenAiTool<Dummy.Request> toolA;
-
-  @BeforeEach
-  void setUp() {
-    toolA = new OpenAiTool<>("functionA", Dummy.Request.class);
-  }
-
   @Test
   void getArgumentsAsMapValid() {
     final var result = FUNCTION_CALL_A.getArgumentsAsMap();
@@ -53,21 +45,24 @@ void getArgumentsAsMapInvalid() {
 
   @Test
   void getArgumentsAsObjectValid() {
-    final Dummy.Request result = FUNCTION_CALL_A.getArgumentsAsObject(toolA.getRequestClass());
+    final Dummy.Request result = FUNCTION_CALL_A.getArgumentsAsObject(Dummy.Request.class);
     assertThat(result).isInstanceOf(Dummy.Request.class);
     assertThat(result.key()).isEqualTo("value");
   }
 
   @Test
   void getArgumentsAsObjectInvalid() {
-    assertThatThrownBy(() -> INVALID_FUNCTION_CALL_A.getArgumentsAsObject(toolA.getRequestClass()))
+    assertThatThrownBy(() -> INVALID_FUNCTION_CALL_A.getArgumentsAsObject(Integer.class))
         .isInstanceOf(IllegalArgumentException.class)
         .hasMessageContaining("Failed to parse JSON string");
   }
 
   @Test
   void executeToolsValid() {
-    toolA.setFunction(Dummy.conCat);
+    final var toolA =
+        OpenAiTool.forFunction(Dummy.conCat)
+            .withArgument(Dummy.Request.class)
+            .withName("functionA");
     final var assistMsg = new OpenAiAssistantMessage(EMPTY_MSG_CONTENT, List.of(FUNCTION_CALL_A));
     final var execution = OpenAiTool.execute(List.of(toolA), assistMsg);
 
@@ -83,19 +78,14 @@ void executeToolsValid() {
         .isEqualTo("{\"toolMsg\":\"value\"}");
   }
 
-  @Test
-  void executeToolsThrowsOnNoFunction() {
-    final var assistMsg = new OpenAiAssistantMessage(EMPTY_MSG_CONTENT, List.of(FUNCTION_CALL_A));
-    assertThatThrownBy(() -> OpenAiTool.execute(List.of(toolA), assistMsg))
-        .isInstanceOf(IllegalStateException.class)
-        .hasMessageContaining("Tool functionA is missing a method reference to execute.");
-  }
-
   @Test
   void executeToolsNoMatchingCall() {
-    final var toolAWithFunction = toolA.setFunction(Dummy.conCat);
+    final var toolA =
+        OpenAiTool.forFunction(Dummy.conCat)
+            .withArgument(Dummy.Request.class)
+            .withName("functionA");
     final var assistMsg = new OpenAiAssistantMessage(EMPTY_MSG_CONTENT, List.of(FUNCTION_CALL_B));
-    final var executions = OpenAiTool.execute(List.of(toolAWithFunction), assistMsg);
+    final var executions = OpenAiTool.execute(List.of(toolA), assistMsg);
     assertThat(executions.getResults()).isEmpty();
     assertThat(executions.getMessages()).isEmpty();
   }
@@ -111,7 +101,10 @@ class NonSerializableResponse {
       }
     }
 
-    toolA.setFunction(request -> new NonSerializableResponse(request.key()));
+    final Function<Dummy.Request, Object> badF =
+        request -> new NonSerializableResponse(request.key());
+    final var toolA =
+        OpenAiTool.forFunction(badF).withArgument(Dummy.Request.class).withName("functionA");
     final var assistMsg = new OpenAiAssistantMessage(EMPTY_MSG_CONTENT, List.of(FUNCTION_CALL_A));
     final var executions = OpenAiTool.execute(List.of(toolA), assistMsg);
 

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

@@ -99,11 +99,12 @@ public OpenAiChatCompletionResponse chatCompletionToolExecution(
     messages.add(OpenAiMessage.user("What's the weather in %s in %s?".formatted(location, unit)));
 
     // 1. Define the function
-    final List<OpenAiTool<?>> tools =
+    final List<OpenAiTool> tools =
         List.of(
-            new OpenAiTool<>("weather", WeatherMethod.Request.class)
-                .setDescription("Get the weather for the given location")
-                .setFunction(WeatherMethod::getCurrentWeather));
+            OpenAiTool.forFunction(WeatherMethod::getCurrentWeather)
+                .withArgument(WeatherMethod.Request.class)
+                .withName("weather")
+                .withDescription("Get the weather for the given location"));
 
     // 2. Assistant calls the function
     final var request = new OpenAiChatCompletionRequest(messages).withToolsExecutable(tools);