Introduce readable thresholds based api

- Multi filter support
- detach per filter logic from generic methods
- add javadoc
- update tests

Author: rpanackal

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -146,17 +146,17 @@ var prompt = new OrchestrationPrompt(
         ```DISCLAIMER: The area surrounding the apartment is known for prostitutes and gang violence including armed conflicts, gun violence is frequent.
         """);
 
-var filterStrict = new AzureContentSafety()
-                .hate(NUMBER_0)
-                .selfHarm(NUMBER_0)
-                .sexual(NUMBER_0)
-    .violence(NUMBER_0);
-
-var filterLoose = new AzureContentSafety()
-                .hate(NUMBER_4)
-                .selfHarm(NUMBER_4)
-                .sexual(NUMBER_4)
-    .violence(NUMBER_4);
+var filterStrict = new AzureContentFilter()
+                .hate(ALLOW_SAFE)
+                .selfHarm(ALLOW_SAFE)
+                .sexual(ALLOW_SAFE)
+    .violence(ALLOW_SAFE);
+
+var filterLoose = new AzureContentFilter()
+                .hate(ALLOW_SAFE_LOW_MEDIUM)
+                .selfHarm(ALLOW_SAFE_LOW_MEDIUM)
+                .sexual(ALLOW_SAFE_LOW_MEDIUM)
+    .violence(ALLOW_SAFE_LOW_MEDIUM);
 
 // changing the input to filterLoose will allow the message to pass
 var configWithFilter = config.withInputFiltering(filterStrict).withOutputFiltering(filterStrict);

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

@@ -0,0 +1,57 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.client.model.AzureContentSafety;
+import com.sap.ai.sdk.orchestration.client.model.AzureContentSafetyFilterConfig;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+/**
+ * A content filter wrapping Azure Content Safety.
+ *
+ * <p>This class allows setting moderation policies for different content categories such as hate,
+ * self-harm, sexual, and violence.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * AzureContentFilter filter = new AzureContentFilter()
+ *     .hate(AzureModerationPolicy.ALLOW_SAFE)
+ *     .selfHarm(AzureModerationPolicy.ALLOW_SAFE_LOW);
+ * }</pre>
+ */
+@Setter
+@NoArgsConstructor
+@Accessors(fluent = true)
+public class AzureContentFilter implements ContentFilter {
+  @Nullable AzureModerationPolicy hate;
+  @Nullable AzureModerationPolicy selfHarm;
+  @Nullable AzureModerationPolicy sexual;
+  @Nullable AzureModerationPolicy violence;
+
+  /**
+   * Converts {@code AzureContentFilter} to its serializable counterpart {@link
+   * AzureContentSafetyFilterConfig}.
+   *
+   * @return the corresponding {@code AzureContentSafetyFilterConfig} object.
+   * @throws IllegalArgumentException if no policies are set.
+   */
+  @Override
+  @Nonnull
+  public AzureContentSafetyFilterConfig toSerializable() {
+    if (hate == null && selfHarm == null && sexual == null && violence == null) {
+      throw new IllegalArgumentException("At least one filter moderation policy must be set");
+    }
+
+    return new AzureContentSafetyFilterConfig()
+        .type(AzureContentSafetyFilterConfig.TypeEnum.AZURE_CONTENT_SAFETY)
+        .config(
+            new AzureContentSafety()
+                .hate(hate != null ? hate.getAzureThreshold() : null)
+                .selfHarm(selfHarm != null ? selfHarm.getAzureThreshold() : null)
+                .sexual(sexual != null ? sexual.getAzureThreshold() : null)
+                .violence(violence != null ? violence.getAzureThreshold() : null));
+  }
+}

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

@@ -0,0 +1,18 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.client.model.AzureThreshold;
+import javax.annotation.Nonnull;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/** An Enum wrapping Azure thresholds with readable names. */
+@Getter
+@AllArgsConstructor
+public enum AzureModerationPolicy {
+  ALLOW_SAFE(AzureThreshold.NUMBER_0),
+  ALLOW_SAFE_LOW(AzureThreshold.NUMBER_2),
+  ALLOW_SAFE_LOW_MEDIUM(AzureThreshold.NUMBER_4),
+  ALLOW_ALL(AzureThreshold.NUMBER_6);
+
+  @Nonnull final AzureThreshold azureThreshold;
+}

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

@@ -0,0 +1,18 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.client.model.FilterConfig;
+
+/**
+ * Interface representing convenience wrappers of serializable content filter that defines
+ * moderation policies for different content categories.
+ */
+public interface ContentFilter {
+
+  /**
+   * A method that produces the serializable equivalent {@link FilterConfig} object from data
+   * encapsulated in the {@link ContentFilter} object.
+   *
+   * @return the corresponding {@code FilterConfig} object.
+   */
+  FilterConfig toSerializable();
+}

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

@@ -1,14 +1,12 @@
 package com.sap.ai.sdk.orchestration;
 
-import com.sap.ai.sdk.orchestration.client.model.AzureContentSafety;
-import com.sap.ai.sdk.orchestration.client.model.AzureContentSafetyFilterConfig;
 import com.sap.ai.sdk.orchestration.client.model.FilteringModuleConfig;
 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 java.util.List;
+import java.util.Arrays;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import lombok.AccessLevel;
@@ -34,36 +32,43 @@
  * </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.
    */
-  @With @Nullable LLMModuleConfig llmConfig;
+  @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}.
    */
-  @With @Nullable TemplatingModuleConfig templateConfig;
+  @Nullable TemplatingModuleConfig templateConfig;
 
   /** A masking configuration to pseudonymous or anonymize sensitive data in the input. */
-  @With @Nullable MaskingModuleConfig maskingConfig;
+  @Nullable MaskingModuleConfig maskingConfig;
 
   /** A content filter to filter the prompt. */
-  @With(AccessLevel.PRIVATE)
-  @Nullable
-  FilteringModuleConfig filteringConfig;
+  @Nullable FilteringModuleConfig filteringConfig;
 
+  /**
+   * Adds input content filters to the orchestration configuration.
+   *
+   * <p>Preferred over {@link #withFilteringConfig(FilteringModuleConfig)} for adding input filters.
+   *
+   * @param contentFilters one or more content filters to apply to the input.
+   * @return a new {@code OrchestrationModuleConfig} instance with the specified input filters
+   *     added.
+   */
   @Nonnull
   public OrchestrationModuleConfig withInputFiltering(
-      @Nonnull final AzureContentSafety contentFilter) {
-    var azureFilter =
-        new AzureContentSafetyFilterConfig()
-            .type(AzureContentSafetyFilterConfig.TypeEnum.AZURE_CONTENT_SAFETY)
-            .config(contentFilter);
-    var inputFilter = new InputFilteringConfig().filters(List.of(azureFilter));
+      @Nonnull final ContentFilter... contentFilters) {
+
+    var filterConfigs = Arrays.stream(contentFilters).map(ContentFilter::toSerializable).toList();
+
+    var inputFilter = new InputFilteringConfig().filters(filterConfigs);
 
     var newFilteringConfig =
         new FilteringModuleConfig()
@@ -73,14 +78,22 @@ public OrchestrationModuleConfig withInputFiltering(
     return this.withFilteringConfig(newFilteringConfig);
   }
 
+  /**
+   * Adds output content filters to the orchestration configuration.
+   *
+   * <p>Preferred over {@link #withFilteringConfig(FilteringModuleConfig)} for adding output
+   * filters.
+   *
+   * @param contentFilters one or more content filters to apply to the output.
+   * @return a new {@code OrchestrationModuleConfig} instance with the specified output filters
+   *     added.
+   */
   @Nonnull
   public OrchestrationModuleConfig withOutputFiltering(
-      @Nonnull final AzureContentSafety contentFilter) {
-    var azureFilter =
-        new AzureContentSafetyFilterConfig()
-            .type(AzureContentSafetyFilterConfig.TypeEnum.AZURE_CONTENT_SAFETY)
-            .config(contentFilter);
-    var outputFilter = new OutputFilteringConfig().filters(List.of(azureFilter));
+      @Nonnull final ContentFilter... contentFilters) {
+
+    var filterConfigs = Arrays.stream(contentFilters).map(ContentFilter::toSerializable).toList();
+    var outputFilter = new OutputFilteringConfig().filters(filterConfigs);
 
     var newFilteringConfig =
         new FilteringModuleConfig()

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

@@ -16,8 +16,8 @@
 import static com.github.tomakehurst.wiremock.client.WireMock.stubFor;
 import static com.github.tomakehurst.wiremock.client.WireMock.urlPathEqualTo;
 import static com.github.tomakehurst.wiremock.client.WireMock.verify;
-import static com.sap.ai.sdk.orchestration.client.model.AzureThreshold.NUMBER_0;
-import static com.sap.ai.sdk.orchestration.client.model.AzureThreshold.NUMBER_4;
+import static com.sap.ai.sdk.orchestration.AzureModerationPolicy.ALLOW_SAFE;
+import static com.sap.ai.sdk.orchestration.AzureModerationPolicy.ALLOW_SAFE_LOW_MEDIUM;
 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;
@@ -28,7 +28,6 @@
 import com.github.tomakehurst.wiremock.junit5.WireMockTest;
 import com.github.tomakehurst.wiremock.stubbing.Scenario;
 import com.sap.ai.sdk.core.AiCoreService;
-import com.sap.ai.sdk.orchestration.client.model.AzureContentSafety;
 import com.sap.ai.sdk.orchestration.client.model.ChatMessage;
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostRequest;
 import com.sap.ai.sdk.orchestration.client.model.DPIConfig;
@@ -213,11 +212,11 @@ void filteringLoose() throws IOException {
                     .withHeader("Content-Type", "application/json")));
 
     final var filter =
-        new AzureContentSafety()
-            .hate(NUMBER_4)
-            .selfHarm(NUMBER_4)
-            .sexual(NUMBER_4)
-            .violence(NUMBER_4);
+        new AzureContentFilter()
+            .hate(ALLOW_SAFE_LOW_MEDIUM)
+            .selfHarm(ALLOW_SAFE_LOW_MEDIUM)
+            .sexual(ALLOW_SAFE_LOW_MEDIUM)
+            .violence(ALLOW_SAFE_LOW_MEDIUM);
 
     client.chatCompletion(prompt, config.withInputFiltering(filter).withOutputFiltering(filter));
     // the result is asserted in the verify step below
@@ -241,11 +240,11 @@ void filteringStrict() {
             .willReturn(jsonResponse(response, SC_BAD_REQUEST)));
 
     final var filter =
-        new AzureContentSafety()
-            .hate(NUMBER_0)
-            .selfHarm(NUMBER_0)
-            .sexual(NUMBER_0)
-            .violence(NUMBER_0);
+        new AzureContentFilter()
+            .hate(ALLOW_SAFE)
+            .selfHarm(ALLOW_SAFE)
+            .sexual(ALLOW_SAFE)
+            .violence(ALLOW_SAFE);
 
     final var configWithFilter = config.withInputFiltering(filter).withOutputFiltering(filter);
 

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

@@ -1,11 +1,11 @@
 package com.sap.ai.sdk.app.controllers;
 
+import com.sap.ai.sdk.orchestration.AzureContentFilter;
+import com.sap.ai.sdk.orchestration.AzureModerationPolicy;
 import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
 import com.sap.ai.sdk.orchestration.OrchestrationClient;
 import com.sap.ai.sdk.orchestration.OrchestrationModuleConfig;
 import com.sap.ai.sdk.orchestration.OrchestrationPrompt;
-import com.sap.ai.sdk.orchestration.client.model.AzureContentSafety;
-import com.sap.ai.sdk.orchestration.client.model.AzureThreshold;
 import com.sap.ai.sdk.orchestration.client.model.ChatMessage;
 import com.sap.ai.sdk.orchestration.client.model.DPIConfig;
 import com.sap.ai.sdk.orchestration.client.model.DPIEntities;
@@ -89,13 +89,13 @@ public OrchestrationChatResponse messagesHistory() {
   /**
    * Apply both input and output filtering for a request to orchestration.
    *
-   * @param threshold A high threshold is a loose filter, a low threshold is a strict filter
+   * @param policy A high threshold is a loose filter, a low threshold is a strict filter
    * @return the result object
    */
-  @GetMapping("/filter/{threshold}")
+  @GetMapping("/filter/{policy}")
   @Nonnull
   public OrchestrationChatResponse filter(
-      @Nonnull @PathVariable("threshold") final AzureThreshold threshold) {
+      @Nonnull @PathVariable("policy") final AzureModerationPolicy policy) {
     final var prompt =
         new OrchestrationPrompt(
             """
@@ -104,11 +104,8 @@ public OrchestrationChatResponse filter(
             ```DISCLAIMER: The area surrounding the apartment is known for prostitutes and gang violence including armed conflicts, gun violence is frequent.
             """);
     final var filterConfig =
-        new AzureContentSafety()
-            .hate(threshold)
-            .selfHarm(threshold)
-            .sexual(threshold)
-            .violence(threshold);
+        new AzureContentFilter().hate(policy).selfHarm(policy).sexual(policy).violence(policy);
+
     final var configWithFilter =
         config.withInputFiltering(filterConfig).withOutputFiltering(filterConfig);
 

sample-code/spring-app/src/test/java/com/sap/ai/sdk/app/controllers/OrchestrationTest.java

@@ -3,8 +3,8 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
+import com.sap.ai.sdk.orchestration.AzureModerationPolicy;
 import com.sap.ai.sdk.orchestration.OrchestrationClientException;
-import com.sap.ai.sdk.orchestration.client.model.AzureThreshold;
 import com.sap.ai.sdk.orchestration.client.model.CompletionPostResponse;
 import com.sap.ai.sdk.orchestration.client.model.LLMChoice;
 import com.sap.ai.sdk.orchestration.client.model.LLMModuleResultSynchronous;
@@ -72,7 +72,7 @@ void testTemplate() {
 
   @Test
   void testLenientContentFilter() {
-    var response = controller.filter(AzureThreshold.NUMBER_4);
+    var response = controller.filter(AzureModerationPolicy.ALLOW_SAFE_LOW_MEDIUM);
     var result = response.getOriginalResponse();
     var llmChoice =
         ((LLMModuleResultSynchronous) result.getOrchestrationResult()).getChoices().get(0);
@@ -85,7 +85,7 @@ void testLenientContentFilter() {
 
   @Test
   void testStrictContentFilter() {
-    assertThatThrownBy(() -> controller.filter(AzureThreshold.NUMBER_0))
+    assertThatThrownBy(() -> controller.filter(AzureModerationPolicy.ALLOW_SAFE))
         .isInstanceOf(OrchestrationClientException.class)
         .hasMessageContaining("400 Bad Request")
         .hasMessageContaining("Content filtered");