Data Masking Convenience

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -184,15 +184,8 @@ var result =
 Use the data masking module to anonymize personal information in the input:
 
 ```java
-var maskingProvider =
-    MaskingProviderConfig.create()
-        .type(MaskingProviderConfig.TypeEnum.SAP_DATA_PRIVACY_INTEGRATION)
-        .method(MaskingProviderConfig.MethodEnum.ANONYMIZATION)
-        .entities(
-            DPIEntityConfig.create().type(DPIEntities.PHONE),
-            DPIEntityConfig.create().type(DPIEntities.PERSON));
-var maskingConfig = MaskingModuleConfig.create().maskingProviders(maskingProvider);
-var configWithMasking = config.withMaskingConfig(maskingConfig);
+var maskingConfig = DpiMaskingConfig.pseudonymization().withEntities(DPIEntities.PERSON, DPIEntities.EMAIL);
+var configWithMasking = config.withDpiMaskingConfig(maskingConfig);
 
 var systemMessage = ChatMessage.create()
         .role("system")
@@ -210,7 +203,7 @@ var result =
     new OrchestrationClient().chatCompletion(prompt, configWithMasking);
 ```
 
-In this example, the input will be masked before the call to the LLM. Note that data cannot be unmasked in the LLM output.
+In this example, the input will be masked before the call to the LLM and unmasked in the output.
 
 ### Set model parameters
 

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

@@ -0,0 +1,88 @@
+package com.sap.ai.sdk.orchestration;
+
+import static com.sap.ai.sdk.orchestration.client.model.DPIConfig.MethodEnum.ANONYMIZATION;
+import static com.sap.ai.sdk.orchestration.client.model.DPIConfig.MethodEnum.PSEUDONYMIZATION;
+import static com.sap.ai.sdk.orchestration.client.model.DPIConfig.TypeEnum.SAP_DATA_PRIVACY_INTEGRATION;
+
+import com.sap.ai.sdk.orchestration.client.model.DPIConfig;
+import com.sap.ai.sdk.orchestration.client.model.DPIEntities;
+import com.sap.ai.sdk.orchestration.client.model.DPIEntityConfig;
+import com.sap.ai.sdk.orchestration.client.model.MaskingModuleConfig;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import javax.annotation.Nonnull;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.Value;
+import lombok.val;
+
+/**
+ * SAP Data Privacy Integration (DPI) can mask personally identifiable information using either
+ * anonymization or pseudonymization.
+ */
+@Value
+@Getter(AccessLevel.PACKAGE)
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+public class DpiMaskingConfig {
+  @Nonnull DPIConfig.MethodEnum maskingMethod;
+  @Nonnull List<DPIEntities> entities;
+
+  /**
+   * Build a configuration applying anonymization.
+   *
+   * @return A builder configured for anonymization
+   */
+  @Nonnull
+  public static Builder anonymization() {
+    return new DpiMaskingConfig.Builder(ANONYMIZATION);
+  }
+
+  /**
+   * Build a configuration applying pseudonymization.
+   *
+   * @return A builder configured for pseudonymization
+   */
+  @Nonnull
+  public static Builder pseudonymization() {
+    return new DpiMaskingConfig.Builder(PSEUDONYMIZATION);
+  }
+
+  @Nonnull
+  MaskingModuleConfig createConfig() {
+    val entitiesDTO = entities.stream().map(it -> new DPIEntityConfig().type(it)).toList();
+    return new MaskingModuleConfig()
+        .addMaskingProvidersItem(
+            new DPIConfig()
+                .type(SAP_DATA_PRIVACY_INTEGRATION)
+                .method(maskingMethod)
+                .entities(entitiesDTO));
+  }
+
+  /**
+   * Builder for creating DPI masking configurations. Allows specifying which entity types should be
+   * masked in the input text.
+   */
+  @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+  public static class Builder {
+    private final DPIConfig.MethodEnum maskingMethod;
+
+    /**
+     * Specifies which entities should be masked in the input text.
+     *
+     * @param entity An entity type to mask (required)
+     * @param entities Additional entity types to mask (optional)
+     * @return A configured {@link DpiMaskingConfig} instance
+     * @see DPIEntities
+     */
+    @Nonnull
+    public DpiMaskingConfig withEntities(
+        @Nonnull final DPIEntities entity, @Nonnull final DPIEntities... entities) {
+      val entitiesList = new ArrayList<DPIEntities>();
+      entitiesList.add(entity);
+      entitiesList.addAll(Arrays.asList(entities));
+      return new DpiMaskingConfig(maskingMethod, entitiesList);
+    }
+  }
+}

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

@@ -62,4 +62,17 @@ public class OrchestrationModuleConfig {
   public OrchestrationModuleConfig withLlmConfig(@Nonnull final OrchestrationAiModel aiModel) {
     return withLlmConfig(aiModel.createConfig());
   }
+
+  /**
+   * Creates a new configuration with the given Data Masking configuration.
+   *
+   * @param dpiMasking The Data Masking configuration to use.
+   * @return A new configuration with the given Data Masking configuration.
+   */
+  @Tolerate
+  @Nonnull
+  public OrchestrationModuleConfig withDpiMaskingConfig(
+      @Nonnull final DpiMaskingConfig dpiMasking) {
+    return withMaskingConfig(dpiMasking.createConfig());
+  }
 }

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

@@ -34,19 +34,15 @@
 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.CompletionPostRequest;
-import com.sap.ai.sdk.orchestration.client.model.DPIConfig;
 import com.sap.ai.sdk.orchestration.client.model.DPIEntities;
-import com.sap.ai.sdk.orchestration.client.model.DPIEntityConfig;
 import com.sap.ai.sdk.orchestration.client.model.FilteringModuleConfig;
 import com.sap.ai.sdk.orchestration.client.model.GenericModuleResult;
 import com.sap.ai.sdk.orchestration.client.model.InputFilteringConfig;
 import com.sap.ai.sdk.orchestration.client.model.LLMModuleResultSynchronous;
-import com.sap.ai.sdk.orchestration.client.model.MaskingModuleConfig;
 import com.sap.ai.sdk.orchestration.client.model.OutputFilteringConfig;
 import com.sap.cloud.sdk.cloudplatform.connectivity.DefaultHttpDestination;
 import java.io.IOException;
 import java.io.InputStream;
-import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -306,10 +302,9 @@ void maskingPseudonymization() throws IOException {
                     .withBodyFile("maskingResponse.json")
                     .withHeader("Content-Type", "application/json")));
 
-    final var maskingConfig =
-        createMaskingConfig(DPIConfig.MethodEnum.PSEUDONYMIZATION, DPIEntities.PHONE);
+    final var maskingConfig = DpiMaskingConfig.pseudonymization().withEntities(DPIEntities.PHONE);
 
-    final var result = client.chatCompletion(prompt, config.withMaskingConfig(maskingConfig));
+    final var result = client.chatCompletion(prompt, config.withDpiMaskingConfig(maskingConfig));
     final var response = result.getOriginalResponse();
 
     assertThat(response).isNotNull();
@@ -328,20 +323,6 @@ void maskingPseudonymization() throws IOException {
     }
   }
 
-  private static MaskingModuleConfig createMaskingConfig(
-      @Nonnull final DPIConfig.MethodEnum method, @Nonnull final DPIEntities... entities) {
-
-    final var entityConfigs =
-        Arrays.stream(entities).map(it -> new DPIEntityConfig().type(it)).toList();
-    return new MaskingModuleConfig()
-        .maskingProviders(
-            List.of(
-                new DPIConfig()
-                    .type(DPIConfig.TypeEnum.SAP_DATA_PRIVACY_INTEGRATION)
-                    .method(method)
-                    .entities(entityConfigs)));
-  }
-
   @Test
   void testErrorHandling() {
     stubFor(

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

@@ -2,6 +2,7 @@
 
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.GPT_35_TURBO;
 
+import com.sap.ai.sdk.orchestration.DpiMaskingConfig;
 import com.sap.ai.sdk.orchestration.OrchestrationChatResponse;
 import com.sap.ai.sdk.orchestration.OrchestrationClient;
 import com.sap.ai.sdk.orchestration.OrchestrationModuleConfig;
@@ -10,15 +11,11 @@
 import com.sap.ai.sdk.orchestration.client.model.AzureContentSafetyFilterConfig;
 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;
-import com.sap.ai.sdk.orchestration.client.model.DPIEntityConfig;
 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.MaskingModuleConfig;
 import com.sap.ai.sdk.orchestration.client.model.OutputFilteringConfig;
 import com.sap.ai.sdk.orchestration.client.model.Template;
-import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import javax.annotation.Nonnull;
@@ -158,9 +155,8 @@ public OrchestrationChatResponse maskingAnonymization() {
     """);
 
     final var prompt = new OrchestrationPrompt(systemMessage, userMessage);
-    final var maskingConfig =
-        createMaskingConfig(DPIConfig.MethodEnum.ANONYMIZATION, DPIEntities.PERSON);
-    final var configWithMasking = config.withMaskingConfig(maskingConfig);
+    final var maskingConfig = DpiMaskingConfig.anonymization().withEntities(DPIEntities.PERSON);
+    final var configWithMasking = config.withDpiMaskingConfig(maskingConfig);
 
     return client.chatCompletion(prompt, configWithMasking);
   }
@@ -197,31 +193,9 @@ public OrchestrationChatResponse maskingPseudonymization() {
 
     final var prompt = new OrchestrationPrompt(systemMessage, userMessage);
     final var maskingConfig =
-        createMaskingConfig(
-            DPIConfig.MethodEnum.PSEUDONYMIZATION, DPIEntities.PERSON, DPIEntities.EMAIL);
-    final var configWithMasking = config.withMaskingConfig(maskingConfig);
+        DpiMaskingConfig.pseudonymization().withEntities(DPIEntities.PERSON, DPIEntities.EMAIL);
+    final var configWithMasking = config.withDpiMaskingConfig(maskingConfig);
 
     return client.chatCompletion(prompt, configWithMasking);
   }
-
-  /**
-   * Helper method to build masking configurations.
-   *
-   * @param method Either anonymization or pseudonymization.
-   * @param entities The entities to mask.
-   * @return A new masking configuration object.
-   */
-  private static MaskingModuleConfig createMaskingConfig(
-      @Nonnull final DPIConfig.MethodEnum method, @Nonnull final DPIEntities... entities) {
-
-    final var entityConfigs =
-        Arrays.stream(entities).map(it -> new DPIEntityConfig().type(it)).toList();
-    return new MaskingModuleConfig()
-        .maskingProviders(
-            List.of(
-                new DPIConfig()
-                    .type(DPIConfig.TypeEnum.SAP_DATA_PRIVACY_INTEGRATION)
-                    .method(method)
-                    .entities(entityConfigs)));
-  }
 }