[Orchestration Convenience] Typed model parameters (#180)

* Initial

* Docs

* Adjust solution

* Update ORCHESTRATION_CHAT_COMPLETION.md

* Adjust solution to (value) type safety.

* Remove unpopular parameters

* Formatting

* Add doc link to JavaDoc

* Update sample code

---------

Co-authored-by: Alexander Dümont <[email protected]>
Co-authored-by: Junjie Tang <[email protected]>
Co-authored-by: SAP Cloud SDK Bot <[email protected]>
Co-authored-by: Matthias Kuhr <[email protected]>

Author: 5 people

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -200,12 +200,10 @@ Change your LLM configuration to add model parameters:
 ```java
 OrchestrationAiModel customGPT4O =
     OrchestrationAiModel.GPT_4O
-        .withParams(
-            Map.of(
-                "max_tokens", 50,
-                "temperature", 0.1,
-                "frequency_penalty", 0,
-                "presence_penalty", 0))
+        .withParam(MAX_TOKENS, 50)
+        .withParam(TEMPERATURE, 0.1)
+        .withParam(FREQUENCY_PENALTY, 0)
+        .withParam(PRESENCE_PENALTY, 0)
         .withVersion("2024-05-13");
 ```
 
@@ -225,4 +223,4 @@ var prompt = new OrchestrationPrompt(Map.of("your-input-parameter", "your-param-
 new OrchestrationClient().executeRequestFromJsonModuleConfig(prompt, configJson);
 ```
 
-While this is not recommended for long term use, it can be useful for creating demos and PoCs.
+While this is not recommended for long term use, it can be useful for creating demos and PoCs.

orchestration/src/main/java/com/sap/ai/sdk/orchestration/OrchestrationAiModel.java

@@ -1,8 +1,10 @@
 package com.sap.ai.sdk.orchestration;
 
 import com.sap.ai.sdk.orchestration.model.LLMModuleConfig;
+import java.util.LinkedHashMap;
 import java.util.Map;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import lombok.AllArgsConstructor;
 import lombok.Value;
 import lombok.With;
@@ -25,6 +27,10 @@ public class OrchestrationAiModel {
    *     "frequency_penalty", 0,
    *     "presence_penalty", 0)
    * }</pre>
+   *
+   * @link <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/harmonized-api">SAP
+   *     AI Core: Orchestration - Harmonized API</a>
    */
   Map<String, Object> params;
 
@@ -114,4 +120,72 @@ public class OrchestrationAiModel {
   LLMModuleConfig createConfig() {
     return LLMModuleConfig.create().modelName(name).modelParams(params).modelVersion(version);
   }
+
+  /**
+   * Additional parameter on this model.
+   *
+   * @param key the parameter key.
+   * @param value the parameter value, nullable.
+   * @return A new model with the additional parameter.
+   * @link <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/harmonized-api">SAP
+   *     AI Core: Orchestration - Harmonized API</a>
+   */
+  @Nonnull
+  public OrchestrationAiModel withParam(@Nonnull final String key, @Nullable final Object value) {
+    final var params = new LinkedHashMap<>(getParams());
+    params.put(key, value);
+    return withParams(params);
+  }
+
+  /**
+   * Additional parameter on this model.
+   *
+   * @param param the parameter key.
+   * @param value the parameter value, nullable.
+   * @param <ValueT> the parameter value type.
+   * @return A new model with the additional parameter.
+   * @link <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/harmonized-api">SAP
+   *     AI Core: Orchestration - Harmonized API</a>
+   */
+  @Nonnull
+  public <ValueT> OrchestrationAiModel withParam(
+      @Nonnull final Parameter<ValueT> param, @Nullable final ValueT value) {
+    return withParam(param.getName(), value);
+  }
+
+  /**
+   * Parameter key for a model.
+   *
+   * @param <ValueT> the parameter value type.
+   */
+  @FunctionalInterface
+  public interface Parameter<ValueT> {
+    /** The maximum number of tokens to generate. */
+    Parameter<Integer> MAX_TOKENS = () -> "max_tokens";
+
+    /** The sampling temperature. */
+    Parameter<Number> TEMPERATURE = () -> "temperature";
+
+    /** The frequency penalty. */
+    Parameter<Number> FREQUENCY_PENALTY = () -> "frequency_penalty";
+
+    /** The presence penalty. */
+    Parameter<Number> PRESENCE_PENALTY = () -> "presence_penalty";
+
+    /** The probability mass to be considered . */
+    Parameter<Number> TOP_P = () -> "top_p";
+
+    /** The number of chat completion choices to generate for each input message. */
+    Parameter<Integer> N = () -> "n";
+
+    /**
+     * The name of the parameter.
+     *
+     * @return the name of the parameter.
+     */
+    @Nonnull
+    String getName();
+  }
 }

orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationModuleConfigTest.java

@@ -2,6 +2,7 @@
 
 import static com.sap.ai.sdk.orchestration.AzureFilterThreshold.ALLOW_SAFE_LOW_MEDIUM;
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.GPT_4O;
+import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.Parameter.MAX_TOKENS;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
@@ -65,6 +66,44 @@ void testDpiMaskingConfig() {
         .hasSize(1);
   }
 
+  @Test
+  void testParams() {
+    // test withParams(Map<String, Object>)
+    {
+      var params = Map.<String, Object>of("foo", "bar", "fizz", "buzz");
+
+      var modelA = GPT_4O.withParams(params);
+      var modelB = modelA.withParams(params);
+      assertThat(modelA).isEqualTo(modelB);
+
+      var modelC = modelA.withParams(Map.of("foo", "bar"));
+      assertThat(modelA).isNotEqualTo(modelC);
+
+      var modelD = modelA.withParams(Map.of("foo", "bazz"));
+      assertThat(modelA).isNotEqualTo(modelD);
+    }
+
+    // test withParam(String, Object)
+    {
+      var modelA = GPT_4O.withParam("foo", "bar");
+      var modelB = modelA.withParam("foo", "bar");
+      assertThat(modelA).isEqualTo(modelB);
+
+      var modelC = modelA.withParam("foo", "bazz");
+      assertThat(modelA).isNotEqualTo(modelC);
+    }
+
+    // test withParam(Parameter, Object)
+    {
+      var modelA = GPT_4O.withParam(MAX_TOKENS, 10);
+      var modelB = modelA.withParam(MAX_TOKENS, 10);
+      assertThat(modelA).isEqualTo(modelB);
+
+      var modelC = modelA.withParam(MAX_TOKENS, 20);
+      assertThat(modelA).isNotEqualTo(modelC);
+    }
+  }
+
   @Test
   void testLLMConfig() {
     Map<String, Object> params = Map.of("foo", "bar");

orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationUnitTest.java

@@ -19,6 +19,7 @@
 import static com.sap.ai.sdk.orchestration.AzureFilterThreshold.ALLOW_SAFE;
 import static com.sap.ai.sdk.orchestration.AzureFilterThreshold.ALLOW_SAFE_LOW_MEDIUM;
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.GPT_35_TURBO_16K;
+import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.Parameter.*;
 import static org.apache.hc.core5.http.HttpStatus.SC_BAD_REQUEST;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -52,12 +53,12 @@
 @WireMockTest
 class OrchestrationUnitTest {
   static final OrchestrationAiModel CUSTOM_GPT_35 =
-      GPT_35_TURBO_16K.withParams(
-          Map.of(
-              "max_tokens", 50,
-              "temperature", 0.1,
-              "frequency_penalty", 0,
-              "presence_penalty", 0));
+      GPT_35_TURBO_16K
+          .withParam(MAX_TOKENS, 50)
+          .withParam(TEMPERATURE, 0.1)
+          .withParam(FREQUENCY_PENALTY, 0)
+          .withParam(PRESENCE_PENALTY, 0);
+
   private final Function<String, InputStream> fileLoader =
       filename -> Objects.requireNonNull(getClass().getClassLoader().getResourceAsStream(filename));
 

sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java

@@ -1,6 +1,7 @@
 package com.sap.ai.sdk.app.controllers;
 
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.GPT_35_TURBO;
+import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.Parameter.TEMPERATURE;
 
 import com.sap.ai.sdk.orchestration.AzureContentFilter;
 import com.sap.ai.sdk.orchestration.AzureFilterThreshold;
@@ -26,8 +27,7 @@
 class OrchestrationController {
   private final OrchestrationClient client = new OrchestrationClient();
   OrchestrationModuleConfig config =
-      new OrchestrationModuleConfig()
-          .withLlmConfig(GPT_35_TURBO.withParams(Map.of("temperature", 0.0)));
+      new OrchestrationModuleConfig().withLlmConfig(GPT_35_TURBO.withParam(TEMPERATURE, 0.0));
 
   /**
    * Chat request to OpenAI through the Orchestration service with a simple prompt.