Merge branch 'main' into orchestration-streaming

# Conflicts:
#	docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

Author: CharlesDuboisSAP

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -186,6 +186,37 @@ var result =
 
 In this example, the input will be masked before the call to the LLM and will remain masked in the output.
 
+### Grounding
+
+Use the grounding module to provide additional context to the AI model. 
+
+```java
+    var message =
+        Message.user(
+            "{{?groundingInput}} Use the following information as additional context: {{?groundingOutput}}");
+    var prompt =
+        new OrchestrationPrompt(Map.of("groundingInput", "What does Joule do?"), message);
+
+    var filterInner =
+        DocumentGroundingFilter.create().id("someID").dataRepositoryType(DataRepositoryType.VECTOR);
+    var groundingConfigConfig =
+        GroundingModuleConfigConfig.create()
+            .inputParams(List.of("groundingInput"))
+            .outputParam("groundingOutput")
+            .addFiltersItem(filterInner);
+    
+    var groundingConfig =
+        GroundingModuleConfig.create()
+            .type(GroundingModuleConfig.TypeEnum.DOCUMENT_GROUNDING_SERVICE)
+            .config(groundingConfigConfig);
+    var configWithGrounding = config.withGroundingConfig(groundingConfig);
+
+    var result =  
+            new OrchestrationClient().chatCompletion(prompt, configWithGrounding);
+```
+
+In this example, the AI model is provided with additional context in the form of grounding information. Note, that it is necessary to provide the grounding input via one or more input variables.
+
 ### Stream chat completion
 
 It's possible to pass a stream of chat completion delta elements, e.g. from the application backend to the frontend in real-time.
@@ -212,7 +243,6 @@ try (Stream<String> stream = client.streamChatCompletion(prompt, config)) {
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java).
 It shows the usage of Spring Boot's `ResponseBodyEmitter` to stream the chat completion delta messages to the frontend in real-time.
 
-
 ### Set model parameters
 
 Change your LLM configuration to add model parameters:

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

@@ -70,6 +70,7 @@ static ModuleConfigs toModuleConfigs(@Nonnull final OrchestrationModuleConfig co
 
     Option.of(config.getFilteringConfig()).forEach(moduleConfig::filteringModuleConfig);
     Option.of(config.getMaskingConfig()).forEach(moduleConfig::maskingModuleConfig);
+    Option.of(config.getGroundingConfig()).forEach(moduleConfig::groundingModuleConfig);
 
     return moduleConfig;
   }

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

@@ -1,6 +1,7 @@
 package com.sap.ai.sdk.orchestration;
 
 import com.sap.ai.sdk.orchestration.model.FilteringModuleConfig;
+import com.sap.ai.sdk.orchestration.model.GroundingModuleConfig;
 import com.sap.ai.sdk.orchestration.model.InputFilteringConfig;
 import com.sap.ai.sdk.orchestration.model.LLMModuleConfig;
 import com.sap.ai.sdk.orchestration.model.MaskingModuleConfig;
@@ -83,6 +84,15 @@ public class OrchestrationModuleConfig {
    */
   @Nullable FilteringModuleConfig filteringConfig;
 
+  /**
+   * A grounding configuration to provide additional context to the AI model.
+   *
+   * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/grounding">SAP
+   *     AI Core: Orchestration - </a>
+   * @since 1.1.0
+   */
+  @Nullable GroundingModuleConfig groundingConfig;
+
   /**
    * Creates a new configuration with the given LLM configuration.
    *

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

@@ -109,6 +109,37 @@ void testCompletion() {
     assertThat(result.getContent()).isNotEmpty();
   }
 
+  @Test
+  void testGrounding() {
+    stubFor(
+        post(anyUrl())
+            .willReturn(
+                aResponse()
+                    .withBodyFile("groundingResponse.json")
+                    .withHeader("Content-Type", "application/json")));
+    final var response = client.chatCompletion(prompt, config);
+    final var result = response.getOriginalResponse();
+    var llmChoice =
+        ((LLMModuleResultSynchronous) result.getOrchestrationResult()).getChoices().get(0);
+
+    final var groundingData =
+        (Map<String, Object>) result.getModuleResults().getGrounding().getData();
+    assertThat(groundingData.get("grounding_query")).isEqualTo("grounding call");
+    assertThat(groundingData.get("grounding_result").toString())
+        .startsWith("Joule is the AI copilot that truly understands your business.");
+    assertThat(result.getModuleResults().getGrounding().getMessage()).isEqualTo("grounding result");
+    assertThat(result.getModuleResults().getTemplating().get(0).getContent())
+        .startsWith(
+            "What does Joule do? Use the following information as additional context: Joule is the AI copilot that truly understands your business.");
+    assertThat(llmChoice.getMessage().getContent())
+        .startsWith(
+            "Joule is an AI copilot that revolutionizes how users interact with their SAP business systems.");
+    assertThat(llmChoice.getFinishReason()).isEqualTo("stop");
+    assertThat(llmChoice.getMessage().getContent())
+        .startsWith(
+            "Joule is an AI copilot that revolutionizes how users interact with their SAP business systems.");
+  }
+
   @Test
   void testTemplating() throws IOException {
     stubFor(

orchestration/src/test/resources/__files/groundingResponse.json

@@ -0,0 +1,62 @@
+{
+  "request_id": "0d9d7ce3-9ded-481f-80c6-977e78e2e905",
+  "module_results": {
+    "grounding": {
+      "message": "grounding result",
+      "data": {
+        "grounding_query": "grounding call",
+        "grounding_result": "Joule is the AI copilot that truly understands your business. Joule revolutionizes how you interact with your SAP business systems, making every touchpoint count and every task simpler.```It enables the companion of the Intelligent Enterprise, guiding you through content discovery within SAP Ecosystem, and giving a transparent role-based access to the relevant processes from everywhere. This is the one assistant experience, a unified and delightful user experience across SAP’s \u01ee solution portfolio."
+      }
+    },
+    "templating": [
+      {
+        "role": "user",
+        "content": "What does Joule do? Use the following information as additional context: Joule is the AI copilot that truly understands your business. Joule revolutionizes how you interact with your SAP business systems, making every touchpoint count and every task simpler.```It enables the companion of the Intelligent Enterprise, guiding you through content discovery within SAP Ecosystem, and giving a transparent role-based access to the relevant processes from everywhere. This is the one assistant experience, a unified and delightful user experience across SAP’s \u01ee solution portfolio."
+      }
+    ],
+    "llm": {
+      "id": "chatcmpl-AbRlNdsyQJfvBINnw3MOTP77WSE4X",
+      "object": "chat.completion",
+      "created": 1733488221,
+      "model": "gpt-35-turbo",
+      "system_fingerprint": "fp_808245b034",
+      "choices": [
+        {
+          "index": 0,
+          "message": {
+            "role": "assistant",
+            "content": "Joule is an AI copilot that revolutionizes how users interact with their SAP business systems. It enables the companion of the Intelligent Enterprise, guiding users through content discovery within the SAP Ecosystem and providing transparent role-based access to relevant processes from anywhere. Joule aims to provide a unified and delightful user experience across SAP's solution portfolio."
+          },
+          "finish_reason": "stop"
+        }
+      ],
+      "usage": {
+        "completion_tokens": 68,
+        "prompt_tokens": 113,
+        "total_tokens": 181
+      }
+    }
+  },
+  "orchestration_result": {
+    "id": "chatcmpl-AbRlNdsyQJfvBINnw3MOTP77WSE4X",
+    "object": "chat.completion",
+    "created": 1733488221,
+    "model": "gpt-35-turbo",
+    "system_fingerprint": "fp_808245b034",
+    "choices": [
+      {
+        "index": 0,
+        "message": {
+          "role": "assistant",
+          "content": "Joule is an AI copilot that revolutionizes how users interact with their SAP business systems. It enables the companion of the Intelligent Enterprise, guiding users through content discovery within the SAP Ecosystem and providing transparent role-based access to relevant processes from anywhere. Joule aims to provide a unified and delightful user experience across SAP's solution portfolio."
+        },
+        "finish_reason": "stop"
+      }
+    ],
+    "usage": {
+      "completion_tokens": 68,
+      "prompt_tokens": 113,
+      "total_tokens": 181
+    }
+  }
+}

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

@@ -14,6 +14,10 @@
 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 com.sap.cloud.sdk.cloudplatform.thread.ThreadContextExecutors;
 import java.util.List;
@@ -246,4 +250,35 @@ OrchestrationChatResponse maskingPseudonymization() {
 
     return client.chatCompletion(prompt, configWithMasking);
   }
+
+  /**
+   * Using grounding to provide additional context to the AI model.
+   *
+   * @link <a href="https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/grounding">SAP
+   *     AI Core: Orchestration - Grounding</a>
+   */
+  @GetMapping("/grounding")
+  @Nonnull
+  OrchestrationChatResponse grounding() {
+    final var message =
+        Message.user(
+            "{{?groundingInput}} Use the following information as additional context: {{?groundingOutput}}");
+    final var prompt =
+        new OrchestrationPrompt(Map.of("groundingInput", "What does Joule do?"), 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);
+
+    return client.chatCompletion(prompt, configWithGrounding);
+  }
 }

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

@@ -74,6 +74,7 @@ <h2>Endpoints</h2>
             <li><a href="/orchestration/filter/NUMBER_0">/orchestration/filter/NUMBER_0</a> Strict filter (fails)</li>
             <li><a href="/orchestration/maskingAnonymization">/orchestration/maskingAnonymization</a></li>
             <li><a href="/orchestration/maskingPseudonymization">/orchestration/maskingPseudonymization</a></li>
+            <li><a href="/orchestration/grounding">/orchestration/grounding</a></li>
         </ul>
     </li>
     <li><h3>Foundation Models</h3>

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

@@ -178,8 +178,16 @@ void testMaskingPseudonymization() {
   @Test
   @DisabledIfSystemProperty(named = "aicore.landscape", matches = "production")
   void testGrounding() {
-    // Placeholder for grounding test
     assertThat(System.getProperty("aicore.landscape")).isNotEqualTo("production");
+    var response = controller.grounding();
+    var result = response.getOriginalResponse();
+    var llmChoice =
+        ((LLMModuleResultSynchronous) result.getOrchestrationResult()).getChoices().get(0);
+    assertThat(response).isNotNull();
+    assertThat(llmChoice.getFinishReason()).isEqualTo("stop");
+    assertThat(result.getModuleResults().getGrounding()).isNotNull();
+    assertThat(result.getModuleResults().getGrounding().getData()).isNotNull();
+    assertThat(result.getModuleResults().getGrounding().getMessage()).isEqualTo("grounding result");
   }
 
   @Test