Orchestration Grounding convenience

Author: CharlesDuboisSAP

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

@@ -0,0 +1,76 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.google.common.annotations.Beta;
+import com.sap.ai.sdk.orchestration.model.DataRepositoryType;
+import com.sap.ai.sdk.orchestration.model.DocumentGroundingFilter;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig.TypeEnum;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfigConfig;
+import java.util.List;
+import java.util.Map;
+import javax.annotation.Nonnull;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+import lombok.val;
+
+/**
+ * Grounding integrates external, contextually relevant, domain-specific, or real-time data into AI
+ * processes. This data supplements the natural language processing capabilities of pre-trained
+ * models, which are trained on general material.
+ *
+ * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/grounding">SAP AI
+ *     Core: Orchestration - Grounding</a>
+ */
+@Beta
+@Setter(onMethod_ = {@Nonnull})
+@Accessors(fluent = true)
+public class Grounding implements GroundingProvider {
+
+  private String id = "someID";
+  private DataRepositoryType dataRepositoryType = DataRepositoryType.VECTOR;
+  private TypeEnum documentGroundingService = TypeEnum.DOCUMENT_GROUNDING_SERVICE;
+
+  /**
+   * Create a new default grounding provider.
+   *
+   * <p>It is by default a document grounding service with a vector data repository and id "someID".
+   *
+   * @return The grounding provider.
+   */
+  @Nonnull
+  public static Grounding create() {
+    return new Grounding();
+  }
+
+  /**
+   * Create a prompt with grounding parameters included in the message.
+   *
+   * <p>It uses the inputParams {@code groundingInput} for the user message and {@code
+   * groundingOutput} for the grounding context.
+   *
+   * @param message The user message.
+   * @return The prompt with grounding.
+   */
+  @Nonnull
+  public OrchestrationPrompt createGroundingPrompt(@Nonnull final String message) {
+    return new OrchestrationPrompt(
+        Map.of("groundingInput", message),
+        Message.user(
+            "{{?groundingInput}} Use the following information as additional context: {{?groundingOutput}}"));
+  }
+
+  @Nonnull
+  @Override
+  public GroundingModuleConfig createConfig() {
+    val filterInner =
+        DocumentGroundingFilter.create().id(id).dataRepositoryType(dataRepositoryType);
+    val groundingConfigConfig =
+        GroundingModuleConfigConfig.create()
+            .inputParams(List.of("groundingInput"))
+            .outputParam("groundingOutput")
+            .addFiltersItem(filterInner);
+    return GroundingModuleConfig.create()
+        .type(documentGroundingService)
+        .config(groundingConfigConfig);
+  }
+}

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

@@ -0,0 +1,21 @@
+package com.sap.ai.sdk.orchestration;
+
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
+import javax.annotation.Nonnull;
+
+/**
+ * Interface for grounding configurations.
+ *
+ * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/grounding">SAP AI
+ *     Core: Orchestration - Grounding</a>
+ */
+public interface GroundingProvider {
+
+  /**
+   * Create a grounding configuration.
+   *
+   * @return the grounding configuration
+   */
+  @Nonnull
+  GroundingModuleConfig createConfig();
+}

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

@@ -12,9 +12,9 @@
 public interface MaskingProvider {
 
   /**
-   * Create a masking provider for the configuration.
+   * Create a masking configuration.
    *
-   * @return the masking provider
+   * @return the masking configuration
    */
   @Nonnull
   MaskingProviderConfig createConfig();

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

@@ -197,4 +197,18 @@ public OrchestrationModuleConfig withOutputFiltering(
 
     return this.withFilteringConfig(newFilteringConfig);
   }
+
+  /**
+   * Creates a new configuration with the given grounding configuration.
+   *
+   * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/grounding">SAP
+   *     AI Core: Orchestration - Grounding</a>
+   * @param groundingProvider The grounding configuration to use.
+   * @return A new configuration with the given grounding configuration.
+   */
+  @Nonnull
+  public OrchestrationModuleConfig withGrounding(
+      @Nonnull final GroundingProvider groundingProvider) {
+    return this.withGroundingConfig(groundingProvider.createConfig());
+  }
 }

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

@@ -3,11 +3,17 @@
 import static com.sap.ai.sdk.orchestration.AzureFilterThreshold.ALLOW_SAFE_LOW_MEDIUM;
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.GPT_4O;
 import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.Parameter.MAX_TOKENS;
+import static com.sap.ai.sdk.orchestration.model.DataRepositoryType.VECTOR;
+import static com.sap.ai.sdk.orchestration.model.GroundingModuleConfig.TypeEnum.DOCUMENT_GROUNDING_SERVICE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import com.sap.ai.sdk.orchestration.model.DPIConfig;
 import com.sap.ai.sdk.orchestration.model.DPIEntities;
+import com.sap.ai.sdk.orchestration.model.DocumentGroundingFilter;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfigConfig;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfigConfigFiltersInner;
+import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
 
@@ -121,4 +127,35 @@ void testLLMConfig() {
         .withFailMessage("Static models should be unchanged")
         .isEqualTo("latest");
   }
+
+  @Test
+  void testGroundingConfig() {
+    var groundingConfig = Grounding.create();
+    var config =
+        new OrchestrationModuleConfig().withLlmConfig(GPT_4O).withGrounding(groundingConfig);
+
+    assertThat(config.getGroundingConfig()).isNotNull();
+    assertThat(config.getGroundingConfig().getType()).isEqualTo(DOCUMENT_GROUNDING_SERVICE);
+
+    GroundingModuleConfigConfig configConfig = config.getGroundingConfig().getConfig();
+    assertThat(configConfig).isNotNull();
+    assertThat(configConfig.getInputParams()).containsExactly("groundingInput");
+    assertThat(configConfig.getOutputParam()).isEqualTo("groundingOutput");
+
+    List<GroundingModuleConfigConfigFiltersInner> filters = configConfig.getFilters();
+    assertThat(filters).hasSize(1);
+    DocumentGroundingFilter filter = (DocumentGroundingFilter) filters.get(0);
+    assertThat(filter.getId()).isEqualTo("someID");
+    assertThat(filter.getDataRepositoryType()).isEqualTo(VECTOR);
+  }
+
+  @Test
+  void testGroundingPrompt() {
+    var prompt = Grounding.create().createGroundingPrompt("Hello, World!");
+    assertThat(prompt.getMessages()).hasSize(1);
+    var message = prompt.getMessages().get(0);
+    assertThat(message.content())
+        .isEqualTo(
+            "{{?groundingInput}} Use the following information as additional context: {{?groundingOutput}}");
+  }
 }

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

@@ -7,24 +7,22 @@
 import com.sap.ai.sdk.orchestration.AzureContentFilter;
 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.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;
-import com.sap.ai.sdk.orchestration.model.DataRepositoryType;
-import com.sap.ai.sdk.orchestration.model.DocumentGroundingFilter;
-import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
-import com.sap.ai.sdk.orchestration.model.GroundingModuleConfigConfig;
 import com.sap.ai.sdk.orchestration.model.Template;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Stream;
 import javax.annotation.Nonnull;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
+import lombok.val;
 import org.springframework.stereotype.Service;
 
 /** Service class for the Orchestration service */
@@ -238,23 +236,9 @@ public OrchestrationChatResponse maskingPseudonymization(@Nonnull final DPIEntit
    */
   @Nonnull
   public OrchestrationChatResponse grounding(@Nonnull final String groundingInput) {
-    final var message =
-        Message.user(
-            "{{?groundingInput}} Use the following information as additional context: {{?groundingOutput}}");
-    final var prompt = new OrchestrationPrompt(Map.of("groundingInput", groundingInput), message);
-
-    final var filterInner =
-        DocumentGroundingFilter.create().id("someID").dataRepositoryType(DataRepositoryType.VECTOR);
-    final var groundingConfigConfig =
-        GroundingModuleConfigConfig.create()
-            .inputParams(List.of("groundingInput"))
-            .outputParam("groundingOutput")
-            .addFiltersItem(filterInner);
-    final var groundingConfig =
-        GroundingModuleConfig.create()
-            .type(GroundingModuleConfig.TypeEnum.DOCUMENT_GROUNDING_SERVICE)
-            .config(groundingConfigConfig);
-    final var configWithGrounding = config.withGroundingConfig(groundingConfig);
+    val groundingConfig = Grounding.create();
+    val prompt = groundingConfig.createGroundingPrompt(groundingInput);
+    val configWithGrounding = config.withGrounding(groundingConfig);
 
     return client.chatCompletion(prompt, configWithGrounding);
   }