Merge branch 'main' into mask-grounding

Jonas-Isr · web-flow · commit 431402d63a97 · 2025-03-05T14:04:28.000+01:00
diff --git a/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md b/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md
@@ -228,6 +228,10 @@ In this example, the input will be masked before the call to the LLM and will re
 
 Use the grounding module to provide additional context to the AI model. 
 
+### Vector Data Repository
+
+One way to provide grounding is by using a vector data repository. This can be done as follows.
+
 ```java
 // optional filter for collections
 var documentMetadata =
@@ -251,7 +255,20 @@ var result = client.chatCompletion(prompt, configWithGrounding);
 
 In this example, the AI model is provided with additional context in the form of grounding information.
 
-`Grounding.create()` is by default a document grounding service with a vector data repository.
+### Grounding via *help.sap.com*
+
+You can also use grounding based on *help.sap.com* for convenient SAP specific grounding. This can be achieved as follows.
+
+```java
+var groundingHelpSapCom =
+        DocumentGroundingFilter.create()
+                .dataRepositoryType(DataRepositoryType.HELP_SAP_COM);
+var groundingConfig = Grounding.create().filters(groundingHelpSapCom);
+var configWithGrounding = config.withGrounding(groundingConfig);
+
+var prompt = groundingConfig.createGroundingPrompt("What is a fuzzy search?");
+var response = client.chatCompletion(prompt, configWithGrounding);
+```
 
 Please find [an example in our Spring Boot application](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java).
 
diff --git a/docs/release-notes/release_notes.md b/docs/release-notes/release_notes.md
@@ -15,6 +15,7 @@
 - [Orchestration] [Add Spring AI Chat Memory support](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/SPRING_AI_INTEGRATION.md#chat-memory)
 - [Orchestration] [Prompt templates can be consumed from registry.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#Chat-completion-with-Templates)
 - [Orchestration] [Masking is now available on grounding.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#mask-grounding)
+- [Orchestration] [Grounding via *help.sap.com* is enabled.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#grounding)
 
 ### 📈 Improvements
 
diff --git a/orchestration/src/main/java/com/sap/ai/sdk/orchestration/Grounding.java b/orchestration/src/main/java/com/sap/ai/sdk/orchestration/Grounding.java
@@ -85,6 +85,11 @@ public GroundingModuleConfig createConfig() {
             .outputParam("groundingContext")
             .filters(filters);
 
+    if (filters.contains(
+        DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.HELP_SAP_COM))) {
+      groundingConfigConfig.setMetadataParams(null);
+    }
+
     return GroundingModuleConfig.create()
         .type(documentGroundingService)
         .config(groundingConfigConfig);
diff --git a/orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationUnitTest.java b/orchestration/src/test/java/com/sap/ai/sdk/orchestration/OrchestrationUnitTest.java
@@ -224,6 +224,34 @@ void testGrounding() throws IOException {
     }
   }
 
+  @Test
+  void testGroundingWithHelpSapCom() throws IOException {
+    stubFor(
+        post(urlPathEqualTo("/completion"))
+            .willReturn(
+                aResponse()
+                    .withBodyFile("groundingHelpSapComResponse.json")
+                    .withHeader("Content-Type", "application/json")));
+    val groundingHelpSapCom =
+        DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.HELP_SAP_COM);
+    val groundingConfig = Grounding.create().filters(groundingHelpSapCom);
+    val configWithGrounding = config.withGrounding(groundingConfig);
+
+    val prompt = groundingConfig.createGroundingPrompt("What is a fuzzy search?");
+    val response = client.chatCompletion(prompt, configWithGrounding);
+
+    assertThat(
+            response.getOriginalResponse().getModuleResults().getGrounding().getData().toString())
+        .contains(
+            "A fuzzy search is a search technique that is designed to be fast and tolerant of errors");
+    assertThat(response.getContent()).startsWith("A fuzzy search is a search technique");
+
+    try (var requestInputStream = fileLoader.apply("groundingHelpSapComRequest.json")) {
+      final String request = new String(requestInputStream.readAllBytes());
+      verify(postRequestedFor(urlPathEqualTo("/completion")).withRequestBody(equalToJson(request)));
+    }
+  }
+
   @Test
   void testTemplating() throws IOException {
     stubFor(
diff --git a/orchestration/src/test/resources/__files/groundingHelpSapComResponse.json b/orchestration/src/test/resources/__files/groundingHelpSapComResponse.json
@@ -0,0 +1,62 @@
+{
+  "request_id": "47ee9f8c-3c54-4028-aabe-358f89409de9",
+  "module_results": {
+    "grounding": {
+      "message": "grounding result",
+      "data": {
+        "grounding_query": "grounding call",
+        "grounding_result": "A fuzzy search is a search technique that is designed to be fast and tolerant of errors"
+      }
+    },
+    "templating": [
+      {
+        "role": "user",
+        "content": "What is a fuzzy search? Use the following information as additional context: A fuzzy search is a search technique that is designed to be fast and tolerant of errors"
+      }
+    ],
+    "llm": {
+      "id": "chatcmpl-B7fExAgihXpKnBaaJ3uXnLgmaC6Ox",
+      "object": "chat.completion",
+      "created": 1741166523,
+      "model": "gpt-4o-2024-08-06",
+      "system_fingerprint": "fp_b705f0c291",
+      "choices": [
+        {
+          "index": 0,
+          "message": {
+            "role": "assistant",
+            "content": "A fuzzy search is a search technique that is designed to be fast and tolerant of errors, such as additional or missing characters or other types of spelling mistakes. This feature is particularly useful in scenarios where exact matches are not required or when dealing with imperfect data"
+          },
+          "finish_reason": "length"
+        }
+      ],
+      "usage": {
+        "completion_tokens": 50,
+        "prompt_tokens": 1222,
+        "total_tokens": 1272
+      }
+    }
+  },
+  "orchestration_result": {
+    "id": "chatcmpl-B7fExAgihXpKnBaaJ3uXnLgmaC6Ox",
+    "object": "chat.completion",
+    "created": 1741166523,
+    "model": "gpt-4o-2024-08-06",
+    "system_fingerprint": "fp_b705f0c291",
+    "choices": [
+      {
+        "index": 0,
+        "message": {
+          "role": "assistant",
+          "content": "A fuzzy search is a search technique that is designed to be fast and tolerant of errors, such as additional or missing characters or other types of spelling mistakes. This feature is particularly useful in scenarios where exact matches are not required or when dealing with imperfect data"
+        },
+        "finish_reason": "length"
+      }
+    ],
+    "usage": {
+      "completion_tokens": 50,
+      "prompt_tokens": 1222,
+      "total_tokens": 1272
+    }
+  }
+}
diff --git a/orchestration/src/test/resources/groundingHelpSapComRequest.json b/orchestration/src/test/resources/groundingHelpSapComRequest.json
@@ -0,0 +1,45 @@
+{
+  "orchestration_config" : {
+    "module_configurations" : {
+      "llm_module_config" : {
+        "model_name" : "gpt-4o",
+        "model_params" : {
+          "max_tokens" : 50,
+          "temperature" : 0.1,
+          "frequency_penalty" : 0,
+          "presence_penalty" : 0,
+          "top_p" : 1,
+          "n" : 1
+        },
+        "model_version" : "latest"
+      },
+      "templating_module_config" : {
+        "template" : [ {
+          "role" : "user",
+          "content" : "{{?userMessage}} Use the following information as additional context: {{?groundingContext}}"
+        } ],
+        "defaults" : { },
+        "tools" : [ ]
+      },
+      "grounding_module_config" : {
+        "type" : "document_grounding_service",
+        "config" : {
+          "filters" : [ {
+            "data_repositories" : [ "*" ],
+            "data_repository_type" : "help.sap.com",
+            "data_repository_metadata" : [ ],
+            "document_metadata" : [ ],
+            "chunk_metadata" : [ ]
+          } ],
+          "input_params" : [ "userMessage" ],
+          "output_param" : "groundingContext"
+        }
+      }
+    },
+    "stream" : false
+  },
+  "input_params" : {
+    "userMessage" : "What is a fuzzy search?"
+  },
+  "messages_history" : [ ]
+}
diff --git a/sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java b/sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/OrchestrationController.java
@@ -192,6 +192,17 @@ Object grounding(
     return response.getContent();
   }
 
+  @GetMapping("/groundingHelpSapCom")
+  @Nonnull
+  Object groundingHelpSapCom(
+      @Nullable @RequestParam(value = "format", required = false) final String format) {
+    final var response = service.groundingHelpSapCom("What is a fuzzy search?");
+    if ("json".equals(format)) {
+      return response;
+    }
+    return response.getContent();
+  }
+
   @GetMapping("/image")
   @Nonnull
   Object imageInput(@RequestParam(value = "format", required = false) final String format) {
diff --git a/sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java b/sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/services/OrchestrationService.java
@@ -348,6 +348,26 @@ public OrchestrationChatResponse grounding(
     return client.chatCompletion(prompt, configWithGrounding);
   }
 
+  /**
+   * Using grounding via *help.sap.com* to provide additional SAP-specific 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>
+   * @param userMessage the user message to provide grounding for
+   * @return the assistant response object
+   */
+  @Nonnull
+  public OrchestrationChatResponse groundingHelpSapCom(@Nonnull final String userMessage) {
+    val groundingHelpSapCom =
+        DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.HELP_SAP_COM);
+    val groundingConfig = Grounding.create().filters(groundingHelpSapCom);
+    val configWithGrounding = config.withGrounding(groundingConfig);
+
+    val prompt = groundingConfig.createGroundingPrompt(userMessage);
+
+    return client.chatCompletion(prompt, configWithGrounding);
+  }
+
   /**
    * Chat request to OpenAI through the Orchestration service using response format with JSON
    * schema.
diff --git a/sample-code/spring-app/src/main/resources/static/index.html b/sample-code/spring-app/src/main/resources/static/index.html
@@ -360,7 +360,17 @@ <h2>Orchestration</h2>
                                     </div>
                                 </div>
                             </li>
-
+                            <li class="list-group-item">
+                                <div class="info-tooltip">
+                                    <button type="submit" formaction="/orchestration/groundingHelpSapCom"
+                                            class="link-offset-2-hover link-underline link-underline-opacity-0 link-underline-opacity-75-hover endpoint">
+                                        <code>/orchestration/groundingHelpSapCom</code>
+                                    </button>
+                                    <div class="tooltip-content">
+                                        Using grounding via *help.sap.com* to provide additional SAP-specific context to the AI model.
+                                    </div>
+                                </div>
+                            </li>
                             <li class="list-group-item">
                                 <div class="info-tooltip">
                                     <button type="submit" formaction="/orchestration/image"
