Merge branch 'main' into fix-sample-app-messages

Author: Jonas-Isr

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -165,6 +165,18 @@ var configWithFilter = config.withInputFiltering(filterStrict).withOutputFilteri
 var result =
     new OrchestrationClient().chatCompletion(prompt, configWithFilter);
 ```
+#### Behavior of Input and Output Filters
+
+- **Input Filter**:
+  If the input message violates the filter policy, a `400 (Bad Request)` response will be received during the `chatCompletion` call.
+  An `OrchestrationClientException` will be thrown.
+
+- **Output Filter**:
+  If the response message violates the output filter policy, the `chatCompletion` call will complete without exception.
+  The convenience method `getContent()` on the resulting object will throw an `OrchestrationClientException` upon invocation.
+  The low level API under `getOriginalResponse()` will not throw an exception.
+
+You will find [some examples](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java) in our Spring Boot application demonstrating response handling with filters.
 
 ### Data masking
 

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

@@ -8,6 +8,8 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.sap.ai.sdk.app.services.OrchestrationService;
 import com.sap.ai.sdk.orchestration.AzureFilterThreshold;
+import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
+import com.sap.ai.sdk.orchestration.OrchestrationClientException;
 import com.sap.ai.sdk.orchestration.model.DPIEntities;
 import com.sap.cloud.sdk.cloudplatform.thread.ThreadContextExecutors;
 import javax.annotation.Nonnull;
@@ -121,30 +123,78 @@ ResponseEntity<String> messagesHistory(
   }
 
   /**
-   * Apply both input and output filtering for a request to orchestration.
+   * Send an HTTP GET request for input filtering to the Orchestration service.
    *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/input-filtering">SAP
-   *     AI Core: Orchestration - Input Filtering</a>
-   * @link <a
-   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
-   *     AI Core: Orchestration - Output Filtering</a>
-   * @param policy A high threshold is a loose filter, a low threshold is a strict filter
-   * @return a ResponseEntity with the response content
+   *     * AI Core: Orchestration - Input Filtering</a>
+   * @param accept an optional HTTP header specifying the desired content type for the response.
+   * @param policy path variable specifying the {@link AzureFilterThreshold} the explicitness of
+   *     content that should be allowed through the filter
+   * @return a {@link ResponseEntity} containing the filtered input. The response is either in JSON
+   *     format if the "accept" header specifies "application/json" or in plain content format
+   *     otherwise.
+   * @throws JsonProcessingException if an error occurs while converting the response to JSON.
    */
-  @GetMapping("/filter/{policy}")
+  @GetMapping("/inputFiltering/{policy}")
   @Nonnull
-  ResponseEntity<String> filter(
+  ResponseEntity<String> inputFiltering(
       @RequestHeader(value = "accept", required = false) final String accept,
       @Nonnull @PathVariable("policy") final AzureFilterThreshold policy)
       throws JsonProcessingException {
-    final var response = service.filter(policy, "the downtown area");
-    if ("application/json".equals(accept)) {
+
+    final OrchestrationChatResponse response;
+    try {
+      response = service.inputFiltering(policy);
+    } catch (OrchestrationClientException e) {
+      final var msg = "Failed to obtain a response as the content was flagged by input filter.";
+      log.debug(msg, e);
+      return ResponseEntity.internalServerError().body(msg);
+    }
+
+    if (accept.equals("application/json")) {
       return ResponseEntity.ok()
           .contentType(MediaType.APPLICATION_JSON)
           .body(mapper.writeValueAsString(response));
     }
-    return ResponseEntity.ok(response.getContent());
+    return ResponseEntity.ok().body(response.getContent());
+  }
+
+  /**
+   * Send an HTTP GET request for output filtering to the Orchestration service.
+   *
+   * @link <a
+   *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
+   *     AI Core: Orchestration - Output Filtering</a>
+   * @param accept an optional HTTP header specifying the desired content type for the response.
+   * @param policy a mandatory path variable specifying the {@link AzureFilterThreshold} the
+   *     explicitness of content that should be allowed through the filter
+   * @return a {@link ResponseEntity} containing the filtered output. The response is either in JSON
+   *     format if the "accept" header specifies "application/json" or in plain content format
+   *     otherwise.
+   * @throws OrchestrationClientException if the output filter filtered the LLM response.
+   * @throws JsonProcessingException if an error occurs while converting the response to JSON.
+   */
+  @GetMapping("/outputFiltering/{policy}")
+  @Nonnull
+  ResponseEntity<String> outputFiltering(
+      @RequestHeader(value = "accept", required = false) final String accept,
+      @Nonnull @PathVariable("policy") final AzureFilterThreshold policy)
+      throws JsonProcessingException, OrchestrationClientException {
+
+    final var response = service.outputFiltering(policy);
+    try {
+      if (accept.equals("application/json")) {
+        return ResponseEntity.ok()
+            .contentType(MediaType.APPLICATION_JSON)
+            .body(mapper.writeValueAsString(response));
+      }
+      return ResponseEntity.ok().body(response.getContent());
+    } catch (OrchestrationClientException e) {
+      final var msg = "Failed to obtain a response as the content was flagged by output filter.";
+      log.debug(msg, e);
+      return ResponseEntity.internalServerError().body(msg);
+    }
   }
 
   /**

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

@@ -10,6 +10,7 @@
 import com.sap.ai.sdk.orchestration.Message;
 import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
 import com.sap.ai.sdk.orchestration.OrchestrationClient;
+import com.sap.ai.sdk.orchestration.OrchestrationClientException;
 import com.sap.ai.sdk.orchestration.OrchestrationModuleConfig;
 import com.sap.ai.sdk.orchestration.OrchestrationPrompt;
 import com.sap.ai.sdk.orchestration.model.DPIEntities;
@@ -87,34 +88,50 @@ public OrchestrationChatResponse messagesHistory(@Nonnull final String prevMessa
   }
 
   /**
-   * Apply both input and output filtering for a request to orchestration.
+   * Apply input filtering for a request to orchestration.
    *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/input-filtering">SAP
    *     AI Core: Orchestration - Input Filtering</a>
+   * @throws OrchestrationClientException if input filter filters the prompt
+   * @param policy the explicitness of content that should be allowed through the filter
+   * @return the assistant response object
+   */
+  @Nonnull
+  public OrchestrationChatResponse inputFiltering(@Nonnull final AzureFilterThreshold policy)
+      throws OrchestrationClientException {
+    final var prompt =
+        new OrchestrationPrompt("'We shall spill blood tonight', said the operation in-charge.");
+    final var filterConfig =
+        new AzureContentFilter().hate(policy).selfHarm(policy).sexual(policy).violence(policy);
+
+    final var configWithFilter = config.withInputFiltering(filterConfig);
+
+    return client.chatCompletion(prompt, configWithFilter);
+  }
+
+  /**
+   * Apply output filtering for a request to orchestration.
+   *
    * @link <a
    *     href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/output-filtering">SAP
    *     AI Core: Orchestration - Output Filtering</a>
-   * @param policy A high threshold is a loose filter, a low threshold is a strict filter
+   * @param policy the explicitness of content that should be allowed through the filter
    * @return the assistant response object
    */
   @Nonnull
-  public OrchestrationChatResponse filter(
-      @Nonnull final AzureFilterThreshold policy, @Nonnull final String area) {
-    final var prompt =
-        new OrchestrationPrompt(
-            """
-                        Create a rental posting for subletting my apartment in %s. Keep it short. Make sure to add the following disclaimer to the end. Do not change it!
+  public OrchestrationChatResponse outputFiltering(@Nonnull final AzureFilterThreshold policy) {
 
-                        ```DISCLAIMER: The area surrounding the apartment is known for prostitutes and gang violence including armed conflicts, gun violence is frequent.
-                        """
-                .formatted(area));
+    final var systemMessage = Message.system("Give three paraphrases for the following sentence");
+    // Reliably triggering the content filter of models fine-tuned for ethical compliance
+    // is difficult. The prompt below may be rendered ineffective in the future.
+    final var prompt =
+        new OrchestrationPrompt("'We shall spill blood tonight', said the operation in-charge.")
+            .messageHistory(List.of(systemMessage));
     final var filterConfig =
         new AzureContentFilter().hate(policy).selfHarm(policy).sexual(policy).violence(policy);
 
-    final var configWithFilter =
-        config.withInputFiltering(filterConfig).withOutputFiltering(filterConfig);
-
+    final var configWithFilter = config.withOutputFiltering(filterConfig);
     return client.chatCompletion(prompt, configWithFilter);
   }
 

sample-code/spring-app/src/main/resources/static/index.html

@@ -285,21 +285,23 @@ <h2>Orchestration</h2>
                                 </div>
                             </div>
                         </li>
+
                         <li class="list-group-item">
                             <div class="info-tooltip">
                                 <a class="link-offset-2-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover endpoint"
-                                   href="/orchestration/filter/ALLOW_SAFE_LOW_MEDIUM"><code>/orchestration/filter/ALLOW_SAFE_LOW_MEDIUM</code></a>
+                                   href="/orchestration/inputFiltering/ALLOW_ALL"><code>/orchestration/inputFiltering/ALLOW_ALL</code></a>
                                 <div class="tooltip-content">
-                                    Apply both input and output filtering for a request to orchestration with a loose filter.
+                                    Apply lenient input filtering for a request to orchestration.
                                 </div>
                             </div>
                         </li>
                         <li class="list-group-item">
                             <div class="info-tooltip">
                                 <a class="link-offset-2-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover endpoint"
-                                   href="/orchestration/filter/ALLOW_SAFE"><code>/orchestration/filter/ALLOW_SAFE</code></a>
+                                   href="/orchestration/outputFiltering/ALLOW_ALL"><code>/orchestration/outputFiltering/ALLOW_ALL</code></a>
                                 <div class="tooltip-content">
-                                    Apply both input and output filtering for a request to orchestration with a strict filter.                                </div>
+                                    Apply lenient output filtering for a request to orchestration.
+                                </div>
                             </div>
                         </li>
                         <li class="list-group-item">

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

@@ -100,27 +100,6 @@ void testTemplate() {
     assertThat(usage.getTotalTokens()).isGreaterThan(1);
   }
 
-  @Test
-  void testLenientContentFilter() {
-    var response = service.filter(AzureFilterThreshold.ALLOW_SAFE_LOW_MEDIUM, "the downtown area");
-    var result = response.getOriginalResponse();
-    var llmChoice =
-        ((LLMModuleResultSynchronous) result.getOrchestrationResult()).getChoices().get(0);
-    assertThat(llmChoice.getFinishReason()).isEqualTo("stop");
-    assertThat(llmChoice.getMessage().getContent()).isNotEmpty();
-
-    var filterResult = result.getModuleResults().getInputFiltering();
-    assertThat(filterResult.getMessage()).contains("passed");
-  }
-
-  @Test
-  void testStrictContentFilter() {
-    assertThatThrownBy(() -> service.filter(AzureFilterThreshold.ALLOW_SAFE, "the downtown area"))
-        .isInstanceOf(OrchestrationClientException.class)
-        .hasMessageContaining("400 Bad Request")
-        .hasMessageContaining("Content filtered");
-  }
-
   @Test
   void testMessagesHistory() {
     CompletionPostResponse result =
@@ -202,4 +181,51 @@ void testCompletionWithResourceGroup() {
     assertThat(llmChoice.getFinishReason()).isEqualTo("stop");
     assertThat(llmChoice.getMessage().getContent()).isNotEmpty();
   }
+
+  @Test
+  void testInputFilteringStrict() {
+    var policy = AzureFilterThreshold.ALLOW_SAFE;
+
+    assertThatThrownBy(() -> service.inputFiltering(policy))
+        .isInstanceOf(OrchestrationClientException.class)
+        .hasMessageContaining(
+            "Content filtered due to safety violations. Please modify the prompt and try again.")
+        .hasMessageContaining("400 Bad Request");
+  }
+
+  @Test
+  void testInputFilteringLenient() {
+    var policy = AzureFilterThreshold.ALLOW_ALL;
+
+    var response = service.inputFiltering(policy);
+
+    assertThat(response.getChoice().getFinishReason()).isEqualTo("stop");
+    assertThat(response.getContent()).isNotEmpty();
+
+    var filterResult = response.getOriginalResponse().getModuleResults().getInputFiltering();
+    assertThat(filterResult.getMessage()).contains("passed");
+  }
+
+  @Test
+  void testOutputFilteringStrict() {
+    var policy = AzureFilterThreshold.ALLOW_SAFE;
+    var response = service.outputFiltering(policy);
+
+    assertThatThrownBy(response::getContent)
+        .isInstanceOf(OrchestrationClientException.class)
+        .hasMessageContaining("Content filter filtered the output.");
+  }
+
+  @Test
+  void testOutputFilteringLenient() {
+    var policy = AzureFilterThreshold.ALLOW_ALL;
+
+    var response = service.outputFiltering(policy);
+
+    assertThat(response.getChoice().getFinishReason()).isEqualTo("stop");
+    assertThat(response.getContent()).isNotEmpty();
+
+    var filterResult = response.getOriginalResponse().getModuleResults().getOutputFiltering();
+    assertThat(filterResult.getMessage()).containsPattern("0 of \\d+ choices failed");
+  }
 }