feat: [Orchestration] Enable grounding via help.sap.com (#372)

* Make it work

* Add unit test

* Add docs and release notes

* Add e2e test

* Small changes, adjust test coverage

* Update docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

Co-authored-by: Charles Dubois <[email protected]>

* Update orchestration/src/test/resources/__files/groundingHelpSapComResponse.json

Co-authored-by: Charles Dubois <[email protected]>

* Update orchestration/src/test/resources/__files/groundingHelpSapComResponse.json

Co-authored-by: Charles Dubois <[email protected]>

* Update ORCHESTRATION_CHAT_COMPLETION.md

* small fix

---------

Co-authored-by: Jonas Israel <[email protected]>
Co-authored-by: Charles Dubois <[email protected]>

Author: Jonas-Isr

docs/guides/ORCHESTRATION_CHAT_COMPLETION.md

@@ -227,6 +227,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 =
@@ -250,7 +254,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).
 

docs/release-notes/release_notes.md

@@ -14,6 +14,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] [Grounding via *help.sap.com* is enabled.](https://github.com/SAP/ai-sdk-java/tree/main/docs/guides/ORCHESTRATION_CHAT_COMPLETION.md#grounding)
 
 ### 📈 Improvements
 

orchestration/pom.xml

@@ -34,7 +34,7 @@
     <coverage.complexity>83%</coverage.complexity>
     <coverage.line>94%</coverage.line>
     <coverage.instruction>94%</coverage.instruction>
-    <coverage.branch>75%</coverage.branch>
+    <coverage.branch>77%</coverage.branch>
     <coverage.method>93%</coverage.method>
     <coverage.class>100%</coverage.class>
   </properties>

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);

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

@@ -206,6 +206,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(

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
+    }
+  }
+}

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" : [ ]
+}

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

@@ -191,6 +191,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) {

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

@@ -340,6 +340,26 @@ public OrchestrationChatResponse grounding(@Nonnull final String userMessage) {
     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.

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

@@ -349,7 +349,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"