Add OrchestrationConfig class

Author: MatKuhr

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

@@ -1,10 +1,16 @@
 package com.sap.ai.sdk.orchestration;
 
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostRequest;
+import com.sap.ai.sdk.orchestration.client.model.FilteringModuleConfig;
+import com.sap.ai.sdk.orchestration.client.model.LLMModuleConfig;
 import com.sap.ai.sdk.orchestration.client.model.ModuleConfigs;
 import com.sap.ai.sdk.orchestration.client.model.TemplatingModuleConfig;
 import java.util.ArrayList;
+import java.util.List;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+import io.vavr.control.Option;
 import lombok.AccessLevel;
 import lombok.NoArgsConstructor;
 import lombok.val;
@@ -14,31 +20,31 @@
 final class ModuleConfigFactory {
   @Nonnull
   static CompletionPostRequest toCompletionPostRequestDto(
-      @Nonnull final OrchestrationPrompt prompt, @Nonnull final ModuleConfigs config) {
-    // copying is required because we have to merge the prompt into the template config
-    // also, users may modify the object before request execution
-    val configCopy = copyModuleConfigs(config);
-    configCopy.setTemplatingModuleConfig(
-        toTemplateModuleConfigDto(prompt, config.getTemplatingModuleConfig()));
+      @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
+    val template = toTemplateModuleConfigDto(prompt, config.getTemplate());
+    // note that the config is immutable and implicitly copied here
+    // copying is required here, to not alter the original config object, which might be reused for subsequent requests
+    val configCopy = config.withTemplate(template);
 
     return CompletionPostRequest.create()
         .orchestrationConfig(
             com.sap.ai.sdk.orchestration.client.model.OrchestrationConfig.create()
-                .moduleConfigurations(configCopy))
+                .moduleConfigurations(toModuleConfigsDto(configCopy)))
         .inputParams(prompt.getTemplateParameters());
   }
 
   @Nonnull
   static TemplatingModuleConfig toTemplateModuleConfigDto(
-      @Nonnull final OrchestrationPrompt prompt, @Nonnull final TemplatingModuleConfig template) {
+      @Nonnull final OrchestrationPrompt prompt, @Nullable final TemplatingModuleConfig template) {
     /*
      * Currently, we have to merge the prompt into the template configuration.
-     * This works around the limitation that the template config isn't optional.
+     * This works around the limitation that the template config is required.
      * This comes at the risk that the prompt unintentionally contains the templating pattern "{{? .. }}".
      * In this case, the request will fail, since the templating module will try to resolve the parameter.
      * To be fixed with https://github.tools.sap/AI/llm-orchestration/issues/662
      */
-    val messagesWithPrompt = new ArrayList<>(template.getTemplate());
+    val messages = Option.of(template).map(TemplatingModuleConfig::getTemplate).getOrElse(List::of);
+    val messagesWithPrompt = new ArrayList<>(messages);
     messagesWithPrompt.addAll(prompt.getMessages());
     if (messagesWithPrompt.isEmpty()) {
       throw new IllegalStateException(
@@ -47,11 +53,27 @@ static TemplatingModuleConfig toTemplateModuleConfigDto(
     return TemplatingModuleConfig.create().template(messagesWithPrompt);
   }
 
-  static ModuleConfigs copyModuleConfigs(@Nonnull final ModuleConfigs configs) {
-    return ModuleConfigs.create()
-        .llmModuleConfig(configs.getLlmModuleConfig())
-        .templatingModuleConfig(configs.getTemplatingModuleConfig())
-        .maskingModuleConfig(configs.getMaskingModuleConfig())
-        .filteringModuleConfig(configs.getFilteringModuleConfig());
+  @Nonnull
+  static ModuleConfigs toModuleConfigsDto(@Nonnull final OrchestrationModuleConfig config) {
+    val llmConfig =
+        Option.of(config.getLlmConfig()).getOrElseThrow(() -> new IllegalStateException("LLM config is required."));
+
+    //noinspection DataFlowIssue the template is always non-null here
+    val moduleConfig =
+        ModuleConfigs.create()
+            .llmModuleConfig(llmConfig)
+            .templatingModuleConfig(config.getTemplate());
+
+    val maybeInputFilter = Option.of(config.getInputContentFilter());
+    val maybeOutputFilter = Option.of(config.getOutputContentFilter());
+
+    if (maybeInputFilter.isDefined() || maybeOutputFilter.isDefined()) {
+      val filter = FilteringModuleConfig.create();
+      maybeInputFilter.forEach(filter::input);
+      maybeOutputFilter.forEach(filter::output);
+    }
+    Option.of(config.getMaskingConfig()).forEach(moduleConfig::maskingModuleConfig);
+
+    return moduleConfig;
   }
 }

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

@@ -76,23 +76,10 @@ public OrchestrationClient(@Nonnull final AiCoreDeployment deployment) {
    */
   @Nonnull
   public CompletionPostResponse chatCompletion(
-      @Nonnull final OrchestrationPrompt prompt, @Nonnull final ModuleConfigs config)
+      @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config)
       throws OrchestrationClientException {
 
-    val request = toCompletionPostRequestDto(prompt, config);
-    return executeRequest(request);
-  }
-
-  /**
-   * Generate a completion for the given prompt.
-   *
-   * @param request The request to send to orchestration.
-   * @return the completion output
-   * @throws OrchestrationClientException if the request fails
-   */
-  @Nonnull
-  public CompletionPostResponse chatCompletion(@Nonnull final CompletionPostRequest request)
-      throws OrchestrationClientException {
+    val request = toCompletionPostRequest(prompt, config);
     return executeRequest(request);
   }
 
@@ -140,8 +127,8 @@ public CompletionPostResponse executeRequest(@Nonnull final CompletionPostReques
    * @return The low-level request DTO to send to orchestration.
    */
   @Nonnull
-  public static CompletionPostRequest toCompletionPostRequestDto(
-      @Nonnull final OrchestrationPrompt prompt, @Nonnull final ModuleConfigs config) {
+  public static CompletionPostRequest toCompletionPostRequest(
+      @Nonnull final OrchestrationPrompt prompt, @Nonnull final OrchestrationModuleConfig config) {
     return ModuleConfigFactory.toCompletionPostRequestDto(prompt, config);
   }
 

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

@@ -0,0 +1,67 @@
+package com.sap.ai.sdk.orchestration;
+
+import javax.annotation.Nullable;
+
+import com.sap.ai.sdk.orchestration.client.model.InputFilteringConfig;
+import com.sap.ai.sdk.orchestration.client.model.LLMModuleConfig;
+import com.sap.ai.sdk.orchestration.client.model.MaskingModuleConfig;
+import com.sap.ai.sdk.orchestration.client.model.OutputFilteringConfig;
+import com.sap.ai.sdk.orchestration.client.model.TemplatingModuleConfig;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.NoArgsConstructor;
+import lombok.Value;
+import lombok.With;
+
+/**
+ * Represents the configuration for the orchestration service. Allows for configuring the different
+ * modules of the orchestration service via a fluent API.
+ *
+ * <p>The orchestration pipeline combines different modules into a single execution flow where the
+ * output of one module serves as input for the next. The pipeline consists of the following
+ * modules:
+ *
+ * <ul>
+ *   <li>LLM Config (Mandatory)
+ *   <li>Templating (Optional)
+ *   <li>Data Masking (Optional)
+ *   <li>Input Content Filtering (Optional)
+ *   <li>Output Content Filtering (Optional)
+ * </ul>
+ */
+@Value
+@With
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+@NoArgsConstructor(force = true)
+public class OrchestrationModuleConfig {
+  /**
+   * The configured language model settings. This configuration is required when executing requests.
+   */
+  @Nullable
+  LLMModuleConfig llmConfig;
+
+  /**
+   * A template to be populated with input parameters. Upon request execution, this template will be
+   * enhanced with any messages and parameter values from {@link OrchestrationPrompt}.
+   */
+  @Nullable
+  TemplatingModuleConfig template;
+
+  /**
+   * A masking configuration to pseudonymous or anonymize sensitive data in the input.
+   */
+  @Nullable
+  MaskingModuleConfig maskingConfig;
+
+  /**
+   * A content filter to filter the prompt.
+   */
+  @Nullable
+  InputFilteringConfig inputContentFilter;
+
+  /**
+   * A content filter to filter the language model response.
+   */
+  @Nullable
+  OutputFilteringConfig outputContentFilter;
+}

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

@@ -15,12 +15,18 @@
 
 class ModuleConfigFactoryTest {
 
+  @Test
+  void testThrowsOnMissingLlmConfig() {
+    assertThatThrownBy(() -> ModuleConfigFactory.toModuleConfigsDto(new OrchestrationModuleConfig()))
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("A prompt is required");
+  }
+
   @Test
   void testThrowsOnMissingMessages() {
     var prompt = new OrchestrationPrompt(Map.of());
-    var templateConfig = TemplatingModuleConfig.create().template();
 
-    assertThatThrownBy(() -> ModuleConfigFactory.toTemplateModuleConfigDto(prompt, templateConfig))
+    assertThatThrownBy(() -> ModuleConfigFactory.toTemplateModuleConfigDto(prompt, null))
         .isInstanceOf(IllegalStateException.class)
         .hasMessageContaining("A prompt is required");
   }
@@ -59,17 +65,4 @@ void testMergingTemplateConfig() {
 
     assertThat(actual).isEqualTo(expected);
   }
-
-  @Test
-  void testCopy() {
-    var moduleConfigs =
-        ModuleConfigs.create()
-            .llmModuleConfig(mock(LLMModuleConfig.class))
-            .templatingModuleConfig(mock(TemplatingModuleConfig.class))
-            .filteringModuleConfig(mock(FilteringModuleConfig.class))
-            .maskingModuleConfig(mock(MaskingModuleConfig.class));
-    assertThat(ModuleConfigFactory.copyModuleConfigs(moduleConfigs))
-        .isEqualTo(moduleConfigs)
-        .isNotSameAs(moduleConfigs);
-  }
 }

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

@@ -58,7 +58,7 @@
 @WireMockTest
 class OrchestrationUnitTest {
   private OrchestrationClient client;
-  private ModuleConfigs config;
+  private OrchestrationModuleConfig config;
   private final Function<String, InputStream> fileLoader =
       filename -> Objects.requireNonNull(getClass().getClassLoader().getResourceAsStream(filename));
 
@@ -100,10 +100,7 @@ void setup(WireMockRuntimeInfo server) {
             .forDeploymentByScenario("orchestration")
             .withResourceGroup("my-resource-group");
     client = new OrchestrationClient(deployment);
-    config =
-        ModuleConfigs.create()
-            .llmModuleConfig(LLM_CONFIG)
-            .templatingModuleConfig(TemplatingModuleConfig.create().template());
+    config = new OrchestrationModuleConfig().withLlmConfig(LLM_CONFIG);
   }
 
   @Test
@@ -306,7 +303,7 @@ void messagesHistory() throws IOException {
         ChatMessage.create().role("user").content("What is the typical food there?");
 
     final var prompt = new OrchestrationPrompt(message);
-    final var request = OrchestrationClient.toCompletionPostRequestDto(prompt, config);
+    final var request = OrchestrationClient.toCompletionPostRequest(prompt, config);
     request.setMessagesHistory(messagesHistory);
 
     final var result = client.chatCompletion(request);
@@ -382,7 +379,7 @@ void maskingAnonymization() throws IOException {
   void testGenericErrorHandling() {
     stubFor(post(anyUrl()).willReturn(serverError()));
 
-    assertThatThrownBy(() -> client.chatCompletion(mock(CompletionPostRequest.class)))
+    assertThatThrownBy(() -> client.executeRequest(mock(CompletionPostRequest.class)))
         .isInstanceOf(OrchestrationClientException.class)
         .hasMessageContaining("500 Server Error");
   }
@@ -396,7 +393,7 @@ void testOrchestrationErrorParsing() {
                     .withHeader("Content-Type", "application/json")
                     .withBodyFile("errorResponse.json")));
 
-    assertThatThrownBy(() -> client.chatCompletion(mock(CompletionPostRequest.class)))
+    assertThatThrownBy(() -> client.executeRequest(mock(CompletionPostRequest.class)))
         .isInstanceOf(OrchestrationClientException.class)
         .hasMessageContaining("400 Bad Request")
         .hasMessageContaining("'orchestration_config' is a required property");

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

@@ -170,7 +170,7 @@ public CompletionPostResponse filter(@Nonnull @PathVariable("threshold") final S
     final var filter =
         FILTERING_CONFIG.apply(AzureThreshold.fromValue(Integer.parseInt(threshold)));
 
-    final var request = OrchestrationClient.toCompletionPostRequestDto(prompt, config);
+    final var request = OrchestrationClient.toCompletionPostRequest(prompt, config);
     request.getOrchestrationConfig().getModuleConfigurations().setFilteringModuleConfig(filter);
 
     return CLIENT.chatCompletion(request);
@@ -193,7 +193,7 @@ public CompletionPostResponse messagesHistory() {
         ChatMessage.create().role("user").content("What is the typical food there?");
     final var prompt = new OrchestrationPrompt(message);
 
-    final var request = OrchestrationClient.toCompletionPostRequestDto(prompt, config);
+    final var request = OrchestrationClient.toCompletionPostRequest(prompt, config);
     request.setMessagesHistory(messagesHistory);
 
     return CLIENT.chatCompletion(request);
@@ -217,7 +217,7 @@ public CompletionPostResponse maskingAnonymization() {
                     .method(MaskingProviderConfig.MethodEnum.ANONYMIZATION)
                     .entities(ALL_DPI_ENTITIES));
 
-    final var request = OrchestrationClient.toCompletionPostRequestDto(prompt, config);
+    final var request = OrchestrationClient.toCompletionPostRequest(prompt, config);
     request
         .getOrchestrationConfig()
         .getModuleConfigurations()
@@ -245,7 +245,7 @@ public CompletionPostResponse maskingPseudonymization() {
                     .method(MethodEnum.PSEUDONYMIZATION)
                     .entities(ALL_DPI_ENTITIES));
 
-    final var request = OrchestrationClient.toCompletionPostRequestDto(prompt, config);
+    final var request = OrchestrationClient.toCompletionPostRequest(prompt, config);
     request
         .getOrchestrationConfig()
         .getModuleConfigurations()