feat: Llama🦙Guard (#308)

* feat: Llama Guard Filter

* trigger filter

* Added e2e test

* Unit test

* Formatting

* doc

* wrong package

* javadoc

* Merge conflicts

* Revert object mapper

* Added missing dependency

---------

Co-authored-by: SAP Cloud SDK Bot <[email protected]>

Author: CharlesDuboisSAP

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -158,8 +158,11 @@ var filterLoose = new AzureContentFilter()
                 .sexual(ALLOW_SAFE_LOW_MEDIUM)
     .violence(ALLOW_SAFE_LOW_MEDIUM);
 
+// choose Llama Guard filter or/and Azure filter
+var llamaGuardFilter = new LlamaGuardFilter().config(LlamaGuard38b.create().selfHarm(true));
+
 // changing the input to filterLoose will allow the message to pass
-var configWithFilter = config.withInputFiltering(filterStrict).withOutputFiltering(filterStrict);
+var configWithFilter = config.withInputFiltering(filterStrict).withOutputFiltering(filterStrict, llamaGuardFilter);
 
 // this fails with Bad Request because the strict filter prohibits the input message
 var result =

docs/release-notes/release_notes.md

@@ -12,7 +12,7 @@
 
 ### ✨ New Functionality
 
--
+- [Add Orchestration `LlamaGuardFilter`](../guides/ORCHESTRATION_CHAT_COMPLETION.md#chat-completion-filter).
 
 ### 📈 Improvements
 

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

@@ -0,0 +1,46 @@
+package com.sap.ai.sdk.orchestration;
+
+import static com.sap.ai.sdk.orchestration.model.LlamaGuard38bFilterConfig.TypeEnum.LLAMA_GUARD_3_8B;
+
+import com.sap.ai.sdk.orchestration.model.LlamaGuard38b;
+import com.sap.ai.sdk.orchestration.model.LlamaGuard38bFilterConfig;
+import javax.annotation.Nonnull;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+/**
+ * A content filter wrapping Llama Guard filter config.
+ *
+ * <p>This class allows setting filters for different content categories such as hate, self-harm,
+ * sexual, and violence.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // values not set are disabled by default
+ * val config =
+ *     LlamaGuard38b.create()
+ *         .violentCrimes(true)
+ *         .selfHarm(true);
+ * val filterConfig = new LlamaGuardFilter().config(config);
+ * }</pre>
+ *
+ * @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>
+ */
+@Accessors(fluent = true)
+@Setter
+public class LlamaGuardFilter implements ContentFilter {
+
+  private LlamaGuard38b config = LlamaGuard38b.create();
+
+  @Nonnull
+  @Override
+  public LlamaGuard38bFilterConfig createConfig() {
+    return LlamaGuard38bFilterConfig.create().type(LLAMA_GUARD_3_8B).config(config);
+  }
+}

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

@@ -53,7 +53,6 @@
 import com.sap.ai.sdk.orchestration.model.LLMModuleResult;
 import com.sap.ai.sdk.orchestration.model.LLMModuleResultSynchronous;
 import com.sap.ai.sdk.orchestration.model.LlamaGuard38b;
-import com.sap.ai.sdk.orchestration.model.LlamaGuard38bFilterConfig;
 import com.sap.ai.sdk.orchestration.model.ModuleConfigs;
 import com.sap.ai.sdk.orchestration.model.MultiChatMessage;
 import com.sap.ai.sdk.orchestration.model.OrchestrationConfig;
@@ -309,11 +308,7 @@ void filteringLoose() throws IOException {
             .sexual(ALLOW_SAFE_LOW_MEDIUM)
             .violence(ALLOW_SAFE_LOW_MEDIUM);
 
-    final ContentFilter llamaFilter =
-        () ->
-            LlamaGuard38bFilterConfig.create()
-                .type(LlamaGuard38bFilterConfig.TypeEnum.LLAMA_GUARD_3_8B)
-                .config(LlamaGuard38b.create().selfHarm(true));
+    final var llamaFilter = new LlamaGuardFilter().config(LlamaGuard38b.create().selfHarm(true));
 
     client.chatCompletion(
         prompt,

sample-code/spring-app/pom.xml

@@ -118,6 +118,10 @@
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+    </dependency>
     <!-- scope "runtime" -->
     <dependency>
       <groupId>ch.qos.logback</groupId>

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

@@ -1,7 +1,10 @@
 package com.sap.ai.sdk.app;
 
+import static com.sap.ai.sdk.core.JacksonConfiguration.getDefaultObjectMapper;
+
+import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
+import com.fasterxml.jackson.annotation.PropertyAccessor;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.sap.ai.sdk.orchestration.OrchestrationJacksonConfiguration;
 import javax.annotation.Nonnull;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
@@ -17,16 +20,16 @@
 public class Application {
 
   /**
-   * Temporary workaround to fix the issue with the Orchestration spec.
+   * Changes Spring Boot's default object mapper to fix serialization issues.
    *
-   * @return a modified object mapper that works for Orchestration.
+   * @return a modified object mapper
    */
   @Bean
   @Primary
   @SuppressWarnings("unused")
   @Nonnull
   public ObjectMapper objectMapper() {
-    return OrchestrationJacksonConfiguration.getOrchestrationObjectMapper();
+    return getDefaultObjectMapper().setVisibility(PropertyAccessor.FIELD, Visibility.ANY);
   }
 
   /**

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

@@ -124,6 +124,27 @@ Object outputFiltering(
     return response.getContent();
   }
 
+  @GetMapping("/llamaGuardFilter/{enabled}")
+  @Nonnull
+  Object llamaGuardInputFiltering(
+      @Nullable @RequestParam(value = "format", required = false) final String format,
+      @PathVariable("enabled") final boolean enabled) {
+
+    final OrchestrationChatResponse response;
+    try {
+      response = service.llamaGuardInputFilter(enabled);
+    } 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 ("json".equals(format)) {
+      return response;
+    }
+    return response.getContent();
+  }
+
   @GetMapping("/maskingAnonymization")
   @Nonnull
   Object maskingAnonymization(

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

@@ -8,6 +8,7 @@
 import com.sap.ai.sdk.orchestration.AzureFilterThreshold;
 import com.sap.ai.sdk.orchestration.DpiMasking;
 import com.sap.ai.sdk.orchestration.Grounding;
+import com.sap.ai.sdk.orchestration.LlamaGuardFilter;
 import com.sap.ai.sdk.orchestration.Message;
 import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
 import com.sap.ai.sdk.orchestration.OrchestrationClient;
@@ -18,6 +19,7 @@
 import com.sap.ai.sdk.orchestration.model.DataRepositoryType;
 import com.sap.ai.sdk.orchestration.model.DocumentGroundingFilter;
 import com.sap.ai.sdk.orchestration.model.GroundingFilterSearchConfiguration;
+import com.sap.ai.sdk.orchestration.model.LlamaGuard38b;
 import com.sap.ai.sdk.orchestration.model.SearchDocumentKeyValueListPair;
 import com.sap.ai.sdk.orchestration.model.SearchSelectOptionEnum;
 import com.sap.ai.sdk.orchestration.model.Template;
@@ -150,6 +152,47 @@ public OrchestrationChatResponse outputFiltering(@Nonnull final AzureFilterThres
     return client.chatCompletion(prompt, configWithFilter);
   }
 
+  /**
+   * Apply the Llama Guard filter.
+   *
+   * @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 filter enable or disable the filter
+   * @return the assistant response object
+   */
+  @Nonnull
+  public OrchestrationChatResponse llamaGuardInputFilter(final boolean filter)
+      throws OrchestrationClientException {
+    val prompt =
+        new OrchestrationPrompt("'We shall spill blood tonight', said the operation in-charge.");
+
+    // values not set are disabled by default
+    val config =
+        LlamaGuard38b.create()
+            .violentCrimes(filter)
+            .nonViolentCrimes(filter)
+            .sexCrimes(filter)
+            .childExploitation(filter)
+            .defamation(filter)
+            .specializedAdvice(filter)
+            .privacy(filter)
+            .intellectualProperty(filter)
+            .indiscriminateWeapons(filter)
+            .hate(filter)
+            .selfHarm(filter)
+            .sexualContent(filter)
+            .elections(filter)
+            .codeInterpreterAbuse(filter);
+
+    val filterConfig = new LlamaGuardFilter().config(config);
+
+    val configWithFilter = this.config.withInputFiltering(filterConfig);
+
+    return client.chatCompletion(prompt, configWithFilter);
+  }
+
   /**
    * Let the orchestration service evaluate the feedback on the AI SDK provided by a hypothetical
    * user. Anonymize any names given as they are not relevant for judging the sentiment of the

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

@@ -273,6 +273,16 @@ <h2>Orchestration</h2>
                                 </div>
                             </div>
                         </li>
+                        <li class="list-group-item">
+                            <div class="info-tooltip">
+                                <button type="submit" formaction="/orchestration/llamaGuardFilter/false" class="link-offset-2-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover endpoint">
+                                    <code>/orchestration/llamaGuardFilter/false</code>
+                                </button>
+                                <div class="tooltip-content">
+                                    Apply lenient input filtering for a request to orchestration.
+                                </div>
+                            </div>
+                        </li>
                         <li class="list-group-item">
                             <div class="info-tooltip">
                                 <button type="submit" formaction="/orchestration/maskingAnonymization" class="link-offset-2-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover endpoint">

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

@@ -228,4 +228,24 @@ void testOutputFilteringLenient() {
     var filterResult = response.getOriginalResponse().getModuleResults().getOutputFiltering();
     assertThat(filterResult.getMessage()).containsPattern("0 of \\d+ choices failed");
   }
+
+  @Test
+  void testLlamaGuardEnabled() {
+    assertThatThrownBy(() -> service.llamaGuardInputFilter(true))
+        .isInstanceOf(OrchestrationClientException.class)
+        .hasMessageContaining(
+            "Content filtered due to safety violations. Please modify the prompt and try again.")
+        .hasMessageContaining("400 Bad Request");
+  }
+
+  @Test
+  void testLlamaGuardDisabled() {
+    var response = service.llamaGuardInputFilter(false);
+
+    assertThat(response.getChoice().getFinishReason()).isEqualTo("stop");
+    assertThat(response.getContent()).isNotEmpty();
+
+    var filterResult = response.getOriginalResponse().getModuleResults().getInputFiltering();
+    assertThat(filterResult.getMessage()).contains("passed");
+  }
 }